内容
<div align="center">
# 运行时完整性保护（RIG）
**一款智能的MCP代理，实时检测和阻止工具投毒、rug-pull和提示注入攻击。**
[](https://nextjs.org/)
[](https://react.dev/)
[](https://www.typescriptlang.org/)
[](https://tailwindcss.com/)
[](https://www.python.org/)
[](https://ai.google.dev/)
[](https://www.docker.com/)
[](https://opensource.org/licenses/MIT)
</div>
---
## 问题
**模型上下文协议（MCP）**允许大型语言模型调用外部工具，但这些工具服务器可能被入侵。攻击者可以：
- **工具投毒：** 在工具描述中注入隐藏指令以劫持大型语言模型行为。
- **Rug-Pull攻击：** 在会话中替换安全工具定义为恶意定义。
- **提示注入：** 在工具响应中嵌入`<SYSTEM>`覆盖或数据泄露命令。
**RIG位于大型语言模型客户端和MCP服务器之间**，实时检查每个JSON-RPC消息，以防止这些攻击到达模型。
---
## 架构
```mermaid
graph LR
subgraph Client
A["Claude Desktop / 大型语言模型客户端"]
end
subgraph RIG["RIG代理 - 数据平面"]
B["proxy.py — stdin/stdout桥接"]
C["rig.py — 4层检测引擎"]
end
subgraph MCP["MCP服务器"]
D["目标工具服务器"]
end
subgraph Control["控制平面"]
E["Next.js仪表盘 — 实时审计UI"]
F["audit.jsonl — 结构化事件日志"]
end
A -- "JSON-RPC" --> B
B -- "检查" --> C
C -- "允许" --> B
C -- "阻止" --> B
B -- "转发/丢弃" --> D
D -- "响应" --> B
B -- "日志事件" --> F
F -- "流式传输" --> E
style A fill:#1a1a2e,stroke:#58a6ff,color:#e6edf3
style B fill:#161b22,stroke:#f85149,color:#e6edf3
style C fill:#161b22,stroke:#f85149,color:#e6edf3
style D fill:#1a1a2e,stroke:#3fb950,color:#e6edf3
style E fill:#161b22,stroke:#58a6ff,color:#e6edf3
style F fill:#0d1117,stroke:#8b949e,color:#8b949e
```
### 检测管道（深度防御）
| 层级 | 名称 | 技术 | 延迟 |
|:---:|---|---|:---:|
| **L1** | 基线完整性 | 工具模式的SHA-256哈希值与已知良好快照的比较 | < 1毫秒 |
| **L2** | 上下文窗口保护 | 丢弃超过安全令牌限制（>50k字符）的有效载荷以防止上下文泛滥 | < 1毫秒 |
| **L3** | 模式匹配 | 基于正则表达式的已知攻击签名检测（`<SYSTEM>`、 `[PROMPT OVERRIDE]`、凭证泄露模式） | < 5毫秒 |
| **L4** | 大型语言模型语义判断 | 将可疑的有效载荷发送到Gemini 2.5 Flash进行深度语义意图分析 | ~500毫秒 |
---
## 目录结构
```
├── proxy.py # 数据平面：多线程stdin/stdout MCP代理
├── rig.py # 核心：4层检测引擎（L1-L4）
├── pre_cache.py # 实用工具：为工具模式生成基线哈希值
├── requirements.txt # Python依赖项
│
├── src/ # 控制平面：Next.js仪表盘（应用路由器）
│ └── app/
│ ├── page.tsx # 主仪表盘UI（React + Tailwind）
│ ├── layout.tsx # 根布局与元数据
│ ├── globals.css # 设计系统令牌
│ └── api/logs/
│ └── route.ts # 服务器API路由（读取audit.jsonl）
│
├── tests/ # 测试基础设施
│ ├── echo_server.py # 良性MCP服务器用于基线测试
│ ├── malicious_server.py# 具有注入有效载荷的敌对MCP服务器
│ ├── test_rig_direct.py # 直接引擎单元测试
│ └── run_all_tests.py # 完整的端到端测试框架
│
├── Dockerfile # 多阶段生产容器
├── docker-compose.yml # 一键部署
├── package.json # Node.js依赖项
├── next.config.ts # Next.js配置（独立输出）
└── tsconfig.json # TypeScript配置
```
---
## 快速入门
### 先决条件
- **Python 3.11+** 及pip
- **Node.js 20+** 及npm
- **Gemini API密钥** （可选，用于L4大型语言模型判断）
### 1. 安装依赖项
```bash
# Python代理引擎
pip install -r requirements.txt
# Next.js仪表盘
npm install
```
### 2. 生成安全基线
```bash
python pre_cache.py python tests/echo_server.py
```
### 3. 启动指挥中心
```bash
npm run dev
```
在 **http://localhost:3000** 打开实时安全仪表盘。
### 4. 将RIG附加到Claude Desktop
编辑您的 `claude_desktop_config.json`:
```json
{
"mcpServers": {
"protected-server": {
"command": "python",
"args": [
"C:/path/to/proxy.py",
"python",
"C:/path/to/tests/echo_server.py"
]
}
}
}
```
### 5. 运行攻击模拟
```bash
cd tests
python run_all_tests.py
```
---
## Docker部署
```bash
docker-compose up -d --build
```
---
## 环境变量
| 变量 | 默认值 | 描述 |
|---|---|---|
| `GEMINI_API_KEY` | — | Gemini 2.5 Flash的API密钥（启用L4大型语言模型判断） |
| `RIG_LAYER4_SAMPLE_RATE` | `1.0` | 发送到L4的请求分数（0.0–1.0） |
| `RIG_LAYER4_CONFIDENCE_THRESHOLD` | `70.0` | 触发BLOCK判决的最低置信度分数 |
| `AUDIT_LOG_PATH` | `./audit.jsonl` | 结构化审计日志的路径覆盖 |
---
## 技术栈
| 层级 | 技术 | 目的 |
|---|---|---|
| **代理引擎** | Python 3.11+，`subprocess`，`threading` | 多线程stdin/stdout MCP桥接 |
| **检测引擎** | SHA-256，正则表达式，Google Gemini 2.5 Flash | 4层深度防御管道 |
| **仪表盘** | Next.js 16，React 19，TypeScript 5 | 实时安全监控UI |
| **样式** | Tailwind CSS 4，Lucide图标 | GitHub暗黑模式启发的设计系统 |
| **容器化** | Docker，Docker Compose | 生产部署 |
| **协议** | JSON-RPC 2.0（MCP规范） | 大型语言模型↔工具通信标准 |
