收集 Duo 實體內容記錄

剖析器版本:2.0

支援的服務:

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

事前準備

請確認您符合下列必要條件:

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

設定 Duo Admin API 應用程式

  1. 登入 Duo 管理面板。
  2. 依序前往「Applications」>「Protect an Application」。
  3. 搜尋「Admin API」,然後按一下「保護」。
  4. 記錄下列值:
    • 整合金鑰 (ikey)
    • 密鑰 (skey)
    • API 主機名稱 (例如 api-XXXXXXXX.duosecurity.com)
  5. 在「Permissions」中,啟用「Grant resource - Read」(讀取使用者、群組、電話、端點、權杖和 WebAuthn 憑證)。
  6. 按一下「儲存」。

建立 Google Cloud Storage bucket

  1. 前往 Google Cloud 控制台。
  2. 選取專案或建立新專案。
  3. 在導覽選單中,依序前往「Cloud Storage」>「Bucket」。
  4. 按一下「建立值區」。
  5. 提供下列設定詳細資料:

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

  7. 請記下 bucket 名稱和區域,以供日後參考。

建立 Cloud Run 函式的服務帳戶

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

建立服務帳戶

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

這些角色適用於:

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

授予 GCS bucket 的 IAM 權限

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

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

建立 Pub/Sub 主題

建立 Pub/Sub 主題,Cloud Scheduler 會發布至該主題,Cloud Run 函式則會訂閱該主題。

  1. 在 GCP 控制台中,依序前往「Pub/Sub」>「主題」。
  2. 按一下「建立主題」。
  3. 提供下列設定詳細資料:
    • 主題 ID:輸入 duo-entity-context-trigger。
    • 其他設定保留預設值。
  4. 點選「建立」。

建立 Cloud Run 函式,收集實體比對內容資料

Cloud Scheduler 傳送的 Pub/Sub 訊息會觸發 Cloud Run 函式,從 Duo Admin API 擷取實體內容資料,並寫入 GCS。

  1. 在 GCP 控制台中,前往「Cloud Run」。
  2. 按一下「Create service」(建立服務)。
  3. 選取「函式」(使用直接修改建立函式)。
  4. 在「Configure」(設定) 部分,提供下列設定詳細資料:

    設定 值
    服務名稱 duo-entity-context-collector
    區域 選取與 GCS bucket 相符的區域 (例如 us-central1)
    執行階段 選取「Python 3.12」或更新版本
  5. 在「Trigger (optional)」(觸發條件 (選用)) 部分:

    1. 按一下「+ 新增觸發條件」。
    2. 選取「Cloud Pub/Sub」。
    3. 在「Select a Cloud Pub/Sub topic」(選取 Cloud Pub/Sub 主題) 中,選擇 Pub/Sub 主題 (duo-entity-context-trigger)。
    4. 按一下「儲存」。
  6. 在「Authentication」(驗證) 部分:

    1. 選取「需要驗證」。
    2. Identity and Access Management (IAM)。
  7. 向下捲動並展開「容器、網路、安全性」。

  8. 前往「安全性」分頁:

    • 服務帳戶:選取服務帳戶 (duo-entity-context-sa)。
  9. 前往「容器」分頁:

    1. 按一下「Variables & Secrets」(變數與密鑰)。
    2. 針對每個環境變數,按一下「+ 新增變數」:
    變數名稱 範例值
    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
  10. 在「Variables & Secrets」(變數與密鑰) 部分,捲動至「Requests」(要求):

    • 要求逾時:輸入 600 秒 (10 分鐘)。
  11. 前往「容器」的「設定」分頁:

    • 在「Resources」(資源) 部分:
      • 「記憶體」:選取「512 MiB」或以上。
      • CPU:選取「1」。
    • 按一下「完成」。
  12. 捲動至「Execution environment」(執行環境):

    • 選取「預設」(建議)。
  13. 在「Revision scaling」(修訂版本資源調度) 部分:

    • 「Minimum number of instances」(執行個體數量下限):輸入 0。
    • 「執行個體數量上限」:輸入 100 (或依預期負載調整)。
  14. 點選「建立」。

  15. 等待服務建立完成 (1 至 2 分鐘)。

  16. 服務建立完成後,內嵌程式碼編輯器會自動開啟。

