收集 Digital Shadows SearchLight 記錄

支援的國家/地區：

本文說明如何使用 Amazon S3，將 Digital Shadows SearchLight 記錄檔擷取至 Google Security Operations。剖析器會從 JSON 記錄檔中擷取安全事件資料。這個外掛程式會初始化整合式資料模型 (UDM) 欄位、剖析 JSON 酬載、將相關欄位對應至 UDM 結構定義、使用 grok 模式擷取電子郵件和主機名稱等實體，並在 UDM 事件中建構 security_result 和 metadata 物件。

事前準備

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

  • Google SecOps 執行個體。
  • Digital Shadows SearchLight 租戶的特殊存取權。
  • AWS 的特殊權限 (S3、Identity and Access Management (IAM)、Lambda、EventBridge)。

收集 Digital Shadows SearchLight 的必要條件 (ID、API 金鑰、機構 ID、權杖)

  1. 登入 Digital Shadows SearchLight 入口網站。
  2. 依序前往「設定」>「API 憑證」。
  3. 建立新的 API 用戶端或金鑰組。
  4. 複製下列詳細資料並存放在安全位置：
    • API 金鑰
    • API 密鑰
    • 帳戶 ID
    • API 基礎網址：https://api.searchlight.app/v1 或 https://portal-digitalshadows.com/api/v1

為 Google SecOps 設定 AWS S3 值區和 IAM

  1. 按照這份使用者指南建立 Amazon S3 bucket：建立 bucket
  2. 儲存 bucket 的「名稱」和「區域」，以供日後參考 (例如 digital-shadows-logs)。
  3. 請按照這份使用者指南建立使用者：建立 IAM 使用者。
  4. 選取建立的「使用者」。
  5. 選取「安全憑證」分頁標籤。
  6. 在「Access Keys」部分中，按一下「Create Access Key」。
  7. 選取「第三方服務」做為「用途」。
  8. 點選「下一步」。
  9. 選用：新增說明標記。
  10. 按一下「建立存取金鑰」。
  11. 按一下「下載 .CSV 檔案」，儲存「存取金鑰」和「私密存取金鑰」以供日後參考。
  12. 按一下 [完成]。
  13. 選取「權限」分頁標籤。
  14. 在「權限政策」部分中，按一下「新增權限」。
  15. 選取「新增權限」。
  16. 選取「直接附加政策」。
  17. 搜尋「AmazonS3FullAccess」AmazonS3FullAccess政策。
  18. 選取政策。
  19. 點選「下一步」。
  20. 按一下「Add permissions」。

設定 S3 上傳的身分與存取權管理政策和角色

  1. 在 AWS 控制台中，依序前往「IAM」>「Policies」(政策)。
  2. 按一下「建立政策」>「JSON」分頁。
  3. 複製並貼上下列政策。

  4. 政策 JSON (如果您輸入的 bucket 名稱不同，請替換 digital-shadows-logs)：

    {
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowPutObjects",
      "Effect": "Allow",
      "Action": "s3:PutObject",
      "Resource": "arn:aws:s3:::digital-shadows-logs/*"
    },
    {
      "Sid": "AllowGetStateObject",
      "Effect": "Allow",
      "Action": "s3:GetObject",
      "Resource": "arn:aws:s3:::digital-shadows-logs/digital-shadows-searchlight/state.json"
    }
  ]
}

  5. 依序點選「下一步」>「建立政策」。

  6. 依序前往「IAM」>「Roles」>「Create role」>「AWS service」>「Lambda」。

  7. 附加新建立的政策。

  8. 為角色命名 digital-shadows-lambda-role，然後按一下「建立角色」。

建立 Lambda 函式

  1. 在 AWS 控制台中，依序前往「Lambda」>「Functions」>「Create function」。
  2. 按一下「從頭開始撰寫」。

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

    設定 值
    名稱 digital-shadows-collector
    執行階段 Python 3.13
    架構 x86_64
    執行角色 digital-shadows-lambda-role

  4. 建立函式後，開啟「程式碼」分頁，刪除存根並貼上以下程式碼 (digital-shadows-collector.py)。

    import json
import os
import base64
import logging
import time
from datetime import datetime, timedelta, timezone
from urllib.parse import urlencode

import boto3
import urllib3

logger = logging.getLogger()
logger.setLevel(logging.INFO)

HTTP = urllib3.PoolManager(retries=False)

def _basic_auth_header(key: str, secret: str) -> str:
    token = base64.b64encode(f"{key}:{secret}".encode("utf-8")).decode("utf-8")
    return f"Basic {token}"

