ai-code-scanner

@guardbee/mcp-ai-code-scanner

🇬🇧 英語 | 🇹🇷 トルコ語 | 🇨🇳 中国語 | 🇯🇵 日本語 | 🇰🇷 韓国語 | 🇧🇷 ポルトガル語 | 🇪🇸 スペイン語 | 🇩🇪 ドイツ語

LLM／AI 連携でよく見られるセキュリティパターンをコードベースからスキャンする MCP（Model Context Protocol）サーバーです。

secret-scanner が漏えいしたシークレットや API キーを探すのに対し、このパッケージはパターンを探します。モデルの出力をどの程度信頼しているか、モデルが呼び出せるツールにどの程度の権限があるか、サードパーティの LLM にどのようなデータが送信されるかなど、静的な認証情報スキャンでは検出できないリスクを調べます。

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

Claude ──► ai-code-scanner ──► Your codebase
              │
              ├─ Client-exposure    (dangerouslyAllowBrowser: true)
              ├─ Output handling    (eval(llmOutput), unvalidated JSON.parse)
              ├─ Excessive agency   (an agent tool named execute_command)
              ├─ Data privacy       (email/national ID interpolated directly into a prompt)
              └─ Prompt injection   (raw request data mixed into a system prompt)

---

機能

• 5 カテゴリー、10 パターン — クライアントの露出、出力の処理、過剰な自律性、データプライバシー、プロンプトインジェクション
• すべての検出結果に、リスクの理由と対処方法（recommendation）が含まれます。「検出した」というだけではありません
• SARIF 2.1.0 出力 — CI/CD 連携（GitHub Code Scanning など）
• guardbee.yml による設定ファイルのサポート
• カスタムルールパック — JSON ファイルを使って、組織固有のパターン（KVKK／GDPR のフィールド名、内部ツール名）を追加して検出範囲を拡張できます。フォークは不要です
• 36 件のユニットテスト — 組み込みパターンごとに、陽性と陰性（誤検出）のシナリオを用意し、カスタムルールの読み込みと検証もテストします

---

クイックスタート

Claude Desktop／MCP クライアント

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

CLI（CI/CD）

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

---

MCP ツール

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

---

検出パターン

カテゴリ	パターン	深刻度	意味
クライアントへの露出	openai_dangerously_allow_browser	critical	OpenAI キーがブラウザーに漏えいしています
クライアントへの露出	client_bundled_ai_api_key	critical	NEXT_PUBLIC_／VITE_／REACT_APP_ 経由で AI キーがクライアントバンドルに含まれています
出力の取り扱い	eval_llm_output	critical	モデルの出力が eval()／Function() によってコードとして実行されています
出力の取り扱い	exec_llm_output	critical	モデルの出力がシェルコマンドに渡されています（コマンドインジェクション）
出力の取り扱い	llm_output_dangerously_set_inner_html	high	モデルの出力が生の HTML として描画されています（XSS）
出力の取り扱い	llm_json_no_validation	medium	モデルの出力がスキーマ検証なしで JSON.parse されています
過剰な権限	excessive_agency_tool_name	high	エージェントにシェル／コード実行を許可するツールです
過剰な権限	unbounded_agent_loop	medium	反復回数に上限のないエージェントループです（コスト／DoS）
データプライバシー	pii_field_in_llm_prompt	high	メールアドレス、国民 ID、カード番号などのデータがプロンプトに直接含まれています
プロンプトインジェクション	unsanitized_input_in_system_prompt	medium	未加工のリクエスト／ユーザーデータがシステムプロンプトに混在しています

これらはヒューリスティックな検出結果です。静的なテキストパターンのスキャンであり、完全な AST 解析ではありません。誤検知を少なくするように設計されていますが、検出結果はすべて手動で確認してください。

---

設定（guardbee.yml）

ai-code-scanner:
  fail-on: high       # any | critical | high | medium | low | none
  max-files: 5000
  rules-dir: .guardbee/rules   # custom rule packs, see below
  exclude:
    - ".test.ts"
    - "fixtures/"

---

カスタムルール

組み込みパターンは、AI／LLM 統合でよくあるミスをカバーしていますが、フィールド名や内部規約（たとえば、KVKK の規制対象データを含むプロパティ名）はプロジェクトごとに異なります。1 つ以上の JSON ファイルを .guardbee/rules/ に配置すると（rules-dir で設定可能）、スキャン時に組み込みルールと統合されます。CLI と MCP サーバーの両方に適用されます（list_patterns では (custom) と表示されます）。

ファイルには、単一のルールオブジェクトまたはルールの配列を記述します。

{
  "id": "kvkk_musteri_tc_no",
  "name": "musteriTcNo interpolated into a prompt",
  "category": "data-privacy",
  "pattern": "musteriTcNo",
  "flags": "gi",
  "severity": "high",
  "recommendation": "Mask the national ID before it enters the prompt."
}

category は client-exposure | output-handling | excessive-agency | data-privacy | prompt-injection | cost-control のいずれか、severity は critical | high | medium | low のいずれかです。pattern は JS の正規表現ソース文字列です （flags のデフォルトは "g"）。組み込みルールまたは別のカスタムルールと ID が重複するルールは拒否されます。スキャナーは実行を続けますが、標準エラーに問題を報告し、その項目をスキップします。

---

開発

npm run build
npm test             # 36 unit tests

---

ライセンス

MIT — GuardBee

フィードバック

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