Mengumpulkan log konteks entitas Duo

Didukung di:

Google SecOps SIEM

Dokumen ini menjelaskan cara menyerap data konteks entitas Duo ke Google Security Operations menggunakan Google Cloud Storage. Parser mengubah log JSON menjadi model data terpadu (UDM) dengan terlebih dahulu mengekstrak kolom dari JSON mentah, lalu memetakan kolom tersebut ke atribut UDM. UDM menangani berbagai skenario data, termasuk informasi pengguna dan aset, detail software, dan label keamanan, sehingga memastikan representasi yang komprehensif dalam skema UDM.

Sebelum memulai

Pastikan Anda memiliki prasyarat berikut:

Instance Google SecOps
Akses istimewa ke tenant Duo (aplikasi Admin API dengan hak istimewa administratif yang memadai untuk mengelola aplikasi)
Project GCP dengan Cloud Storage API diaktifkan
Izin untuk membuat dan mengelola bucket GCS
Izin untuk mengelola kebijakan IAM di bucket GCS
Izin untuk membuat layanan Cloud Run, topik Pub/Sub, dan tugas Cloud Scheduler

Mengonfigurasi aplikasi Duo Admin API

Login ke Panel Admin Duo.
Buka Applications > Protect an Application.
Telusuri Admin API, lalu klik Protect.
Catat nilai berikut:
- Kunci integrasi (ikey)
- Kunci rahasia (skey)
- Nama host API (misalnya, api-XXXXXXXX.duosecurity.com)
Di Permissions, aktifkan Grant resource - Read (untuk membaca pengguna, grup, ponsel, endpoint, token, dan kredensial WebAuthn).
Klik Simpan.

Catatan: Anda harus memiliki hak istimewa administratif yang memadai (misalnya, Pemilik atau peran setara yang diizinkan untuk mengelola aplikasi) di Duo untuk membuat atau mengubah aplikasi Admin API.

Membuat bucket Google Cloud Storage

Buka Google Cloud Console.
Pilih project Anda atau buat project baru.
Di menu navigasi, buka Cloud Storage > Buckets.
Klik Create bucket.

Berikan detail konfigurasi berikut:

Setelan	Nilai
Beri nama bucket Anda	Masukkan nama yang unik secara global (misalnya, `duo-context`)
Location type	Pilih berdasarkan kebutuhan Anda (Region, Dual-region, Multi-region)
Lokasi	Pilih lokasi (misalnya, `us-central1`)
Kelas penyimpanan	Standar (direkomendasikan untuk log yang sering diakses)
Access control	Seragam (direkomendasikan)
Alat perlindungan	Opsional: Aktifkan pembuatan versi objek atau kebijakan retensi

Klik Buat.
Simpan nama bucket dan region untuk referensi di masa mendatang.

Buat akun layanan untuk Cloud Run Function

Fungsi Cloud Run memerlukan akun layanan dengan izin untuk menulis ke bucket GCS dan dipanggil oleh Pub/Sub.

Membuat akun layanan

Di GCP Console, buka IAM & Admin > Service Accounts.
Klik Create Service Account.
Berikan detail konfigurasi berikut:
- Nama akun layanan: Masukkan duo-entity-context-sa.
- Deskripsi akun layanan: Masukkan Service account for Cloud Run function to collect Duo entity context data.
Klik Create and Continue.
Di bagian Berikan akun layanan ini akses ke project, tambahkan peran berikut:
1. Klik Pilih peran.
2. Telusuri dan pilih Storage Object Admin.
3. Klik + Add another role.
4. Telusuri dan pilih Cloud Run Invoker.
5. Klik + Add another role.
6. Telusuri dan pilih Cloud Functions Invoker.
Klik Lanjutkan.
Klik Selesai.

Peran ini diperlukan untuk:

