prompt-injection-scanner

@guardbee/mcp-prompt-injection-scanner

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

RAG チャンク、スクレイピングしたウェブページ、ドキュメントなどのコンテンツをスキャンし、間接的なプロンプトインジェクションのペイロードを検出する MCP（Model Context Protocol）サーバーです。

ai-code-scanner と mcp-server-auditor はコードをスキャンしますが、このパッケージはデータをスキャンします。従来のプロンプトインジェクションでは、攻撃者が自ら悪意のあるプロンプトを書きます。一方、間接的なプロンプトインジェクションでは、攻撃者がモデルに直接話しかけることはありません。その代わり、後でモデルが読むドキュメント、ウェブページ、ツールの結果に指示を埋め込みます。RAG による検索やウェブ取得を通じてモデルがこのコンテンツをコンテキストに取り込むと、埋め込まれた指示はユーザー自身の指示と同じ権限を持つかのように見えます。

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

Web page/RAG document ──► prompt-injection-scanner ──► LLM context
              │
              ├─ Instruction override   ("ignore all previous instructions", "önceki talimatları yok say")
              ├─ Role spoofing          ("System:", <|im_start|>, [INST], <system>)
              ├─ Hidden text            (zero-width, Unicode tag and bidi characters, display:none + instruction, HTML comment)
              ├─ Direct address         ("Dear AI, ...")
              └─ Exfiltration           (system prompt extraction request, data → URL instruction, templated img beacon)

---

特徴

• 17 個のパターン、5 つのカテゴリー — 指示の上書き、ロールの偽装、隠しテキスト、直接呼びかけ、情報の持ち出し。英語とトルコ語の表現に対応
• ルールは @guardbee/guard-core にあり、@guardbee/mcp-security-proxy と共有されています。そのため、このスキャナーが報告する表現は、プロキシが実行時にブロックする表現と同じです
• 検出結果にはすべて、リスクの理由と対処方法（recommendation）が含まれます。単に「検出した」と伝えるだけではありません
• SARIF 2.1.0 の出力 — CI/CD との統合に対応（例：PR ごとにナレッジベースのリポジトリを自動スキャン）
• guardbee.yml による設定ファイルのサポート
• 単体テスト 45 件 — 各パターンに陽性シナリオと陰性（誤検出）シナリオを用意しています。絵文字の ZWJ シーケンスや通常の display:none モーダルなど、既知の誤検出要因も個別にテストしています

---

クイックスタート

Claude Desktop / MCP クライアント

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

CLI（CI/CD — 例：PR ごとに RAG ナレッジベースのリポジトリをスキャン）

npx @guardbee/mcp-prompt-injection-scanner scan ./knowledge-base --fail-on=high --format=sarif > results.sarif

---

MCP ツール

ツール	説明
scan_text	指定されたテキストまたはドキュメントのスニペットをスキャンします
scan_file	単一のファイルをスキャンします
scan_directory	ディレクトリを再帰的にスキャンします（例：RAG ナレッジベース）。node_modules、.git、dist は自動的にスキップされます
list_patterns	カテゴリー別に、サポートされているすべてのパターンを一覧表示します

---

検出されたパターン

カテゴリー	パターン	深刻度	意味
instruction-override	instruction_override_phrase	high	「以前の指示を無視する／破棄する／忘れる」のような典型的な上書きフレーズです
instruction-override	instruction_override_tr	high	トルコ語の表現です：「önceki talimatları yok say / unut / görmezden gel」
instruction-override	dan_mode	high	脱獄用ペルソナ「DAN mode」を求めています
instruction-override	bypass_safety	high	モデルの安全対策やガードレールを回避または無効化するよう指示します
role-spoofing	system_role_spoof	medium	コンテンツ内の行頭にある、偽の「System:」ロールラベルです
role-spoofing	chat_template_marker_injection	high	コンテンツ内の生のチャットテンプレート制御トークン（<|im_start|>、[INST]）です
role-spoofing	system_tag	high	データをシステムメッセージに見せかけようとする <system> タグです
hidden-text	hidden_zero_width_chars	medium	ゼロ幅スペース／ワードジョイナー（U+200B/U+2060）です。人間のレビュアーには見えないテキストです
hidden-text	unicode_tag_smuggling	critical	隠されたテキストを含む不可視の Unicode タグ文字（U+E0000–E007F）です。🏴󠁧󠁢󠁥󠁮󠁧󠁿 のような旗の絵文字は除外されます
hidden-text	bidi_control_chars	medium	テキストの表示順を読み取り順と異なる順序にする、双方向テキストのオーバーライド／分離文字です
hidden-text	css_hidden_text_with_instruction	high	指示に見える文言を含む display:none／白地に白文字の要素です
hidden-text	html_comment_instruction	high	指示に見える文言を含む HTML コメントです
direct-address	direct_address_to_ai	medium	コンテンツが「AI」／「アシスタント」に直接語りかけています
exfiltration	exfiltration_url_template_in_image	high	{{...}}／${...} テンプレートを含む Markdown 画像 URL です。データ流出用のビーコンです
exfiltration	reveal_system_prompt_request	high	モデルにシステムプロンプトの開示を求める文です
exfiltration	reveal_system_prompt_tr	high	トルコ語の表現です：「sistem istemini göster」
exfiltration	send_data_to_url_instruction	critical	データを外部 URL に送信するよう明示的に命令する指示です

これらはヒューリスティックによる検出結果です。静的なテキストパターンのスキャンであり、意味や意図の分析ではありません。誤検出を少なくするよう設計されています（例：絵文字の ZWJ シーケンスや通常の display:none モーダルは明示的に除外されます）が、検出結果はすべて手動で確認してください。

---

LLM による判定（任意）

パターン検出では攻撃フレーズを認識しますが、言い換えられた指示、間接的な指示、翻訳された指示はすり抜けることがあります。--judge を使うと、モデルが各ファイルをチャンクごとに読み込み、エージェントを標的とする指示を judge_semantic_injection（high）として報告します。検出結果には judge: { model, version, confidence } が含まれ、SARIF の properties にも記録されます。判定機能は検出結果を追加するだけです。

GUARDBEE_JUDGE_URL=http://127.0.0.1:11434/v1 GUARDBEE_JUDGE_MODEL=qwen2.5:7b \
  npx @guardbee/mcp-prompt-injection-scanner scan ./docs --judge

設定されていない場合は無効です。コンテンツはエンドポイントに送信されるため、ローカル以外のエンドポイントを使用するには --judge-allow-remote と https が必要です。GuardBee の判定ベンチマーク（英語とトルコ語のサンプル 50 件）では、パターン検出で攻撃の 16% を検出し、qwen2.5:7b では誤検出なしですべて検出しました。

設定（guardbee.yml）

prompt-injection-scanner:
  fail-on: high       # any | critical | high | medium | low | none
  max-files: 5000
  exclude:
    - ".test.ts"
    - "fixtures/"

---

開発

npm run build
npm test             # 45 unit tests

---

ライセンス

MIT — GuardBee

フィードバック

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