cyb3rkan/soar-ioc-enrichment-playbook

# SOAR — IOC 富集 Playbook 为 Microsoft Sentinel 开发的 IOC 富集 playbook 的 **n8n 已验证参考实现**。 与其在 Logic Apps 上直接进行试错，不如先在一个可运行的 prototype 上验证决策流/错误处理/输出 schema。本 repo 包含该 prototype、测试集以及设计决策。 ## 它的功能 接收来自 Sentinel incident webhook 的 indicator (IOC)，根据其类型进行验证，使用外部威胁情报进行富集，并生成标准化的结果。 ``` Webhook → Config → IOC ayrıştırma → Tip tespiti → Normalizasyon → Doğrulama → Zenginleştirme (AbuseIPDB / VirusTotal) → Risk değerlendirme → SOC bildirimi | Incident yorumu → Tek çıktı şeması ``` | 字段 | 范围 | |---|---| | 支持的 IOC 类型 | IP (v4/v6)、域名、URL、文件 hash (MD5/SHA-1/SHA-256) | | 提供商 | AbuseIPDB (IP)、VirusTotal (域名 / URL / hash) | | 风险级别 | HIGH · MEDIUM · LOW · UNKNOWN | | 状态码 | `SUCCESS` · `INVALID_IOC` · `NON_ROUTABLE_IOC` · `UNSUPPORTED_IOC` · `MISSING_REQUIRED_FIELD` · `AUTHENTICATION_ERROR` · `NOT_FOUND` · `RATE_LIMITED` · `PROVIDER_TIMEOUT` · `PROVIDER_UNAVAILABLE` · `ENRICHMENT_ERROR` | ## 设计原则 **单一输出契约** — 成功、错误、无效和不受支持的分支都在同一个不可变 schema 中汇合。没有任何场景会在不给分析师留下记录的情况下结束。 **先标准化，后验证** — 每个 IOC 都在单个节点进行标准化（在大小写不敏感的字段中使用小写字母、清理空格/根点、URL 规范化、提取凭据），然后再进行验证。可疑输入不会被修复，而是被拒绝。 **未经验证的 indicator 不对外输出** — 任何未通过格式验证的值都不会发送给提供商。 **范围控制** — RFC1918 私有地址、loopback、link-local（包括云 metadata）、CGNAT 和内部命名空间（`.local`、`.lan`、`.corp` …）免受外部情报查询；它们会被标记为 `NON_ROUTABLE_IOC` 并路由到内部 telemetry。内部网络地址不会泄露给第三方。 **错误分类** — 提供商错误根据 HTTP 状态分为六个类别；分析师可以区分身份验证失败与真正的“无记录”结果。 **关联分析** — 每次运行都标记有唯一的 `workflowRunId` 和 `processingTime`。 ## 示例 **请求** ``` { "incidentName": "Suspicious Outbound Connection", "severity": "High", "hostname": "WS-FIN-014", "source": "Microsoft Sentinel", "iocType": "ip", "iocValue": "185.220.101.1" } ``` **响应** ``` { "incidentName": "Suspicious Outbound Connection", "iocType": "IP", "iocValue": "185.220.101.1", "provider": "AbuseIPDB", "riskLevel": "HIGH", "riskScore": 100, "status": "SUCCESS", "actionTaken": "SOC_NOTIFICATION_DISPATCHED", "message": "High risk IP detected. SOC notification dispatched.", "detectionSummary": "Score: 100/100 | Reports: 172 | Country: DE | ISP: Artikel10 e.V.", "errorCode": null, "severity": "High", "hostname": "WS-FIN-014", "source": "Microsoft Sentinel", "timestamp": "2026-07-23T08:23:59.212Z", "workflowRunId": "run-177-1784795036286", "processingTime": 2926, "playbookVersion": "1.3.1" } ``` 在提交多个 IOC（`iocs: [...]`）时，响应将返回 `totalIocs`、`highestRiskLevel`、`statusCounts` 和 `results[]` 字段。 ## 测试 11 个类别的自动回归测试集：功能流、标准化、范围控制、边界值、路由、错误分类、注入攻击、payload 鲁棒性、幂等性、并发、关联分析。 ``` .\tests\Test-Playbook-Full.ps1 # tam koşu .\tests\Test-Playbook-Full.ps1 -SkipProvider # API'ye gitmeyen testler ``` 每个响应不仅针对预期的 `status` 进行验证，还针对 12 条不可变规则（schema 完整性、字段一致性、版本匹配）进行验证。 ## 安装说明 1. n8n → **Import from File** → `workflow/soar-ioc-enrichment-v1.3.1.json` 2. **Credentials** → 创建两个 *Header Auth*： - `VirusTotal API` → Name: `x-apikey` - `AbuseIPDB API` → Name: `Key` 3. 在四个 HTTP node 上选择相应的 credential，并绑定 SMTP credential 4. 在 `Load Configuration` node 中编辑 `socEmail` / `fromEmail` 值 5. 发布 Workflow ## 路线图 - [x] IOC 类型检测与路由 - [x] 标准化与格式验证层 - [x] 错误分类（6 类） - [x] 范围控制（IP / 域名 / URL） - [x] Medium 风险等级 - [x] 多 IOC 支持 - [ ] 迁移至 Microsoft Sentinel / Logic Apps - [ ] 自动向 incident 写入评论和标签 ## 注意事项 这是一个 prototype 和设计验证工作；在投入生产环境之前，必须添加 webhook 身份验证、密钥管理和企业审批流程。

标签：AI合规, IOC富化, Libemu, Microsoft Sentinel, n8n, SOAR, 威胁情报, 开发者工具