malindarathnayake/ThreatBridge
GitHub: malindarathnayake/ThreatBridge
一个轻量级的威胁情报 API，旨在将分散的免费 IP/域名信誉源聚合为高速 REST 接口，以支持 SIEM 的日志富化与查询。
Stars: 0 | Forks: 0
# ThreatBridge
一个轻量级的威胁情报 API，将免费的 IP/域名信誉源聚合到一个快速的、可查询的 REST API 中，用于 SIEM 日志富化。
## 为什么选择这个项目？
| 方案 | 问题 |
|----------|---------|
| **MISP / OpenCTI** | 对于简单的查询来说是大材小用 —— 需要 MySQL、ElasticSearch、8GB+ RAM，设置复杂。专为 TI 共享社区设计，而非快速的 SIEM 富化。 |
| **商业 API** (GreyNoise, Recorded Future, AbuseIPDB) | 昂贵（$5K-50K/年）或免费层级有严格限制（100-1000 次查询/天）。 |
| **免费 TI 源** (Emerging Threats, CINS Army, Abuse.ch) | 高质量数据但仅为文本文件 —— 无 API，不可查询。 |
**ThreatBridge 填补了这一空白：**
```
FREE/PAID TEXT FEEDS THREATBRIDGE COMMERCIAL APIs
───────────────── ──────────── ───────────────
• Just files • Aggregates feeds • GreyNoise
• No API • Redis-backed • Recorded Future
• Manual parsing • Simple REST API • $5K-50K/year
• Not queryable • SIEM-ready • Rate limited
• FREE
```
**主要用例：** 通过 HTTP 查找表进行 Graylog 日志富化。
**同时也适用于：** 任何能发起 HTTP 请求的工具 - Splunk, Elastic SIEM, Logstash, Wazuh, SOAR 平台, 自定义脚本等。
## 功能特性
- **快速查询**：基于 Redis 的存储，实现毫秒级 IP/域名查询
- **PSL 感知匹配**：使用 Public Suffix List 逻辑进行子域名匹配
- **CIDR 支持**：自动展开 CIDR 表示法（例如 `192.168.0.0/24`）
- **Feed 管理**：自动下载、解析和增量跟踪
- **管理 UI**：用于查看 Feed 状态和快速查询的 Web 仪表板
- **Prometheus 指标**：全面的监控指标
- **速率限制**：针对手动 Feed 刷新的内置速率限制
- **Docker 就绪**：使用 Docker Compose 完全容器化
## 架构
```
┌─────────────────┐ ┌──────────────────┐ ┌─────────────┐
│ External │ │ Docker Stack │ │ Consumers │
│ Sources │ │ │ │ │
├─────────────────┤ ├──────────────────┤ ├─────────────┤
│ MalwareURL │───→│ ThreatBridge │←───│ Graylog │
│ Proofpoint │ │ - API endpoints │ │ Prometheus │
│ Public Suffix │ │ - Background │ │ Browser UI │
│ List │ │ scheduler │ │ │
└─────────────────┘ │ - Management UI │ └─────────────┘
│ │
│ Redis │
│ - Feed storage │
│ - Metadata │
│ - Rate limiting │
└──────────────────┘
```
## 快速部署（无需构建） 🚀
**TL;DR:** 下载 2 个文件并运行 `docker-compose up -d`
```
# 1. 下载部署文件
curl -O https://raw.githubusercontent.com/malindarathnayake/ThreatBridge/main/deploy/docker-compose.yml
curl -O https://raw.githubusercontent.com/malindarathnayake/ThreatBridge/main/deploy/feeds.sample.yml
# 2. 复制并自定义 feed 配置
cp feeds.sample.yml feeds.yml
# 编辑 feeds.yml - 根据需要启用/禁用 feeds
# 3. 可选：为自定义设置创建 .env（大多数用户可以跳过此步骤）
# curl -O https://raw.githubusercontent.com/malindarathnayake/ThreatBridge/main/deploy/.env.example
# cp .env.example .env # 如果需要自定义 feed URL 请编辑
# 4. 启动服务（从 GitHub Container Registry 拉取预构建镜像）
docker-compose up -d
# 5. 验证是否正常工作
curl http://localhost:8000/health
curl "http://localhost:8000/check/ip?ip=1.2.3.4"
```
**你将获得：**
- 预构建的 Docker 镜像（无需编译）
- 自动 Feed 加载和每小时刷新
- 管理界面位于 http://localhost:8000
- 默认启用两个免费威胁源（Emerging Threats, CINS Army）
### 升级
```
# 拉取最新镜像
docker compose pull
# 使用新镜像重建容器
docker compose up -d
# 或者如果已在运行，只需重启
docker compose restart
```
## 开发设置（从源码构建）
如果你想修改代码或从源码构建：
### 1. 克隆与设置
```
git clone https://github.com/malindarathnayake/ThreatBridge.git
cd ThreatBridge
# 复制并自定义 feed 配置
cp source/config/feeds.sample.yml source/config/feeds.yml
# 编辑 source/config/feeds.yml - 启用/禁用 feeds，添加你自己的 URL
```
### 2. 配置环境
创建包含你的 Feed URL 的 `.env` 文件（用于使用 `from env var:` 语法的 Feed）：
```
# 必需：MalwareURL feed URL
MALWAREURL_FEED_URL=https://www.malwareurl.com/your-feed-url
# 可选：Proofpoint feed URL（默认禁用）
PROOFPOINT_FEED_URL=https://your-proofpoint-url
# 可选：日志级别
LOG_LEVEL=INFO
# 可选：API 端口
API_PORT=8000
```
### 3. 启动服务
```
# 构建并启动所有服务
docker-compose up -d
# 检查状态
docker-compose ps
# 查看日志
docker-compose logs -f threatbridge
```
### 4. 验证安装
```
# 健康检查
curl http://localhost:8000/health
# 访问管理 UI
open http://localhost:8000
# 测试查询
curl "http://localhost:8000/check/ip?ip=1.2.3.4"
curl "http://localhost:8000/check/domain?domain=example.com"
```
## API 端点
### 健康检查
```
GET /health
```
### IP 查询
```
GET /check/ip?ip=1.2.3.4
```
**响应：**
```
{
"found": true,
"query": "1.2.3.4",
"type": "ip",
"feeds": ["malwareurl"],
"risk": "high"
}
```
### 域名查询
```
GET /check/domain?domain=foo.kortin.click
```
**响应：**
```
{
"found": true,
"query": "foo.kortin.click",
"type": "domain",
"match_type": "parent",
"matched_value": "kortin.click",
"feeds": ["malwareurl"],
"risk": "high"
}
```
### Feed 管理
```
GET /feeds # List all feeds
GET /feeds/{name} # Get feed details
POST /feeds/{name}/refresh # Manual refresh (rate limited)
```
### 指标
```
GET /metrics # Prometheus metrics
```
## 配置
## 域名匹配逻辑
## 监控
## Feed 管理
Feed 会在启动时、每 60 分钟（可配置）以及通过手动刷新 API 自动加载。
## Graylog 集成
详细的 Graylog 配置请参阅 `docs/graylog-setup.md`。
**快速设置：**
1. 创建 HTTP JSON 查找表：
- TI IP Lookup: `http://threatbridge:8000/check/ip?ip=${key}`
- TI Domain Lookup: `http://threatbridge:8000/check/domain?domain=${key}`
2. 添加 Pipeline 规则：
```
rule "ti_enrich_srcip"
when
has_field("srcip")
then
let ti = lookup("ti_ip_lookup", to_string($message.srcip));
if (ti != null && ti.found == true) {
set_field("ti_hit", true);
set_field("ti_risk", ti.risk);
set_field("ti_feeds", to_string(ti.feeds));
}
end
```
## 开发
## 故障排除
## 安全注意事项
- Redis 默认仅绑定到 localhost
- 无需认证（假设为内部网络）
- Feed URL 敏感 —— 请使用环境变量
- 如需外部访问，请考虑使用带有 HTTPS 的反向代理
- 监控 Feed URL 的变更/劫持
## 更新日志
📋 **[完整更新日志](CHANGELOG.md)** - 包含所有详情的完整发布历史。
## 许可证
MIT 许可证 - 可免费使用、修改和分发。详情请参阅 [LICENSE](LICENSE)。
## 贡献
欢迎贡献！这个项目源于一个需求 —— 如果你觉得它有用并希望改进它：
1. Fork 本仓库
2. 创建一个功能分支
3. 提交 Pull Request
贡献方向：
- 额外的 Feed 解析器（JSON, CSV, STIX）
- 新的免费 Feed 源
- 其他 SIEM 的集成指南
- 性能改进
## 支持
如有问题和疑问：
1. 查阅此 README 和故障排除部分
2. 查看日志：`docker-compose logs -f`
3. 检查 `/health` 端点和指标
4. 提交包含日志和配置的 GitHub Issue
feeds.yml - Feed 配置选项
复制 `config/feeds.sample.yml` 到 `config/feeds.yml` 并进行自定义： ``` feeds: - name: my_feed description: "My threat feed" url: "from env var: MY_FEED_URL" # Or direct URL risk: high # high | medium | low enabled: true refresh_minutes: 300 # Optional: per-feed refresh interval (overrides global) settings: reload_interval_minutes: 60 # Default refresh interval for all feeds download_timeout_seconds: 300 # HTTP timeout for downloads max_entry_length: 253 # Max DNS name length min_cidr_prefix: 20 # Min CIDR to expand (/20=4096 IPs max) ``` **单 Feed 刷新：** 每个 Feed 可以有自己的 `refresh_minutes` 来覆盖全局设置。 **CIDR 展开：** 带有 CIDR 表示法的 Feed 会自动展开。`min_cidr_prefix` 限制展开（默认 `/20` = 最多 4096 个 IP）。环境变量 - 所有配置选项
| 变量 | 默认值 | 描述 | |----------|---------|-------------| | `REDIS_HOST` | redis | Redis 主机名 | | `REDIS_PORT` | 6379 | Redis 端口 | | `REDIS_DB` | 0 | Redis 数据库 | | `API_PORT` | 8000 | API 服务器端口 | | `LOG_LEVEL` | INFO | 日志级别 | | `FEEDS_CONFIG` | /config/feeds.yml | Feed 配置路径 | | `MALWAREURL_FEED_URL` | - | MalwareURL Feed URL（必需） | | `PROOFPOINT_FEED_URL` | - | Proofpoint Feed URL（可选） | | `LOADER_CHECK_INTERVAL` | 3600 | 加载器检查 Feed 是否需要刷新的频率（秒） | | `IPINFO_TOKEN` | - | 用于 Web UI 中 IP 富化的 IPInfo API token（可选） | **更改 API 端口：** ``` API_PORT=9000 docker-compose up -d ``` **IPInfo 富化（仅限 Web UI）：** Web UI 中的快速查询可以使用 [IPInfo Lite API](https://ipinfo.io/developers/lite) 显示 IP 地址的 ASN、组织和地理位置数据。 1. 在 https://ipinfo.io/signup 获取免费 token（每月 5 万次免费请求） 2. 在 `feeds.yml` 中配置（推荐）或通过环境变量： ``` # 在 feeds.yml 中 - 添加到 settings 部分： settings: ipinfo_token: "your_token_here" ``` ``` # 或者通过环境变量（覆盖 feeds.yml）： IPINFO_TOKEN=your_token_here docker-compose up -d ```PSL 感知匹配 - 域名查询的工作原理
1. **精确匹配**：检查域名是否直接存在于 Feeds 中 2. **父级遍历**：如果无精确匹配且域名为子域名： - 使用 Public Suffix List 提取可注册域名 (eTLD+1) - 检查可注册域名是否在“可遍历”域名中 - 如果找到则返回父级匹配 **示例：** - `kortin.click` → 可遍历（可注册域名） - `foo.kortin.click` → 通过父级 `kortin.click` 匹配 - `github.io` → 可遍历（特殊情况的可注册域名） - `user.github.io` → 通过父级 `github.io` 匹配Prometheus 指标 - 可通过 /metrics 访问
- `ti_feed_entries_total` - 每个 Feed 的条目数 - `ti_feed_last_load_timestamp` - 最后成功加载时间 - `ti_lookup_requests_total` - 查询请求计数器 - `ti_lookup_duration_seconds` - 查询延迟直方图 - `ti_redis_connection_status` - Redis 连接状态 📊 **[完整指标参考](source/docs/prometheus-metrics.md)** - 包含 Grafana 示例和告警规则的完整指标文档。健康与日志 - 监控命令
``` # 检查 API 健康状态 curl http://localhost:8000/health # 检查容器健康状态 docker-compose ps # 检查 Redis docker-compose exec redis redis-cli ping # 查看日志 docker-compose logs -f threatbridge docker-compose logs -f redis ```手动刷新
``` # 通过 API（速率限制：每 15 分钟一次） curl -X POST http://localhost:8000/feeds/malwareurl/refresh # 通过管理 UI，地址为 http://localhost:8000 ```添加新 Feed
1. 编辑 `config/feeds.yml`： ``` feeds: - name: new_feed description: "New threat feed" url: "from env var: NEW_FEED_URL" # Or direct URL risk: medium enabled: true ``` 2. 如果使用 `from env var:`，添加到 `.env`： ``` NEW_FEED_URL=https://your-feed-url ``` 3. 重启：`docker-compose restart threatbridge`本地开发
``` # 构建并运行 docker compose up -d --build threatbridge # 检查日志 docker compose logs threatbridge # 测试端点 curl http://localhost:8000/health curl "http://localhost:8000/check/ip?ip=8.8.8.8" ```代码结构
``` source/ ├── src/ # Application source code │ ├── config.py # Configuration management │ ├── models.py # Pydantic data models │ ├── redis_client.py # Redis connection and operations │ ├── psl_classifier.py # Domain classification logic │ ├── metrics.py # Prometheus metrics │ ├── loader.py # Feed download and parsing │ ├── ti_api.py # FastAPI application (gunicorn + uvicorn workers) │ └── static/index.html # Management UI ├── config/ # Feed configuration files └── docs/ # Documentation deploy/ # Production deployment files ```常见问题
**Redis 连接失败** ``` docker-compose ps redis docker-compose logs redis docker-compose exec redis redis-cli ping ``` **Feed 下载错误** ``` docker-compose logs threatbridge | grep -i error curl http://localhost:8000/feeds/malwareurl ``` **内存占用高 / 查询缓慢** ``` docker-compose exec redis redis-cli info memory docker-compose exec redis redis-cli --latency curl http://localhost:8000/metrics | grep ti_lookup_duration ``` **Redis 内存超额分配警告** - 在 Docker 主机上修复： ``` sudo sysctl vm.overcommit_memory=1 ```性能调优
**Redis：** 对于大型 Feed 增加 `maxmemory`，启用 RDB 快照。 **API：** 调整 `reload_interval_minutes`，优化 `download_timeout_seconds`，水平扩展容器。API 默认使用 4 个 gunicorn worker 运行以提高吞吐量。v1.3.0 (2025-12-06) - 点击展开
- **流式 Feed 处理**，用于内存高效地处理大型 Feed（1900 万+ 行） - **Redis 原生增量计算**，避免将大型集合加载到内存中 - **异步批处理**，具有可配置的批处理大小 - **修复了 OOM 崩溃** 和大型 Feed 导致的 worker 超时终止v1.2.0 (2025-12-04) - 点击展开
- **Gunicorn 与 4 个 worker**，以提升 API 吞吐量和并发性v1.1.0 (2025-12-04) - 点击展开
- 单 Feed 刷新间隔（`refresh_minutes` 配置选项） - UI 中的大型 Feed 警告（> 100 万条目） - 后台刷新进度跟踪 - Redis 客户端弹性改进 - 大型 Feed 的批量 Redis 写入 - 修复了刷新端点上的 HTTP 状态码v1.0.0 (初始版本) - 点击展开
- 具有 IP/域名查询功能的核心威胁情报 API - Redis 支持的存储，具有 PSL 感知的域名匹配 - 管理 UI 仪表板 - Prometheus 指标端点 - 自动 Feed 刷新调度标签：API, CIDR, Elastic SIEM, ESC4, Graylog, IOC, IP信誉, LangChain, Logstash, OSINT, PSL, Redis, REST API, SOAR, ThreatBridge, TI, Wazuh, 域名信誉, 威胁情报, 安全运营, 开发者工具, 扫描框架, 搜索引擎查询, 攻击指标, 数据聚合, 日志富化, 自定义请求头, 请求拦截, 轻量级, 逆向工具