收集 Duo 實體內容記錄

支援的國家/地區：

Google SecOps SIEM

本文說明如何使用 Google Cloud Storage，將 Duo 實體環境資料擷取至 Google Security Operations。剖析器會先從原始 JSON 擷取欄位，然後將這些欄位對應至 UDM 屬性，藉此將 JSON 記錄轉換為統合式資料模型 (UDM)。可處理各種資料情境，包括使用者和資產資訊、軟體詳細資料和安全性標籤，確保 UDM 架構中的完整呈現。

事前準備

請確認您已完成下列事前準備事項：

Google SecOps 執行個體
Duo 租戶的特殊存取權 (具備足夠管理權限的管理員 API 應用程式，可管理應用程式)
已啟用 Cloud Storage API 的 GCP 專案
建立及管理 GCS 值區的權限
管理 Google Cloud Storage 值區 IAM 政策的權限
建立 Cloud Run 服務、Pub/Sub 主題和 Cloud Scheduler 工作的權限

設定 Duo Admin API 應用程式

登入 Duo 管理面板。
依序前往「應用程式」>「保護應用程式」。
搜尋「Admin API」，然後按一下「Protect」。
記錄下列值：
- 整合金鑰 (ikey)
- 密鑰 (skey)
- API 主機名稱 (例如 api-XXXXXXXX.duosecurity.com)
在「Permissions」(權限) 中，啟用「Grant resource - Read」(授予資源 - 讀取) (讀取使用者、群組、電話、端點、權杖和 WebAuthn 憑證)。
按一下 [儲存]。

注意： 您必須在 Duo 中具備足夠的管理員權限 (例如擁有者或有權管理應用程式的同等角色)，才能建立或修改 Admin API 應用程式。

建立 Google Cloud Storage 值區

前往 Google Cloud 控制台。
選取專案或建立新專案。
在導覽選單中，依序前往「Cloud Storage」>「Bucket」。
按一下「建立值區」。

請提供下列設定詳細資料：

設定	值
為 bucket 命名	輸入全域不重複的名稱 (例如 `duo-context`)
位置類型	根據需求選擇 (區域、雙區域、多區域)
位置	選取位置 (例如 `us-central1`)
儲存空間級別	標準 (建議用於經常存取的記錄)
存取控管	統一 (建議)
保護工具	選用：啟用物件版本管理或保留政策

點選「建立」。
請儲存 bucket 名稱和區域，以供日後參考。

為 Cloud Run 函式建立服務帳戶

Cloud Run 函式需要具備 GCS bucket 寫入權限的服務帳戶，並由 Pub/Sub 叫用。

建立服務帳戶

在 GCP 主控台中，依序前往「IAM & Admin」(IAM 與管理) >「Service Accounts」(服務帳戶)。
按一下 [Create Service Account] (建立服務帳戶)。
請提供下列設定詳細資料：
- 服務帳戶名稱：輸入 duo-entity-context-sa。
- 服務帳戶說明：輸入 Service account for Cloud Run function to collect Duo entity context data。
按一下「建立並繼續」。
在「將專案存取權授予這個服務帳戶」部分，新增下列角色：
1. 按一下「選擇角色」。
2. 搜尋並選取「Storage 物件管理員」。
3. 點選「+ 新增其他角色」。
4. 搜尋並選取「Cloud Run Invoker」。
5. 點選「+ 新增其他角色」。
6. 搜尋並選取「Cloud Functions Invoker」(Cloud Functions 叫用者)。
按一下「繼續」。
按一下 [完成]。

這些角色適用於：

Storage 物件管理員：將記錄檔寫入 GCS bucket
Cloud Run 叫用者：允許 Pub/Sub 叫用函式
Cloud Functions 叫用者：允許函式叫用

授予 GCS 值區的 IAM 權限

授予服務帳戶 GCS bucket 的寫入權限：

依序前往「Cloud Storage」>「Buckets」。
按一下 bucket 名稱。
前往「權限」分頁標籤。
按一下「授予存取權」。
請提供下列設定詳細資料：
- 新增主體：輸入服務帳戶電子郵件地址 (例如 duo-entity-context-sa@PROJECT_ID.iam.gserviceaccount.com)。
- 指派角色：選取「Storage 物件管理員」。
按一下 [儲存]。

