收集 Proofpoint TAP Forensics 記錄

支援的國家/地區：

本文說明如何使用 Google Cloud Storage V2，將 Proofpoint TAP Forensics 記錄檔擷取至 Google Security Operations。

Proofpoint Targeted Attack Protection (TAP) 是一套進階電子郵件安全平台，可偵測、分析及封鎖透過電子郵件傳送的威脅，包括惡意附件和網址。TAP Forensics API 會提供環境中觀察到的個別威脅和活動的詳細鑑識證據，包括沙箱分析結果、行為指標、網路活動、檔案系統變更和程序執行資料。這些鑑識指標可用於確認主機是否遭到入侵、擴充安全情報來源，或協調安全端點的更新。

事前準備

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

  • Google SecOps 執行個體
  • 已啟用 Cloud Storage API 的 GCP 專案
  • 建立及管理 GCS bucket 的權限
  • 建立 Cloud Run 服務、Pub/Sub 主題和 Cloud Scheduler 工作的權限
  • 訂閱 Proofpoint TAP，並取得威脅洞察資訊主頁的存取權
  • TAP API 服務憑證 (服務主體和密鑰)，具備存取 SIEM API 和 Forensics API 的權限

產生 Proofpoint TAP API 服務憑證

  1. 登入 Proofpoint TAP Threat Insight 資訊主頁。
  2. 依序前往「設定」>「已連結的應用程式」>「服務憑證」。
  3. 按一下「建立新憑證」。

  4. 在「Generated Service Credential」(產生的服務憑證) 對話方塊中，複製並安全地儲存下列項目：

    • 服務主體：用於 API 驗證的主體 ID
    • 密鑰：用於 API 驗證的密鑰

驗證 API 存取權

  • 請先測試憑證，再繼續進行整合：

    PRINCIPAL="your-service-principal"
SECRET="your-secret"

# Test SIEM API access (fetch last 5 minutes of events)
curl -s "https://tap-api-v2.proofpoint.com/v2/siem/all?format=json&sinceSeconds=300" \
  --user "${PRINCIPAL}:${SECRET}"

# Test Forensics API access (requires a valid threatId)
# curl -s "https://tap-api-v2.proofpoint.com/v2/forensics?threatId=<threatId>" \
#   --user "${PRINCIPAL}:${SECRET}"

如果 SIEM API 回應成功，會傳回包含 messagesBlocked、messagesDelivered、clicksBlocked 和 clicksPermitted 陣列的 JSON 物件。

  • 如果收到 401 錯誤，請確認服務主體和密碼正確無誤。
  • 如果收到 403 錯誤，請確認帳戶已啟用 TAP API 存取權。

建立 Google Cloud Storage bucket

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

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

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

  6. 點選「建立」。

為 Cloud Run 函式建立服務帳戶

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

建立服務帳戶

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

這些角色適用於：

  • Storage 物件管理員：將鑑識證據資料寫入 GCS 值區，並管理狀態檔案
  • Cloud Run 叫用者：允許 Pub/Sub 叫用函式
  • Cloud Functions 叫用者：允許函式叫用

授予 GCS 值區的 IAM 權限

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

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

建立 Pub/Sub 主題

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

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

建立 Cloud Run 函式來收集鑑識證據

