MCPGuard-Lab

実際の mcp==2.0.0 SDK に基づく MCP ツール呼び出しセキュリティ実験プロジェクト。外部の大規模言語モデルや API キーに依存せず、決定論的なポリシーにより、ツールホワイトリスト、パラメータ検証、ファイル境界、SSRF 対策、機密操作の確認、出力のサニタイズ、ツール説明のポイズニング検出、JSONL 監査を実現し、回帰テストで防御が後の変更で壊れないことを確認します。

使用範囲：本プロジェクトはローカル実験、許可されたテスト、防御研究のみを目的としており、未承認のターゲットに対する攻撃機能は含まれません。

実装済み機能

• MCP 2.0 stdio サーバーと実際のクライアント間の往復テスト。

• 6つのデモツール：安全な計算、ルートディレクトリ内のファイル読み取り、ノートクエリ、公開 URL リクエスト、ツールメタデータチェック、確認後のノート書き込み。

• ツールホワイトリストと JSON Schema による厳格な検証、追加パラメータを拒否。

• ファイルパスの正規化、絶対パス、ディレクトリトラバーサル、ルートディレクトリからの脱出を拒否。

• URL プロトコル、ユーザー情報、ポート、DNS 解決結果のチェック、ループバック、プライベートネットワーク、リンクローカルなどの非パブリックアドレスを拒否。

• 書き込み操作 confirmed=true のゲート。

• 信頼できないツール出力に明示的なラベル付け；パスワード、トークン、API キー、Bearer 資格情報を再帰的にサニタイズ。

• ツール名/説明における高リスクなプロンプトインジェクションシグナルの検出。

• 各決定を JSONL に記録：リクエスト ID、時刻、ツール、パラメータ、許可/拒否、理由、結果。

• pytest ユニット/統合テストと再現可能な攻撃回帰レポート。

Related MCP server: meok-mcp-injection-scan-mcp

アーキテクチャ

MCP Client
   │ stdio / MCP 2.0
   ▼
MCP Server ──► GuardedGateway ──► PolicyEngine
                      │                 ├─ allowlist + schema
                      │                 ├─ path boundary
                      │                 ├─ URL / SSRF
                      │                 └─ confirmation
                      ├─ Tool handler
                      ├─ untrusted labeling + redaction
                      └─ JSONL audit

中核原則は「まず決定、次に実行、出力を浄化し、全過程を記録する」。プロンプトテキストが直接追加の権限を得ることはなく、権限はコード内のホワイトリストとポリシーに基づきます。

クイックスタート（Windows）

py -3.10 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"
.\.venv\Scripts\python.exe -m pytest
.\.venv\Scripts\python.exe -m mcpguard.regression

直接実行することもできます：

powershell -ExecutionPolicy Bypass -File .\scripts\verify.ps1

レポートは以下に生成されます：

• reports/regression-report.md

• reports/regression-report.json

• reports/regression-audit.jsonl

MCP クライアント設定例

最初に pip install -e . を実行し、以下の構造を現在のリポジトリの絶対パスに置き換えてください：

{
  "mcpServers": {
    "mcpguard-lab": {
      "command": "D:/path/to/mcpguard-lab/.venv/Scripts/python.exe",
      "args": ["-m", "mcpguard.server"],
      "env": {
        "MCPGUARD_WORKSPACE": "D:/path/to/mcpguard-lab/fixtures/workspace",
        "MCPGUARD_NOTES": "D:/path/to/mcpguard-lab/fixtures/workspace/notes",
        "MCPGUARD_AUDIT": "D:/path/to/mcpguard-lab/reports/audit.jsonl"
      }
    }
  }
}

実際の限界

• ツール説明のポイズニング検出は高シグナルルールレイヤーであり、人間によるレビューと固定ホワイトリストの代わりにはなりません。

• confirmed=true はローカル実験における明示的な確認ゲートです；本番環境では、ホスト UI/ID システムによって発行され、モデル自身が偽造できない確認資格情報を使用すべきです。

• URL ツールは現在リダイレクトを無効にしており、最初のホップでチェックを通過した後に内部ネットワークにジャンプするのを防ぎます；本番版では応答サイズ、コンテンツタイプ、出口ネットワークも制限すべきです。

• 信頼できないコンテンツへのラベル付けは「データが命令として扱われる」リスクを低減しますが、最終的なホストエージェントは依然として信頼境界に従う必要があります。

• 回帰データはリポジトリ内の固定テストケースのみを表し、すべてのプロンプトインジェクションやすべての MCP リスクをブロックできるわけではありません。

目次

src/mcpguard/       核心实现
tests/              单元测试与真实 MCP stdio 集成测试
fixtures/           可公开的本地测试数据
reports/            自动生成的测试和审计证据
scripts/verify.ps1  一键验证入口

参考

• Model Context Protocol Python SDK

• AgentDojo