MCPSentinel

MCPSentinel

+----------------------------------------------------------------+
|                          MCPSENTINEL                           |
|       Model Context Protocol サーバーのセキュリティレビュー       |
|                    デフォルトでは読み取り専用                    |
+----------------------------------------------------------------+

MCPSentinel は、Model Context Protocol サーバー向けの、精度を最優先するセキュリティスキャナーです。静的ルールによる検出を候補として扱い、報告する前に意味的な意図分析を適用します。これにより、通常に見える fetch や delete ツールをすべて誤検出として報告することなく、パターンマッチングによる迅速な検出範囲を維持できます。

デフォルトの判定器は、オフラインで決定論的なヒューリスティックであり、LLM ではありません。オプションの OpenAI レビューでは、制限および秘匿化されたメタデータが OpenAI に送信されます。どちらのモードも、 サーバーの実装が安全であることを証明するものではありません。

対象バージョン：v0.8.8。 上の PyPI バッジには公開済みバージョンが表示されます。 インストール済みのリリースにここで説明する機能が含まれていない場合は、ソースからインストールしてください。M8ven バッジは、掲載ページにリンクされたソースリビジョンに関するものであり、この作業ツリー、 パッケージの来歴、または実測された検出精度を示すものではありません。根拠と残る確認項目については、 日付入りのエンジニアリング評価をお読みください。

60 秒で開始

python -m pip install mcp-guardian-scan
mcpsentinel                    # safe, no-write onboarding
mcpsentinel scan http://localhost:8000/mcp

最初のコマンドを実行すると、わかりやすくコピー＆ペーストしやすいオンボーディングガイドが開きます。対話型 ターミナルでは色付きパネルが表示されます。自動化向けの json と sarif には装飾テキストが含まれません。

レビューループ

discover metadata  ->  static candidates --------> semantic triage  -> human review
         |                                               ^                    |
         +-> every server instruction (MCP-S001) --------+                    v
                                                     explicitly approve baseline

提供される機能

• stdio および Streamable HTTP 経由の MCP v2 検出。最初に server/discover をネゴシエーションし、失敗した場合は自動的に従来の initialize にフォールバックします
• ツール、プロンプト、リソース、リソーステンプレート、サーバー指示の記述子に対応する、設定可能な静的パターンルール。ツールポイズニング、シャドーイング、サーバー間の問題、OAuth の混乱した代理人シグナルも対象です
• セマンティックトリアージ：デフォルトではオフラインのヒューリスティックを使用し、必要に応じて OpenAI の構造化出力による判定を利用できます。フォールバックには上限が設定されています。サーバーレベルの指示は、正規表現に一致しない場合でも、それぞれ専用の MCP-S001 レビューを受けます
• 明示的なベースライン承認、フィールド単位の記述子差分、安定したサーバー ID／プロトコルのドリフト検出
• ベースラインが信頼済みになる前に、重複した記述子 ID を拒否するプロトコル整合性チェック
• ブランドに合わせた Rich ターミナル、JSON、SARIF、自己完結型 HTML のリスクレポート
• 許可／拒否ポリシーの設定
• 明示的な Docker サンドボックス内での、所有ツールの検証。ネットワークへの送信はありません
• GitHub Action および MCP ネイティブのスキャナーインターフェイス

静的スキャンではメタデータのみを扱います。動的な呼び出しは別途オプトインする経路で、以下に説明します。GitHub Action や MCP ネイティブサーバーから実行されることはありません。

インストールと初期設定

公開済みパッケージをインストールしてから、MCPSentinel CLI を使用します。

python -m pip install mcp-guardian-scan
mcpsentinel

コマンドを指定せずに mcpsentinel を実行すると、書き込みを行わない短いターミナル初期設定ガイドが始まります。このガイドでは読み取り専用のスキャンモデルを説明し、コピーして使える最初のスキャンコマンドを提示します。OpenAI の利用は任意です。再度表示するには mcpsentinel onboard（またはエイリアスの mcpsentinel init）を使用します。サーバーに接続せず、提案されるコマンドを調整することもできます。

mcpsentinel onboard --target https://mcp.example.com/mcp
mcpsentinel onboard --target "python -m example_mcp_server" --transport stdio

対話型ターミナルでは、ガイドに色付きのパネルとコピーして使えるコマンドが表示されます。ターミナル、シェルの設定、または出力のキャプチャによってカラー検出が無効になる場合は、mcpsentinel --color always で明示的に有効にしてください。

