Carlos-Projects/mcpguard

# MCPGuard 🛡️ [](https://github.com/Carlos-Projects/mcpguard/actions/workflows/ci.yml) [](https://codecov.io/gh/Carlos-Projects/mcpguard) [](https://pypi.org/project/mcpguard-proxy/) [](https://pypi.org/project/mcpguard-proxy/) [](LICENSE) [](https://api.star-history.com/svg?repos=Carlos-Projects/mcpguard&type=Date) **用于 Model Context Protocol (MCP) 和 Agent-to-Agent (A2A) 协议的 runtime 安全代理。** MCPGuard 位于 MCP 客户端和服务器之间，实时检查每一条 JSON-RPC 消息，以检测并阻止安全威胁。支持 **HTTP SSE**、**stdio** 和 **WebSocket** 传输模式。 ## MCPGuard 的独特之处 | 能力 | MCPGuard | 原生代理 | 自定义 middleware | |---|---|---|---| | **Prompt injection 检测** | ✅ 14 种 regex 模式 | ❌ | 手动 | | **Tool poisoning 检测** | ✅ 标记可疑的 `tools/list` | ❌ | ❌ | | **SSRF 保护** | ✅ 重定向阻止 + scheme 校验 | ❌ | 手动 | | **Rate limiting** | ✅ 按方法 + 按 IP | ❌ | ❌ | | **实时仪表盘** | ✅ HTMX 位于 `/_mcpguard/` | ❌ | ❌ | | **Prometheus metrics** | ✅ `/metrics` | ❌ | ❌ | | **全 3 种传输模式** | ✅ HTTP SSE + stdio + WebSocket | 部分 | 手动 | | **配置热更新** | ✅ | ❌ | ❌ | | **Circuit breaker** | ✅ 自动恢复 | ❌ | ❌ | ## 功能 | 类别 | 功能 | 描述 | |----------|---------|-------------| | **检测** | Prompt Injection | 扫描 `tools/call` 参数以查找指令覆盖模式（14 种 regex） | | | Tool Poisoning | 在 `tools/list` 响应中标记可疑的 tool 定义 | | | 资源扫描 | 检测敏感 URI 访问（`/etc/passwd`、`file:///`、metadata endpoint） | | | 可疑 Prompt | 标记类似 `debug`、`admin`、`shell` 的 prompt 名称 | | | 异常检测 | 基于突发、流量和占比的异常警报 | | **控制** | Rate Limiting | 具有可配置时间窗口的按方法和按 IP 的 rate limit | | | 允许/拒绝列表 | 控制允许哪些 tool 和方法 | | | Auth Middleware | 具有抗时序攻击比较（`hmac.compare_digest`）的 API key 认证 | | | Circuit Breaker | 5 次上游失败后自动断开，30 秒后恢复 | | | 请求体大小限制 | 拒绝大于 10MB 的请求（413），防止 DoS | | **传输** | HTTP SSE | 代理 MCP Streamable HTTP（重写 endpoint URL） | | | Stdio | 通过命令校验封装本地 MCP 服务器子进程 | | | WebSocket | 对 MCP 服务器提供 WebSocket 传输支持 | | **可观测性** | 实时仪表盘 | 基于 HTMX 的仪表盘位于 `/_mcpguard/`，带有 JS 事件过滤 | | | Prometheus Metrics | 带有计数器和仪表的 `/metrics`（uptime、活跃 SSE） | | | 审计日志 | 将所有事件记录到每日的 JSONL 文件中 | | **安全** | SSRF 保护 | `follow_redirects=False`，目标 URL scheme 校验 | | | 子进程校验 | spawn 前检查命令是否存在 + 可执行性 | | | Rate Limit Header | 429 响应时附带 `Retry-After`、`X-RateLimit-*` | | **平台** | TLS | 通过 `--tls-cert` / `--tls-key` 提供 HTTPS 支持 | | | 配置校验 | 启动时执行 10 条校验规则（端口范围、TLS 路径、冲突） | | | 配置文件 | 通过 `--config` 提供 YAML/JSON 配置，支持对字符串命令的自动拆分 | | | 热更新 | Async 配置监视器（无阻塞线程） | | | Tool 缓存 | 带有可配置 TTL 的 `tools/list` 缓存 | | | 优雅关闭 | 10 秒超时以清理并耗尽连接 | ## 安装说明 ``` pip install mcpguard-proxy ``` 从源码安装： ``` git clone https://github.com/Carlos-Projects/mcpguard.git cd mcpguard pip install -e ".[dev]" ``` ## 快速开始 ``` # HTTP 模式（拦截上游 MCP 服务器） mcpguard proxy --target http://localhost:8000 --port 8080 # Stdio 模式（包装本地 MCP 服务器进程） mcpguard proxy --mode stdio --cmd python3 --cmd /path/to/server.py --port 8080 # 支持 auth、TLS 和 circuit breaker mcpguard proxy --target http://localhost:8000 --port 8443 \ --api-key my-secret --tls-cert cert.pem --tls-key key.pem # 使用配置文件（YAML/JSON） mcpguard proxy --config mcpguard.yaml --hot-reload ``` 客户端连接到 `http://localhost:8080`，而不是直接连接服务器。仪表盘位于 `/_mcpguard/`。 ## CLI 参考 ``` mcpguard proxy [OPTIONS] ``` | 选项 | 默认值 | 描述 | |--------|---------|-------------| | `--target, -t` | `http://localhost:8000` | 上游 MCP 服务器 URL | | `--host, -h` | `127.0.0.1` | 代理监听地址 | | `--port, -p` | `8080` | 代理监听端口 | | `--mode, -m` | `http` | 传输方式：`http` 或 `stdio` | | `--cmd, -c` | `[]` | stdio 命令（可重复） | | `--sse-path` | `/sse` | SSE endpoint 路径 | | `--messages-path` | `/messages/` | 消息 endpoint 路径 | | `--log-dir, -l` | `./mcpguard_logs` | 日志目录 | | `--config, -C` | — | 配置文件（YAML/JSON） | | `--allow, -a` | `[]` | 允许列表中的 tool（可重复） | | `--deny, -d` | `[]` | 拒绝列表中的 tool（可重复） | | `--rate-limit, -r` | `100` | 每个时间窗口的最大请求数 | | `--rate-window, -w` | `60` | rate limit 时间窗口（秒） | | `--api-key, -k` | — | 用于代理认证的 API key | | `--tls-cert` | — | TLS 证书文件 | | `--tls-key` | — | TLS 密钥文件 | | `--hot-reload` | — | 监视配置文件的更改 | | `--request-timeout` | `30.0` | 上游请求超时时间（秒） | ``` mcpguard analyze [LOG_DIR] ``` 使用可选的 `--severity`、`--type`、`--limit` 过滤器分析记录的事件。 ## 架构 ``` ┌──────────────────┐ ┌───▶│ MCPGuard Proxy │───▶ MCP Server (HTTP/SSE) │ │ (port 8080) │ MCP Client (Host)──┤ └──────────────────┘ ┌──────────────────┐ │ │ │ MCP Server │ │ ├──────────────────▶│ (stdio process) │ │ │ └──────────────────┘ │ ┌──────────────────┐ └───▶│ /_mcpguard/ │ │ Dashboard │ └──────────────────┘ │ ┌──────────┴──────────┐ │ /metrics │ │ /health │ │ /health/ready │ └─────────────────────┘ ``` ## 检测插件 | 插件 | 触发条件 | 动作 | |--------|---------|--------| | Prompt Injection | `tools/call` 包含指令覆盖关键字 | 阻止 (403) | | Tool Poisoning | `tools/list` 包含可疑 tool 名称 | 如果 `block_on_poisoning: true` 则阻止 | | 资源扫描器 | `resources/read` 包含敏感 URI | 记录日志 | | 可疑 Prompts | `prompts/get` 包含类似 admin 的名称 | 记录日志 | | Rate Limiter | 超出按方法 + 按 IP 的阈值 | 阻止 (429) 并附带 `Retry-After` | | 异常检测器 | 突发、方法占比过大、大流量模式 | 记录日志 | | Circuit Breaker | 连续 5 次上游失败 | 阻止 (503) 并在 30 秒后恢复 | ## 配置文件示例 ``` mode: http target_url: http://localhost:8000 listen_host: 127.0.0.1 listen_port: 8080 rate_limit: 100 rate_window: 60 block_on_injection: true block_on_poisoning: true max_sse_connections: 50 request_timeout: 30.0 api_key: your-secret-key allowlisted_tools: - get_weather - search denylisted_tools: - execute_bash - delete_files tls_cert_path: /path/to/cert.pem tls_key_path: /path/to/key.pem ``` ## 测试 ``` pip install -e ".[dev]" python -m pytest tests/ -v --cov=mcpguard --cov-report=term-missing ``` ## 生态系统 MCPGuard 是一个 **runtime 守护程序** — 它是以下工具的补充： - **[Cisco MCP Scanner](https://github.com/ciscomanufacturing/mcp-scanner)** — 对 MCP 服务器进行静态分析 - **[MCPwn](https://github.com/Carlos-Projects/mcpwn)** — 用于 MCP 的主动红队测试框架 ## 更新日志 ### v0.4.0 (2025-05-25) - **安全：** 抗时序攻击认证、请求体大小限制（10MB）、子进程命令校验、SSRF 保护 - **可靠性：** Circuit breaker（5 次失败/30 秒恢复）、Async 配置监视器、优雅关闭（10 秒） - **功能：** `/health/ready` endpoint、rate limit header、可配置超时、WebSocket 传输 - **仪表盘：** JS 事件过滤、CDN 回退、uptime/活动连接指标 - **配置：** 启动时校验、自动拆分字符串命令、`request_timeout` 选项 - **测试：** 52 → 104 个测试，覆盖率约 85%，7 个新测试文件，CI 覆盖率报告 - **基础设施：** `.dockerignore`、CI 中的 stdio 集成测试、codecov 集成 ### v0.3.0 (2025-05-24) - HTTP SSE + stdio 传输模式 - Prompt injection、tool poisoning、资源扫描、异常检测 - 实时 HTMX 仪表盘、Prometheus metrics、JSONL 审计日志 - Auth middleware、TLS 支持、rate limiting、允许/拒绝列表 - Docker 支持、CI/CD、PyPI 发布 ## 安全 发现漏洞？请参阅 [SECURITY.md](SECURITY.md)。 ## 开源协议 MIT

标签：Homebrew安装, 自定义请求头, 请求拦截, 逆向工具