nikhilh-20/ThreatLoom
GitHub: nikhilh-20/ThreatLoom
一款 AI 驱动的威胁情报聚合与分析平台，自动采集安全新闻、生成结构化摘要、映射 MITRE ATT&CK，并提供语义搜索与趋势预测。
Stars: 7 | Forks: 1
# Threat Loom
AI 驱动的威胁新闻分析平台 —— 聚合、摘要与预测。
Threat Loom 自动从 RSS 订阅源和研究库中收集网络安全文章，生成带有 MITRE ATT&CK 映射动画的结构化 AI 摘要，并基于收集的数据提供自然语言搜索和趋势预测功能。
**[文档](https://nikhilh-20.github.io/ThreatLoom/)**
## 功能特性
- **Feed 聚合** —— 收录来自 13 个预配置的安全订阅源（The Hacker News, BleepingComputer, Krebs on Security, CISA 等）以及 Malpedia 研究库。基于 LLM 的相关性过滤可去除噪音。
- **AI 摘要** —— 生成结构化摘要，包含执行概览、新颖性评估、技术细节、缓解措施，以及与 MITRE ATT&CK 对齐的 3-8 个分类标签。支持 OpenAI 和 Anthropic 提供商。
- **攻击流可视化** —— 交互式杀伤链时间轴，逐阶段展示攻击序列，包含 MITRE 战术/技术映射和渐进式显示效果。
- **语义搜索** —— 基于 RAG 的聊天界面。使用自然语言提问，并从文章数据库中获取带有引用卡片的答案。
- **历史趋势分析** —— 多轮 LLM 分析，针对每个威胁类别生成季度和年度报告，包含跨时期关联性分析。结果会被缓存并显示在可折叠面板中。
- **趋势预测** —— 类别级别趋势及 3-6 个月预测。深入查看特定威胁行为者、恶意软件家族和攻击工具。生成前显示成本估算，生成后显示实际成本。
- **时间段过滤** —— 一键过滤整个 Feed 视图和所有类别分析，支持 24 小时、7 天、30 天或 90 天回溯。
- **邮件通知** —— 单篇文章邮件提醒或可配置的摘要通知（每日或每周），包含完整的结构化分析（执行摘要、新颖性、细节、缓解措施）和原始来源链接。支持配置任何 SMTP 提供商（Gmail, Outlook, SendGrid）。仅使用 Python stdlib —— 无需额外依赖。
- **Pipeline 控制** —— 按需触发的顶部按钮，用于触发 Feed 刷新（完整刷新或自上次获取以来）、为已摘要文章生成 Embedding、摄取特定文章 URL（无需完整获取 Feed），以及在阶段间中止正在运行的 Pipeline。摘要生成前显示成本估算，生成后显示实际成本。
- **自动分类** —— 文章被归类为 9 个威胁类别（恶意软件、漏洞、威胁行为者、钓鱼、供应链等），并包含针对 300 多个 MITRE ATT&CK 组织和软件家族的实体级子类别。
## 系统要求
- Python 3.10+
- OpenAI API 密钥（用于摘要、Embedding 生成和情报搜索）**或** Anthropic API 密钥（仅用于摘要；Embedding 生成仍需 OpenAI）
- Malpedia API 密钥（可选，用于研究文章摄取）
## 快速开始
### 克隆并安装
```
git clone https://github.com/nikhilh-20/ThreatLoom.git
cd ThreatLoom
python -m venv venv
```
激活虚拟环境：
```
# Linux / macOS
source venv/bin/activate
# Windows
venv\Scripts\activate
```
安装依赖：
```
pip install -r requirements.txt
```
### Windows 一键启动
双击 `run.bat` —— 它会自动创建虚拟环境、安装依赖并启动应用。
### Docker
```
OPENAI_API_KEY=sk-proj-your-key docker compose up
```
或者在 `docker-compose.yml` 中设置密钥并运行 `docker compose up`。应用将通过 `http://localhost:5000` 访问。数据（数据库和配置）保存在本地 `./data` 目录中，并在独立模式和 Docker 模式之间共享。
有关所有支持的选项，请参阅下方的[环境变量](#environment-variables)。
### 运行（不使用 Docker）
```
python app.py
```
应用会初始化数据库、同步订阅源、启动后台调度器，并在浏览器中打开仪表板（默认端口为 5000，如被占用则自动选择下一个可用端口）。
## 配置
首次运行时，会创建一个包含默认设置的 `data/config.json` 文件。您可以直接编辑它，或使用 Web 界面中的设置页面。
```
{
"openai_api_key": "",
"openai_model": "gpt-4o-mini",
"anthropic_api_key": "",
"anthropic_model": "claude-haiku-4-5-20251001",
"llm_provider": "openai",
"fetch_interval_minutes": 30,
"malpedia_api_key": "",
"report_token": "",
"feeds": [
{"name": "The Hacker News", "url": "https://feeds.feedburner.com/TheHackersNews", "enabled": true},
{"name": "BleepingComputer", "url": "https://www.bleepingcomputer.com/feed/", "enabled": true},
...
]
}
```
### 环境变量
API 密钥和服务器设置可以通过环境变量配置，环境变量优先级高于 `config.json`。这是 Docker 部署的推荐方式。
| 变量 | 默认值 | 描述 |
|---|---|---|
| `OPENAI_API_KEY` | — | OpenAI API 密钥（覆盖 `config.json`） |
| `ANTHROPIC_API_KEY` | — | Anthropic API 密钥（覆盖 `config.json`；当 `llm_provider` 为 `anthropic` 时使用） |
| `MALPEDIA_API_KEY` | — | 可选 Malpedia API 密钥（覆盖 `config.json`） |
| `HOST` | `127.0.0.1` | 绑定地址（Docker 中为 `0.0.0.0`） |
| `PORT` | 自动检测 | 监听端口（Docker 中为 `5000`） |
| `DATA_DIR` | `./data` | `config.json` 和 `threatlandscape.db` 的目录（Docker 中为 `/app/data`） |
| `SMTP_HOST` | — | SMTP 服务器主机名（例如 `smtp.gmail.com`） |
| `SMTP_PORT` | `587` | SMTP 服务器端口 |
| `SMTP_USERNAME` | — | SMTP 登录用户名 |
| `SMTP_PASSWORD` | — | SMTP 登录密码或应用专用密码 |
| `NOTIFICATION_EMAIL` | — | 收件人邮箱（设置后自动启用通知） |
### 设置您的 API 密钥
1. 打开应用并导航至 **Settings** (设置)
2. 选择您的 LLM 提供商（**OpenAI** 或 **Anthropic**）
3. 输入您的 API 密钥并点击 **Test** (测试) 进行验证
4. 选择您偏好的模型（见下表）
5. 点击 **Save Settings** (保存设置)
### 添加订阅源
通过设置页面或直接在 `config.json` 中添加自定义 RSS/Atom 订阅源：
```
{"name": "My Custom Feed", "url": "https://example.com/feed.xml", "enabled": true}
```
### 默认订阅源
| 来源 | 启用 |
|---|---|
| The Hacker News | 是 |
| BleepingComputer | 是 |
| Krebs on Security | 是 |
| SecurityWeek | 是 |
| Dark Reading | 是 |
| CISA Alerts | 是 |
| Sophos News | 是 |
| Infosecurity Magazine | 是 |
| HackRead | 是 |
| SC Media | 是 |
| Cyber Defense Magazine | 否 |
| The Record | 是 |
| Schneier on Security | 是 |
### LLM 模型
**OpenAI**
| 模型 | 适用场景 |
|---|---|
| `gpt-4o-mini` | 日常使用 —— 快速、高性价比（默认） |
| `gpt-4o` | 更高质量的摘要和洞察 |
| `gpt-4-turbo` | 复杂分析任务 |
| `gpt-3.5-turbo` | 预算敏感型处理 |
**Anthropic**
| 模型 | 适用场景 |
|---|---|
| `claude-haiku-4-5-20251001` | 日常使用 —— 快速、高性价比（默认） |
| `claude-sonnet-4-6` | 更高质量的摘要和洞察 |
| `claude-opus-4-6` | 最高质量，复杂分析 |
无论选择哪个提供商，Embedding 始终使用 `text-embedding-3-small`（1536 维）。
## 工作原理
应用以可配置的间隔（默认：每 30 分钟）运行自动化 Pipeline。您也可以从仪表板手动触发。
```
RSS Feeds / Malpedia
|
Relevance Filter (LLM batch classification)
|
Scrape Article Content (trafilatura)
|
AI Summarization (structured JSON → markdown)
|
Email Notification (per article, if enabled)
|
Vector Embeddings (text-embedding-3-small)
|
Browse · Search · Forecast
```
**Pipeline 阶段：**
1. **Fetch (获取)** —— 从启用的订阅源下载 RSS/Atom 条目，按日期过滤，按 URL 去重，通过 LLM 批量分类相关性
2. **Malpedia** —— 解析 BibTeX 参考书目，执行相同的相关性过滤（需要 API 密钥）
3. **Scrape (抓取)** —— 使用模拟浏览器的请求头下载文章 HTML，使用 trafilatura 提取文本（每篇文章超时 30 秒）
4. **Cost Gate (成本关卡)** —— 在摘要生成前估算 API 成本并请求确认；可在此中止 Pipeline
5. **Summarize (摘要)** —— 生成包含执行概览、新颖性、细节、缓解措施、标签和攻击流的结构化摘要（12,000 字符输入限制）
6. **Notify (通知)** —— 为每篇已摘要文章发送包含完整分析的邮件提醒（如已启用；失败不会阻塞 Pipeline）
7. **Embed (向量化)** —— 为语义搜索生成 1536 维向量（每批 50 个）
每个阶段仅处理新/未处理的文章。Pipeline 是非阻塞的 —— 运行期间您可以继续浏览。
## 项目结构
```
app.py # Flask web server, all routes and API endpoints
config.py # Configuration loading/saving (config.json)
database.py # SQLite interface, schema, categorization engine
scheduler.py # Background pipeline orchestration (APScheduler)
feed_fetcher.py # RSS/Atom feed ingestion with relevance filtering
malpedia_fetcher.py # Malpedia BibTeX research ingestion
article_scraper.py # HTML download and text extraction (trafilatura)
summarizer.py # LLM summarization, relevance checks, trend/forecast insights
llm_client.py # LLM provider abstraction (OpenAI and Anthropic)
cost_tracker.py # Per-session token and cost tracking
notifier.py # Email notifications via SMTP (stdlib only)
embeddings.py # Vector embedding generation and cosine similarity search
intelligence.py # RAG chat system (retrieval + LLM response)
mitre_data.py # MITRE ATT&CK entity lookup tables
requirements.txt # Python dependencies
run.bat # Windows one-click launcher
Dockerfile # Container image definition
docker-compose.yml # Docker Compose service config
config.json # User configuration (created on first run)
threatlandscape.db # SQLite database (created on first run)
templates/ # Jinja2 HTML templates (dashboard, article, intelligence, settings)
static/ # CSS (dark theme), JavaScript (client-side logic), and images
docs/ # MkDocs documentation source
mkdocs.yml # MkDocs configuration
```
## API 端点
所有端点均返回 JSON。Base URL: `http://127.0.0.1:
`
### 文章
| 方法 | 端点 | 描述 |
|---|---|---|
| GET | `/api/articles` | 分页文章列表（参数：`source_id`, `search`, `tag`, `page`, `limit`） |
| GET | `/api/articles/` | 单篇文章及其完整摘要 |
| GET | `/api/articles/categorized` | 按威胁类别分组的文章（参数：`days`） |
| DELETE | `/api/articles//summary` | 删除某篇文章的 AI 摘要和 Embedding |
### 来源与统计
| 方法 | 端点 | 描述 |
|---|---|---|
| GET | `/api/sources` | 所有配置的订阅源 |
| GET | `/api/stats` | 数据库统计（文章、来源、摘要、待处理/失败计数、has_api_key） |
### Pipeline 控制
| 方法 | 端点 | 描述 |
|---|---|---|
| POST | `/api/refresh` | 触发手动 Pipeline（请求体：`{"days": 1, "since_last_fetch": false}`） |
| GET | `/api/refresh-status` | 轮询 Pipeline 状态（阶段、成本估算、中止状态） |
| POST | `/api/abort` | 在阶段之间中止正在运行的 Pipeline |
| POST | `/api/embed` | 为所有尚无 Embedding 的已摘要文章生成 Embedding |
| POST | `/api/ingest-urls` | 抓取并摘要特定文章 URL，无需完整获取 Feed |
| POST | `/api/clear-db` | 删除文章/摘要；请求体 `{"days": N}` 限制为早于 N 天的文章（0 = 全部） |
### 类别与洞察
| 方法 | 端点 | 描述 |
|---|---|---|
| GET | `/api/subcategories` | 类别内的实体细分（参数：`category`, `limit`, `days`） |
| GET | `/api/category-insight` | 趋势 + 3-6 个月预测（参数：`category`, `subcategory`, `days`） |
| GET | `/api/trend-analysis` | 历史季度 + 年度趋势分析（参数：`category`, `subcategory`, `days`） |
| GET | `/api/insight-estimate` | 生成洞察或趋势前的成本估算（参数：`category`, `subcategory`, `days`, `type`） |
### 情报
| 方法 | 端点 | 描述 |
|---|---|---|
| POST | `/api/intelligence/chat` | RAG 聊天（请求体：`{"messages": [{"role": "user", "content": "..."}]}`） |
| POST | `/api/intelligence/search` | 语义搜索（请求体：`{"query": "...", "top_k": 15}`） |
| GET | `/api/intelligence/status` | Embedding 索引统计 |
### 设置
| 方法 | 端点 | 描述 |
|---|---|---|
| POST | `/api/settings` | 保存配置（包括邮件通知设置） |
| POST | `/api/test-key` | 验证 OpenAI API 密钥 |
| POST | `/api/test-malpedia-key` | 验证 Malpedia API 密钥 |
| POST | `/api/test-email` | 发送测试邮件通知（请求体接受 SMTP 设置） |
| POST | `/api/report` | 向开发者发送 LLM 输出报告邮件（请求体：`{"type", "identifier", "llm_content", "metadata", "user_note", "token"}`） |
## 数据库
启用 WAL 模式的 SQLite。七张表：
- **sources** —— 订阅源定义和最后获取时间戳
- **articles** —— 摄取的文章（标题、URL、作者、日期、抓取的内容、图片）
- **summaries** —— AI 摘要、标签 (JSON)、攻击流 (JSON)、使用的模型
- **article_embeddings** —— 存储为 BLOB 的 1536 维32 向量
- **category_insights** —— 缓存的趋势/预测文本，带基于哈希的失效机制（24 小时 TTL）
- **trend_analyses** —— 缓存的季度和年度历史趋势报告，带基于哈希的失效机制
- **article_correlations** —— 相关文章之间的关系
文章去重通过 URL 上的 UNIQUE 约束强制执行。线程本地连接确保了来自 Flask、调度器和爬虫线程池的安全并发访问。
## 文档
完整文档可通过 MkDocs 查看：
```
pip install mkdocs-material
mkdocs serve
```
然后打开 `http://localhost:8000`。涵盖主题：架构、配置参考、功能深入解析、完整 API 参考、数据库 Schema 和贡献指南。
部署到 GitHub Pages：
```
mkdocs gh-deploy
```
## 技术栈
| 组件 | 技术 |
|---|---|
| Web 框架 | Flask |
| Feed 解析 | feedparser |
| 内容提取 | trafilatura |
| AI / LLM | OpenAI (GPT-4o-mini/4o, text-embedding-3-small), Anthropic (Claude Haiku/Sonnet/Opus) |
| 调度 | APScheduler |
| 数据库 | SQLite (WAL 模式) |
| 向量搜索 | numpy (余弦相似度) |
| 前端 | Vanilla JS, marked.js (Markdown 渲染) |
| 威胁分类法 | MITRE ATT&CK (组织、软件、技术) |
## 免责声明
本工具完全由 [Claude Code](https://claude.ai/claude-code) (Anthropic) 生成。其提供 strictly 用于**教育和信息目的**。严禁将本工具用于任何恶意目的，这可能违反适用法律。作者不对任何滥用行为负责。作者按**“原样”提供本工具，不附带任何形式的保证**，无论是明示或暗示的，并且对因其使用而产生的任何损害或后果不承担责任。
Threat Loom Logo 由 [Nano Banana](https://gemini.google/overview/image-generation/) 使用 Gemini 图像生成技术创作。
## 许可证
BSD-3-Clause标签：AI新闻分析, Anthropic, CIS基准, Cloudflare, DLL 劫持, Docker, HTTP/HTTPS抓包, Kill Chain, MITRE ATT&CK, OpenAI, Petitpotam, Python, RAG, RSS聚合, Ruby, 内存规避, 向量搜索, 大语言模型, 威胁情报, 威胁预测, 安全运营, 安全防御评估, 开发者工具, 态势感知, 扫描框架, 攻击链可视化, 无后门, 漏洞预警, 知识库, 网络安全, 自动化报告, 语义搜索, 请求拦截, 趋势分析, 逆向工具, 隐私保护