初期設定フローで API キーを求めたり、保存したり、送信したりすることはありません。完全なリファレンスについては、mcpsentinel --help または mcpsentinel scan --help を使用してください。

ソースから開発する場合：

python -m venv .venv
. .venv/bin/activate
python -m pip install -e '.[dev]'

サーバーをスキャンする

Streamable HTTP サーバーの場合：

mcpsentinel scan http://localhost:8000/mcp

stdio サーバーの場合は、コマンドをターゲットとして引用符で囲みます。

mcpsentinel scan "python -m example_mcp_server" --transport stdio

または、実行ファイルと引数を分けて指定します。ダッシュで始まる引数には、--arg=value 形式が必要です。

mcpsentinel scan python --transport stdio --arg=-m --arg=example_mcp_server

stdio ターゲットは、信頼されていない子プロセスとして実行されます。デフォルトでは、MCPSentinel が転送するのは実行パスと言語設定のみです。OPENAI_API_KEY、クラウド認証情報、HOME、その他のホスト環境変数は転送されません。サーバーに必要な値だけを --env KEY=VALUE で渡してください。レポートとスナップショットにはキーが表示されますが、値は表示されません。--inherit-env は、信頼できる環境との互換性が必要な場合に限って使用する機能です。環境全体を転送するため、意図的に安全でないものとして示されています。

読み取り専用でも、サンドボックス内で動作するとは限りません。 stdio メタデータを列挙するには、MCPSentinel はターゲットの実行ファイルをホストプロセスとして起動する必要があります。通常のスキャンでは、検出した MCP ツールを呼び出すことはありません。また、デフォルトでは認証情報も渡されませんが、悪意のある実行ファイルは起動中や検出中に、オペレーティングシステム上のユーザーが利用できるファイルシステムやネットワークにアクセスできます。ローカルで起動しても信頼できる stdio 実行ファイルのみをスキャンしてください。対話型ターミナルでは stdio スキャンの前にこの警告が再度表示されます。自動化で使用する非対話型の JSON／SARIF 出力では警告は表示されません。

対話型の結果の例

以下のキャプチャは、ツールのメタデータが意図的に疑わしく設定された、MCPSentinel の管理下にあるローカルテスト用フィクスチャを使用しています。stdio の信頼境界に関する警告と検出結果のレイアウトを示すものであり、サードパーティの MCP サーバーをスキャンしたものではありません。

便利なオプション：

# Machine-readable report and CI failure gate
mcpsentinel scan http://localhost:8000/mcp --format sarif --output results.sarif --fail-on high

# Visual portfolio-ready report
mcpsentinel scan http://localhost:8000/mcp --format html --output risk-report.html

# Use OpenAI's structured-output semantic judge (OPENAI_API_KEY is required)
mcpsentinel scan http://localhost:8000/mcp --judge openai --judge-model gpt-4o-mini

# Scan using a repository-local baseline root (it contains baselines/ and judge-cache/)
mcpsentinel scan http://localhost:8000/mcp --baseline-dir .mcpsentinel

# After reviewing the scan's displayed fingerprint, rediscover and approve only that exact state
mcpsentinel baseline approve http://localhost:8000/mcp --baseline-dir .mcpsentinel \
  --fingerprint sha256:REPLACE_WITH_REVIEWED_FINGERPRINT

--baseline-dir はルートディレクトリです。デフォルトでは ~/.mcpsentinel で、スナップショットは baselines/ に、セマンティックキャッシュ項目は judge-cache/ に保存されます。また、ローカルのモード 0600 の HMAC スコープキーも含まれます。このキーは、同じエンドポイントに対する異なる認証コンテキストを区別し、スナップショットのパスと内容に認証情報が含まれないようにします。ディレクトリは非公開にし、スナップショットだけを別のマシンにコピーしないでください。スナップショットとキャッシュ項目は、一意な一時ファイル、fsync、および POSIX システムでのモード 0600 を使ってアトミックに書き込まれます。

