AI4CTI/feed-comparison
GitHub: AI4CTI/feed-comparison
一个可复现的命令行工具，用于下载、规范化和量化比较多个恶意 URL 威胁情报源之间的覆盖率重叠度和发现时效性差异。
Stars: 0 | Forks: 0
# Feed 比较
[](https://github.com/AI4CTI/feed-comparison/actions/workflows/ci.yml)
[](https://www.gnu.org/licenses/agpl-3.0)
[](https://www.python.org)
一个可复现的命令行工具，用于**比较和基准测试恶意 URL 源**：从威胁情报提供商下载样本，使用 Google Safe Browsing 风格的规范化方法对其暴露的 URL 进行标准化，并量化这些源之间的**重叠度** (SuperVenn) 以及它们的**发现时间**对比（每个 URL 增量的累积分布函数 CDF）。
## 背景
针对恶意 URL 的威胁情报源通常是孤立使用的，但它们的**覆盖率**、**时效性**和**相互重叠度**差异很大。这使得我们很难回答一些实际问题，例如：“*如果我已经订阅了源 A，源 B 能为我提供多少额外的信号？*”或者“*源 A 比源 B 早多少天暴露出钓鱼活动？*”。`feed-comparison` 提供了一个小巧且可复现的工作流，帮助您在可访问的源上回答这些问题。
## v0.1.0 功能
- 开箱即用的**五个源集成**：PhishStats（匿名）、PhishTank（免费用户名）、urlscan.io（API token）、MISP（自托管实例，可选额外依赖）和 Ermes CTI Feed（基于 OAuth 2.0 的 STIX/TAXII，可选额外依赖）。
- 遵循 Google Safe Browsing 方法的**URL 规范化**（主机名规范化、IDNA、百分比编码、查询字符串排序...）。针对约 60 个参考用例的测试行覆盖率达到 92%。
- 基于主机名、已注册域名或完全规范化 URL 使用 SuperVenn 图进行**重叠度分析**。
- **时间增量分析**：相对于所选基准源，计算每个 URL 发现增量的 CDF。
- 使用 [Typer](https://typer.tiangolo.com) 构建的**可发现 CLI**：`list-feeds`、`download`、`compare`、`plot`。具有 Rich 格式化输出、用于脚本编程的 JSON 模式，以及通过 `.env`/环境变量进行的分层配置。
- **可复现的构建**：PEP 621 `pyproject.toml`，`uv` 管理的 lockfile，`hatchling` 构建后端，支持 Python 3.10 到 3.13 的 GitHub Actions CI。
关于 v0.1.0 中**未包含**的内容，请参阅下方的[局限性](#limitations)部分。
## 安装
该软件包尚未发布到 PyPI；对于 v0.1.0 版本，我们建议从源代码进行安装：
```
git clone https://github.com/AI4CTI/feed-comparison.git
cd feed-comparison
uv tool install .
# 或者，使用 pipx：
# pipx install .
```
如果您想基于此代码库进行开发：
```
uv sync --extra dev
uv run pre-commit install
uv run pytest
```
MISP 和 Ermes 集成是可选的额外组件（它们会引入额外的依赖项）：
```
# MISP 自托管（依赖较重的 `pymisp` 依赖项）
uv tool install '.[misp]'
# Ermes CTI Feed（STIX/TAXII + OAuth 2.0 客户端凭证）
uv tool install '.[ermes]'
# 同时执行两者
uv tool install '.[misp,ermes]'
```
## 快速入门
```
# 1. 列出该工具已知的 feeds，以及它们所需的凭证。
feed-comparison list-feeds
# 2. 从 PhishStats 下载一天的样本（无需凭证）。
feed-comparison download phishstats --days 1 --output-dir ./output
# 3. 比较两个 feeds：在 ./output 中生成 SuperVenn + 时间差 CDF。
feed-comparison compare phishstats phishtank --days 1 --benchmark phishstats
# 4. 执行相同的比较，但时间窗口为 30 天，丢弃最近
# 10 天作为“稳定”缓冲（让提交
# pipeline 较慢的 feeds 在测量重叠部分之前赶上进度）。
feed-comparison compare phishstats phishtank --days 30 --ignore-last-days 10
# 5. 使用之前保存的 CSV 重新渲染图表，而无需重新下载。
feed-comparison plot supervenn ./output/dataframe_*.csv --metric domain
```
时间增量 CDF 仅针对两个源*在它们共同观察到的 URL 上*（基于完全规范化的 URL 的交集，而非主机名或域名）计算每个 URL 的增量。因此，如果两个源在相同域名下发布了不同的路径，它们将不会产生交集——在解读图例中异常小的交集规模时请牢记这一点。
## 配置
各源的凭据将从环境变量中读取（如果当前工作目录中存在 `.env` 文件，也会从中读取）。仅要求提供您实际使用的源所需的环境变量：
| 环境变量 | 使用方 | 备注 |
| ----------------------------- | ---------- | ---------------------------------------------------- |
| `MISP_URL` | MISP | 自托管 MISP 实例的基础 URL |
| `MISP_KEY` | MISP | API key |
| `PHISHTANK_USERNAME` | PhishTank | User-Agent 字符串中的免费用户名 |
| `URLSCAN_URL` | urlscan.io | 搜索 API endpoint，例如 `.../api/v1/search/` |
| `URLSCAN_TOKEN` | urlscan.io | API token |
| `ERMES_API_SERVER` | Ermes | Ermes CTI Feed 服务的基础 URL |
| `ERMES_CLIENT_ID` | Ermes | OAuth 2.0 Client Credentials — client id |
| `ERMES_CLIENT_SECRET` | Ermes | OAuth 2.0 Client Credentials — client secret |
| `FEED_COMPARISON_OUTPUT_DIR` | 全局 | 默认输出目录 |
参考模板位于 [`.env.example`](.env.example) 中。
## 可用源
| 名称 | 提供商 | 凭据 |
| ----------- | ----------------------------------- | -------------------------------------------------------------------- |
| `phishstats`|
标签：AI4CTI, Google Safe Browsing, Object Callbacks, PhishTank, Python, STIX, SuperVenn, TAXII, TI feeds, Typer, urlscan.io, URL规范化, 反取证, 威胁情报, 威胁情报源, 安全评估, 开发者工具, 恶意URL, 情报比对, 数据重叠分析, 新鲜度分析, 无后门, 时间差分析, 网络安全, 网络钓鱼, 覆盖率分析, 逆向工具, 隐私保护