MCP Agent Firewall

Model Context Protocol (MCP) 2026-07-28 トラフィックのための決定論的セキュリティゲートウェイ。

エージェント/MCP クライアントとリモート MCP サーバーの間に位置し、信頼境界の両側を強制します:

• 実行前: プロトコル整合性、決定論的ポリシー、ピン留めされたツールスキーマ、署名付きの人間による承認

• 実行後: レスポンス側の資格情報 DLP、制限付き検査、明示的な非信頼コンテンツのラベル付け、プライバシーを最小化した出力監査

セキュリティの判断は LLM に委ねられることはありません。

現在のマイルストーン — v0.5.0

v0.5 ではレスポンス側の出力封じ込めが追加されました。

承認されたツール呼び出しも、信頼できる出力を生成するとは想定されなくなりました。すべてのアップストリームレスポンスは、呼び出し元に返される前に検査されます。シークレット/資格情報に似た出力はブロックされ、プロンプトインジェクションに似たテキストにはフラグが付き、通過したすべてのアップストリームコンテンツには非信頼のラベルが明示的に付けられます。

agent / MCP client
        |
        v
MCP header/body integrity
        |
        v
deterministic policy
        |
        +--> DENY ------------------------------> stop
        |
        v
pinned tool catalog + JSON Schema
        |
        v
signed human approval when required
        |
        v
mcp.upstream.dispatch                   [CLIENT span]
        |
        v
upstream MCP server
        |
        |  UNTRUSTED OUTPUT
        v
mcp.output.inspect
        |
        +--> credential / secret -------------> BLOCK 502 / -32046
        |
        +--> malformed / binary / oversized --> BLOCK 502 / -32046
        |
        +--> prompt-injection signal ----------> FLAG + pass through
        |
        +--> clean ----------------------------> pass through
        |
        v
explicit untrusted-content headers
        |
        v
agent / MCP client

Parallel controls:
- privacy-minimized request + output SQLite audit
- low-cardinality OpenTelemetry metrics
- optional OTLP HTTP export

Related MCP server: guardrails-mcp-server

レスポンス側の封じ込め

資格情報/シークレット DLP

決定論的な出力スキャナーは、認識された資格情報マテリアルをブロックします。これには以下が含まれます:

• access_token、refresh_token、api_key、private_key、authorization、password、secret などの構造化されたシークレットを含むキーと関連バリアント

• PEM 秘密鍵マテリアル

• Bearer 資格情報

• AWS アクセスキー ID

• GitHub スタイルのトークン

• OpenAI スタイルの sk- 資格情報

• JWT 形式の資格情報文字列

ブロックされたアップストリームレスポンスは、ファイアウォールが生成した JSON-RPC エラーに置き換えられます:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32046,
    "message": "Upstream MCP response blocked by output containment",
    "data": {
      "action": "block",
      "signals": ["sensitive_key"],
      "untrusted": true
    }
  }
}

ブロックされたレスポンスボディはエラー内には表示されません。

プロンプトインジェクションへの対応

出力プロンプトインジェクション正規表現はシグナルであり、セキュリティ上の決定権を持つものではありません。

たとえば、「ignore previous instructions（以前の指示を無視する）」のようなコンテンツは、ブロック対象になるシークレットシグナルが含まれていなければ通過が許可されます。ただし、呼び出し元には次の情報が渡されます:

Mcp-Firewall-Untrusted-Content: true
Mcp-Firewall-Output-Inspection: flagged
Mcp-Firewall-Output-Signals: prompt_injection_signal

クリーンな出力であっても、次の情報が提供されます:

Mcp-Firewall-Untrusted-Content: true
Mcp-Firewall-Output-Inspection: clean

これにより、ツールによって返されたデータと信頼された指示との違いが保たれます。

フェイルクローズドなレスポンス境界

出力検査では以下をブロックします:

• JSON として宣言されているにもかかわらず解析できない内容

• 非 UTF-8 のバイナリ出力

• MAX_RESPONSE_BYTES（既定 262,144 バイト）を超えるレスポンス

• 32 レベルを超える深さの JSON

• 10,000 ノードを超える JSON トラバーサル