Storage Object Admin: Menulis log ke bucket GCS
Cloud Run Invoker: Mengizinkan Pub/Sub memanggil fungsi
Cloud Functions Invoker: Mengizinkan pemanggilan fungsi

Memberikan izin IAM pada bucket GCS

Beri akun layanan izin tulis di bucket GCS:

Buka Cloud Storage > Buckets.
Klik nama bucket Anda.
Buka tab Izin.
Klik Grant access.
Berikan detail konfigurasi berikut:
- Tambahkan prinsipal: Masukkan email akun layanan (misalnya, duo-entity-context-sa@PROJECT_ID.iam.gserviceaccount.com).
- Tetapkan peran: Pilih Storage Object Admin.
Klik Simpan.

Membuat topik Pub/Sub

Buat topik Pub/Sub yang akan dipublikasikan oleh Cloud Scheduler dan akan dilanggan oleh fungsi Cloud Run.

Di GCP Console, buka Pub/Sub > Topics.
Klik Create topic.
Berikan detail konfigurasi berikut:
- ID Topik: Masukkan duo-entity-context-trigger.
- Biarkan setelan lainnya tetap default.
Klik Buat.

Membuat fungsi Cloud Run untuk mengumpulkan data konteks entity

Fungsi Cloud Run dipicu oleh pesan Pub/Sub dari Cloud Scheduler untuk mengambil data konteks entitas dari Duo Admin API dan menuliskannya ke GCS.

Di GCP Console, buka Cloud Run.
Klik Create service.
Pilih Function (gunakan editor inline untuk membuat fungsi).
Di bagian Konfigurasi, berikan detail konfigurasi berikut:

Setelan Nilai

Nama layanan duo-entity-context-collector

Wilayah Pilih region yang cocok dengan bucket GCS Anda (misalnya, us-central1)

Runtime Pilih Python 3.12 atau yang lebih baru
Di bagian Pemicu (opsional):
1. Klik + Tambahkan pemicu.
2. Pilih Cloud Pub/Sub.
3. Di Select a Cloud Pub/Sub topic, pilih topik Pub/Sub (duo-entity-context-trigger).
4. Klik Simpan.
Di bagian Authentication:
1. Pilih Wajibkan autentikasi.
2. Periksa Identity and Access Management (IAM).
Catatan: Pub/Sub secara otomatis menangani autentikasi saat memanggil fungsi.
Scroll ke bawah dan luaskan Containers, Networking, Security.
Buka tab Security:
- Akun layanan: Pilih akun layanan (duo-entity-context-sa).

Setelan	Nilai
Nama layanan	`duo-entity-context-collector`
Wilayah	Pilih region yang cocok dengan bucket GCS Anda (misalnya, `us-central1`)
Runtime	Pilih Python 3.12 atau yang lebih baru

Buka tab Containers:

Klik Variables & Secrets.
Klik + Tambahkan variabel untuk setiap variabel lingkungan:

Nama Variabel	Nilai Contoh
`GCS_BUCKET`	`duo-context`
`GCS_PREFIX`	`duo/context/`
`DUO_IKEY`	`DIXYZ...`
`DUO_SKEY`	`****************`
`DUO_API_HOSTNAME`	`api-XXXXXXXX.duosecurity.com`
`LIMIT`	`100`
`RESOURCES`	`users,groups,phones,endpoints,tokens,webauthncredentials`

Di bagian Variabel & Secret, scroll ke Permintaan:
- Waktu tunggu permintaan: Masukkan 600 detik (10 menit).
Buka tab Setelan di Penampung:
- Di bagian Materi:
  - Memori: Pilih 512 MiB atau yang lebih tinggi.
  - CPU: Pilih 1.
- Klik Selesai.
Scroll ke Lingkungan eksekusi:
- Pilih Default (direkomendasikan).
Di bagian Penskalaan revisi:
- Jumlah minimum instance: Masukkan 0.
- Jumlah maksimum instance: Masukkan 100 (atau sesuaikan berdasarkan perkiraan beban).
Klik Buat.
Tunggu hingga layanan dibuat (1-2 menit).
Setelah layanan dibuat, editor kode inline akan terbuka secara otomatis.

