mcp-seatbelt

MCP Seatbelt — AI エージェントツールのランタイムガードレール

プロトコル層で危険な MCP ツール呼び出しをブロックします。スキャンし、プロキシし、強制します。

MCP Security Platform の一部です。 mcp-observatory（236★）で信頼する前にスキャンし、mcp-seatbelt でランタイムに強制します。📄 技術ホワイトペーパーを読む。

🌐 ウェブサイト： kryptosai.github.io/mcp-seatbelt — デモ、比較、料金

---

問題点

AI コーディングエージェント（Cursor、Claude、VS Code、ChatGPT、Windsurf など）は、ファイルシステム、シェルインタープリター、ネットワークアクセス、環境変数を公開する MCP サーバーに接続します。静的スキャナーは危険にさらされていることを知らせますが、事後にしか機能しません。スキャナーがリスクの高いサーバーを検出したときには、エージェントがすでに破壊的なコマンドを実行したり、認証情報を流出させたり、信頼できないエンドポイントに接続したりしている可能性があります。

MCP Seatbelt はランタイムの強制レイヤーを追加します。 エージェントとすべての MCP サーバーの間にポリシープロキシとして配置され、各 JSON-RPC ツール呼び出しを管理下のルールに照らして評価し、危険なリクエストが上流に到達する前に拒否します。TCP レベルでは動作せず、転送前に L7（MCP プロトコル層）ですべての呼び出しを検査し、ゲートチェックします。

---

できること

検出とプロキシ

• 8 つのクライアントの MCP 設定を検出 — Cursor、Claude Desktop、VS Code（ユーザー設定とワークスペース設定）、ChatGPT Desktop、Codex、JetBrains IDE（IntelliJ、PyCharm、WebStorm など）、Windsurf、およびプロジェクトローカルのファイル（.mcp.json、.mcp/config.json）から MCP サーバーの設定を自動的に検出します。手動での接続設定は不要です。

• ポリシーを適用するランタイムプロキシ — ポート 9420 で透過的な JSON-RPC 2.0 プロキシを起動します。すべてのツール呼び出し、リソースへのアクセス、プロンプト要求を傍受し、ポリシーと照合して、許可、拒否、警告、または編集による秘匿を行います。モードは 3 種類です。default-deny（ゼロトラスト）、allowlist（安全性が確認された対象のみ許可）、audit（ブロックせず、ログのみ記録）。

• 組み込みのリスクルール 13 種類 — シェルインタープリター（bash、sh、zsh、python、node）、サンドボックスの回避（--no-sandbox、--disable-web-security）、環境変数内の認証情報の露出、Docker の特権コンテナ、生のネットワークツール（curl、nc、telnet）、プロセスの起動、破壊的なファイルシステム操作、リモート URL へのアクセス、リスクの高いパッケージランナー（npx、uvx）、権限昇格（sudo、chmod）、機密性の高いファイルシステムパスを対象とします。

• 時間枠ルール、学習モード、ルール継承、コンテキスト認識に対応したポリシーエンジン — ルールでは、正規表現によるパターンマッチ、完全一致、部分文字列の包含をサポートします。曜日と時間帯（timeWindow）でツールへのアクセスを制限できます。クライアントの識別情報やリクエスト頻度（contextCondition）に基づいてルールを適用できます。ポリシーは親テンプレートをextendできます。auditモードは学習モードとして機能します。実際のツール使用状況を確認してから、enforceに切り替えてください。

• ライブダッシュボード、SARIF レポート、CI/CD 統合、オブザーバトリーブリッジ — リアルタイムの HTML ダッシュボードで、リクエスト統計、ブロック率、接続中のクライアント、最近ブロックされた呼び出しを確認できます。GitHub Code Scanning 用の SARIF 2.1.0 レポートを生成します。mcp-observatory からセキュリティ上の検出事項をインポートし、自動的にポリシールールへ変換します。mcp-seatbelt checkは、重大なリスクを検出した場合に CI でゼロ以外の終了コードを返します。

• 呼び出しごとのタイムアウト — ハングしたツール呼び出しを終了し、生の 503 ではなく、適切な JSON-RPC エラーを返します。ルールごとに設定できます（シェルコマンドは 10 秒、安全なツールは 60 秒）。

