MCP Safety Warden

MCP safety warden 是一款代理服务，可封装任何 MCP 服务，并为其工具添加行为分析、安全扫描、风险门控和安全执行功能。

目录

• 概览
• 前置条件
• 安装
• 配置
• MCP 集成
• CLI 参考
• 辅助集成
• 开发
• 测试
• 延伸阅读

重要

MCP 安全是一个活跃的研究领域。近期的综述归纳了许多特定于协议的威胁类别，涵盖工具投毒、提示词注入、拉高出货攻击、供应链受损、凭据窃取，以及贯穿整个服务生命周期的组合攻击。参见 Securing the MCP (OpenReview)、Landscape & Threats (arXiv)、When MCP Servers Attack (arXiv) 和 MCP-38 Taxonomy (arXiv)。

概览

可将其用作代理，为任何 MCP 服务添加安全门控；也可以将其指向一个你并不拥有的服务，在不调用任何工具的情况下执行完整的安全审计。

图 1：两种运行模式：代理和审计

行为分析：作用类别、重试安全性、破坏性。借助大模型（Anthropic、OpenAI、Gemini、Ollama），并提供基于规则的后备方案。观察到的统计数据（延迟 p50/p95、失败率、输出大小）会在每次代理调用后更新。

安全扫描：mcpsafety+ 五阶段流水线（侦察、规划、攻击、审计、监督）。Cisco AI Defense（AST/YARA）。Snyk（元数据分析）。Kali 和 Burp Suite 集成通过真实网络数据和 HTTP 层探测丰富流水线。通过熵分析、AST、污点流分析和拉高出货检测，对 GitHub 源代码进行扫描。

图 2．mcpsafety+ 五阶段流水线：对任意 MCP 服务运行完整安全审计时触发

安全执行：参数扫描（20+ 种攻击类别，并由大模型进行第二轮检查）。双层输出注入扫描。风险门控，提供替代方案和逐工具策略。每次调用时检测漂移，也可单独执行检查。

图 3．安全执行流水线：每次经代理转发的工具调用都要通过的五项检查

命令行工具：24 个子命令、交互式风险菜单、每条命令都支持 --json 标志，以及用于 CI 的 --yes。

检测内容

• 提示词注入：工具输出试图劫持 Agent 的行为，包括角色劫持、越狱、伪造系统提示词和指令覆盖。可检测 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 跟踪污点流（从参数到危险接收端）、描述与实现不匹配检测、Bandit 和 Semgrep SAST，以及大模型跨函数推理。支持 Python 和 TypeScript/JavaScript。
• 恶意替换和漂移：首次扫描时存储服务源代码的 SHA-256 哈希值；如果发生变化则发出警报。通过逐次调用的漂移防护机制，实时捕获描述替换、架构变更和工具移除。
• 行为异常：根据作用类别、破坏性和 7 种风险标签对每个工具进行分类：凭据泄露、任意执行、数据外泄、文件系统访问、横向移动、权限提升和提示词注入面。
• 组合攻击：分析工具集合中的链式攻击风险：IDOR 链、读写配对、身份验证流程利用、先写入后执行序列，以及跨多个工具的数据累积与外泄路径。
• 网络和主机风险：注册 Kali Linux MCP 时：检测开放端口、运行中的服务，并通过 nmap 识别操作系统指纹。注册 Burp Suite MCP 时：主动探测 HTTP 层，并通过带外回调检测盲 SSRF。
• 输出中的凭据泄露：存储前对工具响应中的机密进行脱敏。被标记为含注入内容的响应会被隔离，绝不会返回给调用方 Agent，而是按运行 ID 存储，以供取证审查。
• CVE 研究和 Arxiv 发现：mcpsafety+ Auditor 阶段会将发现的能力与已知漏洞和近期安全研究进行交叉比对。

前置条件

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

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

说明

需要本地设置的 stdio 服务（启动前需要本地配置的 stdio 服务，例如缺少配置文件、凭据、数据目录或操作系统特定依赖项的服务）无法由包装器检查——工具发现将失败，且不会存储任何工具。你仍可通过向 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 的机密值（Bearer 令牌、headers 或 env 中的 API 密钥）会自动检测，并在接触模型上下文之前替换为不透明的 cref_ 标识符。实际凭据会加密存储在数据库中，并在连接时静默解析。模型、对话历史和日志中只会出现 cref_<id>。

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

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

启动服务前，将打印出的密钥设为 MCP_DB_ENCRYPTION_KEY。这会对静态存储的服务凭据和 cref_ 值进行加密。

配置

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

