prompt-leak-scanner

@guardbee/mcp-prompt-leak-scanner

🇬🇧 English | 🇹🇷 Türkçe | 🇨🇳 中文 | 🇯🇵 日本語 | 🇰🇷 한국어 | 🇧🇷 Português | 🇪🇸 Español | 🇩🇪 Deutsch

MCP（Model Context Protocol）サーバーであり、スタンドアロンのリバースプロキシでもあります。アプリケーションから送信される前に、送信先の LLM プロンプトに含まれる認証情報や個人識別情報（PII）の漏えいを検出します。

secret-scanner は、コードベース内にあるシークレットを見つけます。このパッケージは、実行時プロンプトに入り込んだシークレットや PII を見つけます。たとえば、サポートエージェントが顧客のチケット（メールアドレスやカード番号）をそのままシステムプロンプトに貼り付けてしまう場合や、デバッグ中に誰かが API キーをチャットに貼り付ける場合、内部ツールがユーザー入力の内容を一切確認せず、そのまま LLM に転送する場合などです。これはパイプライン内の別のタイミングで発生し、.env ファイルの漏えいとは異なる障害です。

テレメトリーはデフォルトでオフです。GUARDBEE_TELEMETRY=1 を設定すると、サーバー、ツール、成功の有無、所要時間、ファイルパスなどの短いパラメーター値が送信されます。長い文字列や、content、token、password などのフィールドはプレースホルダーに置き換えられます。詳細は @guardbee/mcp-telemetry をご覧ください。

Your app ──► prompt-leak-scanner (proxy) ──► Real LLM API (OpenAI/Anthropic/...)
                    │
                    ├─ monitor: forward unchanged, log findings
                    ├─ redact:  forward with matches replaced by [REDACTED:<id>]
                    └─ block:   reject the request before it ever reaches the model

---

2 つの使用方法

1. オンデマンドスキャン（MCP ツール） — scan_text／scan_messages／scan_file／scan_directory。ユーザー入力からプロンプトを作成する機能をリリースする前に、Claude にプロンプト、チャットリクエスト本文のフィクスチャ、またはプロンプトログのディレクトリをチェックするよう依頼できます。

2. ライブリバースプロキシ（proxy CLI コマンド） — アプリケーションと実際の LLM API の間に配置されます。送信リクエスト本文（メッセージ／システムテキスト）のみをバッファリングして検査し、その後、上流からの応答を変更せずにそのままストリーミングで返します。そのため、SSE／ストリーミングによる補完はそのまま通過し、解析されるのは外部へ送信されるプロンプトだけです。実際の API ではなく、プロキシを指すようにアプリの baseURL を設定すれば、統合部分をほかに変更する必要はありません。

guardbee-prompt-leak-scanner proxy --upstream=https://api.openai.com --port=8788 --mode=redact
# your app: baseURL = http://localhost:8788 instead of https://api.openai.com

---

検出精度：正規表現だけでなくチェックサムを使用

「11桁」や「16桁」に対する単純な正規表現では、注文番号、電話の内線番号、タイムスタンプまで頻繁に誤検出してしまいます。実際のチェックサムアルゴリズムがあるPIIパターンには、すべてそのアルゴリズムを使用します。

• TC Kimlik No — 実際の11桁のトルコ国民IDチェックサムアルゴリズム（単なる桁数の正規表現ではありません）
• クレジットカード番号 — Luhnチェックサム
• IBAN — ISO 7064 MOD97-10チェックサム

ランダムな11桁の数字が偶然TC Kimlikのチェックサムを通過する確率は、およそ10分の1です。正規表現だけでは、誤検出が大幅に増えてしまいます。認証情報のパターン（APIキー、JWT、秘密鍵）は、実際のプロバイダー固有のプレフィックスや構造（sk-、AKIA、ghp_、-----BEGIN...PRIVATE KEY-----、JWTの3セグメントのbase64url形式）に照らして照合します。これは、secret-scannerが採用しているのと同じ、誤検出を抑えるアプローチです。チェックサム検証機能は、@guardbee/guard-coreから提供され、@guardbee/mcp-security-proxyと共有されています。