新增函式程式碼

  1. 在「函式進入點」中輸入 main
  2. 在內嵌程式碼編輯器中,建立兩個檔案:

    • 第一個檔案: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:
        """RFC 3986 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.*
    
  3. 按一下「部署」,即可儲存並部署函式。

  4. 等待部署作業完成 (2 至 3 分鐘)。

建立 Cloud Scheduler 工作

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

  1. 在 GCP 控制台中,前往「Cloud Scheduler」。
  2. 點選「建立工作」。
  3. 提供下列設定詳細資料:

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

排程頻率選項

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

    頻率 Cron 運算式 用途
    每小時 0 * * * * 標準 (建議)
    每 2 小時 0 */2 * * * 中等
    每 6 小時 0 */6 * * * 低頻率更新
    每天 0 0 * * * 極少更新

測試排程器工作

  1. 在 Cloud Scheduler 控制台中,找到您的工作 (duo-entity-context-hourly)。
  2. 按一下「強制執行」,手動觸發。
  3. 等待幾秒鐘,然後依序前往「Cloud Run」>「服務」>「duo-entity-context-collector」>「記錄」。
  4. 確認函式是否執行成功。
  5. 檢查 GCS bucket,確認實體比對內容資料已寫入。

擷取 Google SecOps 服務帳戶

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

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

  1. 依序前往「設定」>「資料管理」>「動態饋給」。如果使用的是 SIEM 專用平台,請依序前往「設定」>「動態饋給」。
  2. 按一下「新增動態饋給」。
  3. 按一下「設定單一動態饋給」。
  4. 在「Feed name」(動態饋給名稱) 欄位中,輸入動態饋給名稱 (例如 Duo Entity Context)。
  5. 選取「Google Cloud Storage V2」做為「來源類型」。
  6. 選取「Duo Entity 比對內容資料」做為「記錄類型」。
  7. 按一下「Get Service Account」。系統會顯示專屬服務帳戶電子郵件地址,例如:

    chronicle-12345678@chronicle-gcp-prod.iam.gserviceaccount.com
    
  8. 複製這個電子郵件地址,下一個步驟將會用到。

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

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

  1. 依序前往「Cloud Storage」>「Bucket」。
  2. 按一下 bucket 名稱。
  3. 前往「權限」分頁。
  4. 按一下「授予存取權」。
  5. 提供下列設定詳細資料:
    • 新增主體:貼上 Google SecOps 服務帳戶電子郵件地址。
    • 指派角色:選取「Storage 物件檢視者」。
  6. 按一下「儲存」。

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

  1. 依序前往「設定」>「資料管理」>「動態饋給」。如果使用的是 SIEM 專用平台,請依序前往「設定」>「動態饋給」。
  2. 按一下「新增動態饋給」。
  3. 按一下「設定單一動態饋給」。
  4. 在「Feed name」(動態饋給名稱) 欄位中,輸入動態饋給名稱 (例如 Duo Entity Context)。
  5. 選取「Google Cloud Storage V2」做為「來源類型」。
  6. 選取「Duo Entity 比對內容資料」做為「記錄類型」。
  7. 點選「下一步」。
  8. 指定下列輸入參數的值:

    • Storage bucket URL:輸入 GCS bucket URI,並加上前置字元路徑:

      gs://duo-context/duo/context/
      
      • 更改項目:

        • duo-context:GCS bucket 名稱。
        • duo/context/:儲存記錄的前置字元/資料夾路徑 (必須與 GCS_PREFIX 環境變數相符)。
    • 來源刪除選項:根據偏好選取刪除選項:

      • Never:轉移後一律不刪除任何檔案 (建議用於測試)。
      • 刪除已轉移的檔案:在成功轉移後刪除檔案。
      • 刪除已轉移的檔案和空白目錄:成功轉移後,刪除檔案和空白目錄。

    • 檔案存在時間上限:包含過去幾天內修改過的檔案。預設值為 180 天。

    • Asset namespace:資產命名空間。

    • 擷取標籤:要套用至這個動態饋給事件的標籤。

  9. 點選「下一步」。

  10. 在「完成」畫面中檢查新的新聞動態消息設定,然後按一下「提交」。

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 專家尋求解答。