OneNobleSoul/mcpwarden

# mcpwarden [](https://github.com/OneNobleSoul/mcpwarden/actions/workflows/ci.yml)   在它们审查你之前，先审查你接入本地客户端（Claude Desktop、 Cursor、VS Code、Windsurf 等）的 MCP server。 大多数人安装 MCP server 的方式是从某个 README 中复制粘贴一段 `mcpServers` 配置，然后再也不去管它。这样做有两个潜在隐患： 1. 启动命令或环境变量从一开始就不太安全——硬编码的 token、 `curl | bash` 这种执行方式，或是未固定版本的 `npx`，它会随时拉取最新的包。 2. 该 server 在安装时表现正常，但随后**更改了其工具定义**。 MCP 客户端不会在两次会话之间对比工具描述的差异，因此 server 可以在你批准了它之后，悄悄地将隐藏指令插入到描述中（一种“诱导转向/暗藏杀机”行为）。工具投毒只需得手一次即可。 `mcpwarden` 专门应对这两种情况：它会对配置进行静态扫描，并使用一个 lockfile 来固定工具定义，从而确保第二种情况一旦发生，你绝对会收到警报。 ## 安装 ``` pipx install mcpwarden # 或者，从 clone 开始： pip install -e . ``` 需要 Python 3.11+。唯一的运行时依赖项是 `rich`。 ## 使用方法 对所有能找到的配置进行静态审计： ``` mcpwarden scan ``` 指定某个特定的配置文件进行检查： 连接到各个 server 并查看它们实际暴露的工具： ``` mcpwarden inspect ``` 固定当前的工具定义，以便稍后进行校验： ``` mcpwarden pin # writes mcpwarden.lock mcpwarden verify # re-reads live tools, diffs against the lock ``` `verify` 是可以接入 CI 或 cron 作业的命令。当被固定的工具定义发生变化、出现了新工具，或是描述触发了投毒启发式检测时，它会以非零状态码退出： ``` mcpwarden verify --fail-on high --json ``` ## 标记内容 **配置（静态）：** - `env` 中硬编码的凭据（AWS/GitHub/OpenAI/Slack/Google 密钥、私钥） - 通过 `sh -c` 启动，或是采用下载即执行的方式（`curl … | bash`） - 未固定版本的 `npx`/`uvx`/`pipx` 启动器在启动时才解析具体的包 **工具定义（实时）：** - 针对模型的指令格式文本（“ignore previous…”、“do not tell the user…”、`` 块，以及提及读取 `~/.ssh` / `.env` 的内容） - 隐藏在描述或 schema 中的不可见/零宽字符与 bidi 字符 - Unicode 标签块字符（即 ASCII 走私技巧）——在检测结果中会被解码并展示出来，而不仅仅是简单标记 - 相比于 lockfile 发生改变、新增或移除的工具（用于检测诱导转向行为） 检测结果包含严重级别和稳定的 `rule` ID，因此你可以使用 grep 筛选它们，或者利用 `--fail-on` 进行拦截控制。 ## 影子工具 `inspect` 和 `verify` 还会在你的配置中对比**所有** server 之间的工具名称和描述。MCP 没有加密工具身份验证机制——客户端仅凭名称来区分两个工具——因此，没有任何机制能阻止第二个 server 提供一个名为 `read_file` 的工具，从而导致与你已经信任的工具发生冲突，或是被恶意模仿。 - 两个不同 server 之间的完全名称冲突始终会被标记 （`shadow.name-collision`）；其严重程度取决于描述是否也匹配——两个提供相同工具的合法 server 会被判定为低风险，而描述不匹配的情况则值得进一步排查 - 名称极其相似但不完全相同（`readFile` vs `read_file`，拼写错误，或是多余的字符），且结合了类似的描述，会被标记为高风险 （`shadow.name-similar`）——这种组合正是域名抢注的典型特征，而非巧合 - 属于同一个 server 内部的工具绝对不会相互进行对比，且对于简短/通用的名称，在认为其可信之前需要远超模糊相似度的验证 此功能无需 lockfile，也无需建立额外连接——它直接基于 `inspect`/`verify` 通过 `tools/list` 获取到的数据运行。 ## lockfile `mcpwarden.lock` 是一个简单的 JSON 映射，结构为 `server -> tool -> sha256`。哈希值覆盖了除仅用于展示的 `title` 之外的整个工具定义，因此对描述或输入 schema 的任何更改都会导致哈希值变动。将其与你的 MCP 配置放在一起提交，`verify` 就会变成你可以完全信任的差异比对工具。 ## 限制 / 注意事项 - 远程（HTTP/SSE）server 仅支持被发现，暂不支持检查——目前仅支持 stdio 方式。 - 启发式算法终究只是启发式：它们会漏掉措辞巧妙的投毒，也可能会误报一些直白但合法的描述。它是一个烟雾报警器，而不是数学证明。 - 值得了解的前序项目：Invariant Labs 的 `mcp-scan`。mcpwarden 更加侧重于 lockfile/防诱导转向这一层面，并且完全在本地运行，依赖项极少。 ## 许可证 MIT

标签：Blue Team, MCP, Python, 无后门, 逆向工具, 配置合规