高度なセキュリティ

• OWASP LLM Top 10 へのマッピング — ブロックされた呼び出しにはすべて、OWASP のカテゴリ（LLM01 プロンプトインジェクション、LLM06 過度な自律性など）のタグが付与されます
• コンプライアンスフレームワークへのマッピング — ポリシールールには、SOC2、HIPAA、GDPR、ISO 27001、PCI-DSS の管理策タグが付与されます
• 複数ステップにわたる攻撃チェーンの検出 — XState ベースのステートマシンが、偵察 → 実行 → 永続化 → 情報流出という呼び出しシーケンスを追跡します
• ハニートークンの注入と検出 — ツールの応答におとりの認証情報（AWS キー、GitHub トークン、DB URL）を埋め込み、アクセス時に警告します
• フォレンジックセッションのキャプチャ — インシデント分析用に、リクエストとレスポンスのペアを.mcpcap.jsonとして記録します
• スキーマ対応の引数検証 — 宣言された JSON Schemas に照らしてツール引数を検証し、パストラバーサルやインジェクションを検出します
• 脅威インテリジェンスとの統合 — IP アドレスやドメインのレピュテーション確認に、ThreatFox IOC データベースを照会します
• 入力ファジング — ポリシールールに対してエッジケースのペイロードを生成し、回避手段を見つけます
• ロールベースのアクセス制御 — casbin によるエージェントごとの権限設定。管理者はすべてのツールを実行でき、エージェントにはスコープを限定したアクセス権が付与されます
• レスポンス DLP — 上流のレスポンスをシークレットのパターン（API キー、トークン、秘密鍵）についてスキャンし、該当箇所を編集して秘匿します

---

クイックスタート

npm install -g @kryptosai/mcp-seatbelt  # or: brew install mcp-seatbelt
npx @kryptosai/mcp-seatbelt init        # scan all clients, assess risk, generate policy
npx mcp-seatbelt proxy         # start the enforcing proxy on port 9420
npx mcp-seatbelt dashboard     # view live stats at http://localhost:9421

初回実行時に、initは.mcp-seatbelt/policy.yml（編集可能なルールセット）と.mcp-seatbelt/risk-report.md（各サーバーとそのリスクフラグの概要）を作成します。プロキシはデフォルトでauditモードで起動します。実際のツール使用状況を確認し、準備ができたらenforceに切り替えてください。

mcp-seatbelt fuzz --policy .mcp-seatbelt/policy.yml --iterations 200    # find policy bypasses
mcp-seatbelt record --output .mcp-seatbelt/sessions                      # forensic recording mode
mcp-seatbelt rbac-init -o .mcp-seatbelt                                  # init RBAC model + policy files

Docker

GitHub Actions により、リリースごとにイメージが自動的にビルドされ、公開されます。

docker run -p 9420:9420 -v $(pwd)/.mcp-seatbelt:/app/.mcp-seatbelt ghcr.io/kryptosai/mcp-seatbelt:latest proxy

GitHub Action

公式の GitHub Action を使用して、MCP Seatbelt を CI のセキュリティゲートとして実行できます。検出された MCP 設定をチェックし、代表的なツール呼び出しに対してポリシーをシミュレーションし、重大なリスクがある場合はビルドを失敗させます。

CI/CD との統合

- uses: KryptosAI/[email protected]
  with:
    mode: enforce
    fail-on-critical: true

すべての入力、出力、適用オプションについては、action.yml をご覧ください。

---

仕組み