建立 Pub/Sub 主題

建立 Pub/Sub 主題，Cloud Scheduler 會將訊息發布至該主題，而 Cloud Run 函式會訂閱該主題。

在 GCP Console 中，前往「Pub/Sub」>「Topics」(主題)。
按一下「建立主題」。
請提供下列設定詳細資料：
- 主題 ID：輸入 duo-entity-context-trigger。
- 其他設定保留預設值。
點選「建立」。

建立 Cloud Run 函式，收集實體內容資料

Cloud Run 函式會由 Cloud Scheduler 的 Pub/Sub 訊息觸發，從 Duo Admin API 擷取實體環境資料，並將資料寫入 GCS。

前往 GCP Console 的「Cloud Run」。
按一下「Create service」(建立服務)。
選取「函式」 (使用內嵌編輯器建立函式)。
在「設定」部分，提供下列設定詳細資料：

設定值

服務名稱 duo-entity-context-collector

區域選取與 GCS bucket 相符的區域 (例如 us-central1)

執行階段 選取「Python 3.12」以上版本
在「Trigger (optional)」(觸發條件 (選用)) 專區：
1. 按一下「+ 新增觸發條件」。
2. 選取「Cloud Pub/Sub」。
3. 在「選取 Cloud Pub/Sub 主題」中，選擇 Pub/Sub 主題 (duo-entity-context-trigger)。
4. 按一下 [儲存]。
在「Authentication」(驗證) 部分：
1. 選取「需要驗證」。
2. 檢查 Identity and Access Management (IAM)。
注意： 叫用函式時，Pub/Sub 會自動處理驗證。
向下捲動並展開「Containers, Networking, Security」。
前往「安全性」分頁：
- 服務帳戶：選取服務帳戶 (duo-entity-context-sa)。

設定	值
服務名稱	`duo-entity-context-collector`
區域	選取與 GCS bucket 相符的區域 (例如 `us-central1`)
執行階段	選取「Python 3.12」以上版本

前往「容器」分頁：

按一下「變數與密鑰」。
針對每個環境變數，按一下「+ 新增變數」：

變數名稱	範例值
`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`

在「變數與 Secret」部分，捲動至「要求」：
- 要求逾時：輸入 600 秒 (10 分鐘)。
前往「容器」中的「設定」分頁：
- 在「資源」部分：
  - 記憶體：選取 512 MiB 以上。
  - CPU：選取 1。
- 按一下 [完成]。
捲動至「執行環境」：
- 選取「預設」 (建議選項)。
在「修訂版本資源調度」部分：
- 執行個體數量下限：輸入 0。
- 「Maximum number of instances」(執行個體數量上限)：輸入 100 (或根據預期負載調整)。
點選「建立」。
等待服務建立完成 (1 到 2 分鐘)。
服務建立完成後，系統會自動開啟內嵌程式碼編輯器。

新增函式程式碼

在「Function entry point」(函式進入點) 中輸入 main

在內嵌程式碼編輯器中建立兩個檔案：

第一個檔案：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}")

第二個檔案：requirements.txt:

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

點選「部署」來儲存並部署函式。
等待部署作業完成 (2 到 3 分鐘)。

注意：Pub/Sub 觸發程序設定會自動建立必要的訂閱項目和權限。
注意：不同的 Admin API 端點有不同的上限值。如果特定端點使用的值高於支援的值，就會導致 400 錯誤。預設值 100 適用於所有端點。

建立 Cloud Scheduler 工作

Cloud Scheduler 會定期將訊息發布至 Pub/Sub 主題，觸發 Cloud Run 函式。

前往 GCP 主控台的「Cloud Scheduler」。
點選「建立工作」。

請提供下列設定詳細資料：

設定	值
名稱	`duo-entity-context-hourly`
區域	選取與 Cloud Run 函式相同的區域
頻率	`0 * * * *` (每小時整點)
時區	選取時區 (建議使用世界標準時間)
目標類型	Pub/Sub
主題	選取 Pub/Sub 主題 (`duo-entity-context-trigger`)
郵件內文	`{}` (空白 JSON 物件)