def _load_state(s3, bucket, key, default_days=30) -> str:
    """Return ISO8601 checkpoint (UTC)."""
    try:
        obj = s3.get_object(Bucket=bucket, Key=key)
        state = json.loads(obj["Body"].read().decode("utf-8"))
        ts = state.get("last_timestamp")
        if ts:
            return ts
    except s3.exceptions.NoSuchKey:
        pass
    except Exception as e:
        logger.warning(f"State read error: {e}")
    return (datetime.now(timezone.utc) - timedelta(days=default_days)).isoformat()

def _save_state(s3, bucket, key, ts: str) -> None:
    s3.put_object(
        Bucket=bucket,
        Key=key,
        Body=json.dumps({"last_timestamp": ts}).encode("utf-8"),
        ContentType="application/json",
    )

def _get_json(url: str, headers: dict, params: dict, backoff_s=2, max_retries=3) -> dict:
    qs = f"?{urlencode(params)}" if params else ""
    for attempt in range(max_retries):
        r = HTTP.request("GET", f"{url}{qs}", headers=headers)
        if r.status == 200:
            return json.loads(r.data.decode("utf-8"))
        if r.status in (429, 500, 502, 503, 504):
            wait = backoff_s * (2 ** attempt)
            logger.warning(f"HTTP {r.status} from DS API, retrying in {wait}s")
            time.sleep(wait)
            continue
        raise RuntimeError(f"DS API error {r.status}: {r.data[:200]}")
    raise RuntimeError("Exceeded retry budget for DS API")

def _collect(api_base, headers, path, since_ts, account_id, page_size, max_pages, time_param):
    items = []
    for page in range(max_pages):
        params = {
            "limit": page_size,
            "offset": page * page_size,
            time_param: since_ts,
        }
        if account_id:
            params["account-id"] = account_id

        data = _get_json(f"{api_base}/{path}", headers, params)
        batch = data.get("items") or data.get("data") or []
        if not batch:
            break
        items.extend(batch)
        if len(batch) < page_size:
            break
    return items

def lambda_handler(event, context):
    # Required
    s3_bucket  = os.environ["S3_BUCKET"]
    api_key    = os.environ["DS_API_KEY"]
    api_secret = os.environ["DS_API_SECRET"]

    # Optional / defaults
    s3_prefix  = os.environ.get("S3_PREFIX", "digital-shadows-searchlight/")
    state_key  = os.environ.get("STATE_KEY", "digital-shadows-searchlight/state.json")
    api_base   = os.environ.get("API_BASE", "https://api.searchlight.app/v1")
    account_id = os.environ.get("DS_ACCOUNT_ID", "")
    page_size  = int(os.environ.get("PAGE_SIZE", "100"))
    max_pages  = int(os.environ.get("MAX_PAGES", "10"))

    s3 = boto3.client("s3")
    last_ts = _load_state(s3, s3_bucket, state_key)
    logger.info(f"Checkpoint: {last_ts}")

    headers = {
        "Authorization": _basic_auth_header(api_key, api_secret),
        "Accept": "application/json",
        "User-Agent": "Chronicle-DigitalShadows-S3/1.0",
    }

    records = []

    # Incidents (time filter often 'published-after' or 'updated-since' depending on tenancy)
    incidents = _collect(api_base, headers, "incidents", last_ts, account_id, page_size, max_pages, time_param="published-after")
    for incident in incidents:
        incident['_source_type'] = 'incident'
    records.extend(incidents)

    # Intelligence incidents (alerts)
    intel_incidents = _collect(api_base, headers, "intel-incidents", last_ts, account_id, page_size, max_pages, time_param="published-after")
    for intel in intel_incidents:
        intel['_source_type'] = 'intelligence_incident'
    records.extend(intel_incidents)

    # Indicators (IOCs)
    indicators = _collect(api_base, headers, "indicators", last_ts, account_id, page_size, max_pages, time_param="lastUpdated-after")
    for indicator in indicators:
        indicator['_source_type'] = 'ioc'
    records.extend(indicators)

    if records:
        # Choose newest timestamp seen in this batch
        newest = max(
            (r.get("updated") or r.get("raised") or r.get("lastUpdated") or last_ts)
            for r in records
        )
        key = f"{s3_prefix}digital_shadows_{datetime.now(timezone.utc).strftime('%Y%m%d_%H%M%S')}.json"
        body = "\n".join(json.dumps(r, separators=(",", ":")) for r in records).encode("utf-8")

        s3.put_object(
            Bucket=s3_bucket,
            Key=key,
            Body=body,
            ContentType="application/x-ndjson",
        )
        _save_state(s3, s3_bucket, state_key, newest)
        msg = f"Wrote {len(records)} records to s3://{s3_bucket}/{key}"
    else:
        msg = "No new records"

    logger.info(msg)
    return {"statusCode": 200, "body": msg}

  5. 依序前往「設定」>「環境變數」。

  6. 依序點選「編輯」> 新增環境變數。

  7. 輸入下表提供的環境變數，並將範例值換成您的值。

    環境變數

    鍵 範例值
    S3_BUCKET digital-shadows-logs
    S3_PREFIX digital-shadows-searchlight/
    STATE_KEY digital-shadows-searchlight/state.json
    DS_API_KEY <your-6-character-api-key>
    DS_API_SECRET <your-32-character-api-secret>
    API_BASE https://api.searchlight.app/v1 (或是https://portal-digitalshadows.com/api/v1)
    DS_ACCOUNT_ID <your-account-id> (大多數房客必須提供)
    PAGE_SIZE 100
    MAX_PAGES 10

  8. 建立函式後，請留在函式頁面 (或依序開啟「Lambda」>「Functions」>「your-function」)。

  9. 選取「設定」分頁標籤。

  10. 在「一般設定」面板中，按一下「編輯」。

  11. 將「Timeout」(逾時間隔) 變更為「5 minutes (300 seconds)」(5 分鐘 (300 秒))，然後按一下「Save」(儲存)。

