dronzzer/ioc-enrichment

# IOC 情报富化工具 一款专为 SOC 分析师设计的自动化失陷标示符 (IOC) 情报富化工具——支持针对多个威胁情报源检查 IP、域名和文件哈希，并返回综合判定结果，免去在多个浏览器标签页中手动逐一查询的繁琐。 包含 CLI 和桌面 GUI，并支持批量输入。 ## 面临的问题 在告警分诊期间，通常需要将每个 IOC（IP、域名、文件哈希）放到多个情报源中进行核查，以确定其是否恶意： - VirusTotal — 多引擎信誉扫描 - AbuseIPDB — 滥用举报历史（仅限 IP） - Shodan — 暴露的服务、开放端口、已知漏洞（仅限 IP） 针对每个工单中的每一个 IOC 手动执行此操作会大幅增加工作量，尤其是当单个告警同时包含多个 IOC 时。本工具将所有这些操作整合为一次查询，并支持一次性批量检查多个 IOC。 ## 功能说明 1. **自动检测 IOC 类型** — IP、域名或文件哈希 (MD5/SHA1/SHA256) 2. **处理防脱敏 IOC** — 自动将复制粘贴的报告格式（如 `1[.]2[.]3[.]4`、`evil[.]example[.]com` 或 `hxxp://` URL）还原为可查询的格式 3. **将每个 IOC 路由至对应的情报源：** | IOC 类型 | 查询情报源 | |---|---| | IP | VirusTotal + AbuseIPDB + Shodan | | Domain | VirusTotal（+ 解析的 IP）+ Shodan（针对解析出的 IP） | | File Hash | 仅 VirusTotal | 4. **将结果汇总为一个判定结论** — `Malicious` (恶意) / `Suspicious` (可疑) / `Clean` (干净) / `Unknown` (未知)，并附上详细的判定理由 5. **自动遵守 VirusTotal 免费层级的速率限制** (自动调整请求频率以确保低于 4次/分钟 — 无需手动等待) 6. **同时输出快速扫描摘要和每个情报源的详细分解报告** 7. **按需导出为 CSV**，方便附加到工单或报告中 ## 输出示例 ``` ============================================================ SUMMARY ============================================================ IOC Type Verdict Confidence ---------------------------------------------------------------------- 108.89.40.247 ip Suspicious Medium festung-e.duckdns.org domain Malicious High ============================================================ ──────────────────────────────────────────────────────────── 108.89.40.247 (IP) → Suspicious (Medium confidence) ──────────────────────────────────────────────────────────── VirusTotal: Malicious: 2 Suspicious: 1 Harmless: 78 Undetected: 9 Reputation: -5 Link: https://www.virustotal.com/gui/ip-address/108.89.40.247 AbuseIPDB: Abuse Confidence: 15% Total Reports: 4 Whitelisted: No Country: US ISP: Some Hosting Co Link: https://www.abuseipdb.com/check/108.89.40.247 Shodan: Not available (no query credits) Reasons: - VirusTotal: 2 engine(s) flagged as malicious - AbuseIPDB: abuse confidence score 15% ──────────────────────────────────────────────────────────── ``` ## 设置说明 ``` git clone https://github.com/yourusername/ioc-enrichment cd ioc-enrichment python -m venv venv venv\Scripts\activate # Windows # source venv/bin/activate # macOS/Linux pip install -r requirements.txt cp .env.example .env # Then fill in your own keys — see below ``` ### 所需的 API 密钥（均为免费层级） | 密钥 | 获取地址 | 备注 | |---|---|---| | `VT_API_KEY` | https://www.virustotal.com (Profile → API Key) | 免费层级：4 次请求/分钟，500 次/天 | | `ABUSEIPDB_API_KEY` | https://www.abuseipdb.com (Account → API) | 免费层级：1000 次检查/天 | | `SHODAN_API_KEY` | https://account.shodan.io | 免费层级限制不一 — 详见下文备注 | **切勿提交真实的 `.env` 文件。** Git 中应仅追踪包含占位符值的 `.env.example`。 ## 使用说明 ### CLI ``` python main.py ``` 根据提示粘贴一个或多个 IOC（每行一个，或以逗号/空格分隔），然后在空行处按 Enter 键运行。 ### GUI ``` python gui_app.py ``` GUI 提供： - 一个多行粘贴框，用于输入单个或批量 IOC - 结果表会随着每个 IOC 检测完成而实时填充（由于 VT 的速率控制，批量检查速度较慢，此功能非常实用） - 颜色编码的判定结果（红色 = Malicious，橙色 = Suspicious，绿色 = Clean，灰色 = Unknown） - 点击任意行即可查看其完整的按情报源的详细分解 - 一键导出 CSV ### 独立可执行文件 将 GUI 打包为 Windows `.exe`： ``` pip install pyinstaller pyinstaller --onefile --windowed --name "IOC-Enrichment" gui_app.py ``` 将您的 `.env` 文件放置在生成的 `dist/IOC-Enrichment.exe` 旁边——它并不会被打包进二进制文件中。 ## 架构 ``` Raw IOC Input (single or bulk paste) │ ▼ IOC Detector (refang + classify: IP / domain / hash) │ ├── IP ─────────► VirusTotal + AbuseIPDB + Shodan │ ├── Domain ─────► VirusTotal (resolves IP) ─► Shodan (on resolved IP) │ └── Hash ───────► VirusTotal only │ ▼ Verdict Engine (consolidates signals into one verdict) │ ▼ Summary Table + Detailed Per-Source Breakdown │ ▼ CSV Export (optional) ``` ## 项目结构 ``` ioc-enrichment/ ├── main.py # CLI entry point ├── gui_app.py # Tkinter GUI (reuses main.py's pipeline functions) ├── config.py # Loads API keys from .env ├── requirements.txt ├── .env.example # Template — copy to .env and fill in your own keys │ ├── modules/ │ ├── ioc_detector.py # Refangs and classifies raw input as IP/domain/hash │ ├── vt_checker.py # VirusTotal queries with automatic rate-limit pacing │ ├── abuseipdb_checker.py # AbuseIPDB IP reputation queries │ ├── shodan_checker.py # Shodan host lookups (open ports, services, vulns) │ └── verdict_engine.py # Consolidates all sources into one verdict │ └── output/reports/ # CSV exports land here — gitignored ``` ## 安全说明 - `.env` 已在 `.gitignore` 中列出，且从不被追踪 - 仅提交了包含占位符值的 `.env.example` - 所有 API 密钥均通过 `python-dotenv` 在运行时加载 - 如果您复刻或克隆本项目，必须提供自己的密钥——代码中绝不会硬编码任何密钥 - 如果真实密钥被意外泄露（例如粘贴到了公开场合），请**立即撤销并重新生成密钥**——在后续的 commit 中将其删除并不能将其从 Git 历史记录中抹去 ## 设计说明 如果您打算扩展此项目，以下是一些值得了解的刻意设计决定： - **VirusTotal 限速是自动且全局的** — 整个运行过程中的每次调用都遵守相同的最小 16 秒间隔，因此批量查询本身会比较耗时，但绝不会触发 429 错误。 - **Shodan 的数据是上下文参考性的，不直接决定判定结果** — 主机上的开放端口甚至已知的 CVE 本身并不能证明其具有恶意意图。因此，Shodan 的发现结果仅出现在详细分解和判定理由中，绝不会独立地将最终判定结论更改为 Malicious。 - **AbuseIPDB 的白名单状态会覆盖微弱/嘈杂的信号** — 如果 AbuseIPDB 确认某个 IP 已被列入白名单，那么来自其他来源的轻微矛盾警告将从显示的判定理由中剔除，而不会与“Clean”的判定结果并列显示，否则看起来会自相矛盾。 ## 路线图 - [ ] 解决导致无法完全访问 Shodan 的潜在账户/套餐问题 - [ ] 可选的缓存层，以避免在短时间窗口内重复查询同一个 IOC - [ ] 导出为格式化的 Markdown/HTML 报告（类似于 KEV Investigator 的输出），以便直接作为附件添加到工单中 - [ ] 当 VirusTotal 没有缓存解析记录时，通过 DNS 后备机制进行批量域名 → IP 解析 ## 许可证 MIT — 随意使用、复刻，或将其改编以适用于您自己的 SOC 工作流。

标签：威胁情报, 安全运营, 开发者工具, 扫描框架, 攻击指标, 漏洞挖掘, 自动化分析, 跨站脚本, 逆向工具, 防御判断