通常のスキャンでベースラインが更新されることはありません。SHA-256 の定義フィンガープリントが表示され、baseline approve は書き込み前に対象を再検出します。再検出したフィンガープリントがレビュー済みのものと完全に一致する場合に限り、承認は成功します。定義フィンガープリント v2 とベースラインスナップショット v5 は、ディスクリプターの状態と、安定した識別情報の一部（サーバー名、サーバーバージョン、ネゴシエートされたプロトコルバージョン、公開された機能名）の両方を対象とします。ディスクリプター（サーバーの指示を含む）の変更、追加、削除は MCP-B001 として検出されます。識別情報またはプロトコルの変更は、中程度の重大度の MCP-B002 として別途検出されます。以前に承認されたスナップショットは、明示的に承認するまで保持されます。

同じ kind:name 識別情報を持つディスクリプターが 2 つあると、辞書形式のベースラインではそのカタログを曖昧さなく表現できないため、MCP-N002 が報告されます。サーバーが一意な識別情報を返すまで、承認は拒否されます。古いベースラインは、1 回限りの v5 再承認が必要です。認証情報を含まないレガシースナップショットは、保守的に比較できる場合があります。ただし、対象に URL のユーザー情報、機密性の高いクエリキー、明示的な環境変数の値、認証情報に見える引数、またはホスト環境変数への継承アクセスがある場合、レガシースナップショットが自動的に信頼されたり移行されたりすることはありません。

初回のスキャンでは、承認済みのベースラインが存在しないことが報告されます。これは導入時の状態であり、脆弱性の検出結果ではありません。信頼できるサーバーバージョンと環境でのみ、ベースラインを設定してください。

リスクスコアは、重大度とセマンティック信頼度に重み付けした合計を 0～100 に制限したものです。これは優先順位付けの指標であり、サーバー単体の安全性または危険性を断定するものではありません。

セマンティック判定

--judge heuristic はデフォルトで、完全にオフラインで動作します。--judge openai には OPENAI_API_KEY が必要です。--judge auto を指定すると、そのキーがある場合は OpenAI を使用し、ない場合はヒューリスティックを使用します。OpenAI 判定には Python SDK の Responses 構造化出力 API を使用するため、API の応答がスキャナーの想定する判定スキーマを回避することはできません。判定方法が変更された後に判定結果を保持せずに API の再課金を防ぐため、結果はディスクリプターハッシュと、バージョン管理された判定器／プロンプトの識別情報をキーとしてベースラインディレクトリにキャッシュされます。

OpenAI による各判定では、クライアントのタイムアウトを30秒に設定し、SDK による再試行は最大2回まで行います。OpenAI にリクエストを送信する前に、MCPSentinel は構造化フィールド内のシークレット値を再帰的にマスキングし、さらにテキスト内の一般的な API キー、ベアラー認証情報、秘密鍵をマスキングします。プロンプトは12,000文字に制限され、フィールドを考慮した先頭と末尾の抜粋が使われるため、長いディスクリプターでも、無関係なテキストで最終的な証拠をすべて隠すことはできません。候補の評価では、同時リクエスト数を4に制限します。マスキングは多層防御であり、任意の機密メタデータを安全に送信できる保証ではありません。メタデータをローカルに留める必要がある場合は、heuristic を選択してください。

--judge auto で OpenAI の障害や不正な応答が発生した場合、スキャンはオフラインのヒューリスティックを使って完了し、レポートに明示的な注記を出力します。フォールバックによる判定結果は、OpenAI の判定結果としてキャッシュされません。--judge openai は引き続き厳格に動作し、設定されたプロバイダーを黙って変更することなく失敗します。

セマンティック判定のしきい値は、デフォルトで 0.70 です。この値を下回る候補の検出結果はレポートに含まれません。適合率より再現率を優先する場合に限り、しきい値を下げてください。

サーバーレベルの指示分析

MCP サーバーの指示は独立した攻撃対象領域であるため、MCPSentinel は英語の静的正規表現が一致するまで分析を待ちません。すべての SERVER_INSTRUCTIONS ディスクリプターに対して、専用の MCP-S001 セマンティックレビューが行われます。オフラインのヒューリスティックには、通常の使用ガイダンスを安全と判定しつつ、指示の優先順位の上書き、隠蔽、認証情報の持ち出し、不審な外部転送、および英語、スペイン語、インドネシア語、ポルトガル語、フランス語、ドイツ語の一部の表現を認識する、適合率優先の判定経路があります。MCP-S001 の許可または拒否セレクターは、他のポリシー判断と同様に機能し、セマンティック判定のしきい値も引き続き適用されます。

ヒューリスティックはローカルで動作し、データを送信しません。--judge openai を選択すると、上限を設けて再帰的にマスキングしたメタデータの抜粋が、設定済みの OpenAI モデルに送信されます。内部サーバーの指示に対して有効にする前に、このプライバシー上の境界を確認してください。