建立 EventBridge 排程

  1. 依序前往「Amazon EventBridge」>「Scheduler」>「Create schedule」。
  2. 提供下列設定詳細資料：
    • 週期性時間表：費率 (1 hour)。
    • 目標：您的 Lambda 函式 digital-shadows-collector。
    • 名稱：digital-shadows-collector-1h。
  3. 按一下「建立時間表」。

(選用) 為 Google SecOps 建立唯讀 IAM 使用者和金鑰

  1. 前往 AWS 控制台 > IAM > 使用者。
  2. 點選 [Add users] (新增使用者)。
  3. 提供下列設定詳細資料：
    • 使用者：輸入 secops-reader。
    • 存取類型：選取「存取金鑰 - 程式輔助存取」。
  4. 按一下「建立使用者」。
  5. 附加最低讀取權限政策 (自訂)：依序選取「Users」(使用者) >「secops-reader」>「Permissions」(權限) >「Add permissions」(新增權限) >「Attach policies directly」(直接附加政策) >「Create policy」(建立政策)。

  6. JSON：

    {
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["s3:GetObject"],
      "Resource": "arn:aws:s3:::digital-shadows-logs/*"
    },
    {
      "Effect": "Allow",
      "Action": ["s3:ListBucket"],
      "Resource": "arn:aws:s3:::digital-shadows-logs"
    }
  ]
}

  7. Name = secops-reader-policy。

  8. 依序點選「建立政策」> 搜尋/選取 >「下一步」>「新增權限」。

  9. 為 secops-reader 建立存取金鑰：依序點選「安全憑證」> 存取金鑰。

  10. 按一下「建立存取金鑰」。

  11. 下載 .CSV。(您會將這些值貼到動態饋給中)。

在 Google SecOps 中設定資訊提供，擷取 Digital Shadows SearchLight 記錄

  1. 依序前往「SIEM 設定」>「動態饋給」。
  2. 按一下「+ 新增動態消息」。
  3. 在「動態饋給名稱」欄位中輸入動態饋給名稱 (例如 Digital Shadows SearchLight logs)。
  4. 選取「Amazon S3 V2」做為「來源類型」。
  5. 選取「Digital Shadows SearchLight」做為「記錄類型」。
  6. 點選「下一步」。
  7. 指定下列輸入參數的值：
    • S3 URI：s3://digital-shadows-logs/digital-shadows-searchlight/
    • 來源刪除選項：根據偏好設定選取刪除選項。
    • 檔案存在時間上限：包含在過去天數內修改的檔案。預設值為 180 天。
    • 存取金鑰 ID：具有 S3 值區存取權的使用者存取金鑰。
    • 存取密鑰：具有 S3 bucket 存取權的使用者私密金鑰。
    • 資產命名空間：資產命名空間。
    • 擷取標籤：套用至這個動態饋給事件的標籤。
  8. 點選「下一步」。
  9. 在「完成」畫面中檢查新的動態饋給設定，然後按一下「提交」。

還有其他問題嗎？向社群成員和 Google SecOps 專業人員尋求答案。