implementing-soar-playbook-for-phishing

概述

本技能使用 Splunk SOAR（原 Phantom）REST API 实现网络钓鱼（phishing）事件响应工作流。当举报一封疑似钓鱼邮件时，Agent 会解析邮件头和正文，创建代表事件的 SOAR 容器（container），附加包含失陷指标（Indicator of Compromise，IOC）的制品（artifact，含发件人地址、URL、IP 地址和文件哈希），触发自动化调查剧本（playbook），并轮询动作执行结果。

Splunk SOAR 通过将调查和响应动作链接成剧本来编排并自动化安全运营。/rest/container、/rest/artifact 和 /rest/playbook_run REST API 支持从外部工具、邮件网关和 SIEM 告警中以编程方式创建事件并触发自动化。

前置条件

• Python 3.9 及以上版本，包含 requests 和 email 模块
• 已启用 REST API 访问的 Splunk SOAR 实例（云端或本地部署）
• 具备创建容器和触发剧本权限的 SOAR API 令牌
• 可访问 SOAR 实例 443 端口的网络连接
• 已在 SOAR 中配置好网络钓鱼调查剧本

步骤

1. 解析钓鱼邮件：读取邮件文件（.eml 格式），提取邮件头，包括 From、To、Subject、Reply-To、Return-Path、Received、Message-ID、X-Mailer 以及认证结果（SPF、DKIM、DMARC）。从邮件正文中提取 URL 和 IP 地址。

2. 向 SOAR REST API 认证：在所有 REST API 请求中通过 ph-auth-token 请求头使用 API 令牌进行身份验证。

3. 创建容器：向 /rest/container 发送 POST 请求，携带事件标签、名称、描述、严重级别和状态。容器代表钓鱼事件，响应中会返回容器 ID。

4. 添加邮件头制品：向 /rest/artifact 发送 POST 请求，携带 container_id 和 CEF（Common Event Format，通用事件格式）字段，包含发件人地址（fromAddress）、收件人（toAddress）、主题、来源 IP（sourceAddress）和 Message-ID。除最后一个制品外，其余均将 run_automation 设为 False。

5. 添加 URL 制品：对从邮件正文中提取的每个 URL，创建包含 CEF 字段 requestURL 且类型为 url 的制品。这些制品将作为剧本中 URL 信誉检查的输入。

6. 触发剧本：向 /rest/playbook_run 发送 POST 请求，携带剧本 ID 或名称及容器 ID，启动自动化调查工作流。

7. 轮询动作结果：通过容器 ID 过滤 GET /rest/action_run，监控剧本执行进度，直到所有动作达到终态（成功、失败或已取消）。

8. 汇总响应报告：将剧本动作结果汇总为摘要报告，包含来自 URL 信誉、域名信誉、IP 地理位置和邮件头分析的裁定结论。

预期输出

{
  "incident": {
    "container_id": 1542,
    "status": "new",
    "severity": "high",
    "artifacts_created": 5
  },
  "playbook": {
    "name": "phishing_investigate",
    "run_id": 892,
    "status": "success",
    "actions_completed": 8
  },
  "verdict": "malicious",
  "indicators": {
    "sender_domain_reputation": "malicious",
    "urls_flagged": 2,
    "spf_result": "fail",
    "dkim_result": "fail"
  }
}