bohansec/ioc-enrichment-pipeline
GitHub: bohansec/ioc-enrichment-pipeline
一个面向 SOC 的 IOC 威胁情报富化流水线，通过聚合多源情报并应用风险评分模型，为安全分析师生成可操作的安全洞察。
Stars: 1 | Forks: 0
# IOC 威胁情报富化流水线
一个**面向 SOC 的 IOC 威胁情报富化流水线**，从多个来源聚合威胁情报，为分析师生成可操作的安全洞察。现已支持**本地 AI 驱动的威胁摘要（通过 Ollama 使用 Llama3）**
该工具使用 **VirusTotal** 和 **ThreatFox** 等外部情报来源对妥协指标 (IOC) 进行富化，应用启发式评分，并为调查工作流程生成结构化分析。
专为**SOC 分析师和威胁情报调查**设计。
# 演示
该工具提供**SOC 风格的终端界面**，包括：
* ASCII 横幅启动
* 颜色编码的 IOC 严重级别
* 恶意软件家族归因
* IOC 处理进度条
* 风险评分可见性
* 🔥 AI 生成的威胁摘要（新增）
控制台输出示例：
```
IOC ENRICH
Threat Intelligence Enrichment Tool
Author: Bohan Zhang
[01/06] 42.238.136.98 Low (score=19.47)
[02/06] 113.236.243.32 Low (score=19.15)
[03/06] 123.9.101.216 Low (score=18.51)
[04/06] a1575e3c71357ccdfbf673eed389b2a70a775560e35db0d8222169f14f7a7675 High (score=66.77) LummaStealer
[05/06] sit-v1.savingssit.in.net Medium (score=34.15)
[06/06] 4c9d9e12a691c67939525cfbd4bd416ee027602113dd8159e847aaaab9dbd6de Critical (score=90.0) AsyncRAT
Processing IoCs... 100%
```
# 功能
* 使用 **VirusTotal API** 进行 IOC 富化
* **ThreatFox 情报集成**用于恶意软件归因
* **MalwareBazaar 集成**用于恶意软件样本情报
* 自动 **IOC 类型检测**（IPv4、域名、MD5/SHA1/SHA256）
* 跨多个厂商情报源的**恶意软件家族共识分析**
* 基于威胁情报的**启发式风险评分模型**
* 严重级别的**颜色编码终端输出**
* IOC 处理期间的**交互式进度条**
* ASCII 横幅 CLI 界面
* 用于 SOC 分析的**结构化 CSV 输出**
* 用于流水线可见性的**详细日志记录**
### 🤖 AI 能力（新增）
* 本地 **Llama3 威胁摘要生成**
* SOC 风格的结构化输出：
* 🚨 高危威胁
* ⚠️ 值得关注
* 📊 观察结果
* 🎯 建议操作
* 流式输出（实时生成）
* IOC 类型感知推理
# 架构
```
IOC Input
│
▼
IOC Validation
│
▼
IOC Type Detection
│
▼
VirusTotal Enrichment
│
├── ThreatFox IOC Intelligence
│
└── MalwareBazaar Sample Intelligence (hash only)
│
▼
IOC Age Resolution
│
▼
Risk Scoring Engine
│
▼
Terminal Output + CSV Report
│
▼
🤖 AI Threat Summary (Llama3)
```
# 风险评分模型
该流水线应用**启发式风险评分模型**来估计 IOC 严重程度。
该评分考虑多个情报信号，包括：
评分因素包括：
* **VirusTotal 检测比率**（恶意引擎 vs 总引擎）
* 跨安全厂商的**恶意检测数量**
* **ThreatFox 恶意软件归因**
* **MalwareBazaar 恶意软件归因**
* 跨厂商的**恶意软件家族共识**
* 来自多个情报源的 **IOC 年龄**
严重级别从最终评分映射：
| 评分范围 | 严重级别 |
|-------------|---------|
| 0 – 24 | 低 |
| 25 – 49 | 中 |
| 50 – 79 | 高 |
| 80 – 100 | 严重 |
此评分模型帮助分析师**在调查期间确定指标的优先级**。
# 示例输出
| IOC | IOC 类型 | 恶意 | 可疑 | 无害 | 未检测 | 年龄（天）| 严重级别 | 风险评分 | ThreatFox 家族 | MalwareBazaar 家族 | 家族共识 | 标记 |
|-----|---------|----------|-----------|----------|------------|-----------|----------|-----------|------------------|----------------------|-----------------|------|
| sit-v1.savingssit.in[.]net | 域名 | 13 | 3 | 20 | 55 | 12 | 中 | 34.15 | ClearFake | ClearFake | ClearFake | 有效载荷投递 |
| a1575e3c71357... | SHA256 | 25 | 2 | 10 | 30 | 4 | 高 | 66.77 | LummaStealer | LummaStealer | LummaStealer | 恶意软件分发 |
| 4c9d9e12a69... | SHA256 | 41 | 5 | 5 | 12 | 1 | 严重 | 90.00 | AsyncRAT | AsyncRAT | AsyncRAT | C2 基础设施 |
CSV 输出包含完整的富化数据集，包括厂商检测数量、多个情报源的恶意软件归因、IOC 年龄和计算的风险评分。
结果导出到：
```
result.csv
```
# 安装
克隆仓库：
```
git clone https://github.com/bohansec/ioc-enrichment-pipeline.git
cd ioc-enrichment-pipeline
```
安装依赖项：
```
pip install -r requirements.txt
```
创建 `.env` 文件：
```
VIRUSTOTAL_API_KEY=your_api_key_here
AbuseCh_API_KEY=your_abusech_api_key
```
# 🤖 AI 设置（通过 Ollama 使用 Llama3）
### 1. 安装 Ollama
下载地址：
[ollama.com](https://ollama.com)
验证：
```
ollama --version
```
### 2. 拉取模型
```
ollama pull llama3
```
可选（更快、更轻量）：
```
ollama pull llama3:instruct
```
### 3. 启动 Ollama
```
ollama serve
```
默认端点：
```
http://localhost:11434
```
# 使用方法
查询单个 IOC：
```
python main.py -ip 1.2.3.4
```
查询域名：
```
python main.py -domain example.com
```
查询文件哈希：
```
python main.py -hash
```
从文件查询多个 IOC：
```
python main.py -filename iocs.txt
```
### 多个 IOC 输入（CLI）
您可以直接通过命令行提供**多个 IOC**。
支持以下方式：
* **空格分隔输入**
* **逗号分隔输入**
#### 示例
**空格分隔**
```
python main.py -ip 1.1.1.1 8.8.8.8 9.9.9.9
Comma-separated
python main.py -ip 1.1.1.1,8.8.8.8,9.9.9.9
Mixed (also supported)
python main.py -ip 1.1.1.1,8.8.8.8 9.9.9.9
This works for all IOC types:
python main.py -domain example.com,test.com
python main.py -hash hash1 hash2 hash3
```
### 🔥 带 AI 摘要
```
python main.py -file iocs.txt --ai
```
# AI 输出示例
```
=== AI THREAT SUMMARY ===
🚨 Top threats
AsyncRAT hash shows strong malware behavior with C2 activity.
⚠️ Worth attention
Suspicious domain linked to payload hosting.
📊 What stands out
Cluster of credential theft malware families.
🎯 What to do
- Isolate affected hosts
- Block malicious IPs
- Hunt for execution via EDR
```
# 支持的输入文件
该流水线支持通过 **TXT 或 CSV 文件**输入 IOC。
### TXT 示例
```
1.2.3.4
example.com
44d88612fea8a8f36de82e1278abb02f
```
### CSV 示例
支持的列名包括：
```
ip
ip_address
ioc
```
如果未找到匹配的列，流水线将自动使用**第一列**。
# ⚠️ 限制与设计考量
### 🔹 软速率限制（重要）
此流水线**未实施硬速率限制**。
相反，它使用：
* 线程池并行（`max_workers=5`）
* 带延迟的重试逻辑
* 基于 TTL 的本地缓存
此设计提高了性能和分析师体验，但引入了**软速率限制行为**。
### 🚨 实际影响
外部 API（尤其是 VirusTotal）执行严格的速率限制。
一次处理过多 IOC 可能导致：
* HTTP 429（速率限制错误）
* 临时 API 限流或阻止
* 重试增加 → 执行变慢
* 部分或不完整的富化结果
### ✅ 建议使用方式
为获得最佳性能和稳定性：
* 处理**小批量 IOC（建议：每次 5–15 个）**
* 避免大量批量输入（例如 50–100+ IOC），除非分批处理
* 缓存预热后重新运行工具以获得更快的结果
### ⚡ 为什么小批量效果更好
流水线包括：
* 每个 IOC 锁定（防止重复 API 调用）
* 通过线程池的并发处理
* 瞬态故障的重试处理
* 缓存优先查询策略
然而，没有严格的速率限制：
| IOC 数量 | 行为 |
|----------|--------|
| 5–15 | ✅ 稳定 |
| 20–50 | ⚠️ 偶尔速率限制 |
| 50+ | ❌ 可能不稳定 / 被限流 |
### 🧠 设计权衡
这是有意为之的设计选择：
| 方式 | 优点 | 缺点 |
|--------|------|------|
| 硬速率限制 | 安全、可预测 | 缓慢、用户体验差 |
| 软速率限制（当前） | 快速、响应灵敏 | 需要控制使用 |
此工具优先考虑：
# 日志记录
执行日志写入：
```
logs/ioc_enrichment.log
```
日志包括：
* IOC 处理事件
* API 查询活动
* 查询失败
* 富化状态
* AI 计时指标
# 支持的 IOC 类型
* IPv4 地址
* 域名
* 文件哈希（MD5 / SHA1 / SHA256）
# 项目结构
```
ioc-enrichment/
├── asset/
│ └── screenshot.png # CLI demo screenshot used in README
│
├── engine/
│ ├── init.py
│ ├── worker.py # 🔥 Core concurrent IOC processing (thread-safe, retry, cache-aware)
│ ├── risk_engine.py # Risk scoring model
│ ├── age_resolver.py # IOC age calculation
│ ├── flags.py # Threat flag generation (VT + comments)
│ ├── dataframe.py # DataFrame builder and sorting logic
│ └── ai_summary.py # 🤖 Llama3 (Ollama) AI threat summarization
│
├── providers/
│ ├── init.py
│ ├── vt.py # VirusTotal enrichment + comments
│ └── abuse_ch.py # ThreatFox + MalwareBazaar integration
│
├── utils/
│ └── ioc_utils.py # IOC type detection & routing logic
│
├── logs/
│ └── ioc_enrichment.log # Execution logs
│
├── .env # Environment variables (API keys)
├── .env.example # Example environment configuration
├── .gitignore
│
├── config.py # API key loader & validation
├── cache.py # TTL-based caching system
├── cache.json # Local cache storage
│
├── loaders.py # 🔥 Pipeline orchestrator (thread pool, task coordination, result aggregation)
├── validators.py # IOC validation logic
├── main.py # CLI entry point
│
├── requirements.txt # Python dependencies
├── LICENSE
├── README.md
└── result.csv # Generated enrichment output
```
# 示例用例
在钓鱼调查期间，安全分析师从恶意邮件中提取可疑指标。
分析师无需手动查询多个情报平台，而是运行富化流水线来自动收集情报。
流水线：
1. 查询 **VirusTotal** 获取厂商检测
2. 关联 **ThreatFox 情报**进行恶意软件归因
3. 应用**风险评分模型**
4. 生成**用于调查工作流程的结构化输出**
标签：AI安全分析, AI风险缓解, APT分析, Ask搜索, DAST, DNS 反向解析, HTTP工具, IOC丰富化, IP地址分析, Llama3, LLM评估, MalwareBazaar, Ollama, Sigma 规则, SOC工具, ThreatFox, VirusTotal, 启发式评分, 哈希分析, 域名分析, 威胁情报, 安全运营, 库, 应急响应, 开发者工具, 恶意软件分析, 恶意软件家族, 扫描框架, 漏洞发现, 终端界面, 网络安全, 逆向工具, 隐私保护, 风险评分