rug-pull-detector

@guardbee/mcp-rug-pull-detector

🇬🇧 English | 🇹🇷 Türkçe | 🇨🇳 中文 | 🇯🇵 日本語 | 🇰🇷 한국어 | 🇧🇷 Português | 🇪🇸 Español | 🇩🇪 Deutsch

一个 MCP（Model Context Protocol）服务，可实时连接另一个 MCP 服务并检测 MCP rug pull——也就是某个服务在你批准时展示一种工具定义，之后却悄悄提供另一种定义。

这个 monorepo 中的其他扫描器都会读取一次源代码或配置文件。这个扫描器在架构上有所不同：它是一个 MCP 客户端。它会启动目标服务（stdio），或与之建立会话（Streamable HTTP），调用真实的 tools/list RPC，并记住所见内容——这与 SSH 客户端对主机密钥采用的首次使用即信任模型相同。如果同一服务在两次调用之间更改了某个工具的描述、输入／输出架构或注释，那么无论对该服务的源代码进行何种静态分析，都无法发现这一点，因为服务的源代码可能完全没有变化——它可以在服务器端根据请求决定向哪个客户端告知什么内容。

默认情况下，遥测处于关闭状态。设置 GUARDBEE_TELEMETRY=1 后，它会发送服务、工具、成功状态、耗时和简短的参数值（例如文件路径）；较长的字符串以及 content、token 或 password 等字段会替换为占位符。请参阅 @guardbee/mcp-telemetry。

Claude ──► rug-pull-detector ──► (spawns / connects to) ──► Target MCP server
              │                                                  │
              │                                          tools/list (real RPC)
              ▼
         .guardbee/tool-baselines/<hash>.json
              │
    1st contact: baseline_server → store canonical hash per tool
    every later: check_server    → re-fetch, diff against stored hash

---

首次使用时信任模型

baseline_server 连接一次，获取每个工具的 {name, description, inputSchema, outputSchema, annotations}，对其进行规范化（按键深度排序的 JSON），并存储 SHA-256 哈希和完整快照——每个服务对应 .guardbee/tool-baselines/ 下的一个 JSON 文件。

每次运行 check_server 时，都会扫描实时 tools/list 中的工具是否存在工具投毒，包括首次发现服务时以及尚未存储基线时。恶意描述无需等到第二次访问才会被发现。

之后，check_server 会再次连接——版本升级后、每个会话开始前、按计划定期运行，或按你选择的任何频率——并重新获取相同信息。任何哈希不匹配的工具都会被报告：

• 严重——现有工具的定义发生了变化（tool_definition_drift）。这就是 rug pull 本身。报告会精确指出变更的字段（description / input schema / output schema / annotations），并提供变更前后的描述文本，因为 destructiveHint: true → false 和重写描述一样都是谎言——两者都会改变调用方认为自己正在授权的操作。
• 中等——出现了基线中不存在的新工具（tool_added）。这可能是合理的版本更新，但仍值得留意——服务可以等到无害工具已经赢得信任后，再引入危险工具。
• 低——之前已纳入基线的工具不再提供（tool_removed）。

如果尚无基线，check_server 会自动创建一个并报告正常（传入 autoBaseline: false / --no-auto-baseline，即可要求先显式调用 baseline_server）。

---

功能

• 真正的 MCP 客户端——不是模拟，也不是基于源代码的启发式检测。它通过 stdio 或 Streamable HTTP 使用真实协议，连接你指定的任意服务。
• 规范化哈希涵盖名称、描述、输入架构、输出架构，以及注释（readOnlyHint、destructiveHint 等）——服务无法只修改朴素差异检测会忽略的字段来规避检测。
• 指定目标的三种方式：--stdio="command arg1 arg2"、--url=<http-url>，或 --config=<file> --server=<name>（直接读取 mcpServers 风格的 JSON 配置——与 Claude Desktop 配置格式相同）
• SARIF 2.1.0 输出——用于 CI/CD 集成
• 28 项测试：涵盖哈希、差异比较和存储的纯单元测试，以及针对测试用 MCP 服务（非模拟）的真实 stdio 进程启动集成测试，覆盖漂移、新增、移除和标签隔离。已针对 ai-code-scanner 自己已发布的真实 MCP 服务完成端到端验证——通过真实 stdio JSON-RPC 连接，为其 4 个真实工具创建基线，并确认第二次检查报告正常。

---

快速开始

Claude Desktop / MCP 客户端

{
  "mcpServers": {
    "guardbee-rug-pull-detector": {
      "command": "npx",
      "args": ["-y", "@guardbee/mcp-rug-pull-detector"]
    }
  }
}

然后让 Claude 为你即将添加的服务创建基线，并定期重新检查（例如：“在今天使用这个 MCP 服务之前，先根据其基线进行检查”）。

CLI（CI/CD 或定期检查）

# First contact — do this only after you've reviewed the server's tools
npx @guardbee/mcp-rug-pull-detector baseline --config=claude_desktop_config.json --server=some-third-party-server

# Every later run — e.g. a scheduled job, or right before your app starts
npx @guardbee/mcp-rug-pull-detector check --config=claude_desktop_config.json --server=some-third-party-server --fail-on=critical

---

MCP 工具

工具	描述
baseline_server	连接服务，并将其当前工具存储为可信基线
check_server	连接服务，并将其当前工具与已存储的基线进行比较
list_baselines	列出所有已存储基线的服务

---

配置

无需配置 guardbee.yml 部分——唯一的持久化状态就是基线目录本身（默认为 .guardbee/tool-baselines/，可通过 --baseline-dir 覆盖）。

---

局限性（有意为之）

• --stdio 使用简单的空白字符分割，而不是解析 shell 引号——包含空格的命令或参数会导致出错。对于任何超出简单命令行的情况，请使用 --config=<file> --server=<name>（读取包含规范 args 数组的真实 JSON 配置）。
• 基线身份由你指定的 label 决定（如果未指定，则使用命令行或 URL），而不是服务器本身的任何加密身份信息——更改调用服务器的方式会启动一个新的基线。请保持标签稳定。
• 此工具检测的是服务器提供的工具列表发生的变化，而不是工具调用中一直存在的恶意行为。这是防止暗中掉包的防御措施，不能替代 mcp-server-auditor 或 tool-poisoning-scanner——请同时运行这三者。
• 连接 stdio 目标意味着启动你指定的任何命令——这与添加服务器到配置时，所有 MCP 客户端都会执行的操作相同。只将此工具指向你打算运行的服务器。

---

开发

npm run build
npm test             # 28 tests

---

许可证

MIT — GuardBee

反馈

有问题、想法或发现误报？请在 GitHub Discussions 中发起讨论，或提交问题。如果 GuardBee 对你有用，请在项目仓库点个 ⭐，帮助其他人找到它。