┌─────────┐     JSON-RPC 2.0     ┌────────────────────────────────────┐     JSON-RPC 2.0     ┌─────────────┐
│  Agent  │ ────────────────────▶ │         MCP Seatbelt Proxy        │ ────────────────────▶ │  MCP Server │
│ (Cursor) │                      │          (localhost:9420)          │                       │  (filesystem)│
└─────────┘                      │                                    │                      └─────────────┘
                                 │  ┌──────────────┐  ┌───────────┐  │
                                 │  │ Policy Engine│──│Interceptor │  │
                                 │  │   ┌───────┐  │  │  ┌──────┐ │  │
                                 │  │   │ Rules  │  │  │  │Allow?│ │  │
                                 │  │   │Allowlist│  │  │  │Deny? │ │  │
                                 │  │   │Templates│  │  │  │Redact│ │  │
                                 │  │   │TimeWin │  │  │  │Warn? │ │  │
                                 │  │   └───────┘  │  │  └──────┘ │  │
                                 │  └──────────────┘  └─────┬─────┘  │
                                 │                          │        │
                                 │                    ┌─────▼─────┐  │
                                 │                    │ Transport │  │
                                 │                    │  Client   │  │
                                 │                    └───────────┘  │
                                 └────────────────────────────────────┘

• プロキシ — AI エージェントからの受信 JSON-RPC 2.0 リクエストを待ち受けます。サーバー登録、プロキシ URL のルーティング、接続のライフサイクルを管理します。
• ポリシーエンジン — 各リクエストを読み込まれたポリシーに照らして評価します。ツール名、引数、説明をルールに照らしてチェックし、理由とともに allow、deny、warn、redact のいずれかを返します。
• インターセプター — エンジンの判定を適用します。許可された呼び出しは転送されます。拒否された呼び出しには MCP エラーレスポンスが返されます。警告された呼び出しは処理が続行されますが、ログに記録されます。redact は、認証情報のパターンに一致する引数の値を *** に置き換えます。
• トランスポートクライアント — 許可されたリクエストを実際の上流 MCP サーバーに転送し、レスポンスをエージェントにストリーミングで返します。

プロキシは、上流からの未加工のエラーをエージェントに返しません。呼び出しがタイムアウトすると、子プロセスが強制終了され、エージェントには明確なエラーメッセージが返されます。503 エラーや接続のハングは発生しません。

すべてのリクエストは11 段階のパイプラインを通ります：RBAC → スキーマ検証 → パス安全性 → ポリシーエンジン → 脅威インテリジェンス → ハニートークン → 攻撃チェーン → プロキシ → レスポンス DLP → フォレンジック → 監査ログ。

---

比較

| 機能 | mcp-seatbelt | mcp-firewall | mcp-guardian | Prismor | mcp-proxy | |---|---|---|---|---|---|---| | 実行時のブロック | ✓ | ✓ | ✓ | ✓ | ✗ | | インストール前スキャン | ✓ | ✗ | ✗ | ✗ | ✗ | | 8 以上のクライアントを検出 | ✓ | ✗ | ✗ | ✗ | ✗ | | 引数の秘匿化 | ✓ | ✗ | ✗ | ✗ | ✗ | | 学習モード | ✓ | ✗ | ✗ | ✗ | ✗ | | ライブダッシュボード | ✓ | ✗ | ✓ | ✗ | ✗ | | SARIF ／ GitHub Code Scanning | ✓ | ✗ | ✗ | ✗ | ✗ | | mcp-observatory との統合 | ✓ | ✗ | ✗ | ✗ | ✗ | | 呼び出しごとのタイムアウト | ✓ | ✗ | ✗ | ✗ | ✗ | | OWASP LLM Top 10 へのマッピング | ✓ | ✗ | ✗ | ✗ | ✗ | | コンプライアンスタグ付け（SOC2/HIPAA） | ✓ | ✗ | ✗ | ✗ | ✗ | | 攻撃チェーンの検出 | ✓ | ✗ | ✗ | ✗ | ✗ | | ハニートークン／インジェクションの検出 | ✓ | ✗ | ✗ | ✗ | ✗ | | スキーマ対応の検証 | ✓ | ✗ | ✗ | ✗ | ✗ | | 脅威インテリジェンス（IOC 照合） | ✓ | ✗ | ✗ | ✗ | ✗ | | RBAC（エージェントごとのアクセス制御） | ✓ | ✗ | ✗ | ✗ | ✗ |

Seatbelt は、インストール前スキャンと実行時の適用を組み合わせ、主要な AI エージェントクライアントをすべてサポートし、認証情報を含む引数をインラインで秘匿化するとともに、mcp-observatory の静的解析結果を実行時のポリシールールに反映できる唯一のツールです。

