收集 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 存储分区的权限
  • 创建 Cloud Run 服务、Pub/Sub 主题和 Cloud Scheduler 作业的权限
  • 订阅了 Proofpoint TAP 并可访问“威胁洞察信息中心”
  • 具有访问 SIEM API 和 Forensics API 权限的 TAP API 服务凭据（服务正文和密钥）

生成 Proofpoint TAP API 服务凭据

  1. 登录 Proofpoint TAP 威胁洞察信息中心。
  2. 依次前往设置 > 已关联的应用 > 服务凭据。
  3. 点击创建新凭据。

  4. 在生成的服务凭据对话框中，复制并安全存储以下信息：

    • 服务正文：用于 API 身份验证的正文标识符
    • Secret：用于 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 响应会返回一个 JSON 对象，其中包含 messagesBlocked、messagesDelivered、clicksBlocked 和 clicksPermitted 数组。

  • 如果您收到 401 错误，请验证您的服务正文和密钥是否正确。
  • 如果您收到 403 错误，请确认您的账号已启用 TAP API 访问权限。

创建 Google Cloud Storage 存储桶

  1. 前往 Google Cloud 控制台。
  2. 选择您的项目或创建新项目。
  3. 在导航菜单中，依次前往 Cloud Storage > 存储分区。
  4. 点击创建存储分区。

  5. 提供以下配置详细信息：

    设置 值
    为存储桶命名 输入一个全局唯一的名称（例如 proofpoint-tap-forensics-logs）
    位置类型 根据您的需求进行选择（区域级、双区域、多区域）
    位置 选择营业地点（例如 us-central1）
    存储类别 标准（建议用于经常访问的日志）
    访问权限控制 均匀（推荐）
    保护工具 可选：启用对象版本控制或保留政策

  6. 点击创建。

为 Cloud Run 函数创建服务账号

Cloud Run 函数需要一个服务账号，该账号具有写入 GCS 存储桶的权限，并且可以由 Pub/Sub 调用。

创建服务账号

  1. 在 GCP 控制台中，依次前往 IAM 和管理 > 服务账号。
  2. 点击创建服务账号。
  3. 提供以下配置详细信息：
    • 服务账号名称：输入 tap-forensics-collector-sa
    • 服务账号说明：输入 Service account for Cloud Run function to collect Proofpoint TAP Forensics logs
  4. 点击创建并继续。
  5. 在向此服务账号授予对项目的访问权限部分中，添加以下角色：
    1. 点击选择角色。
    2. 搜索并选择 Storage Object Admin。
    3. 点击 + 添加其他角色。
    4. 搜索并选择 Cloud Run Invoker。
    5. 点击 + 添加其他角色。
    6. 搜索并选择 Cloud Functions Invoker。
  6. 点击继续。
  7. 点击完成。

必须拥有这些角色，才能：

  • Storage Object Admin：将取证证据数据写入 GCS 存储桶并管理状态文件
  • Cloud Run Invoker：允许 Pub/Sub 调用函数
  • Cloud Functions Invoker：允许调用函数

授予对 GCS 存储桶的 IAM 权限

向服务账号授予对 GCS 存储桶的写入权限：

  1. 前往 Cloud Storage > 存储分区。
  2. 点击您的存储桶名称。
  3. 前往权限标签页。
  4. 点击授予访问权限。
  5. 提供以下配置详细信息：
    • 添加主账号：输入服务账号电子邮件地址（例如 tap-forensics-collector-sa@PROJECT_ID.iam.gserviceaccount.com）
    • 分配角色：选择 Storage Object Admin
  6. 点击保存。

创建 Pub/Sub 主题