カスタム静的ルール

--rules path/to/rules.json を渡すと、組み込みルールにルールオブジェクトを追加できます。各ルールの形式は次のとおりです。

{
  "id": "ORG001",
  "title": "Example organization policy",
  "category": "tool_poisoning",
  "severity": "high",
  "description": "Why this candidate deserves semantic review.",
  "patterns": ["(?i)example pattern"],
  "fields": ["description", "schema"]
}

サポートされるカテゴリは prompt_injection、tool_poisoning、tool_shadowing、ssrf、secret_exfiltration、command_execution、destructive_operation、cross_server_attack、oauth_confused_deputy、rug_pull、resource_exhaustion、protocol_integrity です。

正規表現を評価する前に、スキャナーは Unicode NFKC 正規化を適用し、幅ゼロ文字などの書式制御文字を削除し、分析専用ビューで空白をまとめます。正当なメタデータを誤って表現するリスクがあるため、スクリプトをまたぐホモグリフの書き換えは意図的に行いません。これらへの対応を主張する前に、ベンチマークを使ってカバレッジの不足を追跡してください。ディスクリプターフィールドにはバイト数の上限もあります（名前は4 KiB、説明は64 KiB、スキーマとメタデータはそれぞれ192 KiB、合計512 KiB）。上限を超えたディスクリプターでは、元のバイト数と SHA-256 を含む MCP-N001 が生成され、レポート、ルール、ベースライン、または任意のセマンティック判定器に渡されるデータは上限内に制限されます。

カスタムルールは信頼されたセキュリティ設定として扱ってください。病的なパターンでは、Python の正規表現によって CPU を大量に消費する可能性があります。レビューされていないルール変更を、権限の強い CI ワークフローで実行しないでください。これらのファイルは、ポリシー変更と同様に保護し、レビューしてください。

ポリシー設定

--policy path/to/policy.json では、組織固有の許可／拒否制御を指定します。許可セレクターは、一致する静的候補または専用サーバー指示候補を抑制します。拒否セレクターは、セマンティック判定に依存せず、ポリシーによって強制された検出結果を出力します。セレクターには、ルール ID または記述子名の正規表現で範囲を限定したオブジェクトを指定できます。

{
  "allow": [{"rule_id": "MCP003", "subject_pattern": "^controlled_fetch$"}],
  "deny": ["MCP002"],
  "semantic_threshold": 0.75
}

完全なファイルについては、examples/policy.json を参照してください。ポリシーファイルはソース管理下に置き、変更をセキュリティ上重要な設定としてレビューしてください。

動的な Docker 検証

動的テストは、意図的にオプトイン方式とし、自分が所有するサーバーまたはローカルのテストフィクスチャに限定しています。実行には、明示的な確認、事前にビルドされたローカルイメージ、確信度の高いツール名の明示、および JSON 引数が必要です。ランナーは、ネットワークなし、ホストマウントなし、ルートファイルシステム読み取り専用、ケーパビリティの削除、非特権ユーザー、リソース制限、および呼び出しタイムアウトを設定した新しい Docker コンテナーを作成します。スキャンプロセスの環境変数がコンテナーに転送されることはありません。

mcpsentinel scan "python -m my_server" --transport stdio \
  --dynamic --i-own-this-target \
  --dynamic-image my-mcp-server:test \
  --dynamic-entrypoint "python -m my_server" \
  --dynamic-invoke 'unsafe_tool={"fixture": true}'

動的サーバーのイメージは、事前にローカルに存在している必要があります。MCPSentinel は --pull=never を使用します。明示的に呼び出すツールごとに、新しいコンテナー／セッションが作成されるため、選択したツール間で状態が影響することはありません。通常のメタデータスキャンに Docker は不要です。動的レスポンスは、SHA-256 ダイジェストとコンテンツタイプの概要のみ保持されます。ダイジェストの計算前に、MCP SDK が動的レスポンスをデコードする必要があります。そのため、レスポンスの動作を信頼できる、自分が所有するフィクスチャ／サーバーのみを呼び出してください。