---

高度なセキュリティ機能

mcp-seatbelt には多層防御のセキュリティパイプラインが含まれており、すべてのツール呼び出しを複数のレイヤーを通じて評価します。

レイヤー	機能	説明
1	RBAC	エージェントとツールを対象とする、Casbin ベースのロールベースアクセス制御です。mcp-seatbelt rbac-init でモデルファイルとポリシーファイルを生成します。
2	スキーマ検証	コンパイル済みスキーマに照らしてツール引数を検証する、AJV ベースの JSON Schema 検証です。
3	パス安全性	引数内のパストラバーサル、ヌルバイトインジェクション、機密パスへのアクセスを検出します。
4	ポリシーエンジン	正規表現／完全一致／部分一致による照合、時間枠、コンテキスト条件、引数制約を備えたルールベースの評価です。
5	脅威インテリジェンス	ツール引数内の IP アドレスとドメインを対象に、ThreatFox IOC を非同期で照会します。
6	ハニートークン	応答におとり認証情報を埋め込み、後続の呼び出しにハニートークンが現れた場合に情報流出を検出します。
7	攻撃チェーンの追跡	複数段階の攻撃パターン（偵察→実行→永続化→情報流出）を追跡する、XState ベースのステートマシンです。
8	フォレンジックキャプチャ	有効にすると、すべてのリクエストと応答を署名付きの .mcpcap.json セッションファイルに記録します。
9	応答 DLP	上流からの応答をシークレットパターン（API キー、トークン、秘密鍵）についてスキャンし、検出した値をマスキングします。
10	入力ファジング	JSON スキーマからエッジケースのペイロードを生成し、ポリシー回避への耐性をテストします。mcp-seatbelt fuzz --policy policy.yml

入力ファジング

mcp-seatbelt fuzz は、json-schema-faker を使用してランダム化されたツール呼び出し引数を生成し、エッジケースのペイロード（パストラバーサル、コマンドインジェクション、SQL インジェクション、Log4Shell）を注入して、各ペイロードをポリシーに照らして評価します。回避が見つかった場合は、具体的なペイロードと、本来それをブロックするべきだったルールを報告します。

mcp-seatbelt fuzz --policy .mcp-seatbelt/policy.yml --iterations 200 --json

---

ポリシーリファレンス

CLI

mcp-seatbelt init --policy enforce     # generate an enforcing policy
mcp-seatbelt proxy --config my.yml     # start proxy with custom policy
mcp-seatbelt report --sarif           # SARIF 2.1.0 output for CI
mcp-seatbelt check                    # exit 1 if critical risks found
mcp-seatbelt diff old.yml new.yml     # compare two policy files
mcp-seatbelt import-observatory       # convert observatory findings to rules

新しいコマンド（v0.4.0）

コマンド	説明
mcp-seatbelt fuzz	ツールスキーマに照らしてポリシーをファジングし、回避を検出します
mcp-seatbelt record	フォレンジック記録モードでプロキシを起動します
mcp-seatbelt rbac-init	RBAC のモデルファイルとポリシーファイルを初期化します
mcp-seatbelt simulate	ポリシーに照らしてツール呼び出しをシミュレートし、評価のトレースを表示します
mcp-seatbelt benchmark	プロキシのパフォーマンスベンチマークを実行します
mcp-seatbelt test-policy	テスト用 YAML ファイルからポリシーテストを実行します
mcp-seatbelt baseline	監査ログから動作のベースラインを生成します
mcp-seatbelt verify-audit	署名付き監査ログの完全性を検証します

組み込みルール（デフォルトポリシー）

ルール	対象	説明
block-shell-execution	command	シェルインタープリターの直接呼び出し（bash、sh、zsh、cmd、powershell）をブロックします
block-sensitive-paths	file	/etc、/root、~/.ssh、~/.aws、C:\Windows へのファイルシステム書き込みをブロックします
block-credential-access	command	説明にパスワード、シークレット、トークン、キーへの言及があるツールをブロックします
redact-credentials	command	キー名が認証情報のパターンに一致する引数値をマスキングします
block-private-network	network	プライベート／ループバックアドレス範囲への HTTP リクエストをブロックします
block-process-execution	process	子プロセスの起動またはコードの評価を行うツールをブロックします
allow-filesystem-writes-business-hours	file	月曜から金曜の 09:00～17:00 のみ、ファイルシステムへの書き込みを許可します

