MCP Tool Security Inspector

Model Context Protocol ツールのメタデータに対する、説明可能で決定的な静的解析。

セキュリティ免責: MCP Tool Security Inspector は防御的な解析ツールです。潜在的な問題を通知しますが、MCP ツールやサーバーが指定する悪意を持つか安全であるかを判断することはできません。

スクリーンショットのプレースホルダ

• screenshots/clean-scan.png — クリーンなカタログの要約

• screenshots/suspicious-scan.png — 検出されたエビデンスと推奨事項

• screenshots/drift-comparison.png — ベースラインのドリフト比較

Related MCP server: mcp-guardian

問題の背景

AI クライアントは、MCP ツール名、説明、スキーマ、メタデータをモデルに公開します。このカタログは信頼の境界です。誤解を招く説明、隠れた機能、意図しない資格情報フィールド、またはその後のスキーマ変更は、ツールが実行されていない場合でもレビューの対象になります。mcpsec は、ツールを使用したりメタデータURLを取得したりすることなく、静的な面を解析します。

MCPとMCPツールとは

Model Context Protocol は、AI アプリをコンテキストと機能を公開するサーバーに接続するためのオープンなプロトコルです。ツールとは、名前付きで呼び出し可能な機能メタデータ、入力とオプションの出力用の JSON スキーマを持つものです。このリリースは、公式の 2026-07-28 仕様と安定版の公式 Python SDK v2 を対象とし、開発中の一般的なカタログのエンベロープにも対応します。

脅威モデルとツールポイズニング

ツールメタデータは、人の承認とモデルのツール選択の両方に影響を与える可能性があります。悪意のあるパブルかサーバーか、依存関係。依存関係、または偶発的な変更加や、モデルへの指示、シークレットの場所、特権フィールド、難読化が追加される可能性があります。脅威モデル を参照し、ツールポイズニング も参照してください。

特徴

• 単一ツール、配列、直接の tools オブジェクト、および JSON-RPC tools/list レスポンスの読み込み

• 未知のフィールドの保持と、Unicode NFC 正規化

• 安定した UTF-8 正規化 JSON と SHA-256 の全体/コンポーネントのフィンガープリント

• プライバシーできないベースラインと、フィールド単位のドリフト分類

• 検出: 指示は許し、隠れい、機密データ、スキーマ、不整合、難読化、ケーパビリティ可用性

• safe_load と境界付きリテラルマッチングによるデータ専用 YAML ルール

• 説明可能な上限付きリスクスコア（0–100）

• リッチなターミナル、JSON、CSV、SARIF 2.1.0 の出力

• エビデンスマスクとスプレッドシート公式インジェクション対策

• CI での重大度値をまとめた文書化された終了コード

• 使用なし、テレメトリなし、ツール呼び出しなし、アイコン使用なし、URL 取得なし、メタデータ実行なし

アーキテクチャ

flowchart LR
  A["Hostile JSON catalog"] --> B["Bounded loader"]
  B --> C["Normalizer"]
  C --> D["Canonicalizer + SHA-256"]
  C --> E["Detectors + data-only rules"]
  E --> F["Capped risk engine"]
  D --> G["Baseline comparator"]
  F --> H["Terminal / JSON / CSV / SARIF"]
  G --> H

この実装では、カタログ内容をモデルに送信することがあります。また、スキャンしたメタデータを実行することありません。アーキテクチャ を参照してください。

インストール

python -m venv .venv
# Windows: .\.venv\Scripts\Activate.ps1
# Linux/macOS: source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"
mcpsec --help

監査済みの環境とエディタのレファレンスは、PREPARATION.md をご覧ください。

クイックスタートとスキャンの実行

mcpsec scan examples/clean_tools.json
mcpsec scan examples/suspicious_tools.json
mcpsec scan examples/mixed_tools.json --format json
mcpsec scan examples/suspicious_tools.json --format csv --output report.csv --redact
mcpsec scan examples/suspicious_tools.json --format sarif --output report.sarif
mcpsec scan examples/mixed_tools.json --rules rules/default_rules.yml --fail-on high

構造化レポートには ANSI エスケープ シーケンスは含まれません。CSV フィールドの先頭がスプレッドシートの数式であるには、先頭に「ʼ」が付くプレフィックスが付けられます。

ベースラインとスキーマドリフトのワークフロー

mcpsec baseline examples/clean_tools.json --output baseline.json
mcpsec compare examples/clean_tools.json --baseline baseline.json
mcpsec compare examples/changed_tools.json --baseline baseline.json --verbose
mcpsec fingerprint examples/clean_tools.json