所有するターゲットへの呼び出しごとに、MCPSentinel は呼び出しの直前と直後に Docker プロセス数を記録し、さらにコピーオンライトのファイルシステム変更を before → after および差分として記録します。Docker の出力が収集上限に達した場合は、テレメトリーに切り詰められたことを示します。プロセス引数やファイルシステムパスが保持されることはありません。呼び出し後も実行中のプロセスがある場合は MCP-D002 が出力されます。これはバックグラウンド処理のレビューを促すものであり、ホストへのエスケープの証拠ではありません。認証情報らしき内容がレスポンスに含まれる場合は、レスポンスのテキストをディスクに書き込まずに MCP-D001 を出力します。この限定的なテレメトリーでは、システムコールの追跡や任意の環境変数読み取りの検査は行わず、ネットワーク接続が試行されなかったことも証明できません。ネットワークの制御は、引き続きコンテナーの --network=none 境界によって行われます。

このリポジトリには、この境界をエンドツーエンドで検証するための、意図的にローカル専用とした Docker フィクスチャが含まれています。実行中の Docker デーモンが必要で、イメージをビルドするため、通常のテストスイートからは除外されています。

MCPSENTINEL_RUN_DOCKER_TESTS=1 pytest tests/test_dynamic_docker_e2e.py

GitHub Action

リポジトリのルートは複合 GitHub Action です。MCPSentinel をインストールし、スコープ付きベースラインキャッシュを復元して、SARIF を出力し、選択した重大度で失敗させます。動的テストは有効になりません。別のリポジトリからリリースタグを参照してください。サプライチェーンをより厳格に管理するには、完全なコミット SHA への固定を推奨します。

- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
- uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
  with:
    python-version: "3.12"
- uses: gentaArnezzi/[email protected]
  id: mcpsentinel
  with:
    target: https://mcp.example.com/mcp
    transport: http
    fail-on: high
    policy: .mcpsentinel/policy.json
- uses: github/codeql-action/upload-sarif@d6317709a54fd87078d323eeb0e48ec331c8e621 # v3
  if: always()
  with:
    sarif_file: ${{ steps.mcpsentinel.outputs.sarif }}

この Action は ${{ github.base_ref || github.ref_name }} を使ってキャッシュのスコープを設定します。そのため、main へのプッシュでは main の信頼スコープが使われ、main 向けのプルリクエストでは、合成された 42/merge スコープを作成せず、同じ承認済みベースラインを復元します。プルリクエストでは復元のみが行われ、信頼済みベースラインを置き換えて保存することはできません。成功した信頼済みのプッシュ／ワークフロー実行では、実行ごとに不変のキャッシュを保存できます。キャッシュはワークフローの利便性のための状態であり、保護ブランチやレビューに代わるものではありません。通常の fail-on の結果では、ステータス 1 を返す前に SARIF レポートと definition-fingerprint 出力が書き込まれます。セキュリティゲートが失敗した場合にも証跡を保持するには、if: always() のアップロードステップが必要です。

ベースラインを承認するには、まずスキャンの definition-fingerprint 出力を確認してください。次に、保護ブランチ上の別の信頼済みワークフローに、その値をそのまま渡します。この Action はサーバーを再検出し、定義が変更されている場合は承認を拒否します。コントリビューターからのプルリクエストでは、承認を有効にしないでください。

- uses: gentaArnezzi/[email protected]
  if: github.event_name == 'push' && github.ref == 'refs/heads/main'
  with:
    target: https://mcp.example.com/mcp
    transport: http
    fail-on: none
    approve-baseline-fingerprint: "sha256:<fingerprint-you-reviewed>"

この Action は、GitHub ランナー上でプロセスを起動することになるため、デフォルトで stdio ターゲットを拒否します。信頼済みの保護されたプッシュワークフローで、自分が管理するソースに限り有効にしてください。信頼できないプルリクエストやフォークでは、決して有効にしないでください。

- uses: gentaArnezzi/[email protected]
  if: github.event_name == 'push' && github.ref == 'refs/heads/main'
  with:
    target: python server.py
    transport: stdio
    allow-stdio-execution: "true"

judge: openai または auto を選択する場合に限り、ワークフローで OPENAI_API_KEY を設定してください。heuristic がデフォルトのままです。たとえば、env: OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }} を指定して、スキャンステップだけに GitHub Actions のシークレットを公開します。

MCP ネイティブスキャナー

