holmes-ai/ioc-extractor

# IOC 提取器 [](https://github.com/yourname/ioc-extractor/actions/workflows/ci.yml) [](LICENSE) [](pyproject.toml) 从非结构化文本（威胁报告、网络钓鱼电子邮件、粘贴内容、日志摘录）中提取、验证、处理防篡改（defang-aware）的标准化，并导出**入侵指标**，输出为 JSON、CSV 或轻量级 STIX 2.1 bundle，以便下游 SIEM/TIP 系统摄取。 这是一个**防御性、只读**的分析工具。它从不会主动获取 URL、执行 payload 或执行任何网络操作——它仅解析您提供的文本。  ## 为什么需要这个工具 分析师经常需要手动从 PDF 报告和供应商博客中复制粘贴 IOC。此工具可自动完成这第一步的分诊工作：找到每个候选指标，将其还原（refang）为标准形式，验证其不是误报（如版本号字符串、不可路由的 IP、格式错误的 CVE ID），进行去重，并为您提供可直接用于黑名单或导入 TIP 的结构化输出。 ## 支持的指标类型 | 类型 | 示例 | |---|---| | IPv4 / IPv6 | `8.8.8.8`，防篡改形式 `8[.]8[.]8[.]8` | | 域名 | `evil-corp.xyz` | | URL | `hxxps://evil-corp[.]xyz/drop/payload.exe` | | 电子邮件 | `attacker[at]protonmail[.]com` | | MD5 / SHA1 / SHA256 / SHA512 | 文件哈希 | | CVE | `CVE-2023-4863` | | 比特币地址 | `1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa` | | 文件路径 | Windows 和 POSIX 路径 | ## 安装 ``` pip install ioc-extractor ``` 或从源码安装： ``` git clone https://github.com/yourname/ioc-extractor.git cd ioc-extractor pip install -e ".[dev]" ``` ## 用法 ### CLI ``` # 扫描文件，输出 JSON 到 stdout ioc-extractor examples/sample_report.txt # 输出 CSV 到文件 ioc-extractor report.txt -f csv -o iocs.csv # 输出 STIX 2.1 bundle ioc-extractor report.txt -f stix # 从 stdin 读取 cat report.txt | ioc-extractor ``` ### 作为库使用 ``` from ioc_extractor import extract result = extract(open("report.txt").read()) print(result.summary()) # {'ipv4': 3, 'domain': 5, ...} print(result.by_type("domain")) # list of IOC objects ``` 请参阅 [`examples/extract_example.py`](examples/extract_example.py)，其中包含针对 [`examples/sample_report.txt`](examples/sample_report.txt) 的完整操作演示。 ### Docker ``` docker build -t ioc-extractor . cat report.txt | docker run -i ioc-extractor ``` ## 架构 有关完整的设计文档，请参阅 [`docs/architecture.md`](docs/architecture.md)。简而言之：`core`（纯领域逻辑）→ `io`（文件/stdin 读取器，JSON/CSV/STIX 写入器）→ `cli`（组合根）。核心部分具有零依赖和零 I/O，这使得它能够进行穷尽式的单元测试。 ``` src/ioc_extractor/ ├── core/ │ ├── models.py # IOC, IOCType, ExtractionResult │ ├── patterns.py # regex registry per IOC type │ ├── defanging.py # detect + reverse analyst defanging notation │ ├── validators.py # false-positive filtering │ └── extractor.py # orchestration: match → refang → validate → dedupe ├── io/ │ ├── readers.py # file / stdin adapters │ └── writers.py # JSON / CSV / STIX-lite adapters └── cli.py # argparse entry point (composition root) ``` ## 开发 ``` pip install -e ".[dev]" pre-commit install ruff check src tests black --check src tests mypy src pytest ``` ## 安全 有关如何报告漏洞，请参阅 [SECURITY.md](SECURITY.md)。 ## 已知限制 - **比特币地址未经过 Base58Check 校验和验证。** `btc_address` 模式可匹配正确的字符集和长度范围，但不会验证校验和，因此看起来格式正确但实际无效的地址仍可能会被报告。请将其视为候选对象，而非已确认的钱包。 - **文件完全在内存中处理。** `extract()` 将整个文档作为单个字符串接收；目前没有流式传输/分块模式。这对于常规的报告和日志摘录没有问题，但在扫描非常大的输入（几百 MB 以上）之前应将其拆分。 - **日志被刻意保持在最低限度。** 此工具遵循 Unix 管道惯例：stdout 专用于输出数据，且设计上不提供详细/调试日志输出，因此它可以与 `|`、`>` 和其他 CLI 工具完美组合，而不会产生多余的干扰信息。 ## 路线图 / 未来改进 - [ ] 可插拔的模式包（特定行业的 IOC 类型） - [ ] 每个指标的置信度评分（共现性、上下文关键词） - [ ] MISP event 导出格式 - [ ] 用于扫描大型报告语料库的异步批处理模式 - [ ] 可选的丰富性钩子（仅限离线的白名单检查） ## 许可证 MIT — 详见 [LICENSE](LICENSE)。

标签：IOC提取, Python, 威胁情报, 开发者工具, 文本解析, 无后门, 请求拦截, 逆向工具, 防御框架