検出結果に実際の値が表示されることはありません。 検出結果のmaskedMatchには、先頭3文字と末尾2文字のみが表示されます（sk-…wx）。検出した値そのものを記録したり表示したりしては、検出する意味がありません。プロキシの監査イベントではさらに、該当したパターンと位置を記録し、一致したテキスト自体は記録しません。

---

特長

• 13個のパターン、4つのカテゴリ：credential（9）、financial-pii（2、チェックサム検証済み）、national-id（1、チェックサム検証済み）、contact-pii（2）
• チャット本文を認識 — フラットなテキストだけでなく、OpenAI/Anthropic形式のmessages[].content（文字列またはコンテンツブロック配列）とsystemフィールドを理解します
• ライブリバースプロキシモード（monitor／redact／blockポリシー対応） — リクエストのみを検査し、レスポンスはそのままストリーミングします
• マスク済みの検出結果と、認証情報を含まない監査イベント — ツールが漏えいの二次的なコピーになることはありません
• SARIF 2.1.0出力 — CI/CDとの統合（GitHub Code Scanningなど）
• guardbee.ymlによる設定ファイルのサポート
• 単体テスト29件 — チェックサム検証機能は既知の正常／異常なテストベクトルで検証済み。プロキシは、3つすべてのモードで、プロセス内のモックだけでなく実際のローカルHTTPクライアント／サーバー間の往復通信をテスト済み

---

クイックスタート

Claude Desktop／MCP クライアント

{
  "mcpServers": {
    "guardbee-prompt-leak-scanner": {
      "command": "npx",
      "args": ["-y", "@guardbee/mcp-prompt-leak-scanner"]
    }
  }
}

CLI（CI/CD）

npx @guardbee/mcp-prompt-leak-scanner scan ./prompt-fixtures --fail-on=high --format=sarif > results.sarif

CLI（ライブプロキシ）

npx @guardbee/mcp-prompt-leak-scanner proxy --upstream=https://api.openai.com --mode=block --fail-on-severity=critical

---

MCP ツール

ツール	説明
scan_text	生のテキスト文字列をスキャンします
scan_messages	OpenAI/Anthropic形式のチャットリクエスト本文オブジェクトをスキャンします
scan_file	単一のファイル（プレーンテキスト、またはJSONリクエスト本文のフィクスチャ。自動判別）をスキャンします
scan_directory	プロンプトログ／フィクスチャのディレクトリを再帰的にスキャンします
list_patterns	カテゴリ別に、サポートされているすべてのパターンを一覧表示します

---

検出されるパターン

カテゴリ	パターン	重大度
credential	OpenAI／Anthropic／Google／StripeのAPIキー、AWSアクセスキーID、GitHub PAT、Slackトークン、PEM秘密鍵ブロック	critical
credential	JWT	high
financial-pii	クレジットカード番号（Luhn検証済み）	high
financial-pii	IBAN（mod-97検証済み）	high
national-id	TC Kimlik No（チェックサム検証済み）	high
contact-pii	メールアドレス	medium
contact-pii	トルコの電話番号	medium

---

設定（guardbee.yml）

prompt-leak-scanner:
  fail-on: high       # any | critical | high | medium | low | none
  max-files: 5000
  exclude:
    - "fixtures/known-safe/"

---

制限事項（設計上）

• プロキシが検査するのはリクエスト本文のみです。ストリーミングSSEレスポンスの解析や変更は行わず、そのまま中継します。
• チャット本文から抽出されるのは、messages[].content（文字列または{type:"text"}のコンテンツブロック）とトップレベルのsystemのみです。その形式に含まれないプロバイダー固有のフィールドはスキャンされません。
• これはパターンとチェックサムに基づく検出機能であり、汎用的なNER／PIIモデルではありません。既知の構造パターンに一致しないPII（例：自由記述文中の氏名や住所）は検出できません。

---

開発

npm run build
npm test             # 29 unit tests

---

ライセンス

MIT — GuardBee

フィードバック

ご質問やアイデア、誤検知がありましたら、GitHub Discussionsでスレッドを開始するか、issue を作成してください。GuardBee が役に立った場合は、リポジトリに ⭐ を付けていただくと、ほかの方にも見つけてもらいやすくなります。