memory-poisoning-scanner

@guardbee/mcp-memory-poisoning-scanner

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

エージェントのコードをスキャンしてメモリポイズニングを検出する MCP（Model Context Protocol）サーバーです。メモリポイズニングとは、信頼できない入力がエージェントの永続的かつセッションをまたぐメモリに書き込まれ、後に呼び出されて信頼できるコンテキストとしてモデルに再度渡されることです。その結果、まったく関係のない将来のセッションに影響する可能性があります。

prompt-injection-scanner は、モデルが一度だけ読むコンテンツ（ドキュメントやスクレイピングしたページなど）に含まれるインジェクションペイロードを検出します。このパッケージが検出するのは、構造的に異なる問題です。インジェクションペイロードが、モデル自身の長期的な知識として扱われるものの一部になるコードパターンです。これは、ブラウザーの DOM ではなくエージェントのメモリに適用された、反射型 XSS と格納型 XSS の違いと同じです。

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

Claude ──► memory-poisoning-scanner ──► Your agent's source
              │
              ├─ memory-write     (untrusted input persisted into archival/core memory or a vector KB)
              └─ memory-readback  (recalled memory fed into a system/assistant-role message or prompt)

---

通常の会話メモリが対象外である理由

生のチャットのやり取りを保持する ConversationBufferMemory や、単純な chatHistory.push({role: "user", content: userInput}) はまったく一般的なものであり、脆弱性ではなく、単なる会話履歴です。このパッケージは意図的に、これらを検出しません。

対象となるのは、より限定的で、より重大なリスクを伴うものです。現在の会話が終わった後も残る永続的なメモリへの書き込み、つまり将来の無関係なセッションでも呼び出される MemGPT 形式のアーカイブメモリや、設計上、すべてのターンでシステムプロンプトに再挿入されるコアメモリ、あるいは会話ごとの RAG コンテキストではなく長期的なナレッジベースとして使われるベクトルストアです。信頼できない入力がサニタイズされずにそこへ入ると、現在のやり取りに影響するだけではありません。誰かが気づくまで、いつまでも、誰に対しても、エージェントが真実だと信じるものの一部になってしまいます。

リスクの後半も同様に重要です。メモリやベクトル検索の結果が system／assistant ロールのメッセージやプロンプトテンプレートに直接流れ込むと、ポイズニングされたメモリは単なる読み取り対象のデータではなく、モデルが従う指示として「効果を発揮」します。

---

機能

• 5 つのメモリ書き込みパターン：生の入力を受け取る MemGPT の archival_memory_insert／core_memory_append／core_memory_replace、生の入力を受け取るベクトルストアの add_texts／add_documents／upsert、およびカスタム名の長期メモリ／ナレッジベースストア向けの汎用的な包括パターン
• 3 つのメモリ読み戻しパターン：アーカイブ／ベクトル検索の結果がシステム／アシスタントロールのメッセージに渡されるパターン、またはプロンプトテンプレートに直接補間されるパターン
• SARIF 2.1.0 出力 — CI/CD との連携（GitHub Code Scanning など）
• guardbee.yml による設定ファイルのサポート
• 17 件のユニットテスト — すべてのパターンで、肯定ケースと否定ケース（誤検知）のシナリオを検証します。通常の会話バッファーの使用では検出結果がゼロになることも明示的に確認しています。現実的な脆弱性を仕込んだフィクスチャでエンドツーエンド検証済み（書き込みと読み戻しの両方を検出）。guardbee-mcp モノレポ全体（386 ファイル）でも検証済みで、本番コードでの誤検知はゼロです。

---

クイックスタート

Claude Desktop / MCP クライアント

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

CLI（CI/CD）

npx @guardbee/mcp-memory-poisoning-scanner scan ./src --fail-on=high --format=sarif > results.sarif

---

MCP ツール

ツール	説明
scan_text	コードスニペットをスキャンします
scan_file	単一のファイルをスキャンします
scan_directory	ディレクトリを再帰的にスキャンします
list_patterns	カテゴリ別にサポートされているすべてのパターンを一覧表示します

---

検出されるパターン

カテゴリ	パターン	重大度
memory-write	archival_memory_insert_raw_input	critical
memory-write	core_memory_write_raw_input (append/replace)	critical
memory-write	vector_store_add_raw_input	high
memory-write	generic_named_memory_write_raw_input	medium
memory-readback	archival_memory_feeds_trusted_role	critical
memory-readback	vector_retrieval_feeds_trusted_role	high
memory-readback	memory_retrieval_feeds_prompt_template	high

---

設定（guardbee.yml）

memory-poisoning-scanner:
  fail-on: high       # any | critical | high | medium | none
  max-files: 5000
  exclude:
    - ".test.ts"

---

制限事項（設計上のもの）

• ヒューリスティックであり、汚染追跡ではありません。 書き込みチェックと読み戻しチェックはそれぞれ、特定の書き込みから後続の特定の読み取りまでのデータフローパスを証明するのではなく、範囲を限定した 1 か所を調べます。検出結果は、コード内にリスクの 形 が存在することを示すものであり、数学的に確認されたエクスプロイトチェーンを意味するものではありません。
• パターンの対象範囲は、MemGPT の用語と汎用的な JS の命名に基づいています。 関数名や変数名がまったく異なる独自の長期メモリシステムは、汎用パターン（*memory*／*knowledge_base* という命名、または vectorstore 型の API）に該当しない限り認識されません。
• メモリポイズニングを可能にするコードパターンを検出するものであり、実行時に実際にポイズニングされたメモリストアを検出するものではありません。メモリの内容を直接調べられる場合は、実際に保存されている内容をスキャンする prompt-injection-scanner と組み合わせてください。

---

開発

npm run build
npm test             # 17 unit tests

---

ライセンス

MIT — GuardBee

フィードバック

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