adrienclaire/threat-intel-rag

# threat-intel-rag 面向安全分析师的本地优先威胁情报检索助手。 这个 MVP 从一个紧凑的本地安全语料库中回答分析师的问题，并返回其引用的段落。它被刻意设计得简单且透明：优先使用词法检索，并为后续升级到 embedding 或完整的 RAG pipeline 保留清晰的路径。 ## 为什么创建这个仓库 安全问题通常可以从已知参考资料中找到答案，但这些上下文散布在 ATT&CK 技术、安全公告、分析师笔记和响应指南中。本项目展示了一个小型检索工作流，在生成每个回答时都会附带引用的源材料。 它被设计为一个可用于作品集展示的示例，展示了： - 网络安全知识检索 - 可解释的本地优先 AI 架构 - FastAPI 服务设计 - 可测试的 Python 代码 - 从 MVP 到生产级 RAG 的现实路径 ## 功能 - 加载紧凑的 JSON 安全参考语料库 - 从 `data/notes/` 摄取可选的 markdown 分析师笔记 - 在本地对每份文档进行 token 化处理 - 使用紧凑的 BM25 风格词法 ranker 对文档进行评分 - 返回由最匹配段落合成的答案 - 保留引用信息，包含 `doc_id`、`title`、`source`、`source_url`、score 和段落片段 - 提供小型的 FastAPI API 和浏览器 UI ## 当前语料库 演示语料库包含了受常见安全参考类型启发的示例： - MITRE ATT&CK 风格的技术 - 供应商安全公告风格的漏洞说明 - CISA 风格的勒索软件防范指南 该语料库被刻意设置得很小，以便于轻松检查和解释检索行为。 ## 架构 ``` Analyst question | v FastAPI /query endpoint | v retriever.py -> lexical scoring over loaded documents | v answer + citations ``` 关键文件： - `app/main.py` — FastAPI 应用和请求验证 - `app/indexer.py` — 语料库加载和 token 化 - `app/retriever.py` — 排序和答案构建 - `data/corpus.json` — 紧凑的演示安全语料库 - `tests/` — retriever、API 和语料库质量测试 ## 技术栈 - Python 3.12+ - FastAPI - Uvicorn - Pytest ## API endpoint | 方法 | 路径 | 用途 | |---|---|---| | `GET` | `/` | 用于分析师查询的小型浏览器 UI | | `GET` | `/health` | 服务健康检查 | | `POST` | `/query` | 提出威胁情报问题 | ## 设置 手动设置： ``` python3 -m venv .venv source .venv/bin/activate python -m pip install --upgrade pip python -m pip install -r requirements-dev.txt ``` 或使用 Makefile： ``` make install ``` ## 运行测试 ``` source .venv/bin/activate python -m pytest -q ``` 或： ``` make test ``` 预期结果： ``` 12 passed ``` ## 本地运行 ``` source .venv/bin/activate uvicorn app.main:app --reload ``` 或： ``` make run ``` 打开 API 文档： ``` http://localhost:8000/docs ``` ## 使用 Docker 运行 构建镜像： ``` make docker-build ``` 运行容器： ``` make docker-run ``` 或使用 Docker Compose： ``` make docker-up ``` API 监听地址： ``` http://localhost:8000 ``` 停止 Compose 栈： ``` make docker-down ``` ## 示例请求 ``` curl -X POST http://localhost:8000/query \ -H "Content-Type: application/json" \ -d '{"question":"How should we triage phishing that may have captured credentials?"}' ``` ## 示例响应结构 ``` { "question": "How should we triage phishing that may have captured credentials?", "answer": "Phishing: MITRE ATT&CK T1566 covers phishing techniques used to obtain credentials...", "citations": [ { "doc_id": "mitre-t1566", "title": "Phishing", "source": "MITRE ATT&CK", "source_url": "https://attack.mitre.org/techniques/T1566/", "score": 1.23, "passage": "MITRE ATT&CK T1566 covers phishing techniques used to obtain credentials or deliver malicious content" } ] } ``` ## 分析师示例问题 - `我们应该如何处理可能已窃取凭据的网络钓鱼？` - `在收到远程代码执行安全公告后，我们应该验证什么？` - `哪些迹象表明存在合法账号滥用？` - `我们应该为勒索软件防范做些什么？` - `如何检测可疑的 PowerShell 执行？` ## 公开发布检查清单 在将此仓库公开之前，请验证： - [x] 不存在真实的客户数据、密钥、token 或内部笔记 - [x] 语料库仅使用演示/安全公告风格的内容 - [x] 测试在本地通过 - [x] README 包含设置、测试和演示用法 - [x] 请求验证避免了明显的 API 错误 - [x] Docker 镜像和 Compose 演示可用 - [x] GitHub topics 已配置 - [x] 仓库可见性已按计划更改为公开 ## 路线图 接下来值得做的改进： 1. [x] 添加 TF-IDF 或 BM25 评分，同时保持引用行为不变。 2. [x] 添加用于分析师笔记的 markdown 文档摄取。 3. [ ] 在相同的 `rank_documents` 接口背后添加基于 embedding 的检索。 4. [x] 添加源 URL 和段落级别的引用范围。 5. [x] 添加一个用于分析师查询的小型 Web UI。 ## 许可证 MIT

标签：AV绕过, FastAPI, RAG, 信息检索, 威胁情报, 开发者工具, 网络安全, 网络测绘, 请求拦截, 逆向工具, 隐私保护