ポリシーテンプレート

テンプレート	デフォルトのアクション	用途
minimal-workstation	allow	シェルの実行と認証情報へのアクセスのみをブロックし、それ以外はすべて許可します
pci-compliance	deny	シェル、認証情報、PAN／カード会員データのパス、監査ログの改ざんをブロックします
strict-production	deny	すべてのツール呼び出し、ネットワークリクエスト、ファイルシステム操作をデフォルトでブロックします

ポリシーファイルの extends フィールドを使用して、テンプレートを拡張できます。

version: '1'
mode: enforce
extends:
  - pci-compliance
rules:
  - id: custom-rule
    target: network
    match: pattern
    values: ['.*']
    action: deny

ルールスキーマ

rules:
  - id: example-rule                # unique identifier
    description: What this blocks   # human-readable explanation
    target: command                 # command | file | network | env | process
    match: pattern                  # exact | pattern | contains
    values:                         # list of strings or regex patterns
      - '^rm\s+-rf'
    action: deny                    # allow | deny | warn | redact
    timeWindow:                     # optional — restrict by day/hour
      days: [Monday, Tuesday, Wednesday, Thursday, Friday]
      startHour: 9
      endHour: 17
    contextCondition:               # optional — restrict by client or rate
      clientIn: [cursor, claude-desktop]
      maxRequestsPerMinute: 60

許可リスト

許可リストのエントリーは、すべての拒否ルールをバイパスします。init の実行後に使用して、信頼できるツール、パス、ホスト、環境変数をホワイトリストに登録します。

allowlist:
  tools: [safe-tool, read-only-fs]
  paths: [/home/user/projects/]
  hosts: [api.github.com]
  envVars: [NODE_ENV, PATH]

---

クライアント統合ガイド

プロキシを起動した後、各クライアントの MCP 設定を更新し、localhost:9420 経由でルーティングします。起動時にプロキシがプロキシ URL の表を表示するので、それをコピーして貼り付けます。

Cursor — ~/.cursor/mcp.json

{ "mcpServers": { "my-server": { "url": "http://localhost:9420/my-server" } } }

Claude Desktop — ~/Library/Application Support/Claude/claude_desktop_config.json

{ "mcpServers": { "my-server": { "url": "http://localhost:9420/my-server" } } }

VS Code — .vscode/mcp.json またはユーザー設定

{ "servers": { "my-server": { "url": "http://localhost:9420/my-server" } } }

ChatGPT Desktop — アプリの設定

{ "mcpServers": { "my-server": { "url": "http://localhost:9420/my-server" } } }

Codex / JetBrains / Windsurf — 同じ方法で、command／args トランスポートを "url": "http://localhost:9420/<server-name>" に置き換えます。

---

mcp-observatory との併用

mcp-observatory は、MCP サーバーの稼働前にスキャンし、ソースコード、サプライチェーンの状態、マニフェストの衛生状態を監査します。Seatbelt は実行時の対策を提供します。

ワークフロー：

1. 最初にスキャンする — インストール前に、mcp-observatory を実行してすべての MCP サーバーを監査します。セキュリティ上の検出結果を JSON アーティファクトとして生成します。
2. 変換する — mcp-seatbelt import-observatory ./observatory-results.json を実行して、検出結果をポリシールールに変換します。
3. 実行時に適用する — プロキシがそれらのルールを読み込み、observatory の検出結果に一致するツール呼び出しをブロックします。これにより、静的解析から実行時の適用までの一連の流れが完成します。

observatory ブリッジ（mergeObservatoryPolicy）を使うと、カスタムルールを上書きせずに、検出結果を既存の seatbelt ポリシーに統合できます。

---

パフォーマンス

Apple M3、Node.js 22、macOS で測定 — 即座に応答するアップストリームに対して、同時実行数 10 で 1,000 件のリクエストを実行（3 回の実行の中央値、失敗したリクエストはゼロ）：