mcpsentinel-mcp を実行すると、stdio 経由でスキャナーを MCP ツール scan_mcp_server として公開できます。CLI より意図的に制約が厳しく、オペレーターが許可リストに登録した HTTP ターゲットのみをスキャンします。ターゲットの stdio コマンド、動的実行、ベースライン承認を拒否するため、MCP クライアントがスキャンリクエストをローカルプロセスの実行に利用したり、信頼スナップショットをひそかに変更したりすることはできません。構造化レスポンスには、JSON レポートや HTML レポートと同じ認証情報を安全に扱うシリアライズが使われます。

export MCPSENTINEL_ALLOWED_HOSTS="mcp.example.com,localhost"
mcpsentinel-mcp

許可リストには host または完全一致の host:port を指定できます。HTTP リダイレクトは拒否され、各検出セッションの期限は30秒です。MCP によるデコード前の生 HTTP レスポンスは最大2 MiB に制限され、プライベートアドレスまたは予約済みアドレスはデフォルトで拒否されます。検証済みの DNS アドレスセットは HTTP トランスポートに固定される一方、元のホスト名は HTTP Host および TLS SNI 名として維持されます。これは、信頼済みのプライベートネットワークを明示的に許可している場合にも適用されるため、2回目の DNS ルックアップによって接続先アドレスが変わることを防ぎます。

オプションのオペレーター設定は MCPSENTINEL_MCP_BASELINE_DIR、MCPSENTINEL_RULES_PATH、MCPSENTINEL_POLICY_PATH、MCPSENTINEL_MCP_JUDGE、MCPSENTINEL_MCP_JUDGE_MODEL です。MCP 呼び出し元は任意のポリシーファイルやベースラインパスを選択できず、MCP ネイティブスキャンでベースラインが承認されることもありません。信頼済みの stdio サーバーには、人間が操作する CLI を使用してください。スキャンのフィンガープリントを確認してから、そのフィンガープリントを指定して mcpsentinel baseline approve を実行します。

レジストリへの公開

MCPSentinel は PyPI では mcp-guardian-scan として、公式 MCP Registry では公開されています。mcpsentinel は使用できなかったため、PyPI パッケージの名前は異なりますが、製品名、インポートパッケージ、CLI は MCPSentinel と mcpsentinel のままです。

具体的な registry/server.json は、パッケージとバージョンを一致させて管理しています。リリースワークフローでは、アーティファクトをビルドして監査し、信頼されたパブリッシングを通じて PyPI に公開した後、GitHub OIDC を通じて対応する Registry メタデータを送信します。リリースの詳細については registry/README.md と、公式のパッケージタイプのドキュメントを参照してください。

コンテナーイメージ

プレリリースではない GitHub Release ごとに、バージョン付きイメージと latest が GitHub Container Registry に公開されます。

docker pull ghcr.io/gentaarnezzi/mcpsentinel:0.8.8
docker run --rm ghcr.io/gentaarnezzi/mcpsentinel:0.8.8 scan https://mcp.example.com/mcp --transport http

初回の GHCR パッケージは、リポジトリ所有者が GitHub Packages で公開範囲を Public に設定する必要がある場合があります。ローカル開発では、スキャナーイメージを直接ビルドしてください。

docker build -t mcpsentinel:local .
docker run --rm mcpsentinel:local scan https://mcp.example.com/mcp --transport http

このイメージには意図的に Docker ソケットが含まれておらず、動的レイヤーを実行できません。動的検証は、Docker を設定した信頼できるホストから実行してください。

データセット

datasets/vulnerable_by_design には、すべてのデフォルトの静的ルールを対象とした回帰テスト用に、制御された記述子レベルのグラウンドトゥルースが含まれています。これを使うと、決定論的に200 個の合成記述子が生成されます。内訳は、手作業で精選したコントロール 35 件と、テンプレートで生成したバリアント 165 件です。安全なハードネガティブ、Unicode／ゼロ幅文字による回避、非英語のコントロール、メタデータ／スキーマのバリアント、意図的にカバー対象外としたコントロールが含まれています。実在するサードパーティのターゲットや、実行可能な破壊的ペイロードは含まれていません。ラベリングプロトコルには、出自とレビューの取り決めが記載されています。

オフライン判定器を使って、再現可能な精度と所要時間の測定を実行します。

mcpsentinel benchmark datasets/vulnerable_by_design/manifest.json --format json --output benchmark.json

