provnai/McpVanguard

# 🛡️ McpVanguard ### 面向使用 MCP 的 AI Agent 的安全代理 MCP (Model Context Protocol) 允许像 Claude 或 GPT 这样的 AI Agent 在您的计算机上调用工具 —— 读取文件、运行命令、浏览网页。**McpVanguard 位于两者之间**，在每次工具调用到达您的系统之前对其进行检查，并拦截任何看起来像恶意行为的请求。 无需更改您的 Agent。无需更改您的服务器。只需将其包装即可。 [](https://github.com/provnai/McpVanguard/actions/workflows/test.yml) [](https://pypi.org/project/mcp-vanguard/) [](LICENSE) [](https://python.org) **[Provnai Open Research Initiative](https://provnai.com)** 的一部分 —— 构建 AI 的免疫系统。 ## ⚡ 快速开始 ``` pip install mcp-vanguard ``` **本地 stdio 包装**（无网络）： ``` vanguard start --server "npx @modelcontextprotocol/server-filesystem ." ``` **云端安全网关**（SSE，部署于 Railway）： ``` export VANGUARD_API_KEY="your-secret-key" vanguard sse --server "npx @modelcontextprotocol/server-filesystem ." ``` [](https://railway.com/deploy/PCkNLS?referralCode=4AXmAG&utm_medium=integration&utm_source=template&utm_campaign=generic) ## 🧠 工作原理 每当 AI Agent 调用工具（例如 `read_file`、`run_command`）时，McpVanguard 会在请求到达底层服务器之前通过三个层级对其进行检查： | Layer | What it checks | Latency | |-------|---------------|---------| | **L1 — 安全区域与规则** | 内核级隔离（`openat2` / Windows 规范化）和 50+ 种确定性签名 | ~16ms | | **L2 — 语义** | 基于 LLM 的意图评分，用于处理模棱两可的请求 | Async | | **L3 — 行为** | 香农熵 ($H(X)$) 侦测和滑动窗口异常检测 | Stateful | 如果请求被拦截，Agent 会收到标准的 JSON-RPC 错误响应。底层服务器永远不会看到该请求。 ## 🛡️ 拦截内容 - **沙箱逃逸**：TOCTOU 符号链接攻击、Windows 8.3 短文件名（`PROGRA~1`）、DOS 设备命名空间 - **数据渗出**：高熵载荷（H > 7.5 加密密钥）和基于速率的密钥窃取 - **文件系统攻击**：路径遍历（`../../etc/passwd`）、空字节、受限路径（`~/.ssh`）、Unicode 同形字欺骗 - **命令注入**：管道至 Shell、反向 Shell、通过 `;` `&&` `\n` 进行命令链接、展开绕过 - **网络滥用**：SSRF、云元数据端点（AWS/GCP/Azure）、十六进制/八进制编码 IP - **Prompt 注入**：越狱模式、指令忽略序列、隐藏的 Unicode 字符 - **权限提升**：SUID 二进制文件创建、`LD_PRELOAD` 注入、crontab 篡改 ## 📊 VEX Protocol — 不可变审计日志 当 McpVanguard 拦截攻击时，它会创建一个兼容 OPA/Cerbos 的 **安全工具清单**，详细记录 Principal、Action、Resource 和环境快照。 该清单随后作为加密签名报告发送到 **[VEX Protocol](https://github.com/provnai/vex)**。VEX 通过 CHORA Gate 将该报告锚定到 Bitcoin 区块链。 这意味着审计员可以独立验证*具体拦截了什么、熵值得分以及原因* —— 而无需依赖您的本地日志。 ``` export VANGUARD_VEX_URL="https://api.vexprotocol.com" export VANGUARD_VEX_KEY="your-agent-jwt" vanguard sse --server "..." --behavioral ``` ## 🏗️ 架构 ``` ┌─────────────────────────────────────────────────┐ AI Agent │ McpVanguard Proxy │ (Claude, GPT) │ │ │ │ ┌───────────────────────────────────────────┐ │ │ JSON-RPC │ │ L1 — Rules Engine │ │ │──────────────▶│ │ 50+ YAML signatures (path, cmd, net...) │ │ │ (stdio/SSE) │ │ BLOCK on match → error back to agent │ │ │ │ └────────────────┬──────────────────────────┘ │ │ │ │ pass │ │ │ ┌────────────────▼──────────────────────────┐ │ │ │ │ L2 — Semantic Scorer (optional) │ │ │ │ │ Ollama / OpenAI intent scoring 0.0→1.0 │ │ │ │ │ Async — never blocks the proxy loop │ │ │ │ └────────────────┬──────────────────────────┘ │ │ │ │ pass │ │ │ ┌────────────────▼──────────────────────────┐ │ │ │ │ L3 — Behavioral Analysis (optional) │ │ │ │ │ Sliding window: scraping, enumeration │ │ │ │ │ In-memory or Redis (multi-instance) │ │ │ │ └────────────────┬──────────────────────────┘ │ │ │ │ │ │◀── BLOCK ─────│───────────────────┤ (any layer) │ │ (JSON-RPC │ │ ALLOW │ │ error) │ ▼ │ │ │ MCP Server Process │ │ │ (filesystem, shell, APIs...) │ │ └──────────────────┬──────────────────────────────┘ │ │ │◀─────────────── response ────────┘ │ │ (on BLOCK) └──────────────▶ VEX API ──▶ CHORA Gate ──▶ Bitcoin Anchor (async, fire-and-forget audit receipt) ``` ## 🗺️ 项目状态 | Phase | Goal | Status | |-------|------|--------| | **阶段 1** | 基础（Proxy, CLI, 防御规则） | ✅ 已完成 | | **阶段 2** | 智能化（L2 语义, L3 行为） | ✅ 已完成 | | **阶段 3** | 飞行记录仪（VEX & CHORA 集成） | ✅ 已完成 | | **阶段 4** | 分发（稳定版 PyPI 发布） | ✅ 已完成 | | **阶段 5** | 生产加固（v1.1.3 稳定性） | ✅ 已完成 | | **阶段 6** | 安全审计整改（v1.1.4 加固） | ✅ 已完成 | | **阶段 7** | Titan 级 L1 边界（v1.5.0 取证加固） | ✅ 已完成 | | **阶段 8** | Agent 身份与 VEX v0.2 规范 | 🔄 进行中 | ## 📚 资源 - [部署指南](docs/DEPLOYMENT.md) - [架构](docs/ARCHITECTURE.md) - [贡献指南](CONTRIBUTING.md) - [生态系统报告](https://github.com/provnai/provnai) ## 📄 许可证 Apache License 2.0 — 详见 [LICENSE](LICENSE)。 由 **[Provnai Open Research Initiative](https://provnai.com)** 构建。 *“验证自主 Agent 的思想与行动。”*

标签：AI代理防护, AI免疫系统, AI网关, AI风险缓解, Claude工具, DNS 反向解析, GPT工具, HTTP工具, MCP协议, Prompt注入, Python, Streamlit, 云安全网关, 大模型安全, 安全中间件, 安全代理, 指令注入防护, 搜索引擎查询, 数据防泄露, 无后门, 模型上下文协议, 系统加固, 网络安全审计, 访问控制, 请求响应过滤, 逆向工具, 防御系统, 防火墙