Menambahkan kode fungsi

Masukkan main di Function entry point

Di editor kode inline, buat dua file:

File pertama: main.py:

import functions_framework
from google.cloud import storage
import json
import os
import time
import hmac
import hashlib
import base64
import email.utils
import urllib.parse
from urllib.request import Request, urlopen

# Environment variables
DUO_IKEY = os.environ["DUO_IKEY"]
DUO_SKEY = os.environ["DUO_SKEY"]
DUO_API_HOSTNAME = os.environ["DUO_API_HOSTNAME"].strip()
GCS_BUCKET = os.environ["GCS_BUCKET"]
GCS_PREFIX = os.environ.get("GCS_PREFIX", "duo/context/")

# Default resources can be adjusted via ENV
RESOURCES = [r.strip() for r in os.environ.get("RESOURCES", "users,groups,phones,endpoints,tokens,webauthncredentials,desktop_authenticators").split(",") if r.strip()]

# Duo paging: default 100; max varies by endpoint
LIMIT = int(os.environ.get("LIMIT", "100"))

# Initialize Storage client
storage_client = storage.Client()

def _canon_params(params: dict) -> str:
    """RFC3986 encoding with '~' unescaped, keys sorted lexicographically."""
    if not params:
        return ""
    parts = []
    for k in sorted(params.keys()):
        v = params[k]
        if v is None:
            continue
        ks = urllib.parse.quote(str(k), safe="~")
        vs = urllib.parse.quote(str(v), safe="~")
        parts.append(f"{ks}={vs}")
    return "&".join(parts)

def _sign(method: str, host: str, path: str, params: dict) -> dict:
    """Construct Duo Admin API Authorization + Date headers (HMAC-SHA1)."""
    now = email.utils.formatdate()
    canon = "\n".join([
        now,
        method.upper(),
        host.lower(),
        path,
        _canon_params(params)
    ])
    sig = hmac.new(
        DUO_SKEY.encode("utf-8"),
        canon.encode("utf-8"),
        hashlib.sha1
    ).hexdigest()
    auth = base64.b64encode(f"{DUO_IKEY}:{sig}".encode("utf-8")).decode("utf-8")
    return {
        "Date": now,
        "Authorization": f"Basic {auth}"
    }

def _call(method: str, path: str, params: dict) -> dict:
    host = DUO_API_HOSTNAME
    assert host.startswith("api-") and host.endswith(".duosecurity.com"), \
        "DUO_API_HOSTNAME must be e.g. api-XXXXXXXX.duosecurity.com"

    qs = _canon_params(params)
    url = f"https://{host}{path}" + (f"?{qs}" if method.upper() == "GET" and qs else "")

    req = Request(url, method=method.upper())
    for k, v in _sign(method, host, path, params).items():
        req.add_header(k, v)

    with urlopen(req, timeout=60) as r:
        return json.loads(r.read().decode("utf-8"))

def _write_json(obj: dict, when: float, resource: str, page: int) -> str:
    bucket = storage_client.bucket(GCS_BUCKET)
    prefix = GCS_PREFIX.strip("/") + "/" if GCS_PREFIX else ""
    key = f"{prefix}{time.strftime('%Y/%m/%d', time.gmtime(when))}/duo-{resource}-{page:05d}.json"

    blob = bucket.blob(key)
    blob.upload_from_string(
        json.dumps(obj, separators=(",", ":")),
        content_type="application/json"
    )
    return key