この変更では、電卓の説明と入力スキーマを変更し、unit_converter を追加します。ベースラインには、ハッシュと構造的な要約のみが保存され、完全な説明、デフォルト値、サンプルの機密情報は保存されません。スキーマドリフト を参照してください。

リスクのスコアリング

各検出に割り当てられた貢献は、検出の信頼度を乗算します。貢献度はカテゴリにグループ化され、カテゴリごとに35で課されます。カテゴリ リスクは 100 × (1 − Π(1 − カテゴリ/100)) で結合されます。既知の相関により、(指示の上書き ＋ 隠れ) では 10、(隠れ ＋ 機密データ) では 7 が加わります。最終的な値は丸められ、上限は 100 です。

バンド： 0–19 情報、20–39 低、40–59 中、60–79 高、80–100 クリティカル。このスコアはレビューの優先度を示すもので、確率や断定ではありません。

ルールと説明可能性

mcpsec rules list
mcpsec rules validate rules/default_rules.yml
mcpsec explain SEC-001

カスタムルールでは、ID、名前、カテゴリ、フィールド、リテラルパターン、重大度、信頼度、スコア、推奨事項、根拠、正常性の用途、有効状態を設定できます。Python 式、シェルコマンド、インポート、テンプレート、実行可能な正規表現は使用できません。検出ルール を参照してください。

出力形式

ターミナル・テーブルはツールの数、クリーン/権限付きの結果、重大度、リスク、ルール ID、エビデンス、および推奨事項を示します。JSON は構造化された検出結果を保存し、CSV は分析に適しています。SARIF は GitHub コードスキャン互換の構造で、将来の統合向けです。

CI での使用方法

終了コードは、設定されたしきい値を超えるものがなければ 0、完了後のスキャンが --fail-on を超えると 1、無効な入力は 2、内部障害は 3 です。

mcpsec scan catalog.json --fail-on medium

同梱の GitHub Actions ワークフローは Python のインストール、Ruff の lint/format チェック、mypy、scovr のある pytest を実行します。CPU リソースの利用やサーバーへの接続はありません。

テスト

ruff check .
ruff format --check .
mypy src
python -m pytest --cov=mcpsec --cov-report=term-missing --cov-report=html

Windows で環境がアクティブでない場合も、scripts\test.ps1 -q は正しい仮想環境インタープリタを実行します。ローカルのデモンサーバーでは、scripts\dev-inspector.ps1 ユニットしてください。サンプルサーバーのガイド を参照してください。Inspector が出力する /sandbox アドレスは内部URLであり、メインのユーザーインターフェースではありません。

テスト対象: 入力形式、Unicode、正規化、ハッシュ、ベースライン、ドリフト、検出器、リスク上限、ルール検証、safe YAML、構造化レポート、CSV アンクション、終了コード。

セキュリティモデルと偽陽性

すべての入力は信頼できないデータです。ファイルはサイズが無制限や、文字列は長さ制限され、YAML は safe_load で読み取り、スキーマの内容は検証され、実行されません。カスタムマッチはリテラルマッチで、記号があり、端末エスケープバイトは無害化され、リポーターは HTML を描画しません。検出結果は「疑わしい」または「要確認」を示すもので、「攻撃された」という断言ではありません。システムルールには、根拠、無害なトリガー、および具体的な操作が、mcpsec explain で説明されています。

SECURITY.md、検出ルール、および 制限事項 を参照してください。

制約

スキャンがクリーンでも安全性を保証しません。スキャンが疑わしくでも悪意を証明するものではありません。静的メタデータは実行時の実装と異なる場合があります。ヒューリシス方法は、すべての言語、ビジネスコンテキスト、スキーマ リファレンス、インプロンプトインジェクションのバリアントを理解することはできません。人間のレビューと実行時の制御は引き続き重要です。

ロードマップ

• v0.2: オプトイジェクトされたローカルカタログの取得（SDK の tools/list のみ）

• さらに強化された MCP 2026-07-28 の x-mcp-header 検証

• 署名付きのベースラインエンベロープとポリシーベースのプロファイル

• ルールパックのバージョン管理、規制の調整と差分 SARIF

• 言語固有のヒューリシスと、コーパス・ドリブンの偽陽性測定

コントリビュートとライセンス

CONTRIBUTING.md を参照してください。セキュリティ報告は SECURITY.md を参照してください。MIT License のもとでライセンスされています。