Gioxfight/ioc-enricher-api
GitHub: Gioxfight/ioc-enricher-api
一款基于 FastAPI 的 REST 服务，并行查询 VirusTotal 和 AbuseIPDB 来聚合 IOC 威胁情报，帮助安全分析师通过单次 API 调用完成告警分诊。
Stars: 0 | Forks: 0
# IOC Enricher API
## 功能介绍
IOC Enricher API 是一款专为 SOC 分析师设计的 REST 服务。它接收 IOC（Indicators of Compromise，妥协指标——如 IP 地址、文件哈希或域名），**并行**查询多个威胁情报源，并返回一份聚合报告：包含将其标记为恶意的引擎数量、滥用置信度评分、国家/地区、所有者以及最后报告日期。
每个请求在边界处都会通过 Pydantic 进行验证（无效的 IOC 会在进行任何外部调用之前，以详细的 `422` 错误被拒绝），上游调用通过 `asyncio.gather` 并发执行，并且结果会在内存中缓存，TTL 为 1 小时——重复查询同一 IOC 的响应时间约为 2 ms，且不会消耗免费版 API 额度。
## 开发动机
当告警触发时，第一个问题总是相同的：*这个 IOC 是已知的恶意指标吗？* 人工解答这个问题意味着要打开 VirusTotal，接着是 AbuseIPDB，然后比较结果——对于每一次告警，每一次都要如此。此工具将这一例行工作转化为一次单一的 API 调用，可供任何脚本、SOAR playbook 或 n8n 工作流调用。
## 技术栈
- Python 3.11+ / FastAPI
- httpx（异步 HTTP 客户端）
- Pydantic v2 + pydantic-settings
- Docker
## 快速开始
```
git clone https://github.com/Gioxfight/ioc-enricher-api.git
cd ioc-enricher-api
cp .env.example .env # add your VirusTotal and AbuseIPDB API keys
docker build -t ioc-enricher-api .
docker run --rm -p 8000:8000 --env-file .env ioc-enricher-api
```
交互式文档：http://127.0.0.1:8000/docs
不使用 Docker：
```
python -m venv .venv && source .venv/bin/activate # Windows: .\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
uvicorn app.main:app --reload
```
## 示例
```
curl -X POST http://127.0.0.1:8000/enrich/ip \
-H "Content-Type: application/json" \
-d '{"ip": "8.8.8.8"}'
```
```
{
"ip": "8.8.8.8",
"vt": {
"stats": {
"malicious": 0,
"suspicious": 0,
"undetected": 36,
"harmless": 55,
"timeout": 0
},
"reputation": 543,
"country": "US",
"as_owner": "Google LLC"
},
"abuseipdb": {
"abuseConfidenceScore": 0,
"totalReports": 128,
"countryCode": "US",
"lastReportedAt": "2026-06-09T20:16:14+00:00",
"isp": "Google LLC"
}
}
```
无效的 IOC 永远不会到达上游服务：
```
curl -X POST http://127.0.0.1:8000/enrich/ip \
-H "Content-Type: application/json" \
-d '{"ip": "999.1.1.1"}'
# → 422 {"detail": [{"msg": "value is not a valid IPv4 or IPv6 address", ...}]}
```
## 架构
```
Client ──> FastAPI (Pydantic validation)
│
├── cache hit? ──> instant response (TTL 1h)
│
└── asyncio.gather ──┬── VirusTotal API
└── AbuseIPDB API
```
设计决策：
- **使用内存缓存而非 Redis** —— 该服务作为单实例运行，缓存是一个带 TTL 的纯字典：零额外依赖，在设计上支持容错重启（冷缓存只会消耗少量的上游调用）。如果服务未来扩展到多个副本，Redis 将是顺理成章的下一步。
- **端到端异步** —— 上游查询主导了响应时间（每个约 300–700 ms）。`asyncio.gather` 并发执行它们，因此总延迟取决于最慢的调用，而非所有调用的总和。
- **通过环境变量管理密钥** —— API 密钥保存在 `.env`（已在 git 中忽略）并在运行时注入；Docker 镜像中不包含任何凭据。
## 路线图
- [ ] `/enrich/hash` 和 `/enrich/domain` endpoint
- [ ] 优雅的上游错误处理（在提供商宕机时返回 502）
- [ ] pytest 测试套件 + GitHub Actions CI
- [ ] `/enrich/bulk` 用于并行批量查询
## 许可证
[MIT](LICENSE)
标签：AV绕过, Docker, FastAPI, Python, REST API, 威胁情报, 安全运营(SOC), 安全防御评估, 开发者工具, 无后门, 请求拦截, 运行时操纵, 逆向工具