指標	値
スループット	約 2,000 req/s（プロキシなしの直接接続では約 4,300 req/s）
エンドツーエンドレイテンシ（p50）	約 3.9 ms（直接接続より約 2 ms 増加）
エンドツーエンドレイテンシ（p95）	約 6.6 ms
ポリシー評価（p50）	6.6 µs（7 ルール）；8.5 µs（20 ルール）
ポリシー評価（p95）	7.7 µs（7 ルール）
DLP オーバーヘッド	応答あたり約 +0.1 ms
スキーマ検証のオーバーヘッド	呼び出しあたり < 1 µs
メモリ（アイドル時）	約 74 MB
メモリ（負荷時）	約 74 MB（10,000 件のリクエスト後も一定）

ポリシーのサイズ（1 → 20 ルール）によるエンドツーエンドへの影響は測定できません。ルールあたりのコストは約 0.25 µs で、トランスポート I/O よりはるかに小さい値です。測定方法の詳細とシナリオ別の表については、docs/benchmarks.md を参照してください。お使いのハードウェアで mcp-seatbelt benchmark を実行できます。

---

エンタープライズ

mcp-observatory Cloud は、ホスト型ダッシュボード、プライベート CI スキャン、認定バッジ、チームや組織向けのサプライチェーンコンプライアンスレポートを提供します。Seatbelt は実行時の適用レイヤーとして統合されます。observatory はインストールするものを検証し、seatbelt は実行時にそれが実行できる内容を制御します。

• Observatory Cloud：ホスト型スキャン、プライベートレジストリ、チームダッシュボード
• Seatbelt：ポリシーの適用、編集、ライブモニタリングに対応したマシン上のプロキシ
• 併用：稼働前のスキャン + 実行時の適用 = MCP セキュリティライフサイクルの完全な実現

ロードマップ

• 複数クライアントの検出（8 クライアント）
• リクエストのインターセプト機能を備えた、実行時の JSON-RPC 2.0 プロキシ
• 正規表現／完全一致／部分一致、時間帯、コンテキスト条件に対応したポリシーエンジン
• リスク評価エンジン（13 ルール）
• 自動更新に対応したライブダッシュボードの Web UI
• SARIF 2.1.0 および Markdown レポートの生成
• mcp-observatory 統合ブリッジ
• CI/CD チェックコマンド（mcp-seatbelt check）
• OWASP LLM Top 10 へのマッピングとコンプライアンスフレームワークのタグ付け
• 複数段階の攻撃チェーンの検出（XState ステートマシン）
• ハニートークンの注入と検出
• フォレンジックセッションの記録（.mcpcap.json）
• スキーマを考慮した引数の検証
• 脅威インテリジェンスとの統合（ThreatFox IOC の照会）
• ポリシールールに対する入力ファジング
• ロールベースのアクセス制御（casbin RBAC）
• ポリシーの差分表示と移行ツール（#12）
• 可観測性スタック向け Prometheus /metrics エンドポイント（#15）
• OPA/Rego ポリシーの統合（#18）
• ツールごとの細かな制御 — 同じサーバー上でツール A を許可し、ツール B を拒否（#20）
• SQLite による永続的な監査証跡とリクエストログ（#22）
• カスタムリスクルール向けのプラグインシステム（#25）

---

貢献

開発環境のセットアップ、テスト手順、プルリクエストのガイドラインについては、CONTRIBUTING.md を参照してください。セキュリティ上の問題については、SECURITY.md の手順に従ってください。

• 18 のテストスイート（CLI、検出器、ポリシーエンジン、プロキシサーバー、プロキシのインターセプト、レポート、セキュリティモジュール、RBAC、脅威インテリジェンス、LLM ジャッジ、フォレンジック、ハニートークン、攻撃チェーン、スキーマバリデーター、監査、通知、ベースライン、統合）にわたる 485 件のテスト
• npm test で Vitest の全テストスイートを実行し、npm run typecheck で TypeScript を検証します
• 新しいルール、検出器、ポリシー機能に関する PR には、テストを含めてください

---

ライセンス

MIT — mcp-seatbelt の貢献者