创建一个 Pub/Sub 主题，Cloud Scheduler 将向该主题发布消息，而 Cloud Run 函数将订阅该主题。

  1. 在 GCP 控制台中，前往 Pub/Sub > 主题。
  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 控制台中，前往 Cloud Run。
  2. 点击创建服务。
  3. 选择函数（使用内嵌编辑器创建函数）。

  4. 在配置部分中，提供以下配置详细信息：

    设置 值
    Service 名称 tap-forensics-collector
    区域 选择与您的 GCS 存储桶匹配的区域（例如 us-central1）
    运行时 选择 Python 3.12 或更高版本

  5. 在触发器（可选）部分中：

    1. 点击 + 添加触发器。
    2. 选择 Cloud Pub/Sub。
    3. 在选择 Cloud Pub/Sub 主题部分，选择主题 tap-forensics-collector-trigger。
    4. 点击保存。

  6. 在身份验证部分中：

    1. 选择需要进行身份验证。
    2. 检查 Identity and Access Management (IAM)。

  7. 向下滚动并展开容器、网络、安全性。

  8. 前往安全性标签页：

    • 服务账号：选择服务账号 tap-forensics-collector-sa

  9. 前往容器标签页：

    1. 点击变量和密钥。
    2. 为每个环境变量点击+ 添加变量：
    变量名称 示例值 说明
    GCS_BUCKET proofpoint-tap-forensics-logs GCS 存储桶名称
    GCS_PREFIX tap-forensics 日志文件的前缀
    STATE_KEY tap-forensics/state.json 状态文件路径
    TAP_PRINCIPAL your-service-principal TAP API 服务正文
    TAP_SECRET your-secret TAP API Secret
    LOOKBACK_HOURS 1 初始回溯期（以小时为单位，最长 7 天）
    MAX_THREATS 500 每次运行可获取取证数据的唯一威胁数量上限

  10. 在变量和 Secret 部分中，向下滚动到请求：

    • 请求超时：输入 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 Console 中，前往 Cloud Scheduler。
  2. 点击创建作业。

  3. 提供以下配置详细信息：

    设置 值
    名称 tap-forensics-collector-hourly
    区域 选择与 Cloud Run 函数相同的区域
    频率 0 * * * *（每小时一次，整点时）
    时区 选择时区（建议选择世界协调时间 [UTC]）
    目标类型 Pub/Sub
    主题 选择主题 tap-forensics-collector-trigger
    消息正文 {}（空 JSON 对象）

  4. 点击创建。

时间表频率选项

根据日志量和延迟时间要求选择频次：

频率 Cron 表达式 使用场景
每隔 15 分钟 */15 * * * * 威胁数量较多的高流量环境
每小时 0 * * * * 标准（推荐）
每 6 小时 0 */6 * * * 低容量环境

测试集成

  1. 在 Cloud Scheduler 控制台中，找到您的作业。
  2. 点击强制运行以手动触发作业。
  3. 等待几秒钟。
  4. 前往 Cloud Run > 服务。
  5. 点击函数名称 tap-forensics-collector。
  6. 点击日志标签页。

  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 > 存储分区。

  9. 点击您的存储桶名称。

  10. 前往前缀文件夹 tap-forensics/。

  11. 验证是否已创建具有当前时间戳的新 .ndjson 文件。

如果您在日志中看到错误，请执行以下操作：

  • HTTP 401：检查环境变量中的 TAP_PRINCIPAL 和 TAP_SECRET。验证服务正文和密钥是否正确。
  • HTTP 403：确认您的 TAP 账号已启用 API 访问权限。
  • HTTP 429：速率限制 - 函数将自动重试并进行退避。请考虑降低调度频率。
  • 未发现任何威胁：如果在时间范围内未检测到任何威胁，这是正常现象。TAP 仅报告由 网址 Defense 或 Attachment Defense 识别的威胁。
  • 缺少环境变量：检查是否已设置所有必需的变量。

在 Google SecOps 中配置 Feed 以注入 Proofpoint TAP Forensics 日志

  1. 依次前往 SIEM 设置 > Feed。
  2. 点击添加新 Feed。
  3. 点击配置单个 Feed。
  4. 在 Feed 名称字段中，输入 Feed 的名称（例如 Proofpoint TAP Forensics）。
  5. 选择 Google Cloud Storage V2 作为来源类型。
  6. 选择 Proofpoint Tap Forensics 作为日志类型。

  7. 点击获取服务账号。系统会显示一个唯一的服务账号电子邮件地址，例如：

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

  8. 复制此电子邮件地址，以便在下一步中使用。

  9. 点击下一步。

  10. 为以下输入参数指定值：

    • 存储桶网址：输入带有前缀路径的 GCS 存储桶 URI：

      gs://proofpoint-tap-forensics-logs/tap-forensics/
      • 替换：
        • proofpoint-tap-forensics-logs：您的 GCS 存储桶名称。
        • tap-forensics：存储日志的可选前缀/文件夹路径（留空表示根目录）。

    • 来源删除选项：根据您的偏好选择删除选项：

      • 永不：转移后永不删除任何文件（建议用于测试）。
      • 删除已转移的文件：在成功转移后删除文件。
      • 删除已转移的文件和空目录：成功转移后删除文件和空目录。

    • 文件存在时间上限：包含在过去指定天数内修改的文件（默认值为 180 天）

    • 资产命名空间：资产命名空间

    • 注入标签：要应用于此 Feed 中事件的标签

  11. 点击下一步。

  12. 在最终确定界面中查看新的 Feed 配置，然后点击提交。

向 Google SecOps 服务账号授予 IAM 权限

Google SecOps 服务账号需要您的 GCS 存储桶的 Storage Object Viewer 角色。

  1. 前往 Cloud Storage > 存储分区。
  2. 点击您的存储桶名称。
  3. 前往权限标签页。
  4. 点击授予访问权限。
  5. 提供以下配置详细信息：
    • 添加主账号：粘贴 Google SecOps 服务账号电子邮件地址
    • 分配角色：选择 Storage Object Viewer

  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 专业人士的解答。