内容
> [!IMPORTANT]
> **本仓库已停用。** 它不再被维护。
本软件包现已成为 **[AppliedIR/sift-mcp](https://github.com/AppliedIR/sift-mcp)** 聚合仓库的一部分。
文档： [appliedir.github.io/aiir](https://appliedir.github.io/aiir/)
---
# RAG-MCP：事件响应知识服务器
提供来自 23 个权威安全来源的事件响应知识的语义搜索的 MCP 服务器。
## 安装选项
### 选项 A：作为 Claude-IR 的一部分（推荐）
该 MCP 是作为 [Claude-IR](https://github.com/scriptedstatement/claude-ir) AI 辅助事件响应工作站的组件而设计的。
```bash
git clone https://github.com/scriptedstatement/claude-ir.git
cd claude-ir
./setup.sh
claude
```
**使用 Claude-IR 安装的好处：**
- 带有组件选择的引导式设置
- 预配置的 MCP 集成
- 与 windows-triage-mcp（文件验证）和 opencti-mcp（威胁情报）配合使用
- 法医学科规则和调查工作流程
### 选项 B：独立安装
在您只需要 RAG 搜索而不需要完整的 IR 工作站时使用独立安装。
```bash
git clone https://github.com/scriptedstatement/forensic-rag-mcp.git
cd forensic-rag-mcp
# 创建虚拟环境
python3 -m venv .venv
source .venv/bin/activate
# 安装依赖
pip install -e .
# 构建索引（获取在线源，约 5 分钟）
python -m rag_mcp.build
# 检查状态
python -m rag_mcp.status
# 运行 MCP 服务器（用于 Claude Code 集成）
python -m rag_mcp.server
```
**详细设置选项（在线源 vs. 自定义内容）：** 请参阅 `SETUP.md`
## 功能
- **23 个在线源**: 自动与权威安全存储库同步
- **语义搜索**: BGE 嵌入与 ChromaDB 矢量存储
- **MCP 集成**: 用于 Claude Code 的工具（搜索、列出源、获取统计信息）
- **用户文档**: 通过监视文件夹或一次性摄入添加您自己的知识
- **增量更新**: 快速刷新而无需完全重建
- **文件系统安全性**: 基于 Sentinel 的删除保护，防止意外数据丢失
- **网络强化**: 仅 HTTPS、大小限制、重试和退避、SSRF 保护
- **精确源过滤**: 确定的 `source_ids` 过滤器，用于获取可靠的结果
## 在线源
| 源 | 描述 | 记录数 |
|--------|-------------|---------|
| sigma | SigmaHQ 检测规则 | ~3,100 |
| mitre_attack | MITRE ATT&CK（技术、组、恶意软件、战役、缓解措施） | ~2,100 |
| atomic | Atomic Red Team 测试 | ~1,800 |
| elastic | Elastic 检测规则 | ~1,500 |
| cisa_kev | CISA 已知利用漏洞 | ~1,500 |
| capec | MITRE CAPEC 攻击模式 | ~1,500 |
| splunk_security | Splunk 安全内容 | ~1,000 |
| kape | KAPE 目标和模块 | ~800 |
| forensic_artifacts | ForensicArtifacts 定义 | ~700 |
| hijacklibs | DLL 劫持数据库 | ~600 |
| loldrivers | LOLDrivers 漏洞驱动器数据库 | ~500 |
| mitre_d3fend | MITRE D3FEND 对策 | ~490 |
| gtfobins | GTFOBins（Linux） | ~450 |
| velociraptor | Velociraptor 制品 | ~300 |
| lolbas | LOLBAS 项目 | ~130 |
| mitre_car | MITRE CAR 分析 | ~100 |
| stratus_red_team | 云攻击技术 | ~80 |
| mbc | MITRE MBC 恶意软件行为目录 | ~650 |
| mitre_atlas | MITRE ATLAS AI/ML 攻击框架 | ~50 |
| mitre_engage | MITRE Engage 对手参与 | ~45 |
| chainsaw | Chainsaw 法医检测规则 | ~110 |
| hayabusa | Hayabusa 内置检测规则 | ~190 |
| forensic_clarifications | 权威法医制品澄清 | 5 |
## 命令
### 构建索引
```bash
# 完整构建（获取所有源）
python -m rag_mcp.build
# 仅使用缓存源（离线模式）
python -m rag_mcp.build --skip-online
# 强制重新获取所有源
python -m rag_mcp.build --force-fetch
# 预览将要构建的内容
python -m rag_mcp.build --dry-run
```
### 刷新索引
```bash
# 检查更新并应用
python -m rag_mcp.refresh
# 仅检查（不应用）
python -m rag_mcp.refresh --check-only
# 刷新特定源
python -m rag_mcp.refresh --source sigma
```
### 检查状态
```bash
# 显示状态
python -m rag_mcp.status
# JSON 输出
python -m rag_mcp.status --json
# 跳过更新检查（更快）
python -m rag_mcp.status --no-check
```
## 捆绑参考内容
`knowledge/` 文件夹随附两个参考源的 JSONL 提取，包含在内：
| 源 | 原始位置 |
|--------|-------------------|
| **SANS 海报** | https://www.sans.org/posters |
| **应用事件响应** | https://www.appliedincidentresponse.com/resources |
这些在 `rag_mcp.build` 期间自动索引。 要在不包含捆绑内容的情况下构建，请使用 `--no-bundled`。
## 用户文档
### 监视文档（knowledge/ 文件夹）
将文件放在 `knowledge/` - 它们将在构建/刷新时自动索引：
```
knowledge/
├── my-playbook.md # Markdown
├── ioc-list.txt # 纯文本
└── detections.jsonl # JSONL 记录
```
支持的格式： `.txt`, `.md`, `.json`, `.jsonl`
### 一次性摄入
对于您不想保存在磁盘上的敏感文档：
```bash
# 摄入并附上友好名称
python -m rag_mcp.ingest /path/to/doc.txt --name "my-doc"
# 列出摄入的文档
python -m rag_mcp.ingest --list
# 删除特定文档
python -m rag_mcp.ingest --remove "my-doc"
# 删除所有摄入的文档
python -m rag_mcp.ingest --remove-all
```
## MCP 工具
当作为 MCP 服务器运行时，暴露这些工具：
| 工具 | 描述 |
|------|-------------|
| `search` | 带有可选过滤器的语义搜索 |
| `list_sources` | 列出可用的知识源 |
| `get_stats` | 获取索引统计信息 |
### 搜索过滤器
```python
# 按源过滤
search(query="credential dumping", source="sigma")
# 按 MITRE 技术过滤
search(query="persistence", technique="T1053")
# 按平台过滤
search(query="privilege escalation", platform="windows")
```
## MCP 配置
添加到您的 MCP 配置（例如 `.claude/mcp.json`）：
```json
{
"mcpServers": {
"rag-knowledge": {
"command": "/path/to/forensic-rag-mcp/.venv/bin/python",
"args": ["-m", "rag_mcp.server"],
"cwd": "/path/to/forensic-rag-mcp",
"env": {
"PYTHONPATH": "/path/to/forensic-rag-mcp/src"
}
}
}
}
```
## 配置
设置通过 `Config` 数据类（`config.py`）使用显式 `validate()` 方法和 `get_config()` 中的全局单例缓存进行加载。 设置 `RAG_LOG_FORMAT=json` 以进行结构化 JSON 日志记录。
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `RAG_INDEX_DIR` | `./data` | ChromaDB 位置 |
| `RAG_KNOWLEDGE_DIR` | `./knowledge` | 用户文档 |
| `RAG_MODEL_NAME` | `BAAI/bge-base-en-v1.5` | 嵌入模型 |
| `GITHUB_TOKEN` | （可选） | 更高的 API 速率限制（参见安全部分） |
| `RAG_MAX_DOWNLOAD_BYTES` | `62914560` （60MB） | 网络获取的最大下载大小 |
| `RAG_ALLOW_HTTP` | `false` | 允许 HTTP（不推荐；默认强制 HTTPS） |
| `RAG_FETCH_MAX_RETRIES` | `3` | 暂态网络故障的最大重试次数 |
| `RAG_MAX_TOP_K` | `50` | 查询的最大 top_k |
| `RAG_MAX_QUERY_LENGTH` | `1000` | 最大查询字符串长度 |
| `RAG_LOG_FORMAT` | `text` | 日志格式："text" 或 "json" |
## 项目结构
```
rag-mcp/
├── src/rag_mcp/
│ ├── server.py # MCP 服务器
│ ├── index.py # 搜索引擎包装器
│ ├── sources.py # 在线源管理（23 个源）
│ ├── ingest.py # 用户文档处理
│ ├── build.py # 完整索引构建器
│ ├── refresh.py # 增量更新
│ ├── status.py # 状态报告
│ ├── config.py # 集中式配置管理
│ ├── fs_safety.py # 文件系统安全防护
│ ├── constants.py # 项目范围的常量
│ └── utils.py # 共享实用程序
├── data/ # 构建的索引（gitignored，用户重建）
│ ├── chroma/ # ChromaDB 矢量存储
│ ├── sources/ # 缓存的在线源 JSONL
│ └── *.json # 状态文件
├── knowledge/ # 用户文档 - .txt, .md, .json, .jsonl（监视文件夹）
└── tests/ # 测试套件
```
## 分数解释
| 分数 | 质量 | 操作 |
|-------|---------|--------|
| 0.85+ | 优秀 | 高置信度匹配 |
| 0.75-0.84 | 良好 | 相关结果 |
| 0.65-0.74 | 一般 | 可能切线 |
| < 0.65 | 弱 | 可能不相关 |
## 查询分析和调优
该系统包括用于监控查询质量和基于实际使用模式调优阈值的工具。
### 日志设置
**默认情况下查询日志关闭** 以保护隐私。 查询文本原样记录，可能包括敏感的搜索词。 仅在您了解隐私影响时启用日志记录。
**隐私考虑因素：**
- 查询日志包含用户搜索的确切文本
- 在受监管的环境中（HIPAA、SOX 等），考虑加密存储日志文件
- 确保日志文件权限限制访问权限
要启用查询日志记录，您必须显式添加处理程序：
```python
# 在您的日志记录配置中
import logging
# 创建处理程序 FIRST
metrics_handler = logging.FileHandler("logs/query_metrics.log")
attention_handler = logging.FileHandler("logs/attention.log")
# 获取记录器并添加处理程序（这启用日志记录）
metrics_logger = logging.getLogger("rag_mcp.query_metrics")
metrics_logger.setLevel(logging.INFO)
metrics_logger.addHandler(metrics_handler)
metrics_logger.propagate = True # 如果您还希望控制台输出，请启用传播
attention_logger = logging.getLogger("rag_mcp.attention")
attention_logger.setLevel(logging.WARNING)
attention_logger.addHandler(attention_handler)
attention_logger.propagate = True
```
### 分析和调优
定期运行分析工具以审查查询性能并调整阈值：
```bash
# 完整交互工作流（分析、推荐、批准）
python -m rag_mcp.analyze_queries
# 仅查看报告而不进行更改
python -m rag_mcp.analyze_queries --report-only
# 分析最近 7 天仅
python -m rag_mcp.analyze_queries --since 7d
# 设置批准者名称以进行审计跟踪
python -m rag_mcp.analyze_queries --approver "your-name"
# 将分析结果导出为 JSON
python -m rag_mcp.analyze_queries --export analysis.json
```
### 交互式工作流
该工具设计用于人类操作员和 AI 代理：
1. **分析**：读取查询日志并计算统计信息
2. **报告**：显示查询类型分解、关注问题、内容空白
3. **建议**：生成具有理由的具体调优建议
4. **批准**：提示对每个建议进行 Y/N 批准
5. **应用**：将批准的更改保存到 `data/tuning_config.json`
6. **审计跟踪**：记录谁批准了每个更改以及原因
示例会话：
```
$ python -m rag_mcp.analyze_queries
Analyzing query logs...
======================================================================
RAG 查询分析报告
======================================================================
期间：2026-01-15 08:00 至 2026-02-02 10:30
分析的查询总数：1523
----------------------------------------------------------------------
查询类型统计
----------------------------------------------------------------------
类型 计数 平均 P25 最小 低%
----------------------------------------------------------------------
general 892 0.712 0.645 0.412 8.2%
mitre_id 456 0.789 0.715 0.521 3.1%
detection 175 0.698 0.621 0.445 12.0%
======================================================================
建议
======================================================================
[1] 将检测阈值从 0.55 降低到 0.52
类型：threshold
置信度：中等
受影响的查询：21
理由：12.0% 的 175 个查询得分低于当前阈值。
----------------------------------------------------------------------
需要批准
----------------------------------------------------------------------
[1/1] 将检测阈值从 0.55 降低到 0.52
理由：12.0% 的 175 个查询得分低于当前阈值。
更改：0.55 -> 0.52
置信度：中等
是否批准？ [Y/N/Q]：y
-> 已批准
1 个更改已应用并保存到 tuning_config.json
```
### 什么会被标记
关注日志记录器会标记这些情况以供审查：
| 条件 | 含义 | 操作 |
|-----------|---------|--------|
| `zero_results` | 未找到匹配项 | 内容空白 - 添加相关数据 |
| `low_score:<score>` | 最高分数低于 0.50 | 语义匹配较差 |
| `unknown_mitre_ids:<ids>` | MITRE ID 不在查找表中 | 需要数据刷新 |
| `weak_mitre_match:<score>` | MITRE 查询得分低于 0.60 | 检查增强 |
### 调优配置
批准的更改保存到 `data/tuning_config.json`:
```json
{
"version": "1.0",
"thresholds": {
"general": 0.50,
"mitre_id": 0.55,
"detection": 0.52,
"forensic": 0.55
},
"source_boosts": {
"forensic_clarifications": 1.15
},
"keyword_boost": 1.15,
"last_modified": "2026-02-02T10:45:00",
"last_modified_by": "analyst",
"modification_history": [...]
}
```
索引在启动时自动加载此配置。
### 安全边界
自动建议保持在安全范围内：
- 阈值：0.40 - 0.70（永远不会太宽容或限制）
- 提升：1.0 - 1.30（最大 30% 提升）
### 审计跟踪
调优配置维护修改历史以便追责：
- `tuning_config.json` 中保留最多 100 条记录
- 当达到限制时，旧条目在删除前记录
- 每个条目记录：时间戳、参数、旧/新值、批准者、原因
用于长期审计保留，请配置日志记录以捕获 `rag_mcp.tuning_config` INFO 消息到持久的日志聚合器。
## 安全
### 文件系统安全
构建系统使用基于 Sentinel 的删除保护以防止意外数据丢失：
- 管理目录包含 `.rag_mcp_managed` Sentinel 文件
- **所有删除** 都通过具有完整安全检查的 `safe_rmtree()` 进行
- Sentinel 要求可以为首次设置放松，但所有其他保护措施保持不变
- 禁止路径（/、/home、/root 等）无论 Sentinel 如何阻止
- 最小深度检查防止删除顶级目录
- 根容器确保删除操作在项目边界内
### 网络强化
所有网络获取包括多个安全层：
| 保护措施 | 描述 |
|------------|-------------|
| **仅 HTTPS** | 默认拒绝 HTTP URL（可配置） |
| **大小限制** | 下载上限为 60MB 以防止资源耗尽 |
| **主机允许列表** | 仅允许批准的主机（github.com、raw.githubusercontent.com 等） |
| **IP 字面量阻止** | 直接 IP 地址阻止以防止 SSRF |
| **重定向验证** | 重定向目标必须在允许列表上 |
| **重试和退避** | 暂态故障（429、5xx、超时）带有指数退避 |
### GITHUB_TOKEN 权限
如果您设置 `GITHUB_TOKEN` 以获得更高的 API 速率限制，请使用最小权限：
```bash
# 创建细粒度个人访问令牌：
# - 公共仓库（只读） - 不需要其他权限
# - 不访问私有仓库
# - 不写权限
export GITHUB_TOKEN="github_pat_..."
令牌仅用于：
- 检查最新的提交 SHA 版本（版本检测）
- 检查最新的发布标签
- 克隆公共仓库
**永远不要使用具有写访问权限或私有仓库访问权限的令牌。**
### 依赖项扫描
定期扫描依赖项以便知晓已知漏洞：
```bash
# 安装 pip-audit
pip install pip-audit
# 扫描漏洞
pip-audit
# 或使用 requirements 文件
pip-audit -r requirements.txt
```
考虑添加到 CI/CD 管道以便自动扫描。
### 网络暴露警告
MCP 服务器使用 **stdio 传输**（stdin/stdout）。这是本地使用时安全的。
**不要暴露此服务器在网络**而不进行额外的强化：
- 没有身份验证
- 没有速率限制
- 没有 TLS/加密
如果需要网络访问，请将其放在经过身份验证的反向代理后面并进行速率限制。
## 需求
- Python 3.10+
- 约 2GB 磁盘空间（模型 + 索引）
- 搜索操作约 1GB RAM
## 致谢
架构和方向由 Steve Anson 提供。由 Claude Code（Anthropic）实现。
## 许可
MIT
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器