mcpsafetywarden

MCP safety warden 是一个代理服务器，它包装任何 MCP 服务器，并为其工具添加行为分析、安全扫描、风险门控和安全执行。

目录

• 概述
• 前提条件
• 安装
• 配置
• MCP 集成
• CLI 参考
• 辅助安全工具集成
• 开发
• 测试
• 进一步阅读

[!IMPORTANT] MCP 安全是一个活跃的研究领域。最近的调查列举了许多特定于协议的威胁类别，涵盖工具投毒、提示注入、rug-pull 攻击、供应链破坏、凭据泄露以及整个服务器生命周期中的组合攻击。参见 保护 MCP (OpenReview)，现状与威胁 (arXiv)，当 MCP 服务器攻击 (arXiv)，以及 MCP-38 分类法 (arXiv)。

概述

用作代理，为任何 MCP 服务器添加安全门控，或者指向一个您不拥有的服务器，在不进行任何工具调用的情况下运行完整的安全审计。

图 1. 两种操作模式：代理和审计

行为分析：效果类别、重试安全性、破坏性。借助 LLM 辅助（Anthropic、OpenAI、Gemini、Ollama），并带基于规则的备用方案。每次代理调用后更新观测统计信息（延迟 p50/p95、失败率、输出大小）。

安全扫描：mcpsafety+ 五阶段管道（侦察、规划、黑客、审计员、监督员）。Cisco AI Defense（AST/YARA）。Snyk（元数据分析）。Kali 和 Burp Suite 集成通过真实网络数据和 HTTP 层探针丰富管道。从 GitHub 进行源代码扫描，包含熵分析、AST、污点流和 rug-pull 检测。

图 2. mcpsafety+ 五阶段管道，当您对任意 MCP 服务器运行完整安全审计时触发

安全执行：参数扫描（20+ 攻击类别，LLM 二次检查）。两层输出注入扫描。风险门控，提供替代方案和每工具策略。每次调用和独立检查中的漂移检测。

图 3. 安全执行管道：每个代理工具调用通过的五项检查

CLI：24 个子命令，交互式风险菜单，每个命令支持 --json 标志，--yes 用于 CI。

检测内容

• 提示注入：试图劫持代理的工具输出：角色劫持、越狱、虚假系统提示、指令覆盖。检测 11 种混淆技术，包括 Unicode 相似字符、零宽度字符和 base64 编码的有效载荷。
• 恶意工具元数据：包含注入字符串的描述、硬编码密钥、可疑下载 URL、工具冒充（影子）、直接财务执行、系统服务修改以及不受信任的外部依赖。由 19 项 Snyk 检查提供支持。
• 参数注入：每次工具调用在转发前检查的 20+ 攻击类别：针对云元数据端点（AWS、GCP、Azure、Alibaba）的 SSRF、路径遍历、凭据文件访问（.aws、.ssh、.kube、.env）、命令注入、SQL/NoSQL/LDAP/XPath 注入、XXE、模板注入（SSTI）、CRLF、空字节、反序列化有效载荷（Java、Python pickle、PHP、.NET）、Windows UNC/ADS 攻击以及上述所有类型的 base64 混淆变体。
• 源代码风险：获取服务器的 GitHub 源代码并运行 6 个分析层：硬编码密钥的熵扫描、AST 污点流追踪（参数到危险 sink）、描述与实现不匹配、Bandit 和 Semgrep SAST 以及 LLM 跨函数推理。支持 Python 和 TypeScript/JavaScript。
• Rug-pull 和漂移：首次扫描时存储服务器源代码的 SHA-256 哈希值，并在发生变化时发出警报。通过每次调用的漂移防护实时捕获描述交换、模式更改和工具移除。
• 行为异常：按效果类别、破坏性和 7 个风险标签对每个工具进行分类：凭据暴露、任意执行、数据泄露、文件系统访问、横向移动、权限提升和提示注入面。
• 组合攻击：分析工具集的链式风险：IDOR 链、读写对、认证流利用、写入然后执行序列以及跨多个工具的数据积累+泄露路径。
• 网络与主机风险：当注册了 Kali Linux MCP 时：开放端口、运行服务、通过 nmap 的 OS 指纹。当注册了 Burp Suite MCP 时：HTTP 层主动探测和通过带外交回的盲 SSRF。
• 输出中的凭据暴露：在存储前从工具响应中擦除密钥。被标记为注入的响应被隔离，永远不会返回给调用代理——在运行 ID 下存储以供取证审查。
• CVE 研究与 arXiv 发现：mcpsafety+ 审计员阶段将发现的能力与已知漏洞和最新安全研究进行交叉引用。

前提条件