Cloud Run 函式會由 Cloud Scheduler 的 Pub/Sub 訊息觸發，從 Proofpoint TAP SIEM API 擷取威脅事件、使用 Forensics API 擷取每個不重複威脅的鑑識證據，並將結果寫入 GCS。

  1. 前往 GCP Console 的「Cloud Run」。
  2. 按一下「Create service」(建立服務)。
  3. 選取「函式」 (使用內嵌編輯器建立函式)。

  4. 在「設定」部分，提供下列設定詳細資料：

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

  5. 在「Trigger (optional)」(觸發條件 (選用)) 專區：

    1. 按一下「+ 新增觸發條件」。
    2. 選取「Cloud Pub/Sub」。
    3. 在「選取 Cloud Pub/Sub 主題」中，選擇主題 tap-forensics-collector-trigger。
    4. 按一下 [儲存]。

  6. 在「Authentication」(驗證) 部分：

    1. 選取「需要驗證」。
    2. 檢查 Identity and Access Management (IAM)。

  7. 向下捲動並展開「容器」、「網路」和「安全性」。

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

    • 服務帳戶：選取服務帳戶 tap-forensics-collector-sa

  9. 前往「容器」分頁：

    1. 按一下「變數與密鑰」。
    2. 針對每個環境變數，按一下「+ 新增變數」：
    變數名稱 範例值 說明
    GCS_BUCKET proofpoint-tap-forensics-logs GCS bucket 名稱
    GCS_PREFIX tap-forensics 記錄檔的前置字串
    STATE_KEY tap-forensics/state.json 狀態檔案路徑
    TAP_PRINCIPAL your-service-principal TAP API 服務主體
    TAP_SECRET your-secret 輕觸「API 密鑰」
    LOOKBACK_HOURS 1 以小時為單位的初始回溯期 (最多 7 天)
    MAX_THREATS 500 每次執行可擷取鑑識資料的不重複威脅數量上限

  10. 在「變數與密鑰」部分中，向下捲動至「要求」：

    • 要求逾時：輸入 540 秒 (9 分鐘)

  11. 前往「設定」分頁：

    • 在「資源」部分：
      • 記憶體：選取 512 MiB 以上
      • CPU：選取 1

  12. 在「修訂版本資源調度」部分：

    • 執行個體數量下限：輸入 0
    • 執行個體數量上限：輸入 100 (或根據預期負載調整)

  13. 點選「建立」。

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

  15. 服務建立完成後，系統會自動開啟內嵌程式碼編輯器。

新增函式程式碼

  1. 在「進入點」欄位中輸入「main」。

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

    • 第一個檔案 - main.py:

      import functions_framework
from google.cloud import storage
import json
import os
import urllib3
from datetime import datetime, timezone, timedelta
import time
import base64

# Initialize HTTP client with timeouts
http = urllib3.PoolManager(
  timeout=urllib3.Timeout(connect=10.0, read=60.0),
  retries=False,
)

# Initialize Storage client
storage_client = storage.Client()

# Environment variables
GCS_BUCKET = os.environ.get('GCS_BUCKET')
GCS_PREFIX = os.environ.get('GCS_PREFIX', 'tap-forensics').strip('/')
STATE_KEY = os.environ.get('STATE_KEY') or f"{GCS_PREFIX}/state.json"
TAP_PRINCIPAL = os.environ.get('TAP_PRINCIPAL')
TAP_SECRET = os.environ.get('TAP_SECRET')
LOOKBACK_HOURS = int(os.environ.get('LOOKBACK_HOURS', '1'))
MAX_THREATS = int(os.environ.get('MAX_THREATS', '500'))

API_BASE = 'https://tap-api-v2.proofpoint.com'

def get_auth_header():
  """Build HTTP Basic Authentication header."""
  auth_string = f"{TAP_PRINCIPAL}:{TAP_SECRET}"
  auth_bytes = auth_string.encode('utf-8')
  auth_b64 = base64.b64encode(auth_bytes).decode('utf-8')
  return f"Basic {auth_b64}"