def _fetch_resource(resource: str) -> dict:
    """Fetch all pages for a list endpoint using limit/offset + metadata.next_offset."""
    path = f"/admin/v1/{resource}"
    offset = 0
    page = 0
    now = time.time()
    total_items = 0

    while True:
        params = {"limit": LIMIT, "offset": offset}
        data = _call("GET", path, params)
        _write_json(data, now, resource, page)
        page += 1

        resp = data.get("response")
        # most endpoints return a list; if not a list, count as 1 object page
        if isinstance(resp, list):
            total_items += len(resp)
        elif resp is not None:
            total_items += 1

        meta = data.get("metadata") or {}
        next_offset = meta.get("next_offset")
        if next_offset is None:
            break

        # Duo returns next_offset as int
        try:
            offset = int(next_offset)
        except Exception:
            break

    return {
        "resource": resource,
        "pages": page,
        "objects": total_items
    }

@functions_framework.cloud_event
def main(cloud_event):
    """
    Cloud Run function triggered by Pub/Sub to fetch Duo entity context data and write to GCS.

    Args:
        cloud_event: CloudEvent object containing Pub/Sub message
    """
    results = []
    for res in RESOURCES:
        print(f"Fetching resource: {res}")
        result = _fetch_resource(res)
        results.append(result)
        print(f"Completed {res}: {result['pages']} pages, {result['objects']} objects")

    print(f"All resources fetched successfully: {results}")

File kedua: requirements.txt:

functions-framework==3.*
google-cloud-storage==2.*

Klik Deploy untuk menyimpan dan men-deploy fungsi.
Tunggu hingga deployment selesai (2-3 menit).

Catatan: Konfigurasi pemicu Pub/Sub secara otomatis membuat langganan dan izin yang diperlukan.
Catatan: Endpoint Admin API yang berbeda memiliki nilai batas maksimum yang berbeda. Menggunakan nilai yang lebih tinggi daripada yang didukung untuk endpoint tertentu akan menghasilkan error 400. Nilai default 100 aman untuk semua endpoint.

Buat tugas Cloud Scheduler

Cloud Scheduler memublikasikan pesan ke topik Pub/Sub secara berkala, sehingga memicu fungsi Cloud Run.

Di GCP Console, buka Cloud Scheduler.
Klik Create Job.

Berikan detail konfigurasi berikut:

Setelan	Nilai
Nama	`duo-entity-context-hourly`
Wilayah	Pilih region yang sama dengan fungsi Cloud Run
Frekuensi	`0 * * * *` (setiap jam, tepat pada waktunya)
Zona waktu	Pilih zona waktu (UTC direkomendasikan)
Jenis target	Pub/Sub
Topik	Pilih topik Pub/Sub (`duo-entity-context-trigger`)
Isi pesan	`{}` (objek JSON kosong)

Klik Buat.

Opsi frekuensi jadwal

Pilih frekuensi berdasarkan persyaratan keaktualan data:

Frekuensi	Ekspresi Cron	Kasus Penggunaan
Setiap jam	`0 * * * *`	Standar (direkomendasikan)
Setiap 2 jam	`0 /2 * *`	Keaktualan sedang
Setiap 6 jam	`0 /6 * *`	Update frekuensi rendah
Harian	`0 0 * * *`	Update minimal

Menguji tugas penjadwal

Di konsol Cloud Scheduler, temukan tugas Anda (duo-entity-context-hourly).
Klik Jalankan paksa untuk memicu secara manual.
Tunggu beberapa detik, lalu buka Cloud Run > Services > duo-entity-context-collector > Logs.
Pastikan fungsi berhasil dieksekusi.
Periksa bucket GCS untuk mengonfirmasi bahwa data konteks entitas telah ditulis.

Mengambil akun layanan Google SecOps

Google SecOps menggunakan akun layanan unik untuk membaca data dari bucket GCS Anda. Anda harus memberi akun layanan ini akses ke bucket Anda.

Dapatkan email akun layanan