• Python 3.10 或更高版本
• 至少一个要代理的 MCP 服务器（stdio、SSE 或 streamable_http）
• 推荐：一个 LLM API 密钥（Anthropic、OpenAI 或 Gemini）

如果没有密钥，包装器将以仅基于规则的模式运行：工具分类置信度较低，仅基于正则表达式的注入扫描，风险门控中无替代方案，无 mcpsafety+ 管道。对于完全本地设置，运行 Ollama，设置 OLLAMA_MODEL，并显式传递 --provider ollama（Ollama 不会被自动检测）。

[!NOTE] 需要本地设置的 stdio 服务器（需要本地配置后才能启动的 stdio 服务器——缺少配置文件、凭据、数据目录或特定于 OS 的依赖项）无法被包装器检测——工具发现将失败，并且将存储 0 个工具。您仍然可以通过为 scan/onboard 传递 --github-url，或者为 security_scan_server 传递 github_url 参数，在不启动服务器的情况下运行完整的源代码安全检查。mcpsafety+ 管道将直接从 GitHub 获取并分析源代码。sse 和 streamable_http 服务器不受影响。

安装

pip install mcpsafetywarden

包含所有可选扩展：

pip install "mcpsafetywarden[all]"

或特定扩展：

pip install "mcpsafetywarden[anthropic,snyk]"

从源码安装：

git clone https://github.com/gautamvarmadatla/mcpsafetywarden
cd mcpsafetywarden
pip install .

SQLite 数据库在首次运行时自动创建于平台用户数据目录（Linux 上为 ~/.local/share/mcpsafetywarden/，macOS 上为 ~/Library/Application Support/mcpsafetywarden/，Windows 上为 %APPDATA%\mcpsafetywarden\）。可通过 MCP_DB_PATH 覆盖。

凭据保护（自动，无需操作）

传递给 register_server 或 onboard_server 的密钥值（headers 或 env 中的 Bearer 令牌、API 密钥）会被自动检测，并在任何内容触及模型上下文之前替换为不透明的 cref_ 标识符。真实凭据在数据库中加密存储，并在连接时静默解析。模型、对话历史记录和日志仅能看到 cref_<id>。

可选：存储凭据的静态加密

pip install cryptography
python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

在启动服务器之前，将打印的密钥设置为 MCP_DB_ENCRYPTION_KEY。这将对服务器凭据和 cref_ 值进行静态加密。

配置

所有配置均通过环境变量完成。

安全说明： 切勿提交 API 密钥或加密密钥。包装器在生成 stdio 服务器之前会从其子进程环境中剥离自己的密钥。

MCP 集成

与 Claude Desktop 连接

将包装器添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "mcpsafetywarden": {
      "command": "mcpsafetywarden-server",
      "args": [],
      "env": {
        "ANTHROPIC_API_KEY": "sk-ant-...",
        "MCP_DB_ENCRYPTION_KEY": "<生成的_fernet_密钥>"
      }
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/yourname/Documents"]
    }
  }
}

在使用前向包装器注册每个服务器：

mcpsafetywarden register filesystem --transport stdio \
  --command npx \
  --args '["-y", "@modelcontextprotocol/server-filesystem", "/Users/yourname/Documents"]'

关于所有工具调用必须通过包装器的强制网关设置，请参见 docs/DEPLOYMENT.md。

可用的 MCP 工具

请参见 docs/TOOLS.md 获取完整的工具参考。

CLI 参考

涵盖所有 25 个 MCP 工具的 24 个子命令。每个命令支持 --json 以获得机器可读输出，以及 --yes / -y 以跳过确认提示。

请参见 docs/CLI.md 获取带有标志和示例的完整参考。

辅助安全工具集成

Kali Linux MCP、Burp Suite MCP 和 Snyk 一旦注册即可自动集成。Kali 通过真实的 nmap/traceroute 数据丰富侦察阶段和 ping_server。Burp 添加原始 HTTP 探测、带外交回和代理证据。Snyk 分析工具元数据以检测注入字符串、工具影子、硬编码密钥及其他 16 项检查。

有关设置说明，请参见 docs/INTEGRATIONS.md。

开发

以可编辑模式安装：

pip install -e ".[all]"

运行服务器并观察日志：

mcpsafetywarden-server 2>server.log

每个模块使用 logging.getLogger(__name__)。服务器本身不调用 logging.basicConfig —— 请在入口点导入前配置日志记录。

测试

pytest tests/ -v

设置 LLM API 密钥以包含 LLM 辅助测试；没有密钥时它们会自动跳过。有关分类、注入扫描、风险门控和策略执行的逐步验证，请参见 docs/TESTING.md。

进一步阅读

贡献

代码标准和拉取请求指南请参见 CONTRIBUTING.md。

许可证

Apache License 2.0。详情见 LICENSE。