{ または [ で始まる UTF-8 出力は、アップストリームサーバーがうつ場合であっても非 JSON メディアタイプを宣言している場合でも JSON としてパースされるため、構造化キー DLP の単純なコンテンツタイプによる回避を防ぎます。

現時点での制限: httpx はサイズチェックを行う前にアップストリームレスポンスをバッファリングします。そのため、この制限は検査/返却の動作を制約しますが、ストリーミング時のネットワークメモリ制約にはまだなっていません。

プライバシーを最小化した出力監査

GET /v1/audit/output は、リクエスト監査と同様に X-Operator-Token 制御によって保護されています。

出力監査レコードには以下のみが含まれます:

• タイムスタンプ

• メソッド/ツール名

• clean、flagged、blocked のいずれかの結果

• 固定語彙のシグナル名

• レスポンスの SHA-256

• レスポンスのバイト長

生のアップストリームレスポンスボディは出力監査に永続化されることはありません。

OpenTelemetry による可観測性

セキュリティ関連のスパンは以下を含みます:

• mcp.firewall.request

• mcp.policy.evaluate

• mcp.schema.validate

• mcp.approval.issue

• mcp.approval.verify

• mcp.approval.consume

• mcp.upstream.dispatch

• mcp.output.inspect

低カーディナリティなメトリクス:

ツール名とリクエストハッシュはトレース専用であり、メトリクスのディメンションには含まれません。トレース文字列はサニタイズされ、長さが制限されています。生のリクエスト引数、レスポンスボディ、承認レシート、ID、認証トークンはテレメトリから除外されます。

v0.1–v0.4 から引き継がれたリクエスト側の制御

• MCP-Protocol-Version、Mcp-Method、Mcp-Name の整合性チェック

• デフォルト拒否の決定論的ツールポリシー

• シェル/コマンド/資格情報スタイルのツールに対する明示的拒否パターン

• 影響の大きい送信/作成/更新/削除/購入/転送/デプロイ系ツールに対する人間の承認

• ネストされたシークレットキー、保護パス、文字列サイズ、数値のリクエスト制約

• 正規表現にセキュリティ権限を与えないプロンプトインジェクションシグナル

• SHA-256 でピン留めされた信頼ツールカタログ

• JSON Schema 2020-12 の引数検証

• 信頼された x-mcp-header / Mcp-Param-* ボディヘッダー検証

• HMAC-SHA256 の短時間有効な一回限り承認レシート

• 呼び出し元の認可をアップストリームに転送しない

• プロセス単位のレート制限と上限付きリクエストボディ

• W3C TraceContext の抽出 + 生成されたアップストリーム伝播

• オプションの OTLP HTTP トレース/メトリクスエクスポート

セットアップ

UPSTREAM_MCP_URL=https://your-mcp-server.example/mcp
MAX_BODY_BYTES=65536
MAX_RESPONSE_BYTES=262144

APPROVAL_SIGNING_KEY=<random-secret-at-least-32-bytes>
APPROVAL_ISSUER_TOKEN=<operator-only-token>
APPROVAL_DEFAULT_TTL_SECONDS=300
APPROVAL_MAX_TTL_SECONDS=900

TRUSTED_TOOL_CATALOG_PATH=./config/trusted_tools.example.json
TRUSTED_TOOL_CATALOG_SHA256=<canonical-catalog-sha256>

AUDIT_READ_TOKEN=<operator-only-token>

OTEL_ENABLED=false
OTEL_SERVICE_NAME=mcp-agent-firewall
OTEL_EXPORTER_OTLP_ENDPOINT=

すべてのゲートを実行

pip install -e ".[dev]"
ruff check app tests scripts
pytest -q
python scripts/run_benchmark.py --fail-on-unsafe
python scripts/run_approval_benchmark.py
python scripts/run_schema_benchmark.py
python scripts/run_observability_benchmark.py
python scripts/run_output_benchmark.py
docker build -t mcp-agent-firewall:test .

検証済み v0.5 回帰テストの結果

v0.5 実装について GitHub Actions で検証済み:

• pytest テスト 74 件合格

• ポリシー安全性ベンチマーク: 32/32 の完全判定一致

• ポリシー安全性ベンチマーク: 安全でない誤受理 0 件、誤ブロック 0 件

• 署名付き承認セキュリティベンチマーク: 11/11 合格

• 署名付き承認セキュリティベンチマーク: 安全でない誤受理 0 件

• 信頼済みスキーマ / MCP ヘッダーベンチマーク: 12/12 合格

• 信頼済みスキーマ / MCP ヘッダーベンチマーク: 安全でない誤受理 0 件、誤ブロック 0 件

• 可観測性プライバシー / 伝播ベンチマーク: 14/14 合格

• 可観測性ベンチマーク: テレメトリの漏洩検出 0 件

• 出力封じ込めベンチマーク: 11/11 合格

• 出力封じ込めベンチマーク: 安全でない誤受理 0 件

• Ruff: 合格

• Docker ビルド: 合格

出力封じ込めベンチマークは、クリーンなパススルー、構造化シークレットキー、PEM 秘密鍵、Bearer 資格情報、GitHub スタイル資格情報、プロンプトインジェクションシグナル、不正な JSON、バイナリ出力、レスポンスサイズ上限、誤解を招くコンテンツタイプ、元の内容を表示しない公開検査メタデータをカバーしています。

可観測性ベンチマークは、実際の FastAPI/MCP リクエストを通じて、W3C 親コンテキスト、ポリシー/スキーマ/承認/出力スパン、制限付きメトリクスのディメンション、生成されたアップストリームトレース伝播、出力の非信頼ラベル付け、取得したテレメトリ内に注入を検出しないことを検証します。シークレットセンチネルが注入されていないことも確認します。

これらは合成回帰テストであり、本番環境での普遍的なセキュリティや、資格情報/プロンプトインジェクションの完全な検出を保証するものではありません。

信頼境界、制御、および残存リスクについては、docs/THREAT_MODEL.md を参照してください。

今後のマイルストーン

1. キー ID と限定された期間でバックアップした承認署名キーのローテーション

2. ストリーミングレスポンスサイズの強制と、オプションの安全なコンテンツタイプ許可リスト

3. マルチレプリカ展開のための共有 レプレイ/レートリミット 状態

4. ピン留めカタログに対するライブ アップストリーム tools/list のドリフト検出

5. 決定論的なローカルフォールバックを備えたオプションの OPA/Rego バックエンド

6. 実 MCP トレースから導出された敵対的コーパス