點選「建立」。

排程頻率選項

根據資料更新間隔需求選擇頻率：

頻率	Cron 運算式	用途
每小時	`0 * * * *`	標準 (建議採用)
每 2 小時	`0 /2 * *`	中等新鮮度
每 6 小時	`0 /6 * *`	更新頻率較低
每日	`0 0 * * *`	最少更新次數

測試排程器工作

在 Cloud Scheduler 控制台中，找出您的作業 (duo-entity-context-hourly)。
按一下「強制執行」即可手動觸發。
等待幾秒鐘，然後依序前往「Cloud Run」>「Services」(服務) >「duo-entity-context-collector」>「Logs」(記錄)。
確認函式是否已順利執行。
檢查 GCS bucket，確認實體內容資料已寫入。

擷取 Google SecOps 服務帳戶

Google SecOps 會使用專屬服務帳戶，從 GCS bucket 讀取資料。您必須授予這個服務帳戶值區存取權。

取得服務帳戶電子郵件地址

依序前往「SIEM 設定」>「動態饋給」。
按一下「新增動態消息」。
按一下「設定單一動態饋給」。
在「動態饋給名稱」欄位中輸入動態饋給名稱 (例如 Duo Entity Context)。
選取「Google Cloud Storage V2」做為「來源類型」。
選取「Duo Entity context data」做為「記錄類型」。
按一下「取得服務帳戶」。系統會顯示專屬的服務帳戶電子郵件地址，例如：
```
chronicle-12345678@chronicle-gcp-prod.iam.gserviceaccount.com
```
複製這個電子郵件地址，以便在下一步中使用。

注意： 每個 Google SecOps 執行個體都有專屬的服務帳戶。請勿使用其他說明文件或範例中的服務帳戶。

將 IAM 權限授予 Google SecOps 服務帳戶

Google SecOps 服務帳戶需要 GCS bucket 的「Storage 物件檢視者」角色。

依序前往「Cloud Storage」>「Buckets」。
按一下 bucket 名稱。
前往「權限」分頁標籤。
按一下「授予存取權」。
請提供下列設定詳細資料：
- 新增主體：貼上 Google SecOps 服務帳戶電子郵件地址。
- 指派角色：選取「Storage 物件檢視者」。
按一下 [儲存]。

注意： 如果打算使用「刪除已轉移的檔案」或「刪除已轉移的檔案並清空目錄」刪除選項，請授予「Storage 物件管理員」角色，而非「Storage 物件檢視者」角色。

在 Google SecOps 中設定動態饋給，擷取 Duo 實體內容資料

依序前往「SIEM 設定」>「動態饋給」。
按一下「新增動態消息」。
按一下「設定單一動態饋給」。
在「動態饋給名稱」欄位中輸入動態饋給名稱 (例如 Duo Entity Context)。
選取「Google Cloud Storage V2」做為「來源類型」。
選取「Duo Entity context data」做為「記錄類型」。
點選 [下一步]。
指定下列輸入參數的值：
- 儲存空間 bucket URL：輸入 GCS bucket URI，並加上前置路徑：
```
gs://duo-context/duo/context/
```
  - 取代：
    - duo-context：您的 GCS bucket 名稱。
    - duo/context/：儲存記錄的前置字元/資料夾路徑 (必須與 GCS_PREFIX 環境變數相符)。
  注意： URI 結尾一律要加上尾端斜線 (/)。
- 來源刪除選項：根據偏好設定選取刪除選項：
  - 永不：移轉後一律不刪除任何檔案 (建議用於測試)。
  - 刪除已轉移的檔案：成功轉移檔案後刪除檔案。
  - 刪除已轉移的檔案和空白目錄：成功轉移後刪除檔案和空白目錄。
    
    注意： 如果選取刪除選項，服務帳戶必須具備「Storage 物件管理員」角色，而非「Storage 物件檢視者」角色。請據此更新 IAM 權限。
