ard1102/ip-intelligence
GitHub: ard1102/ip-intelligence
一个自托管的容器化威胁情报平台，聚合 10 个开源情报源并提供标准化的 IP 富化查询与防火墙导出能力。
Stars: 0 | Forks: 0
# IP 情报平台
一个自托管的、容器化的威胁情报聚合与富化服务。它接入 10 个开源威胁情报源，使用规范化的安全上下文对 IP 查询进行富化，并通过 REST API 和 MCP 服务器公开结果。所有输出均规范化为 [OCSF Class 4001 (Network Activity)](https://schema.ocsf.io/classes/network_activity)。
## 功能
- **10 个威胁情报源** — Feodo Tracker、Emerging Threats、Spamhaus、TOR exits、CINS、Blocklist.de、SAPICS ASN、ThreatFox、OTX、Shadowserver
- **实时富化** — 地理定位 (ip-api.com)、Shodan InternetDB、反向 DNS、AbuseIPDB
- **OCSF Class 4001 输出** — 所有响应均规范化为 Open Cybersecurity Schema Framework
- **REST API** — 基于 FastAPI，OpenAPI 文档位于 `/docs`
- **MCP server** — FastMCP 2.x 流式 HTTP，兼容 claude.ai MCP 连接器
- **自愈情报源** — SelfRepairAgent 自动隔离漂移或过期的情报源
- **防火墙导出** — 支持 NDJSON、纯文本和 CIDR-block 导出
- **零密钥阶段 1** — 所有开源情报源无需 API 密钥即可运行
## 快速开始
```
# 克隆并配置
git clone https://github.com/your-username/ip-intelligence.git
cd ip-intelligence
cp .env.example .env
# 编辑 .env — 至少设置 ADMIN_KEY
# 使用 Docker Compose 运行
docker compose up -d
# 验证
curl http://localhost:8004/health
```
API 将在 `http://localhost:8004` 提供，OpenAPI 文档位于 `http://localhost:8004/docs`。
## API 参考
| 方法 | Endpoint | 描述 |
|--------|----------|-------------|
| `GET` | `/lookup/{ip}` | 富化单个 IP — 返回 OCSF 4001 |
| `POST` | `/bulk` | 批量查询最多 500 个 IP |
| `GET` | `/health` | 情报源健康状态与修复代理状态 |
| `GET` | `/export/{format}` | 导出黑名单 (ndjson, txt, cidr) |
| `GET` | `/asn/{asn}/ranges` | 将 ASN 扩展为 IP 范围 |
| `POST` | `/admin/*` | 管理操作（需要 `ADMIN_KEY`） |
### 示例
```
curl http://localhost:8004/lookup/1.2.3.4
```
```
{
"class_uid": 4001,
"severity_id": 4,
"dst_endpoint": { "ip": "1.2.3.4" },
"enrichments": [
{ "name": "geo", "value": { "country": "CN", "city": "Beijing" } },
{ "name": "feodo", "value": { "tags": ["C2", "Emotet"] } }
],
"attacks": [{ "technique": { "uid": "T1071" } }]
}
```
## MCP 工具
从任何兼容 MCP 的客户端（Claude Desktop、claude.ai）连接到 `http://localhost:8004/mcp`。
| 工具 | 描述 |
|------|-------------|
| `ip_lookup` | 富化单个 IP |
| `bulk_hunt` | 批量 IP 富化 |
| `asn_expand` | 将 ASN 扩展为 IP 范围 |
| `feed_status` | 查询情报源健康状态 |
| `promote_ioc` | 将 IP 提升至监控列表 |
| `explain_verdict` | 生成 IP 的人类可读判定说明 |
## 威胁情报源
### 阶段 1 — 无需 API 密钥
| 情报源 | 来源 | 更新频率 |
|------|--------|---------------|
| Feodo Tracker | abuse.ch | 每 30 分钟 |
| Emerging Threats | ProofPoint | 每 60 分钟 |
| Spamhaus DROP | Spamhaus | 每 12 小时 |
| TOR Exit Nodes | torproject.org | 每 60 分钟 |
| CINS Army | CINS | 每 60 分钟 |
| Blocklist.de | blocklist.de | 每 60 分钟 |
| SAPICS ASN | SAPICS | 每 24 小时 |
### 阶段 2 — 可选 API 密钥
| 情报源 | 环境变量 | 获取地址 |
|------|---------|-------------|
| ThreatFox | `THREATFOX_API_KEY` | [abuse.ch/threatfox](https://abuse.ch/threatfox) |
| OTX | `OTX_API_KEY` | [otx.alienvault.com](https://otx.alienvault.com) |
| Shadowserver | `SHADOWSERVER_API_KEY` | [shadowserver.org](https://www.shadowserver.org) |
| AbuseIPDB | `ABUSEIPDB_API_KEY` | [abuseipdb.com](https://www.abuseipdb.com) |
## 架构
```
┌─────────────────────────────────────────────┐
│ Clients │
│ curl / Claude Desktop / Browser UI │
└──────────────┬──────────────────────────────┘
│
┌──────────────▼──────────────────────────────┐
│ FastAPI + FastMCP │
│ app/main.py (port 8004) │
├─────────────────────────────────────────────┤
│ LookupEngine │ Enrichers │ MCP Tools │
│ (bisect) │ geo/shodan │ 6 tools │
├─────────────────────────────────────────────┤
│ IntelStore │
│ (in-memory, atomic swap) │
├─────────────────────────────────────────────┤
│ APScheduler │ SelfRepairAgent │
│ (10 cron jobs)│ (health monitoring) │
├─────────────────────────────────────────────┤
│ Feed Updaters (10) │
└─────────────────────────────────────────────┘
```
## 配置
所有配置均通过环境变量进行。将 `.env.example` 复制为 `.env`：
```
cp .env.example .env
```
核心设置：
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `PORT` | `8004` | 服务器端口 |
| `ADMIN_KEY` | — | 用于 admin endpoint 的必需密钥 |
| `REPAIR_AGENT_ENABLED` | `true` | 启用对降级情报源的自动修复 |
| `FRESHNESS_ALERT_HOURS` | `48` | 如果情报源数据早于 N 小时则发出警报 |
## 开发
```
# 安装依赖
pip install -r requirements.txt
# 本地运行（不使用 Docker）
uvicorn app.main:app --reload --port 8004
# 运行测试（仅单元测试，无网络）
pytest tests/ -v -m "not live_feeds"
# 运行所有测试（需要网络访问）
pytest tests/ -v
```
### 项目结构
```
app/
├── main.py # FastAPI app + FastMCP mount
├── mcp_tools.py # MCP @mcp.tool() definitions
├── intel_store.py # Unified in-memory store
├── lookup.py # Bisect engine
├── scorer.py # Risk score computation
├── repair_agent.py # Self-healing feed monitor
├── scheduler.py # APScheduler cron setup
├── ocsf.py # OCSF 4001 serialization
├── enrichers/ # Geo, Shodan, rDNS, AbuseIPDB
├── models/ # Pydantic v2 models
└── updaters/ # Per-feed update scripts (10 feeds)
```
## Claude Code 集成
本仓库提供了完整的 [Claude Code](https://claude.ai/code) 设置。当您在 Claude Code 中打开该项目时，它会自动加载：
- **项目说明** (`CLAUDE.md`) — 架构、不变量、约定和测试命令
- **专用子代理** (`.claude/agents/`) — 每个代理负责技术栈中的某一层：
| 代理 | 职责 |
|-------|------|
| `api-builder` | `app/main.py`、`app/mcp_tools.py`，所有 REST 路由和 MCP 工具 |
| `feed-builder` | `app/updaters/` — 情报源抓取、解析、验证、替换 |
| `repair-engineer` | `app/repair_agent.py`、`app/scheduler.py` — 健康状态机 |
| `schema-validator` | `app/models/`、`app/ocsf.py`、`app/config.py` — Pydantic v2 模型 |
| `test-writer` | `tests/` — pytest fixture、覆盖率、回归测试 IP |
- **自动测试钩子** (`.claude/settings.json`) — 每次编辑 Python 文件后运行 `pytest -m "not live_feeds"`
- **开发服务器启动** (`.claude/launch.json`) — 在端口 5173 启动 UI 开发服务器
无需额外设置 — 克隆仓库，在 Claude Code 中打开它，代理即可随时使用。
## 安全
要报告漏洞，请参阅 [SECURITY.md](SECURITY.md)。请勿开启公开的 issue。
## 许可证
[MIT](LICENSE)
标签：AV绕过, Docker, FastAPI, IP情报, 威胁情报, 威胁情报聚合, 安全防御评估, 开发者工具, 网络测绘, 请求拦截, 逆向工具