Buka Setelan SIEM > Feed.
Klik Tambahkan Feed Baru.
Klik Konfigurasi satu feed.
Di kolom Nama feed, masukkan nama untuk feed (misalnya, Duo Entity Context).
Pilih Google Cloud Storage V2 sebagai Source type.
Pilih Data konteks Entitas Duo sebagai Jenis log.
Klik Get Service Account. Email akun layanan yang unik akan ditampilkan, misalnya:
```
chronicle-12345678@chronicle-gcp-prod.iam.gserviceaccount.com
```
Salin alamat email ini untuk digunakan di langkah berikutnya.

Catatan: Setiap instance Google SecOps memiliki akun layanan yang unik. Jangan gunakan akun layanan dari dokumentasi atau contoh lain.

Memberikan izin IAM ke akun layanan Google SecOps

Akun layanan Google SecOps memerlukan peran Storage Object Viewer di bucket GCS Anda.

Buka Cloud Storage > Buckets.
Klik nama bucket Anda.
Buka tab Izin.
Klik Grant access.
Berikan detail konfigurasi berikut:
- Add principals: Tempel email akun layanan Google SecOps.
- Tetapkan peran: Pilih Storage Object Viewer.
Klik Simpan.

Catatan: Jika Anda berencana menggunakan opsi penghapusan "Hapus file yang ditransfer" atau "Hapus file yang ditransfer dan direktori kosong", berikan peran Storage Object Admin, bukan Storage Object Viewer.

Mengonfigurasi feed di Google SecOps untuk menyerap data Konteks Entitas Duo

Buka Setelan SIEM > Feed.
Klik Tambahkan Feed Baru.
Klik Konfigurasi satu feed.
Di kolom Nama feed, masukkan nama untuk feed (misalnya, Duo Entity Context).
Pilih Google Cloud Storage V2 sebagai Source type.
Pilih Data konteks Entitas Duo sebagai Jenis log.
Klik Berikutnya.
Tentukan nilai untuk parameter input berikut:
- URL bucket penyimpanan: Masukkan URI bucket GCS dengan jalur awalan:
```
gs://duo-context/duo/context/
```
  - Ganti:
    - duo-context: Nama bucket GCS Anda.
    - duo/context/: Jalur folder/awalan tempat log disimpan (harus cocok dengan variabel lingkungan GCS_PREFIX).
  Catatan: Selalu sertakan garis miring (/) di akhir URI.
- Opsi penghapusan sumber: Pilih opsi penghapusan sesuai preferensi Anda:
  - Jangan pernah: Tidak pernah menghapus file apa pun setelah transfer (direkomendasikan untuk pengujian).
  - Hapus file yang ditransfer: Menghapus file setelah transfer berhasil.
  - Hapus file yang ditransfer dan direktori kosong: Menghapus file dan direktori kosong setelah transfer berhasil.
    
    Catatan: Jika Anda memilih opsi penghapusan, akun layanan harus memiliki peran Storage Object Admin, bukan Storage Object Viewer. Perbarui izin IAM yang sesuai.
- Usia File Maksimum: Menyertakan file yang diubah dalam beberapa hari terakhir. Defaultnya adalah 180 hari.
- Namespace aset: Namespace aset.
- Label penyerapan: Label yang akan diterapkan ke peristiwa dari feed ini.
Klik Berikutnya.
Tinjau konfigurasi feed baru Anda di layar Selesaikan, lalu klik Kirim.

Tabel pemetaan UDM