@functions_framework.cloud_event
def main(cloud_event):
  """
  Cloud Run function triggered by Pub/Sub to fetch Proofpoint TAP
  forensic evidence and write to GCS.

  The function first queries the SIEM API to discover threat IDs,
  then calls the Forensics API for each unique threat to retrieve
  detailed forensic evidence (sandbox results, behavioral
  indicators, network activity, file changes, and process data).

  Args:
    cloud_event: CloudEvent object containing Pub/Sub message
  """

  if not all([GCS_BUCKET, TAP_PRINCIPAL, TAP_SECRET]):
    print('Error: Missing required environment variables')
    return

  try:
    bucket = storage_client.bucket(GCS_BUCKET)

    # Load state
    state = load_state(bucket, STATE_KEY)

    # Determine time window
    now = datetime.now(timezone.utc)
    last_time = None

    if isinstance(state, dict) and state.get('last_event_time'):
      try:
        last_time = parse_datetime(state['last_event_time'])
        # Overlap by 2 minutes to catch delayed events
        last_time = last_time - timedelta(minutes=2)
      except Exception as e:
        print(f"Warning: Could not parse last_event_time: {e}")

    if last_time is None:
      last_time = now - timedelta(hours=LOOKBACK_HOURS)

    # TAP SIEM API allows max 1 hour per request and max 7 days lookback
    if (now - last_time) > timedelta(days=7):
      last_time = now - timedelta(days=7)
      print("Warning: Lookback capped to 7 days (TAP API limit)")

    print(f"Fetching threats from {last_time.isoformat()} to {now.isoformat()}")

    # Step 1: Fetch threat IDs from the SIEM API
    threat_ids = fetch_threat_ids(last_time, now)

    if not threat_ids:
      print("No threats found in the specified time window.")
      save_state(bucket, STATE_KEY, now.isoformat())
      return

    print(f"Found {len(threat_ids)} unique threat IDs")

    # Step 2: Fetch forensic evidence for each threat
    forensic_records = fetch_forensics_for_threats(threat_ids)

    if not forensic_records:
      print("No forensic evidence retrieved.")
      save_state(bucket, STATE_KEY, now.isoformat())
      return

    # Write to GCS as NDJSON
    timestamp = now.strftime('%Y%m%d_%H%M%S')
    object_key = f"{GCS_PREFIX}/tap_forensics_{timestamp}.ndjson"
    blob = bucket.blob(object_key)

    ndjson = '\n'.join(
      [json.dumps(record, ensure_ascii=False) for record in forensic_records]
    ) + '\n'
    blob.upload_from_string(ndjson, content_type='application/x-ndjson')

    print(f"Wrote {len(forensic_records)} records to gs://{GCS_BUCKET}/{object_key}")

    # Update state
    save_state(bucket, STATE_KEY, now.isoformat())

    print(f"Successfully processed forensics for {len(threat_ids)} threats")

  except Exception as e:
    print(f'Error processing TAP forensics: {str(e)}')
    raise

def load_state(bucket, key):
  """Load state from GCS."""
  try:
    blob = bucket.blob(key)
    if blob.exists():
      state_data = blob.download_as_text()
      return json.loads(state_data)
  except Exception as e:
    print(f"Warning: Could not load state: {e}")
  return {}

def save_state(bucket, key, last_event_time_iso):
  """Save the last event timestamp to GCS state file."""
  try:
    state = {'last_event_time': last_event_time_iso}
    blob = bucket.blob(key)
    blob.upload_from_string(
      json.dumps(state, indent=2),
      content_type='application/json'
    )
    print(f"Saved state: last_event_time={last_event_time_iso}")
  except Exception as e:
    print(f"Warning: Could not save state: {e}")

def parse_datetime(value):
  """Parse ISO datetime string to datetime object."""
  if value.endswith('Z'):
    value = value[:-1] + '+00:00'
  return datetime.fromisoformat(value)

def fetch_threat_ids(start_time, end_time):
  """
  Fetch unique threat IDs from the TAP SIEM API by querying
  in 1-hour intervals within the specified time window.

  Args:
    start_time: Start of the time window (datetime)
    end_time: End of the time window (datetime)

  Returns:
    Set of unique threat ID strings
  """
  headers = {
    'Authorization': get_auth_header(),
    'Accept': 'application/json',
    'User-Agent': 'GoogleSecOps-TAPForensicsCollector/1.0',
  }

  threat_ids = set()
  current_start = start_time
  backoff = 1.0

  while current_start < end_time:
    # TAP SIEM API allows max 1 hour per request
    current_end = min(current_start + timedelta(hours=1), end_time)

    interval = (
      f"{current_start.strftime('%Y-%m-%dT%H:%M:%SZ')}"
      f"/{current_end.strftime('%Y-%m-%dT%H:%M:%SZ')}"
    )
    url = f"{API_BASE}/v2/siem/all?format=json&interval={interval}"

    try:
      response = http.request('GET', url, headers=headers)

      if response.status == 429:
        retry_after = int(
          response.headers.get('Retry-After', str(int(backoff)))
        )
        print(f"Rate limited (429). Retrying after {retry_after}s...")
        time.sleep(retry_after)
        backoff = min(backoff * 2, 60.0)
        continue

      backoff = 1.0

      if response.status != 200:
        print(f"SIEM API HTTP Error: {response.status}")
        response_text = response.data.decode('utf-8')
        print(f"Response body: {response_text[:500]}")
        current_start = current_end
        continue

      data = json.loads(response.data.decode('utf-8'))

      # Extract threat IDs from all event types
      for key in ['messagesBlocked', 'messagesDelivered']:
        for msg in data.get(key, []):
          for threat_info in msg.get('threatsInfoMap', []):
            tid = threat_info.get('threatID')
            if tid:
              threat_ids.add(tid)

      for key in ['clicksBlocked', 'clicksPermitted']:
        for click in data.get(key, []):
          tid = click.get('threatID')
          if tid:
            threat_ids.add(tid)

      event_count = sum(
        len(data.get(k, []))
        for k in [
          'messagesBlocked',
          'messagesDelivered',
          'clicksBlocked',
          'clicksPermitted',
        ]
      )
      print(
        f"Interval {interval}: {event_count} events, "
        f"{len(threat_ids)} unique threats so far"
      )

    except Exception as e:
      print(f"Error fetching SIEM events: {e}")

    current_start = current_end

    if len(threat_ids) >= MAX_THREATS:
      print(f"Reached max threats limit ({MAX_THREATS})")
      break

  return threat_ids

