rug-pull-detector

@guardbee/mcp-rug-pull-detector

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

別の MCP サーバーにライブで接続し、MCP ラグプルを検出する MCP（Model Context Protocol）サーバーです。承認時にはあるツール定義を提示し、その後ひそかに別の定義を提供するサーバーを検出します。

このモノレポにある他のスキャナーは、ソースコードまたは設定ファイルを一度読み込むだけです。このスキャナーは設計が異なり、MCP クライアントとして動作します。対象のサーバーを起動する（stdio）か、対象サーバーとのセッションを開始し（Streamable HTTP）、実際のtools/list RPCを呼び出して、取得した内容を記録します。これは、SSH クライアントがホストキーに対して使う、初回利用時に信頼するモデルと同じです。同じサーバーへの2回の呼び出しの間に、ツールの説明、入出力スキーマ、またはアノテーションが変更されたことは、そのサーバーのソースコードを静的に解析しても検出できません。サーバーはソースをまったく変更せず、リクエスト時に、どのクライアントに何を伝えるかをサーバー側で決定できるためです。

テレメトリーはデフォルトでオフです。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 ハッシュと完全なスナップショットを保存します。サーバーごとに 1 つの JSON ファイルが .guardbee/tool-baselines/ に保存されます。

すべての check_server では、ライブの tools/list に対してツールポイズニングのカタログスキャンも実行します。サーバーを初めて確認するときや、ベースラインがまだ保存されていないときも対象です。ポイズニングされた説明が、2 回目の確認まで見逃されることはありません。

check_server は後から再度接続し、バージョン更新後、各セッションの前、スケジュールに従ってなど、選んだ頻度で同じ情報を再取得します。ハッシュが一致しなくなったツールは、次のように報告されます。

• critical — 既存のツール定義が変更されました（tool_definition_drift）。これがラグプルそのものです。検出結果には、変更されたフィールド（description ／ input schema ／ output schema ／ annotations）が、変更前と変更後の説明文とともに正確に示されます。destructiveHint: true → false も、書き換えられた説明文と同じくらいの虚偽です。どちらも、呼び出し元が何を許可していると信じるかを変えてしまうためです。
• medium — ベースラインに存在しなかった新しいツールが追加されました（tool_added）。正当なリリースかもしれません。それでも確認する価値があります。無害なツールで信頼を得た後に、サーバーが危険なツールを導入することを阻むものは何もありません。
• low — 以前ベースラインに記録されていたツールが提供されなくなりました（tool_removed）。

ベースラインがまだない場合、check_server は自動的にベースラインを取得し、問題なしと報告します（先に明示的に baseline_server を呼び出すことを必須にするには、autoBaseline: false ／ --no-auto-baseline を渡します）。

---

機能

• 実際の MCP クライアント — モックでもソースコードのヒューリスティックでもありません。指定した任意のサーバーと、stdio または Streamable HTTP 経由で実際のプロトコルを使用して通信します。
• 正規化ハッシュの対象は、name、description、input schema、output schema、および annotations（readOnlyHint、destructiveHint、...）です。単純な差分検出では見落とされるフィールドだけを変更して、サーバーが検出を回避することはできません。
• ターゲットの指定方法は 3 通りです。--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 つのツールをベースラインに記録した後、2 回目の確認で問題なしと報告されることを確認しました。

---

クイックスタート

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 はシェルの引用符を解析せず、単純に空白で分割します。そのため、コマンドや引数に空白が含まれていると動作しません。単純なコマンドラインを超える場合は、--config=<file> --server=<name>（適切な args 配列を含む実際の JSON 設定を読み込みます）を使用してください。
• ベースラインの識別には、指定した label が使われます（指定しない場合はコマンドラインまたは URL が使われます）。サーバー自体に関する暗号学的な情報は使われないため、サーバーの起動方法の名前を変更すると、新しいベースラインが作成されます。ラベルは一定に保ってください。
• このツールが検出するのは、サーバーが提示するツール一覧の変化であり、常に存在していたツール呼び出し内の悪意ある動作ではありません。これは不意の仕様変更に対する防御であり、mcp-server-auditor や tool-poisoning-scanner の代わりにはなりません。3 つすべてを実行してください。
• stdio ターゲットに接続すると、指定したコマンドが起動されます。MCP クライアントにサーバーを追加する際に、すべての MCP クライアントがすでに行っていることと同じです。実行する予定のサーバーのみを指定してください。

---

開発

npm run build
npm test             # 28 tests

---

ライセンス

MIT — GuardBee

フィードバック

質問、アイデア、または誤検知がありましたら、GitHub Discussionsでスレッドを立てるか、issue を作成してください。GuardBee が役に立った場合は、リポジトリに ⭐ を付けていただけると、ほかの方にも見つけてもらいやすくなります。