Labeeb2339/cyber-rag
GitHub: Labeeb2339/cyber-rag
该项目是一个完全本地的网络安全 RAG 原型，旨在通过混合检索和 MITRE ATT&CK 图谱锚定，在保护查询隐私的同时提升本地小模型在威胁情报任务中的表现。
Stars: 0 | Forks: 0
# CyberRAG
**一个完全本地的网络安全 RAG 原型，具备混合检索、MITRE ATT&CK 图谱锚定、带引用的回答以及可重复的评估框架。**
*根据已提交的 15 个问题试点快照生成。平均确定性
关键词覆盖率从 0.627 增加到 0.843，预期文档在
14/15 的问题中出现在前五名，并且平均延迟增加了 2.694 秒。
这是一个小规模的本地试点，并非生产环境验证或云模型平价基准。*
我构建 CyberRAG 是为了探索一个实际问题：在将查询时的数据
保留在用户机器上的前提下，检索能在多大程度上提升小型本地模型在
威胁情报任务上的表现？
我开展这个项目是为了响应 CyberSecurity Malaysia 的一份挑战赛简报。它是
一个独立的原型，并非 CyberSecurity Malaysia 的官方委托、
部署或认可的产品。
## 它展示了什么
- **私密的查询路径：** embeddings、检索、reranking、图查找和生成通过本地 Ollama 模型运行。
- **混合检索：** 密集向量 + BM25 + reciprocal-rank fusion，并对 CVE、ATT&CK、CAPEC 和 CWE 标识符提供精确加权。
- **图谱锚定：** MITRE ATT&CK 关系支持有关组织、恶意软件、技术和缓解措施的多跳问题。
- **证据优先的回答：** 检索到的段落和图事实被传递给 prompt，该 prompt 要求内联引用并拒绝不受支持的标识符。
- **将评估作为工程：** 固定的问题集用于衡量关键词覆盖率、检索命中率、模型评委得分和延迟。
## 试点基准测试
已提交的 [15 个问题结果快照](eval/results_2026-06-22_1901.json) 比较了相同本地模型在使用和不使用 CyberRAG 情况下的表现：
| 指标 | 仅本地模型 | 本地模型 + CyberRAG |
|---|---:|---:|
| Keyword coverage | 0.627 | **0.843** |
| Context hit rate | — | **0.933** |
| Model-judge score | 0.427 | **0.647** |
| Mean latency | 11.95 s | 14.65 s |
确定性指标显示出更强的事实覆盖率和检索能力。模型评委的结果是方向性的：原始快照没有记录每个得分是来自外部评委还是本地回退。当前的运行器会记录所选的评委后端，以便未来的结果是可审计的。
这是一个小型的试点基准测试，并非云模型平价或具备生产环境就绪状态的证明。
## 架构
```
flowchart LR
Q[Question] --> R{Route}
R -->|Entity or relationship| KG[MITRE ATT&CK graph]
R --> V[Vector retrieval]
R --> B[BM25 retrieval]
V --> F[RRF + exact-ID boost]
B --> F
F --> RR[Local reranker]
KG --> P[Grounded prompt]
RR --> P
P --> L[Local Ollama model]
L --> A[Answer + citations]
```
| 层级 | 默认实现 |
|---|---|
| Embeddings | 通过 Ollama 的 `nomic-embed-text` |
| Vector store | ChromaDB，本地存储 |
| Lexical retrieval | BM25 |
| Rank fusion | Reciprocal Rank Fusion + exact-ID boost |
| Knowledge graph | 基于 MITRE ATT&CK STIX 的 NetworkX |
| Generator / reranker | 通过 Ollama 的 `qwen2.5-coder:7b` |
设计详情请参见 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)。
## 快速开始
### 环境要求
- Python 3.11+
- 本地运行 [Ollama](https://ollama.com/)
- 足够的本地存储空间和内存，用于所选模型和生成的索引
```
git clone https://github.com/Labeeb2339/cyber-rag.git
cd cyber-rag
python -m venv .venv
# Windows: .venv\Scripts\activate
# Linux/macOS: source .venv/bin/activate
python -m pip install -r requirements.txt
ollama pull nomic-embed-text
ollama pull qwen2.5-coder:7b
```
通过设置 `CYBERRAG_GEN_MODEL` 或 `CYBERRAG_EMBED_MODEL` 来覆盖默认配置，而无需修改代码。
### 构建公开数据索引
此设置阶段会下载权威的公开数据源，因此会使用网络：
```
python ingest/fetch_authoritative.py
python ingest/build_index.py
python rag/hybrid.py build
python rag/kg.py build
```
在数据源和索引存在之后，常规的查询路径均在本地执行：
```
python demo.py "Which techniques does APT29 use and how can they be detected?"
```
### 添加您自己的文档
```
python ingest/ingest_docs.py ./my_reports --source internal-cti --recursive
python rag/hybrid.py build
```
支持的文档格式包括 PDF、DOCX、Markdown、文本和 HTML。请勿提交私有文档、生成的索引或 embedding 缓存。
要在不修改代码的情况下将自定义数据源添加到完整重建中：
```
python ingest/build_index.py --extra-source "my-notes=./notes/*.md"
```
## 评估
```
# 仅本地模型 vs 本地模型 + CyberRAG
python eval/run_eval.py
# 添加本地模型 judge；后端记录在输出中
python eval/run_eval.py --judge --judge-backend local
# 使用从 stdin 读取 prompt 的外部命令
set CYBERRAG_EVAL_COMMAND=your-evaluator-command
python eval/run_eval.py --judge --judge-backend command --cloud
```
云评估是可选的，它从不属于常规的 CyberRAG 查询路径。使用 `--cloud` 或 `--judge-backend command` 可能会将 benchmark prompts 发送到已配置的外部服务。
## 测试
```
python -m pytest -q
```
单元测试涵盖了分词、停用词处理、精确安全标识符提取、reciprocal-rank fusion 以及确定性评估指标。完整的端到端评估还需要 Ollama 以及生成的语料库/索引文件。
验证 README 的基准图表是否仍然与已提交的快照相匹配：
```
python scripts/generate_readme_assets.py --check
```
## 仓库边界
包含内容：
- 摄取和查询的源代码；
- 评估问题和带有日期的结果快照；
- 架构和执行文档。
不包含：
- 生成的 Chroma/BM25/图索引；
- 下载的语料库；
- 私有的事件报告或运营 SOC 数据；
- 生产环境部署或正式安全认证的证据。
## 许可证
MIT — 请参见 [LICENSE](LICENSE)。
标签：AI风险缓解, DLL 劫持, RAG, 大语言模型, 威胁情报, 开发者工具, 本地部署, 特权检测, 网络安全, 逆向工具, 隐私保护