ClockworkZMP/ioc-enrichment-pipeline

# IOC 富化流水线    一个基于 Python 的威胁情报富化流水线，可将入侵指标 (IOC) 并发分发到多个免费的威胁情报 API，汇总结果，并生成带有风险评分的判定以及结构化的 JSON 输出。 专为需要快速、自动化 IOC 分类且无需购买商业 TIP 的 SOC 分析师和检测工程师而构建。 ## 功能 - **多源富化** — 并发查询 VirusTotal v3、AbuseIPDB v2、AlienVault OTX - **自动 IOC 分类** — 自动检测 IPv4、domain、MD5、SHA1、SHA256 和 URL，无需手动标记 - **综合风险评分** — 跨数据源汇总 0–100 的分数，并给出 CLEAN / SUSPICIOUS / MALICIOUS 的判定 - **彩色终端输出** — 提供人类可读的报告，包含每个 IOC 的信号明细 - **JSON 报告导出** — 结构化输出，适合摄入 SIEM 或工单系统 - **兼容 SOAR/CI** — 如果任何 IOC 被判定为 MALICIOUS，则以代码 `2` 退出；可用于自动化流水线 - **批处理** — 单次运行即可处理文件中的数百个 IOC - **指定数据源** — 使用 `--sources` 仅运行您需要的数据源 ## 支持的 IOC 类型 | 类型 | VirusTotal | AbuseIPDB | OTX | |------|-----------|-----------|-----| | IPv4 | ✅ | ✅ | ✅ | | Domain | ✅ | — | ✅ | | MD5 / SHA1 / SHA256 | ✅ | — | ✅ | | URL | ✅ | — | ✅ | ## 快速开始 ### 1. 克隆并安装 ``` git clone https://github.com/ClockworkZMP/ioc-enrichment-pipeline.git cd ioc-enrichment-pipeline pip install -r requirements.txt ``` ### 2. 配置 API 密钥 以下三个 API 均可免费注册： | 数据源 | 注册 | 免费层级 | |--------|-------------|-----------| | [VirusTotal](https://www.virustotal.com/gui/my-apikey) | 免费账户 | 4 次请求/分钟，500 次/天 | | [AbuseIPDB](https://www.abuseipdb.com/account/api) | 免费账户 | 1,000 次检查/天 | | [AlienVault OTX](https://otx.alienvault.com/api) | 免费账户 | 宽松的限制 | ``` cp .env.example .env # 编辑 .env 并添加你的 keys ``` ### 3. 运行 ``` # Enrich 单个 IOC python ioc_enricher.py --ioc 185.220.101.45 # Enrich 包含多个 IOC 的文件 python ioc_enricher.py -i examples/sample_iocs.txt # 将结果写入 JSON python ioc_enricher.py -i examples/sample_iocs.txt --output report.json # 仅使用特定 sources python ioc_enricher.py --ioc evilcorp.ru --sources vt otx # 禁用颜色（用于 logging/piping） python ioc_enricher.py -i iocs.txt --no-color ``` ## 示例输出 ``` ============================================================ IOC Enrichment Report — 2026-06-13 18:00:00 UTC ============================================================ IOC: 185.220.101.45 Type: ip Score: 87/100 Verdict: MALICIOUS Signals: • VT: 14 malicious engines (14/93) • AbuseIPDB confidence: 100% • AbuseIPDB: 2341 reports from 487 users • AbuseIPDB: Tor exit node • OTX: found in 23 threat pulse(s) • OTX adversary attribution: APT28 • OTX malware families: Cobalt Strike, Emotet ──────────────────────────────────────────────────────────── Summary: 9 IOCs — 2 MALICIOUS | 3 SUSPICIOUS | 4 CLEAN ──────────────────────────────────────────────────────────── ``` 完整 JSON 报告请参见 [`examples/sample_output.json`](examples/sample_output.json)。 ## IOC 文件格式 每行一个 IOC。注释以 `#` 开头。支持混合类型。 ``` # 可疑的 IP 185.220.101.45 45.142.212.100 # Domains evil-c2.ru phishing-bank-login.com # File hashes 44d88612fea8a8f36de82e1278abb02f e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 ``` ## 风险评分 综合分数 (0–100) 根据所有数据源的信号计算得出： | 信号 | 分数贡献 | |--------|-------------------| | VT 恶意引擎命中 | 最高 +60（按比例加权） | | VT 可疑引擎命中 | 最高 +15 | | AbuseIPDB 置信度评分 | 最高 +40（按比例缩放） | | Tor 出口节点标记 | +10 | | OTX pulse 匹配 | 最高 +30 | | OTX 对手归因 | +10 | **判定：** CLEAN (0–34) · SUSPICIOUS (35–69) · MALICIOUS (70–100) ## SOAR 集成 当任何 IOC 被判定为 MALICIOUS 时，该工具会以代码 `2` 退出，使其可以轻松接入自动化流水线： ``` python ioc_enricher.py -i alert_iocs.txt --output enriched.json --no-color if [ $? -eq 2 ]; then # Trigger escalation playbook echo "Malicious IOC detected — escalating" fi ``` JSON 输出可以作为 webhook payload 直接传递给 Tines 或 Torq 等 SOAR 平台。 ## 项目结构 ``` ioc-enrichment-pipeline/ ├── ioc_enricher.py # CLI entrypoint ├── enrichers/ │ ├── virustotal.py # VirusTotal v3 API │ ├── abuseipdb.py # AbuseIPDB v2 API │ └── otx.py # AlienVault OTX API ├── utils/ │ ├── ioc_parser.py # IOC type classification │ └── reporter.py # Risk scoring + output formatting ├── examples/ │ ├── sample_iocs.txt # Sample IOC file │ └── sample_output.json # Sample JSON report ├── .env.example # API key template ├── requirements.txt └── README.md ``` ## 许可证 MIT

标签：IOC富化, Python, 威胁情报, 开发者工具, 文档结构分析, 无后门, 逆向工具