def fetch_forensics_for_threats(threat_ids):
  """
  Fetch forensic evidence for each threat ID from the
  Forensics API.

  Args:
    threat_ids: Set of threat ID strings

  Returns:
    List of forensic report dictionaries
  """
  headers = {
    'Authorization': get_auth_header(),
    'Accept': 'application/json',
    'User-Agent': 'GoogleSecOps-TAPForensicsCollector/1.0',
  }

  records = []
  backoff = 1.0
  processed = 0
  skipped = 0

  for threat_id in list(threat_ids)[:MAX_THREATS]:
    url = (
      f"{API_BASE}/v2/forensics"
      f"?threatId={threat_id}"
      f"&includeCampaignForensics=true"
    )

    try:
      response = http.request('GET', url, headers=headers)

      if response.status == 429:
        retry_after = int(
          response.headers.get('Retry-After', str(int(backoff)))
        )
        print(f"Rate limited (429). Retrying after {retry_after}s...")
        time.sleep(retry_after)
        backoff = min(backoff * 2, 60.0)
        # Retry the same threat
        continue

      backoff = 1.0

      if response.status == 204:
        skipped += 1
        processed += 1
        continue

      if response.status != 200:
        print(
          f"Forensics API error for {threat_id}: "
          f"HTTP {response.status}"
        )
        skipped += 1
        processed += 1
        continue

      data = json.loads(response.data.decode('utf-8'))
      reports = data.get('reports', [])

      if reports:
        # Add the threat ID to each report for correlation
        for report in reports:
          report['_threatId'] = threat_id
        records.extend(reports)

      processed += 1

      if processed % 50 == 0:
        print(
          f"Progress: {processed}/{len(threat_ids)} threats, "
          f"{len(records)} forensic reports collected"
        )

    except Exception as e:
      print(f"Error fetching forensics for {threat_id}: {e}")
      skipped += 1
      processed += 1

  print(
    f"Forensics collection complete: {processed} threats processed, "
    f"{skipped} skipped, {len(records)} reports collected"
  )
  return records

    • 第二個檔案 - requirements.txt:

      functions-framework==3.*
google-cloud-storage==2.*
urllib3>=2.0.0

  3. 點選「部署」即可儲存並部署函式。

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

建立 Cloud Scheduler 工作

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

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

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

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

  4. 點選「建立」。

排程頻率選項

根據記錄檔量和延遲時間要求選擇頻率：

頻率 Cron 運算式 用途
每 15 分鐘 */15 * * * * 威脅數量眾多的高用量環境
每小時 0 * * * * 標準 (建議)
每 6 小時 0 */6 * * * 低流量環境

測試整合項目

  1. 在 Cloud Scheduler 控制台中找出您的工作。
  2. 按一下「強制執行」即可手動觸發工作。
  3. 稍等幾秒鐘。
  4. 前往「Cloud Run」>「Services」。
  5. 按一下函式名稱 tap-forensics-collector。
  6. 按一下 [Logs] (記錄) 分頁標籤。

  7. 確認函式是否已順利執行。請注意以下事項：

    Fetching threats from YYYY-MM-DDTHH:MM:SS+00:00 to YYYY-MM-DDTHH:MM:SS+00:00
