harryc295/threat-intel-aggregator
GitHub: harryc295/threat-intel-aggregator
基于多个免费威胁情报 API 的 Python CLI 工具，实现 IP、域名和文件哈希的批量富化、风险评分及可视化报告生成。
Stars: 0 | Forks: 0
# 威胁情报聚合器
一个使用**仅免费 API 层级**来丰富 IP、域名和文件哈希的 Python CLI。
结果将缓存 24 小时以保护速率限制，并写入结构化的 JSON 报告，以及一个独立的 HTML 仪表板。
## 使用的免费服务
| 服务 | 免费额度 | 需要 Key |
|---|---|---|
| VirusTotal | 500 次请求/天 · 4 次请求/分钟 | 是 |
| Shodan | 100 查询额度/月 | 是 |
| AbuseIPDB | 1,000 次请求/天 | 是 |
| ip-api.com | 45 次请求/分钟（仅限非商业用途） | **否** |
| python-whois | 无限（公共 WHOIS 服务器） | **否** |
## 获取免费 API Key 的分步指南
### 1. VirusTotal（500 次请求/天，4 次请求/分钟）
1. 前往 并点击 **Join us**。
2. 填写您的电子邮件和密码，并验证您的电子邮件地址。
3. 登录后，点击您的头像 → **API key**（或前往您的个人资料页面）。
4. 复制 *Personal API key* 下方显示的 **API key**。
5. 将其粘贴到您的 `.env` 文件中，格式为 `VIRUSTOTAL_API_KEY=`。
### 2. Shodan（100 查询额度/月）
1. 前往 并创建一个账户。
2. 注册后，访问 并滚动到 **API Key**。
3. 复制该 key。
4. 将其粘贴到您的 `.env` 文件中，格式为 `SHODAN_API_KEY=`。
### 3. AbuseIPDB（1,000 次请求/天）
1. 前往 并创建一个免费账户。
2. 验证您的电子邮件后，登录并访问 **Account → API**。
3. 点击 **Create Key**，为其命名（例如 "threat-intel"），然后复制该 key。
4. 将其粘贴到您的 `.env` 文件中，格式为 `ABUSEIPDB_API_KEY=`。
### 4. ip-api.com — 无需 key
ip-api.com 对于非商业用途是免费的，每分钟最多 45 次请求，且无需注册。
只需使用该工具；速率限制会自动处理。
### 5. WHOIS — 无需 key
域名的 WHOIS 数据是通过 `python-whois` 库获取的，该库直接查询公共 WHOIS 服务器。不需要账户或 key。
## 安装说明
```
# 克隆 / 下载项目
cd threat-intel-aggregator
# 创建并激活虚拟环境（推荐）
python -m venv .venv
# Windows PowerShell:
.venv\Scripts\Activate.ps1
# macOS / Linux:
source .venv/bin/activate
# 安装依赖
pip install -r requirements.txt
# 复制示例 env 文件并填入你的密钥
copy .env.example .env # Windows
# cp .env.example .env # macOS / Linux
# 然后打开 .env 并将占位符值替换为你的真实 API 密钥
```
## 使用说明
### 丰富单个 IOC
```
# IPv4 地址
python cli.py --ioc 185.220.101.34
# 域名
python cli.py --ioc malware-c2.example.com
# 文件哈希 (MD5、SHA-1 或 SHA-256)
python cli.py --ioc 44d88612fea8a8f36de82e1278abb02f
```
### 从 JSON 文件丰富 IOC 列表
创建一个文件 `iocs.json`：
```
["185.220.101.34", "malware-c2.example.com", "44d88612fea8a8f36de82e1278abb02f"]
```
然后运行：
```
python cli.py --input-file iocs.json
```
### 自定义输出路径
```
python cli.py --ioc 8.8.8.8 --output-json results.json --output-html results.html
```
### 从现有报告生成仪表板
```
python dashboard.py report_20240611_120000.json dashboard.html
```
## 输出
### JSON 报告 (`report_.json`)
每个条目包含：
- `ioc` – 原始指标
- `ioc_type` – `ip`、`domain` 或 `hash`
- `risk_score` – 计算得出的 0-100 综合评分
- `enrichments` – 来自每个服务（virustotal、shodan、abuseipdb、geolocation、whois）的嵌套结果
- `resolved_ip` –（仅限域名）域名在查询时解析到的 IP
### HTML 仪表板 (`dashboard_.html`)
一个独立的单文件，包含：
- 摘要卡片：总 IOC 数、高 / 中 / 低风险计数、平均分
- 所有丰富 IOC 的可搜索、可排序表格
- 颜色编码行：红色 = 高风险 (≥70)，黄色 = 中等风险 (30-69)，绿色 = 低风险/干净
- 按 IOC 类型和风险级别过滤
- 查看时无需互联网连接（没有外部 CDN）
## 缓存
所有 API 响应都会作为 JSON 文件缓存在 `.cache/` 目录中，TTL 为 24 小时。
相同的 IOC 在 24 小时内不会被再次查询，从而保护您的每日和每月免费额度。要强制进行全新查找，请从 `.cache/` 中删除相关文件或清空整个目录。
## 速率限制行为
| 服务 | 强制限制 | 策略 |
|---|---|---|
| VirusTotal | 4 次请求/分钟 | 令牌桶；休眠直到有可用令牌 |
| Shodan | 1 次请求/2 秒（保守） | 令牌桶 |
| AbuseIPDB | 30 次请求/分钟（保守） | 令牌桶 |
| ip-api.com | 45 次请求/分钟 | 令牌桶 |
在收到 **429 Too Many Requests** 响应时，工具会等待 60 秒并在放弃前重试一次。所有错误都会在丰富结果中作为 `{"error": "..."}` 返回，以便继续处理剩余的 IOC。
## 环境变量
| 变量 | 服务 | 必需 |
|---|---|---|
| `VIRUSTOTAL_API_KEY` | VirusTotal | 是 |
| `SHODAN_API_KEY` | Shodan | 是 |
| `ABUSEIPDB_API_KEY` | AbuseIPDB | 是 |
如果缺少 key，会导致相应的丰富函数返回 `{"error": "... not set"}`，处理将继续进行 —— 您仍会获得来自其他服务的结果。
## 项目结构
```
.
├── cli.py # CLI entry point (argparse)
├── enricher.py # All API query functions + unified enrich()
├── dashboard.py # HTML dashboard generator
├── cache.py # File-based TTL cache
├── ratelimiter.py # Token-bucket rate limiters
├── requirements.txt
├── .env.example
├── README.md
└── .cache/ # Auto-created; stores cached API responses (git-ignored)
```
## 免责声明
本工具旨在用于您有权调查的基础设施的**防御性安全研究和威胁分析**。请尊重每个服务的服务条款。免费层级适用于个人、非商业和研究用途 —— 请勿将此工具用于批量商业情报收集。
标签：API集成, GitHub, Python, 代码示例, 可观测性, 威胁情报, 实时处理, 开发者工具, 数据分析, 无后门, 逆向工具