gautamvarmadatla/mcpsafetywarden

MCP safety warden 是一个代理服务器，它可以封装任何 MCP server，并为其工具添加行为分析、安全扫描、风险门控和安全执行功能。 [](https://pypi.org/project/mcpsafetywarden/) [](https://pypi.org/project/mcpsafetywarden/) [](https://pypi.org/project/mcpsafetywarden/) [](LICENSE) [](https://github.com/gautamvarmadatla/mcpsafetywarden/actions/workflows/ci.yml) [](https://github.com/gautamvarmadatla/mcpsafetywarden/actions/workflows/codeql.yml) [](https://registry.modelcontextprotocol.io/v0.1/servers/io.github.gautamvarmadatla%2Fmcpsafetywarden) [](https://hub.docker.com/r/gautamdatla1999/mcpsafetywarden) [](https://scorecard.dev/viewer/?uri=github.com/gautamvarmadatla/mcpsafetywarden) [](https://www.bestpractices.dev/projects/12730) [](https://github.com/gautamvarmadatla/mcpsafetywarden) ## 目录 - [概述](#overview) - [前置条件](#prerequisites) - [安装](#installation) - [配置](#configuration) - [MCP 集成](#mcp-integration) - [CLI 参考](#cli-reference) - [辅助集成](#auxiliary-security-tool-integrations) - [开发](#development) - [测试](#testing) - [延伸阅读](#further-reading) ## 概述 作为代理使用，为任何 MCP server 添加安全门控，或者将其指向您不拥有的服务器，在不进行任何工具调用的情况下运行完整的安全审计。

Fig 1. Two operating modes: proxy and audit

**行为分析**：效果分类、重试安全性、破坏性。基于 LLM（Anthropic, OpenAI, Gemini, Ollama）并带有基于规则的回退机制。在每次代理调用后更新观测统计数据（延迟 p50/p95、失败率、输出大小）。 **安全扫描**：mcpsafety+ 五阶段流水线（Recon, Planner, Hacker, Auditor, Supervisor）。Cisco AI Defense (AST/YARA)。Snyk（元数据分析）。Kali 和 Burp Suite 集成通过真实的网络数据和 HTTP 层探测来丰富流水线。来自 GitHub 的源代码扫描，包含熵、AST、污点流分析和恶意替换检测。

Fig 2. mcpsafety+ five-stage pipeline, triggered when you run a full security audit on any MCP server

**安全执行**：参数扫描（20 多种攻击类别，LLM 二次扫描）。双层输出注入扫描。带有替代方案和逐工具策略的风险门控。在每次调用时进行漂移检测和独立检查。

Fig 3. Safe execution pipeline: the five checks every proxied tool call passes through

**CLI**：24 个子命令，交互式风险菜单，每个命令均支持 `--json` 标志，以及用于 CI 的 `--yes` 标志。 **检测内容** - **提示注入**：试图劫持 agent 的工具输出：角色劫持、越狱、伪造系统提示、指令覆盖。检测 11 种混淆技术，包括 Unicode 相似字符、零宽字符和 base64 编码的 payload。 - **恶意工具元数据**：包含注入字符串、硬编码机密、可疑下载 URL、工具冒充（shadowing）、直接金融执行、系统服务修改和不受信任的外部依赖的描述。由 19 项 Snyk 检查提供支持。 - **参数注入**：在每次工具调用转发之前检查 20 多种攻击类别：针对云元数据端点（AWS, GCP, Azure, Alibaba）的 SSRF、路径遍历、凭证文件访问（.aws, .ssh, .kube, .env）、命令注入、SQL/NoSQL/LDAP/XPath 注入、XXE、模板注入（SSTI）、CRLF、空字节、反序列化 payload（Java, Python pickle, PHP, .NET）、Windows UNC/ADS 攻击，以及上述所有内容的 base64 混淆变体。 - **源代码风险**：获取服务器的 GitHub 源代码并运行 6 个分析层：用于硬编码机密的熵扫描、AST 污点流跟踪（参数到危险 sink）、描述与实现不匹配、Bandit 和 Semgrep SAST，以及 LLM 跨函数推理。支持 Python 和 TypeScript/JavaScript。 - **恶意替换与漂移**：在首次扫描时存储服务器源代码的 SHA-256 哈希，并在其发生更改时发出警报。通过每次调用的漂移防护，实时捕获描述交换、schema 更改和工具移除。 - **行为异常**：按效果分类、破坏性和 7 个风险标签对每个工具进行分类：凭证暴露、任意执行、数据渗出、文件系统访问、横向移动、权限提升和提示注入面。 - **组合攻击**：分析工具集的链式风险：IDOR 链、读写对、身份验证流程利用、先写后执行序列，以及跨多个工具的数据累积 + 渗出路径。 - **网络和主机风险**：当注册了 Kali Linux MCP 时：开放端口、运行服务、通过 nmap 进行 OS 指纹识别。当注册了 Burp Suite MCP 时：HTTP 层主动探测和通过带外回调实现的盲 SSRF。 - **输出中的凭证暴露**：在存储前对工具响应中的机密进行脱敏。被标记为注入的响应将被隔离，并且永远不会返回给调用 agent——存储在运行 ID 下以供取证审查。 - **CVE 研究和 Arxiv 发现**：mcpsafety+ Auditor 阶段将发现的能力与已知漏洞和最新安全研究进行交叉比对。 ## 前置条件 - Python 3.10 或更高版本 - 至少一个被封装以供代理的 MCP server (stdio, SSE, 或 streamable_http) - **推荐：LLM API 密钥** (Anthropic, OpenAI, 或 Gemini) 如果没有密钥，封装器将仅在纯规则模式下运行：置信度较低的工具分类、仅正则的注入扫描、风险门控中无替代方案、无 mcpsafety+ 流水线。对于完全本地的设置，请运行 [Ollama](https://ollama.com)，设置 `OLLAMA_MODEL`，并显式传递 `--provider ollama`（Ollama 不会被自动检测）。 ## 安装 ``` 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 token、`headers` 或 `env` 中的 API 密钥）会在任何内容触及模型上下文之前被自动检测并替换为不透明的 `cref_` 标识符。真实的凭证会被加密存储在数据库中，并在连接时静默解析。模型、对话历史和日志只能看到 `cref_`。 **可选：对存储的凭证进行静态加密** ``` 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 token | | `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": "" } }, "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](docs/DEPLOYMENT.md)。 ### 可用的 MCP 工具 有关完整的工具参考，请参阅 [docs/TOOLS.md](docs/TOOLS.md)。 | 工具 | 功能 | |---|---| | `onboard_server` | 在一次调用中完成注册 + 检查 + 安全扫描 | | `register_server` | 注册服务器；可选自动检查 | | `inspect_server` | 刷新工具列表和配置 | | `check_server_drift` | 根据存储的基线检测 schema 和工具列表漂移 | | `list_servers` | 列出所有已注册的服务器 | | `list_server_tools` | 列出服务器上带有摘要配置的工具 | | `preflight_tool_call` | 不执行的风险评估 | | `safe_tool_call` | 带有风险门控和替代方案的执行 | | `get_tool_profile` | 包含观测统计数据的完整行为配置 | | `get_retry_policy` | 重试和超时建议 | | `suggest_safer_alternative` | LLM 排序的更安全替代品 | | `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 参考 涵盖所有 25 个 MCP 工具的 24 个子命令。每个命令均支持用于机器可读输出的 `--json`，以及用于跳过确认提示的 `--yes` / `-y`。 有关包含标志和示例的完整参考，请参阅 [docs/CLI.md](docs/CLI.md)。 ## 辅助安全工具集成 Kali Linux MCP、Burp Suite MCP 和 Snyk 一旦注册，各自便会自动集成。Kali 通过真实的 nmap/traceroute 数据丰富 Recon 阶段和 `ping_server`。Burp 添加原始 HTTP 探测、带外回调和代理证据。Snyk 分析工具元数据中的注入字符串、工具 shadowing、硬编码机密以及其他 16 项检查。 有关设置说明，请参阅 [docs/INTEGRATIONS.md](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](docs/TESTING.md)。 ## 延伸阅读 | 文档 | 内容 | |---|---| | [docs/TOOLS.md](docs/TOOLS.md) | 全部 25 个 MCP 工具的完整参考 | | [docs/CLI.md](docs/CLI.md) | CLI 子命令、标志和示例 | | [docs/INTEGRATIONS.md](docs/INTEGRATIONS.md) | Kali、Burp Suite 和 Snyk 设置 | | [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md) | stdio、HTTP、容器和网关部署 | | [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) | 常见错误和修复 | | [docs/SECURITY.md](docs/SECURITY.md) | 机密、认证、隔离和扫描详细信息 | | [docs/TESTING.md](docs/TESTING.md) | 各项功能的验证步骤 | | [docs/COMPARISON.md](docs/COMPARISON.md) | 与相关工具的比较 | | [docs/ROADMAP.md](docs/ROADMAP.md) | 计划中的功能 | ## 贡献 有关代码标准和拉取请求指南，请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。 ## 许可证 Apache License 2.0。有关详细信息，请参阅 [LICENSE](LICENSE)。

标签：AI风险缓解, API安全, CISA项目, Docker, JSON输出, LNA, MCP安全, PyPI, Python, Streamlit, 动态防护, 大语言模型安全, 安全沙箱, 安全网关, 安全防御评估, 工具安全扫描, 无后门, 机密管理, 网络安全, 访问控制, 请求拦截, 逆向工具, 隐私保护, 零日漏洞检测, 风险控制