# MCPGuard-Lab

一个基于真实 `mcp==2.0.0` SDK 的 MCP 工具调用安全实验项目。它不依赖外部大模型或 API Key，通过确定性策略完成工具白名单、参数校验、文件边界、SSRF 防护、敏感操作确认、输出脱敏、工具描述投毒检测和 JSONL 审计，并用回归用例验证防护没有被后续改动破坏。

> 使用边界：本项目仅用于本地实验、授权测试和防御研究，不包含面向未授权目标的攻击功能。

## 已实现能力

- MCP 2.0 stdio 服务端与真实客户端往返测试。
- 六个演示工具：安全计算、根目录内文件读取、笔记查询、公开 URL 请求、工具元数据检查、确认后写笔记。
- 工具白名单与 JSON Schema 严格校验，拒绝额外参数。
- 文件路径规范化，拒绝绝对路径、目录穿越和根目录逃逸。
- URL 协议、用户信息、端口、DNS 解析结果检查，拒绝回环、私网、链路本地等非公网地址。
- 写操作 `confirmed=true` 门禁。
- 不可信工具输出显式打标；密码、Token、API Key 与 Bearer 凭据递归脱敏。
- 工具名称/描述中的高风险提示注入信号检测。
- 每次决策写入 JSONL：请求 ID、时间、工具、参数、允许/拒绝、原因和结果。
- pytest 单元/集成测试和可重复的攻击回归报告。

## 架构

```text
MCP Client
   │ stdio / MCP 2.0
   ▼
MCP Server ──► GuardedGateway ──► PolicyEngine
                      │                 ├─ allowlist + schema
                      │                 ├─ path boundary
                      │                 ├─ URL / SSRF
                      │                 └─ confirmation
                      ├─ Tool handler
                      ├─ untrusted labeling + redaction
                      └─ JSONL audit
```

核心原则是“先决策、后执行、再净化输出、全程留痕”。提示词文本不会直接获得额外权限，权限以代码中的白名单和策略为准。

## 快速运行（Windows）

```powershell
py -3.10 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"
.\.venv\Scripts\python.exe -m pytest
.\.venv\Scripts\python.exe -m mcpguard.regression
```

也可以直接运行：

```powershell
powershell -ExecutionPolicy Bypass -File .\scripts\verify.ps1
```

报告会生成在：

- `reports/regression-report.md`
- `reports/regression-report.json`
- `reports/regression-audit.jsonl`

## MCP 客户端配置示例

先执行 `pip install -e .`，再把以下结构换成当前仓库绝对路径：

```json
{
  "mcpServers": {
    "mcpguard-lab": {
      "command": "D:/path/to/mcpguard-lab/.venv/Scripts/python.exe",
      "args": ["-m", "mcpguard.server"],
      "env": {
        "MCPGUARD_WORKSPACE": "D:/path/to/mcpguard-lab/fixtures/workspace",
        "MCPGUARD_NOTES": "D:/path/to/mcpguard-lab/fixtures/workspace/notes",
        "MCPGUARD_AUDIT": "D:/path/to/mcpguard-lab/reports/audit.jsonl"
      }
    }
  }
}
```

## 真实边界

- 工具描述投毒检测是高信号规则层，不能代替人工审查和固定白名单。
- `confirmed=true` 是本地实验中的显式确认门禁；生产环境应使用由宿主 UI/身份系统签发、不可由模型自行伪造的确认凭证。
- URL 工具当前禁用重定向，避免首跳通过检查后跳向内网；生产版还应限制响应大小、内容类型和出口网络。
- 不可信内容打标能降低“数据被当指令”的风险，但最终宿主 Agent 仍需遵循信任边界。
- 回归数据只代表仓库内固定用例，不代表可以阻断所有提示注入或所有 MCP 风险。

## 目录

```text
src/mcpguard/       核心实现
tests/              单元测试与真实 MCP stdio 集成测试
fixtures/           可公开的本地测试数据
reports/            自动生成的测试和审计证据
scripts/verify.ps1  一键验证入口
```

## 参考

- [Model Context Protocol Python SDK](https://github.com/modelcontextprotocol/python-sdk)
- [AgentDojo](https://github.com/ethz-spylab/agentdojo)