- 檔案存在時間上限：包含在過去天數內修改的檔案。預設值為 180 天。
- 資產命名空間：資產命名空間。
- 擷取標籤：要套用至這個動態饋給事件的標籤。
點選 [下一步]。
在「Finalize」(完成) 畫面中檢查新的動態饋給設定，然後按一下「Submit」(提交)。

UDM 對應表

記錄欄位	UDM 對應	邏輯
已啟用	entity.asset.deployment_status	如果「activated」為 false，則設為「DECOMISSIONED」，否則設為「ACTIVE」。
browsers.browser_family	entity.asset.software.name	從原始記錄的「browsers」陣列中擷取。
browsers.browser_version	entity.asset.software.version	從原始記錄的「browsers」陣列中擷取。
「device_name」	entity.asset.hostname	直接從原始記錄對應。
disk_encryption_status	entity.asset.attribute.labels.key: "disk_encryption_status", entity.asset.attribute.labels.value	直接從原始記錄對應，並轉換為小寫。
電子郵件	entity.user.email_addresses	如果原始記錄含有「@」，則直接對應；否則，如果「username」或「username1」含有「@」，則使用這些名稱。
已加密	entity.asset.attribute.labels.key: "Encrypted", entity.asset.attribute.labels.value	直接從原始記錄對應，並轉換為小寫。
epkey	entity.asset.product_object_id	如果存在，則做為「product_object_id」使用，否則使用「phone_id」或「token_id」。
指紋	entity.asset.attribute.labels.key: "Finger Print", entity.asset.attribute.labels.value	直接從原始記錄對應，並轉換為小寫。
firewall_status	entity.asset.attribute.labels.key: "firewall_status", entity.asset.attribute.labels.value	直接從原始記錄對應，並轉換為小寫。
hardware_uuid	entity.asset.asset_id	如有提供，則做為「asset_id」使用，否則會使用「user_id」。
last_seen	entity.asset.last_discover_time	系統會將其剖析為 ISO8601 時間戳記並對應。
模型	entity.asset.hardware.model	直接從原始記錄對應。
數字	entity.user.phone_numbers	直接從原始記錄對應。
os_family	entity.asset.platform_software.platform	根據值 (不區分大小寫) 對應至「WINDOWS」、「LINUX」或「MAC」。
os_version	entity.asset.platform_software.platform_version	直接從原始記錄對應。
password_status	entity.asset.attribute.labels.key: "password_status", entity.asset.attribute.labels.value	直接從原始記錄對應，並轉換為小寫。
phone_id	entity.asset.product_object_id	如果沒有「epkey」，則會當做「product_object_id」使用，否則會使用「token_id」。
security_agents.security_agent	entity.asset.software.name	從原始記錄的「security_agents」陣列中擷取。
security_agents.version	entity.asset.software.version	從原始記錄的「security_agents」陣列中擷取。
時間戳記	entity.metadata.collected_timestamp	在「metadata」物件中填入「collected_timestamp」欄位。
token_id	entity.asset.product_object_id	如果沒有「epkey」和「phone_id」，則會做為「product_object_id」使用。
trusted_endpoint	entity.asset.attribute.labels.key: "trusted_endpoint", entity.asset.attribute.labels.value	直接從原始記錄對應，並轉換為小寫。
類型	entity.asset.type	如果原始記錄的「type」包含「mobile」(不區分大小寫)，請設為「MOBILE」，否則設為「LAPTOP」。
user_id	entity.asset.asset_id	如果沒有「hardware_uuid」，則會做為「asset_id」使用。
users.email	entity.user.email_addresses	如果這是「users」陣列中的第一位使用者，且包含「@」，則會做為「email_addresses」使用。
users.username	entity.user.userid	擷取「@」前的使用者名稱，並在「users」陣列中做為第一個使用者時，將其做為「userid」。
	entity.metadata.vendor_name	「Duo」
	entity.metadata.product_name	「Duo 實體內容資料」
	entity.metadata.entity_type	資產
	entity.relations.entity_type	使用者
	entity.relations.relationship	擁有

需要其他協助嗎？向社群成員和 Google SecOps 專業人員尋求答案。