Kolom Log	Pemetaan UDM	Logika
aktif	entity.asset.deployment_status	Jika 'activated' adalah false, setel ke "DECOMISSIONED", jika tidak, "ACTIVE".
browsers.browser_family	entity.asset.software.name	Diekstrak dari array 'browser' dalam log mentah.
browsers.browser_version	entity.asset.software.version	Diekstrak dari array 'browser' dalam log mentah.
device_name	entity.asset.hostname	Dipetakan langsung dari log mentah.
disk_encryption_status	entity.asset.attribute.labels.key: "disk_encryption_status", entity.asset.attribute.labels.value	Dipetakan langsung dari log mentah, dikonversi menjadi huruf kecil.
email	entity.user.email_addresses	Dipetakan langsung dari log mentah jika berisi "@", atau menggunakan 'username' atau 'username1' jika berisi "@".
dienkripsi	entity.asset.attribute.labels.key: "Encrypted", entity.asset.attribute.labels.value	Dipetakan langsung dari log mentah, dikonversi menjadi huruf kecil.
epkey	entity.asset.product_object_id	Digunakan sebagai 'product_object_id' jika ada, jika tidak, menggunakan 'phone_id' atau 'token_id'.
sidik jari	entity.asset.attribute.labels.key: "Sidik Jari", entity.asset.attribute.labels.value	Dipetakan langsung dari log mentah, dikonversi menjadi huruf kecil.
firewall_status	entity.asset.attribute.labels.key: "firewall_status", entity.asset.attribute.labels.value	Dipetakan langsung dari log mentah, dikonversi menjadi huruf kecil.
hardware_uuid	entity.asset.asset_id	Digunakan sebagai 'asset_id' jika ada, jika tidak, akan menggunakan 'user_id'.
last_seen	entity.asset.last_discover_time	Diuraikan sebagai stempel waktu ISO8601 dan dipetakan.
model	entity.asset.hardware.model	Dipetakan langsung dari log mentah.
angka	entity.user.phone_numbers	Dipetakan langsung dari log mentah.
os_family	entity.asset.platform_software.platform	Dipetakan ke "WINDOWS", "LINUX", atau "MAC" berdasarkan nilai, tidak peka huruf besar/kecil.
os_version	entity.asset.platform_software.platform_version	Dipetakan langsung dari log mentah.
password_status	entity.asset.attribute.labels.key: "password_status", entity.asset.attribute.labels.value	Dipetakan langsung dari log mentah, dikonversi menjadi huruf kecil.
phone_id	entity.asset.product_object_id	Digunakan sebagai 'product_object_id' jika 'epkey' tidak ada, atau menggunakan 'token_id'.
security_agents.security_agent	entity.asset.software.name	Diekstrak dari array 'security_agents' dalam log mentah.
security_agents.version	entity.asset.software.version	Diekstrak dari array 'security_agents' dalam log mentah.
timestamp	entity.metadata.collected_timestamp	Mengisi kolom 'collected_timestamp' dalam objek 'metadata'.
token_id	entity.asset.product_object_id	Digunakan sebagai 'product_object_id' jika 'epkey' dan 'phone_id' tidak ada.
trusted_endpoint	entity.asset.attribute.labels.key: "trusted_endpoint", entity.asset.attribute.labels.value	Dipetakan langsung dari log mentah, dikonversi menjadi huruf kecil.
jenis	entity.asset.type	Jika 'type' log mentah berisi "mobile" (tidak peka huruf besar/kecil), tetapkan ke "MOBILE", jika tidak, tetapkan ke "LAPTOP".
user_id	entity.asset.asset_id	Digunakan sebagai 'asset_id' jika 'hardware_uuid' tidak ada.
users.email	entity.user.email_addresses	Digunakan sebagai 'email_addresses' jika merupakan pengguna pertama dalam array 'users' dan berisi "@".
users.username	entity.user.userid	Nama pengguna diekstrak sebelum "@" dan digunakan sebagai 'userid' jika merupakan pengguna pertama dalam array 'users'.
	entity.metadata.vendor_name	"Duo"
	entity.metadata.product_name	"Data Konteks Entitas Duo"
	entity.metadata.entity_type	ASET
	entity.relations.entity_type	PENGGUNA
	entity.relations.relationship	MEMILIKI

Perlu bantuan lebih lanjut? Dapatkan jawaban dari anggota Komunitas dan profesional Google SecOps.