このベンチマークでは、データセットでレポート対象とされるルールの期待値に対して、生の静的候補とセマンティック検出結果の両方を測定します。適合率、再現率、偽陽性率、F1、混同行列の件数、各ステージの所要時間、セマンティック評価の呼び出し回数、カテゴリ別の内訳、出自別の件数、推定 API コスト（オフラインヒューリスティックでは $0、プロバイダーの料金が設定されていない場合は n/a）を報告します。JSON レポートとターミナルレポートには、追跡可能性を確保するため、ソースマニフェストの SHA-256 とスキャナーのバージョンが含まれます。10 件の有界フェッチコントロールは、意図的に静的解析では偽陽性、セマンティック解析では真陰性としてカウントされるため、ノイズ抑制の回帰を CI やリリースレビューで確認できます。

分母は明示的に 2 種類報告されます。正確な記述子／ルールのペアと、何らかの検出結果がある記述子です。ルールペアの陰性には、特定の記述子には適用されないルールが含まれるため、この偽陽性率は開発者がノイズの多い結果を受け取る確率ではありません。合成した陰性記述子 60 件のうち、静的解析では 10 件（16.7%）にフラグが立ち、ヒューリスティックによるトリアージでは 0 件でした。記述子単位の指標はより粗い指標です。陽性記述子で誤ったルールが検出されても、その記述子は検出済みとしてカウントされます。どちらの指標も、独立してテストされたサーバーの数を表すものではありません。再現可能な JSON 結果を参照してください。

オフラインヒューリスティックとデフォルトのしきい値（0.70）を使った、同梱の 200 件のコーパスでは、静的候補の適合率は 0.932、再現率は 0.958、F1 は 0.944、偽陽性率は 0.005 です（TP=136、FP=10、TN=1848、FN=6）。セマンティックトリアージの適合率は 1.000、再現率は 0.965、F1 は 0.982、偽陽性率は 0.000 です（TP=137、FP=0、TN=1858、FN=5）。専用のサーバー指示文処理経路は、静的解析だけでは出力できないシグナルを 1 件補足します。意図的に検出対象から外した 5 件（非英語の一般的なプロンプトインジェクションコントロール 4 件と、メタデータの配置に関する破壊的操作コントロール 1 件）は、除外されず、引き続き確認できます。SSRF カテゴリは、両方のステージを報告する理由を示しています。このカテゴリの制御されたケースでは、静的解析の適合率が 0.545 であるのに対し、セマンティック解析の適合率は 1.000 です。

これは再現可能な回帰シグナルであり、公開 MCP サーバーの精度、再現率、実環境での偽陽性率、または他のスキャナーに対する優位性を主張するものではありません。生成されたバリアント 165 件は、テスト範囲を広げるためのコントロールであり、実環境における独立した 165 件の観測ではありません。

厳選された公開メタデータ v2

datasets/curated_public_metadata_v2 では、ソースを特定でき、寛容なライセンスで提供されている MCP 実装から、文字どおりのツール記述子を428件追加しています。内訳は、AWS Labs の Apache-2.0 リポジトリから329件、GitHub の MIT ライセンスの MCP サーバーから99件です。各ケースには、リポジトリ、完全なコミット SHA、ライセンス、ソースパス、行番号、ソースファイルの SHA-256 が記録されています。抽出ツールはローカルのチェックアウトのみを読み取り、アップストリームの MCP サーバーに接続したり、呼び出したりすることはありません。

これはネガティブコントロールベンチマークです。通常の、ドキュメント化されたツールメタデータでは、リスク範囲が限定されない問題は検出されないことが想定されています。対象範囲を限定したクラウド削除や書き込み操作を行えるツールが、必ずしも脆弱性となるわけではないため、このコーパスではソースプロジェクトを安全でないものとしてラベル付けしていません。v0.8.8 の10シグナルベンチマーク契約では、ヒューリスティックによる候補の検出はゼロで、記述子とルールのネガティブペア4,280件における偽陽性率は 0.000 です。ラベル付きのポジティブ例がないため、適合率、再現率、F1 は 1.000 ではなく、正しく n/a と表示されます。

mcpsentinel benchmark datasets/curated_public_metadata_v2/manifest.json \
  --judge heuristic --format json --output benchmark-v2.json

v2 コーパスはメンテナーによるレビューを1回受けており、明示的に independent-review-pending とマークされています。これは、公開メタデータにおける偽陽性の証拠を強化するものですが、公開サーバーでの再現率、実環境における脆弱性の発生率、または他のスキャナーに対する優位性を示すものではありません。

許可済みメタデータのポジティブ例 v3

