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 地理位置和邮件头分析的裁定结论。

## 预期输出

```json
{
  "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"
  }
}
```