benjaminchoe123/threat-intel-pipeline
GitHub: benjaminchoe123/threat-intel-pipeline
一个自动化威胁情报管道，将公开情报源经多维度信誉查询和 Claude AI 富化后，以可审计的知识图谱形式存储并生成经人工审批的分析报告。
Stars: 0 | Forks: 0
# 威胁情报 Pipeline
一个自动化的威胁情报 pipeline，每日摄取公开的威胁情报源，使用 Claude（无头模式）将每条情报富化为分析师级别的笔记，将所有内容以 wikilink 的知识图谱形式存储在 Obsidian vault 中，并起草每周的分析师报告。在发布任何内容之前，由人工进行审查和批准。
该项目由一名有抱负的 SOC 分析师构建，作为威胁情报分诊的实战练习：每一个设计决策都旨在优化**诚实、可审计的分析** —— pipeline 的工程设计让 AI 能够说出“我不知道”，并且人类永远是发布前的最后一道关卡。
## 架构
```
flowchart LR
subgraph feeds["Public feeds (daily)"]
KEV["CISA KEV"]
TF["ThreatFox"]
UH["URLhaus"]
MB["MalwareBazaar"]
MTA["MTA blog RSS"]
end
feeds --> ING["Ingest + normalize
(Python)"] ING --> DEDUPE["Dedupe
(SQLite state)"] DEDUPE -->|new items| REP["IOC reputation
(VirusTotal + AbuseIPDB)"] REP --> ENRICH["Claude enrichment
(claude -p, headless)"] ENRICH --> VALIDATE{"Schema
validation"} VALIDATE -->|valid| VAULT["Obsidian vault
threats / families /
techniques / actors"] VALIDATE -->|invalid ×2| QUAR["Quarantine"] ENRICH -.every call.-> AUDIT["Audit log (JSONL)
source vs. claim"] VAULT --> WEEKLY["Weekly report draft
(Sundays)"] WEEKLY --> HUMAN{{"Human review
& approval"}} HUMAN -->|approved| GH["GitHub push"] HUMAN -->|approved| LI["LinkedIn draft
→ clipboard"] ``` ## 是什么让它不同于爬虫 + LLM - **AI 不受信任。** 每一次富化在触及 vault 之前，都会根据严格的 schema（frontmatter 字段、严重性/置信度枚举、ATT&CK ID 格式）进行验证；失败的项目会被隔离，永远不会被发布。参见 `pipeline/enrich.py`。 - **AI 的主张会与真实世界进行核对，而不仅仅是 schema。** ATT&CK 技术 ID 会与真实的 ATT&CK 目录快照进行验证，因此一个虚构但格式正确的 `T9999` 会被拒绝，而不是悄悄地变成图谱中的一个存根页面。`source` 和 `date` 会与其来源条目进行交叉核对。 - **在 prompt 契约中执行了“禁止猜测”规则。** 如果来源不支持某项主张，模型必须设置 `confidence: low` + `flagged: true` 并说明不确定的内容 —— 带有标记的笔记会进入人类的审查队列。评分标准和规则位于 [`skills/threat-analyst.md`](skills/threat-analyst.md) 中。 - **失败是可见的，而非静默的。** 一个悄悄返回空结果的威胁 pipeline 比一个崩溃的 pipeline 更糟糕。abuse.ch 报告已撤销的 API key 时会返回 HTTP 200 和 `query_status: illegal_auth_key`，简单的解析会将其误认为是一个平静的无事之日 —— 这会被检测到并引发异常。Feed 和条目是相互隔离的，因此一个失败不会放弃整个运行过程，并且当有任何内容失败时，进程会以非零状态退出。 - **完整的审计追踪。** 每次富化都会追加一条 JSONL 记录，将原始来源快照与模型的精确输出配对，因此“Claude 声称的内容 vs. 来源所述的内容”始终是可查证的。 - **人工控制的发布。** 报告草稿被 gitignore 忽略；`pipeline/publish.py` 需要交互式确认，并且 LinkedIn 的发布是刻意手动的（草稿复制到剪贴板）—— 没有人的决定，任何内容都不会公开。 - **设计上限制了数据量。** IOC 洪流（ThreatFox/URLhaus）按每个恶意软件家族每天进行聚合；每次运行的富化数量都有上限并支持结转，因此 vault 伴随信号而非噪声增长。 - **来自四个维度的独立信誉上下文。** 在富化之前，每个条目都会根据其适用情况被添加相应的上下文，结果将作为显式上下文移交给模型 —— 因此严重性建立在多源证据之上，而不是仅凭单一情报源的一面之词： - **VirusTotal** — 针对条目的部分 IOC 的引擎判定 - **AbuseIPDB** — 针对 IP IOC 的社区滥用报告评分 - **GreyNoise** — IP 是否在批量扫描互联网或属于专用基础设施。这是其他来源无法回答的问题：已知互联网范围扫描器的高滥用评分是噪声，而一个*安静*的 IP 才是更有趣的目标。 - **EPSS** — CVE 在未来 30 天内被利用的概率。它与 KEV 互补而不重复：KEV 表示*已观察到*被利用，而 EPSS 表示其可能性。一个评分为 23% 的 KEV 条目紧挨着一个评分为 99% 的条目，这是一种优先级排序信号，而不是矛盾。 查询设有上限，在整个运行过程中进行节奏控制，缓存 7 天，并记录在审计日志中。提供商服务中断会降级笔记而不是停止 pipeline，并会明确说明这一点 —— 模型绝不能将失败的查询读取为干净的判定结果。prompt 会警告“未找到”不等于良性（全新的 C2 基础设施通常对扫描仪是未知的）。参见 `pipeline/reputation.py` 及其各服务模块。所有的 key 都是可选的；EPSS 则完全不需要。 ## 出了什么问题，以及它教会了我什么 保留诚实的记录意味着要记录 pipeline 自身的失败，而不仅仅是它捕获的威胁。 一个格式错误的 RSS 条目曾经产生了一个空条目。模型完全按照 prompt 契约的要求执行了 —— 它写下了“疑似摄取失败”，而不是虚构一个威胁。**Pipeline 随后却将该通知作为威胁笔记归档到了 `vault/threats/` 中，并将该条目记录为已查看**，因为验证只检查了笔记的*结构*，而没有检查条目是否有可供分析的内容。该笔记随后被悄悄手动删除，这违反了项目自身的规则。 教训不在于“模型不可信” —— 而在于对模型的护栏并不等同于对围绕它的系统的护栏。现在，摄取失败会在消耗 `claude` 调用之前被捕获（`run.is_enrichable`），并且审计追踪会在 `finally` 块中记录所有的结果，包括失败。 构建该项目还发现，测试套件几个月来一直在向生产审计日志中写入数据 —— 25 条记录中有 12 条是 pytest 留下的痕迹。它们已被一个记录了自身删除操作的脚本移除，而现在的 `conftest.py` 使得这种事情在结构上变得不再可能。 ## 知识图谱 每个威胁笔记都会通过 wikilink 链接到它引用的恶意软件家族、MITRE ATT&CK 技术和威胁行为者；存根页面会被自动创建，因此 Obsidian 的图谱视图可以展示真实的关系 —— 哪些家族使用了哪些技术，哪些 CVE 聚集在哪里。 每次运行还会导出 `vault/docs/attack-layer.json`，这是一个 [ATT&CK Navigator](https://mitre-attack.github.io/attack-navigator/) 图层，根据引用某项技术的笔记数量对其进行评分（打开现有图层 → 从本地上传）。它展示的是观察到的活动，而不是抽象的 ATT&CK 覆盖率 —— 这是数据所支持的唯一主张。 每次运行还会将每个威胁笔记对应的一个 [STIX 2.1](https://oasis-open.github.io/cti-documentation/) bundle 导出到 `vault/docs/stix/` —— Vulnerability/Malware/AttackPattern/Indicator 对象仅根据笔记已经断言的内容（经过 schema 验证的 frontmatter 以及观察到的 IOCs 表）构建，因此它可以输入给 MISP、TheHive/Cortex 或任何其他使用 STIX 的平台。 Malware、technique 和 CVE 对象具有确定性 ID（UUIDv5，而非随机），因此相同的家族或 CVE 在引用它的每个笔记中都会解析为同一个对象。参见 `pipeline/stix.py`。 可选地，`pipeline/misp.py` 会将这些相同的 bundle 作为 event 推送到 [MISP](https://www.misp-project.org/) 实例中 —— IOC 作为 attribute，家族/技术作为 tag。默认关闭（不设置 `MISP_URL`/`MISP_API_KEY`，与 VirusTotal/AbuseIPDB/GreyNoise 使用相同的可选 key 模式）；关于如何通过 Docker 搭建本地实例，请参见 `docs/MISP-SETUP.md`。  *威胁笔记（冗长的带日期标题）链接到了它们引用的 ATT&CK 技术和恶意软件家族。`T1190` 位于 KEV 集群的中心；`Agent Tesla` 和 `AdaptixC2` 引入了各自的技术。这里没有任何东西是手动绘制的 —— 连线是富化过程写入的 wikilink，而存根页面是自动创建的。* ## 设置 ``` git clone && cd threat-intel-pipeline
python -m venv .venv; .\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
copy .env.example .env # add free API keys: abuse.ch, VirusTotal, AbuseIPDB (all optional)
python -m pipeline.run --source kev --limit 3 # first run, bounded
scripts\register_tasks.ps1 # daily 08:00 + Sunday 09:00 via Windows Task Scheduler
```
需要安装并登录 [Claude Code](https://claude.com/claude-code)（富化运行 `claude -p` 无头模式 —— 无需 API key）。
每周流程：周日的任务会起草 `vault/reports/drafts/YYYY-Wnn-DRAFT.md` → 编辑它 → `python -m pipeline.publish YYYY-Wnn`（交互式确认 → git push → 剪贴板上的 LinkedIn 草稿）。
## 测试
220 多个单元测试（TDD）涵盖了去重状态、输出验证（schema、ATT&CK 目录、来源/日期交叉核对）、笔记/存根/仪表盘生成、情报源解析器（包括格式错误的 RSS 回归测试和 abuse.ch 认证失败信封）、信誉查询（速率控制、缓存、429 处理、URL 标识符、未找到处理）、EPSS 评分、运行弹性、报告起草和发布保护：
```
python -m pytest tests/ -q
```
CI 会在 **Windows 和 Linux** 上运行该套件。在这里 Windows 更为重要：pipeline 通过 Task Scheduler 部署在 Windows 上，且使用 cp1252 stdout，因此测试套子现在所覆盖的那些编码和保留文件名相关的 bug 在仅限 Linux 的 CI 中是无法被发现的。
## 来源
**Feeds**
- [CISA 已知被利用漏洞](https://www.cisa.gov/known-exploited-vulnerabilities-catalog)
- [abuse.ch ThreatFox](https://threatfox.abuse.ch/) / [URLhaus](https://urlhaus.abuse.ch/) / [MalwareBazaar](https://bazaar.abuse.ch/) — 一个 Auth-Key 即可驱动全部三个
- [Malware-Traffic-Analysis.net](https://www.malware-traffic-analysis.net/)
**Enrichment**
- [FIRST EPSS](https://www.first.org/epss/) — 利用概率（无需 API key）
- [VirusTotal](https://www.virustotal.com/) — 引擎判定
- [AbuseIPDB](https://www.abuseipdb.com/) — 社区滥用评分
- [GreyNoise 社区版](https://www.greynoise.io/) — 扫描器与定向基础设施对比
- [MITRE ATT&CK](https://attack.mitre.org/) — 技术目录（`python -m pipeline.attack --refresh`）
(Python)"] ING --> DEDUPE["Dedupe
(SQLite state)"] DEDUPE -->|new items| REP["IOC reputation
(VirusTotal + AbuseIPDB)"] REP --> ENRICH["Claude enrichment
(claude -p, headless)"] ENRICH --> VALIDATE{"Schema
validation"} VALIDATE -->|valid| VAULT["Obsidian vault
threats / families /
techniques / actors"] VALIDATE -->|invalid ×2| QUAR["Quarantine"] ENRICH -.every call.-> AUDIT["Audit log (JSONL)
source vs. claim"] VAULT --> WEEKLY["Weekly report draft
(Sundays)"] WEEKLY --> HUMAN{{"Human review
& approval"}} HUMAN -->|approved| GH["GitHub push"] HUMAN -->|approved| LI["LinkedIn draft
→ clipboard"] ``` ## 是什么让它不同于爬虫 + LLM - **AI 不受信任。** 每一次富化在触及 vault 之前，都会根据严格的 schema（frontmatter 字段、严重性/置信度枚举、ATT&CK ID 格式）进行验证；失败的项目会被隔离，永远不会被发布。参见 `pipeline/enrich.py`。 - **AI 的主张会与真实世界进行核对，而不仅仅是 schema。** ATT&CK 技术 ID 会与真实的 ATT&CK 目录快照进行验证，因此一个虚构但格式正确的 `T9999` 会被拒绝，而不是悄悄地变成图谱中的一个存根页面。`source` 和 `date` 会与其来源条目进行交叉核对。 - **在 prompt 契约中执行了“禁止猜测”规则。** 如果来源不支持某项主张，模型必须设置 `confidence: low` + `flagged: true` 并说明不确定的内容 —— 带有标记的笔记会进入人类的审查队列。评分标准和规则位于 [`skills/threat-analyst.md`](skills/threat-analyst.md) 中。 - **失败是可见的，而非静默的。** 一个悄悄返回空结果的威胁 pipeline 比一个崩溃的 pipeline 更糟糕。abuse.ch 报告已撤销的 API key 时会返回 HTTP 200 和 `query_status: illegal_auth_key`，简单的解析会将其误认为是一个平静的无事之日 —— 这会被检测到并引发异常。Feed 和条目是相互隔离的，因此一个失败不会放弃整个运行过程，并且当有任何内容失败时，进程会以非零状态退出。 - **完整的审计追踪。** 每次富化都会追加一条 JSONL 记录，将原始来源快照与模型的精确输出配对，因此“Claude 声称的内容 vs. 来源所述的内容”始终是可查证的。 - **人工控制的发布。** 报告草稿被 gitignore 忽略；`pipeline/publish.py` 需要交互式确认，并且 LinkedIn 的发布是刻意手动的（草稿复制到剪贴板）—— 没有人的决定，任何内容都不会公开。 - **设计上限制了数据量。** IOC 洪流（ThreatFox/URLhaus）按每个恶意软件家族每天进行聚合；每次运行的富化数量都有上限并支持结转，因此 vault 伴随信号而非噪声增长。 - **来自四个维度的独立信誉上下文。** 在富化之前，每个条目都会根据其适用情况被添加相应的上下文，结果将作为显式上下文移交给模型 —— 因此严重性建立在多源证据之上，而不是仅凭单一情报源的一面之词： - **VirusTotal** — 针对条目的部分 IOC 的引擎判定 - **AbuseIPDB** — 针对 IP IOC 的社区滥用报告评分 - **GreyNoise** — IP 是否在批量扫描互联网或属于专用基础设施。这是其他来源无法回答的问题：已知互联网范围扫描器的高滥用评分是噪声，而一个*安静*的 IP 才是更有趣的目标。 - **EPSS** — CVE 在未来 30 天内被利用的概率。它与 KEV 互补而不重复：KEV 表示*已观察到*被利用，而 EPSS 表示其可能性。一个评分为 23% 的 KEV 条目紧挨着一个评分为 99% 的条目，这是一种优先级排序信号，而不是矛盾。 查询设有上限，在整个运行过程中进行节奏控制，缓存 7 天，并记录在审计日志中。提供商服务中断会降级笔记而不是停止 pipeline，并会明确说明这一点 —— 模型绝不能将失败的查询读取为干净的判定结果。prompt 会警告“未找到”不等于良性（全新的 C2 基础设施通常对扫描仪是未知的）。参见 `pipeline/reputation.py` 及其各服务模块。所有的 key 都是可选的；EPSS 则完全不需要。 ## 出了什么问题，以及它教会了我什么 保留诚实的记录意味着要记录 pipeline 自身的失败，而不仅仅是它捕获的威胁。 一个格式错误的 RSS 条目曾经产生了一个空条目。模型完全按照 prompt 契约的要求执行了 —— 它写下了“疑似摄取失败”，而不是虚构一个威胁。**Pipeline 随后却将该通知作为威胁笔记归档到了 `vault/threats/` 中，并将该条目记录为已查看**，因为验证只检查了笔记的*结构*，而没有检查条目是否有可供分析的内容。该笔记随后被悄悄手动删除，这违反了项目自身的规则。 教训不在于“模型不可信” —— 而在于对模型的护栏并不等同于对围绕它的系统的护栏。现在，摄取失败会在消耗 `claude` 调用之前被捕获（`run.is_enrichable`），并且审计追踪会在 `finally` 块中记录所有的结果，包括失败。 构建该项目还发现，测试套件几个月来一直在向生产审计日志中写入数据 —— 25 条记录中有 12 条是 pytest 留下的痕迹。它们已被一个记录了自身删除操作的脚本移除，而现在的 `conftest.py` 使得这种事情在结构上变得不再可能。 ## 知识图谱 每个威胁笔记都会通过 wikilink 链接到它引用的恶意软件家族、MITRE ATT&CK 技术和威胁行为者；存根页面会被自动创建，因此 Obsidian 的图谱视图可以展示真实的关系 —— 哪些家族使用了哪些技术，哪些 CVE 聚集在哪里。 每次运行还会导出 `vault/docs/attack-layer.json`，这是一个 [ATT&CK Navigator](https://mitre-attack.github.io/attack-navigator/) 图层，根据引用某项技术的笔记数量对其进行评分（打开现有图层 → 从本地上传）。它展示的是观察到的活动，而不是抽象的 ATT&CK 覆盖率 —— 这是数据所支持的唯一主张。 每次运行还会将每个威胁笔记对应的一个 [STIX 2.1](https://oasis-open.github.io/cti-documentation/) bundle 导出到 `vault/docs/stix/` —— Vulnerability/Malware/AttackPattern/Indicator 对象仅根据笔记已经断言的内容（经过 schema 验证的 frontmatter 以及观察到的 IOCs 表）构建，因此它可以输入给 MISP、TheHive/Cortex 或任何其他使用 STIX 的平台。 Malware、technique 和 CVE 对象具有确定性 ID（UUIDv5，而非随机），因此相同的家族或 CVE 在引用它的每个笔记中都会解析为同一个对象。参见 `pipeline/stix.py`。 可选地，`pipeline/misp.py` 会将这些相同的 bundle 作为 event 推送到 [MISP](https://www.misp-project.org/) 实例中 —— IOC 作为 attribute，家族/技术作为 tag。默认关闭（不设置 `MISP_URL`/`MISP_API_KEY`，与 VirusTotal/AbuseIPDB/GreyNoise 使用相同的可选 key 模式）；关于如何通过 Docker 搭建本地实例，请参见 `docs/MISP-SETUP.md`。  *威胁笔记（冗长的带日期标题）链接到了它们引用的 ATT&CK 技术和恶意软件家族。`T1190` 位于 KEV 集群的中心；`Agent Tesla` 和 `AdaptixC2` 引入了各自的技术。这里没有任何东西是手动绘制的 —— 连线是富化过程写入的 wikilink，而存根页面是自动创建的。* ## 设置 ``` git clone
标签：逆向工具