datasets/authorized_positive_metadata_v3 では、Cisco の Apache-2.0 ライセンスの MCP Scanner 評価コーパスから、意図的に悪意を持たせたメタデータのフィクスチャを16件追加しています。Cisco が直接付与したシナリオラベルは、プロンプトインジェクションと不正なコード実行を対象としており、MCPSentinel はそれらを18件のルールとケースのペアに対応付けています。各ケースでは、ソースパス、関数の行番号、ファイルダイジェスト、完全なコミットを固定しています。抽出ツールはローカルのチェックアウトのみを読み取ります。

mcpsentinel benchmark datasets/authorized_positive_metadata_v3/manifest.json \
  --judge heuristic --format json --output benchmark-v3.json

v3 はキャリブレーション用の回帰コントロールであり、ホールドアウト精度の調査ではありません。ラベルは、0.7.0 で追加された限定的なメタデータルールに反映されています。この固定された構成では、ラベル付きペア18件すべてが報告される一方、428件の v2 公開ネガティブコントロールでは候補がゼロのままです。これは、改良によって対象となる公開スナップショットで偽陽性が生じなかったことを示す有用な証拠ですが、実環境での再現率を証明するものではありません。メンテナー1名が v3 のマッピングをレビューしています。回帰テストの範囲を超えて引用する場合は、独立レビューのプロトコルを参照してください。

サーバー指示 v4

datasets/server_instructions_v4 では、専用の MCP-S001 パス向けに、メタデータのみを対象とする厳選されたコントロールを28件追加しています。内訳は、英語の無害な指示5件と悪意のある指示5件、英語以外の無害な指示5件と悪意のある指示5件、Unicode／ゼロ幅文字による難読化4件、外部転送に関する曖昧なケース4件です。

mcpsentinel benchmark datasets/server_instructions_v4/manifest.json \
  --judge heuristic --format json --output benchmark-server-instructions.json

v0.8.8 のヒューリスティック構成では、全体のセマンティック評価は適合率 1.000、再現率 1.000、F1 1.000、偽陽性率 0.000 です（TP=27、FP=0、TN=253、FN=0）。専用の MCP-S001 では、英語と英語以外の各セグメントの適合率、再現率、F1 がいずれも 1.000 で、無害なケースと悪意のあるケースがそれぞれ5件含まれています。静的解析だけでは、コーパス内でラベル付けされた27件のペアのうち再現できるのは 0.333 にとどまり、独立したセマンティックパスが存在する理由を示しています。これらは厳選された回帰コントロールであり、実環境における発生率や精度を独立して示す証拠ではありません。

MCPSentinel で分かること、分からないこと

MCPSentinel は、次の 3 つのワークフローにおける事前確認の手がかりとして役立ちます。個人の開発者が MCP サーバーをさらに詳しく調査するかどうかを判断する場合、メンテナーがリリース前にメタデータをセルフ監査する場合、セキュリティチームがブロックしない CI ゲート、またはレビューを経る CI ゲートを追加する場合です。

MCPSentinel は公開されている MCP メタデータを検出しますが、サーバーのソースコードを読み取ることも、認可境界を証明することも、実行時の動作が誠実な説明と一致することを保証することもありません。問題のないレポートが出ても、サーバーが安全である証明にはなりません。動的検証の対象はさらに限定されています。自分が所有するイメージから、明示的に指定した信頼度の高いツールのみを、指定した引数で呼び出せます。プロセスおよびファイルシステムのカウンターは、レビュー用に範囲を限定した証拠であり、完全な動作計測ではありません。任意の公開サーバーを調査する安全な方法ではありません。

デフォルトのスキャナーは読み取り専用です。検出したツールの呼び出し、HTTP リダイレクトの追跡、GitHub Action または MCP ネイティブサーバーからの動的実行の有効化は一切行いません。結果はレビューの証拠として使用し、ソースレビュー、依存関係レビュー、権限／外部通信の制御、および通常のインシデント対応プロセスと組み合わせてください。

開発

pytest
ruff check .

このプロジェクトは、意図的に依存関係を最小限に抑えています。mcp はプロトコルの検出を処理し、Rich は対話型ターミナル表示を行います。また、コアのルールエンジン、スナップショットストア、レポート出力機能には標準ライブラリを使用します。

セキュリティ

脆弱性の報告方法とサポート対象バージョンについては、SECURITY.md を参照してください。