Interval .../...: X events, Y unique threats so far
Found Z unique threat IDs
Forensics collection complete: Z threats processed, 0 skipped, N reports collected
Wrote N records to gs://proofpoint-tap-forensics-logs/tap-forensics/tap_forensics_YYYYMMDD_HHMMSS.ndjson
Successfully processed forensics for Z threats

  8. 依序前往「Cloud Storage」>「Buckets」。

  9. 按一下 bucket 名稱。

  10. 前往前置字元資料夾 tap-forensics/。

  11. 確認是否已建立新的 .ndjson 檔案，且檔案名稱包含目前的時間戳記。

如果記錄中顯示錯誤：

  • HTTP 401：檢查環境變數中的 TAP_PRINCIPAL 和 TAP_SECRET。確認服務主體和密碼正確無誤。
  • HTTP 403：確認 TAP 帳戶已啟用 API 存取權。
  • HTTP 429：頻率限制 - 函式會自動重試，並延遲一段時間。建議降低排程頻率。
  • 未發現任何威脅：如果在時間範圍內未偵測到任何威脅，這是正常現象。TAP 只會回報 URL Defense 或附件防禦機制偵測到的威脅。
  • 缺少環境變數：請檢查是否已設定所有必要變數。

在 Google SecOps 中設定動態饋給，擷取 Proofpoint TAP Forensics 記錄

  1. 依序前往「SIEM 設定」>「動態饋給」。
  2. 按一下「新增動態消息」。
  3. 按一下「設定單一動態饋給」。
  4. 在「動態饋給名稱」欄位中輸入動態饋給名稱 (例如 Proofpoint TAP Forensics)。
  5. 選取「Google Cloud Storage V2」做為「來源類型」。
  6. 選取「Proofpoint Tap Forensics」做為「記錄類型」。

  7. 按一下「取得服務帳戶」，系統會顯示專屬服務帳戶電子郵件地址，例如：

    chronicle-12345678@chronicle-gcp-prod.iam.gserviceaccount.com

  8. 複製這個電子郵件地址，以便在下一步中使用。

  9. 點選「下一步」。

  10. 指定下列輸入參數的值：

    • 儲存空間 bucket URL：輸入 GCS bucket URI，並加上前置路徑：

      gs://proofpoint-tap-forensics-logs/tap-forensics/
      • 取代：
        • proofpoint-tap-forensics-logs：您的 GCS bucket 名稱。
        • tap-forensics：儲存記錄的選用前置字元/資料夾路徑 (如為根目錄，請留空)。

    • 來源刪除選項：根據偏好設定選取刪除選項：

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

    • 檔案存在時間上限：包含在過去天數內修改的檔案 (預設為 180 天)

    • 資產命名空間：資產命名空間

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

  11. 點選「下一步」。

  12. 在「Finalize」(完成) 畫面中檢查新的動態饋給設定，然後按一下「Submit」(提交)。

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

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

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

  6. 按一下 [儲存]。

UDM 對應表

記錄欄位 UDM 對應 邏輯
malicious_label additional.fields 已合併
threat_type_label additional.fields 已合併
generated metadata.event_timestamp 剖析為 ISO8601
has_principal metadata.event_type 已對應：true → STATUS_UPDATE
protocol network.ip_protocol 直接對應
prin_ip principal.asset.ip 已合併
domain principal.domain.name 直接對應
path principal.file.full_path 直接對應
file_hash_sha256 principal.file.sha256 直接對應
prin_ip principal.ip 已合併
port principal.port 直接對應
url principal.url 直接對應
_security_result security_result 已合併
不適用 metadata.event_type 常數：STATUS_UPDATE
不適用 metadata.product_event_type 常數：Forensic Reports
不適用 metadata.product_name 常數：TAP Forensics
不適用 metadata.vendor_name 常數：Proofpoint
不適用 principal.asset.platform_software.platform 常數：WINDOWS

變更記錄

查看這個剖析器的變更記錄

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