变量	默认值	用途
MCP_TRANSPORT	stdio	传输模式：stdio、sse 或 streamable_http
MCP_HOST	127.0.0.1	HTTP 传输的绑定地址
MCP_PORT	8000	HTTP 传输的绑定端口
MCP_AUTH_TOKEN	（未设置）	HTTP 传输身份验证的 Bearer 令牌
MCP_DB_ENCRYPTION_KEY	（未设置）	用于对静态存储的凭据进行加密的 Fernet 密钥
ANTHROPIC_API_KEY	（未设置）	启用 Anthropic 作为 LLM 提供方
OPENAI_API_KEY	（未设置）	启用 OpenAI 作为 LLM 提供方
GEMINI_API_KEY 或 GOOGLE_API_KEY	（未设置）	启用 Gemini 作为 LLM 提供方（优先使用 GEMINI_API_KEY）
OLLAMA_MODEL	（未设置）	Ollama 的模型名称（例如 llama3.1）
OLLAMA_BASE_URL	http://localhost:11434/v1	Ollama API 基础 URL
SNYK_TOKEN	（未设置）	启用 Snyk E001 提示词注入检测
MCP_SCANNER_API_KEY	（未设置）	Cisco AI Defense 云端 ML 引擎密钥
MCP_SCANNER_LLM_API_KEY	（未设置）	Cisco 内部 AST 分析的 LLM 密钥
MCP_DB_PATH	（未设置）	覆盖 SQLite 数据库文件路径
MCP_GRAPH_POLICY	warn	safe_tool_call 中的图谱强制策略：off（禁用）、warn（在响应中附加风险上下文）、block（除非设置 approved=True，否则硬性阻止具有严重风险或高爆炸半径的工具）
GITHUB_TOKEN	（未设置）	用于源代码扫描的 GitHub 个人访问令牌（将速率限制从每小时 60 次提高到 5,000 次）

**安全提示：**切勿提交 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": "<generated_fernet_key>"
      }
    },
    "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。

工具	功能
onboard_server	一次调用完成注册、检查和安全扫描
register_server	注册服务；可选择自动检查
inspect_server	刷新工具列表和配置文件
check_server_drift	检测架构和工具列表是否偏离已存储的基线
list_servers	列出所有已注册的服务
list_server_tools	列出服务上的工具及其摘要配置文件
preflight_tool_call	在不执行的情况下评估风险
safe_tool_call	通过风险门控和替代方案执行
get_tool_profile	获取包含观测统计数据的完整行为配置文件
get_retry_policy	获取重试和超时建议
suggest_safer_alternative	由大模型排序的更安全替代方案
run_replay_test	幂等性测试（调用工具两次）
security_scan_server	实时安全审计（mcpsafety+、Cisco、Snyk）
scan_all_servers	对所有已注册服务运行 mcpsafety+ 流程
get_security_scan	获取最新的已存储扫描报告
set_tool_policy	为工具设置永久允许或阻止策略
get_run_history	获取工具近期执行历史
ping_server	检查可达性并测量延迟
discover_servers	扫描文件系统中的 MCP 客户端配置并提取服务条目
onboard_discovered_servers	批量注册已发现的服务
get_risk_graph	构建或查询库存风险图（服务、工具、发现项、Agent 客户端）
explain_tool_risk	梳理工具的风险路径：影响范围、组合风险、MITRE 标签、建议措施
explain_client_risk	分析单个 Agent 客户端下所有服务的跨服务风险
analyze_cve_blast_radius	报告影响同一客户端下多个服务的 CVE
export_graph	将风险图导出为 JSON 或 Mermaid 图

CLI 参考

24 个子命令涵盖全部 25 个 MCP 工具。每个命令都支持 --json，用于生成机器可读的输出；也支持 --yes / -y，用于跳过确认提示。

完整参考（含标志和示例）请参阅 docs/CLI.md。

辅助安全工具集成

注册后，Kali Linux MCP、Burp Suite MCP 和 Snyk 都会自动集成。Kali 会通过真实的 nmap/traceroute 数据增强 Recon 阶段和 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

设置大模型 API 密钥以运行大模型辅助测试；未设置时会自动跳过。分类、注入扫描、风险门控和策略执行的逐步验证说明，请参阅 docs/TESTING.md。

延伸阅读

文档	内容
docs/TOOLS.md	全部 25 个 MCP 工具的完整参考
docs/CLI.md	CLI 子命令、标志和示例
docs/DASHBOARD.md	本地 Web 仪表板：界面、扫描、快捷方式和安全模型
docs/INTEGRATIONS.md	Kali、Burp Suite 和 Snyk 的设置
docs/DEPLOYMENT.md	stdio、HTTP、容器和网关部署
docs/TROUBLESHOOTING.md	常见错误及其解决方法
docs/SECURITY.md	机密信息、身份验证、隔离和扫描详情
docs/TESTING.md	各项功能的验证步骤
docs/COMPARISON.md	与相关工具的比较
docs/ROADMAP.md	计划中的功能

贡献

代码规范和拉取请求指南请参阅 CONTRIBUTING.md。

许可证

Apache License 2.0。详情请参阅 LICENSE。