a2a-auditor

@guardbee/mcp-a2a-auditor

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

エージェント自身のAgent2Agent（A2A）プロトコル実装をスキャンしてアンチパターンを検出する MCP（Model Context Protocol）サーバーです。仕様書の文面から推測したものではなく、リファレンス SDK（@a2a-js/sdk、a2a-sdk）と公式サンプルコードから直接読み取ったパターンを使用します。

A2A には、引用できる MCP 形式の「セキュリティに関する考慮事項」セクションがまだありません。そのため、推測する代わりに、このパッケージのパターンはリファレンス SDK のソースコード自体から見つかった次の3点に基づいています。公式のプッシュ通知送信処理は、ホストの確認を一切せず、クライアントが指定した Webhook URL をフェッチします。公式のサンプルエージェントには、空のセキュリティスキームと、文字どおり noAuthentication を指定したリクエストハンドラーが含まれています。また、Python SDK の AgentCard(...) コンストラクターでは、2つのセキュリティ関連のキーワード引数が完全に任意として扱われ、渡さない場合は何も通知されずに「認証なし」を意味します。

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

Claude ──► a2a-auditor ──► Your A2A agent's source
              │
              ├─ webhook-ssrf            (push-notification webhook URL fetched with no allowlist)
              ├─ missing-authentication  (Agent Card / request handler requires no auth at all)
              └─ credential-exposure     (literal credential inside publicly-served Agent Card metadata)

---

特にこの3つを取り上げる理由

Webhook SSRF：リファレンスの DefaultPushNotificationSender は、実際に const url = pushConfig.url; ... fetch(url, ...) を実行します。pushConfig.url はタスク更新を購読したクライアントによって設定され、SDK はホストを一切検証せずにその URL をフェッチします。このコードを実行するサーバーに対して、呼び出し元は内部サービス、クラウドのメタデータエンドポイント、またはサーバーのネットワークから到達可能なその他の宛先を指定できます。

認証の欠如：SDK 自身のサンプルエージェント（src/samples/agents/movie-agent）には、securitySchemes: {}、securityRequirements: []、userBuilder: UserBuilder.noAuthentication が含まれています。コピーして使いやすい形ですが、プレースホルダーのように見えて、実際には「誰からのリクエストでも受け入れる」という意味です。Python SDK にも、明示的な空の値ではなく、値が存在しないことで同じ問題が生じます。AgentCard(...) では security_schemes／security_requirements が必須ではないため、リファレンスの例に従って構築した実際のエージェントが、認証なしになっても、そのことを知らせるエラーは発生しない可能性があります。

認証情報の漏えい：Agent Card は公開されており、/.well-known/agent-card.json（または同等の検出レスポンス）に到達できる人なら誰でも、カード自体の取得には認証を必要とせず、その内容を読めます。その JSON に文字どおりの API キーが含まれていれば、事実上公開されていることになります。

---

機能

• 3 つのカテゴリー：webhook-ssrf、missing-authentication、credential-exposure
• TypeScript と Python の両方の A2A コードに対応 — SDK では同じ問題に対して異なる慣用的な記述方法（空のオブジェクトと kwargs の不在）が使われるため、片方の言語だけでなく両方をチェックします
• 6 つのチェックのうち 2 つは、単一の呼び出し箇所に一致させるのではなく、数行にわたるデータフローを追跡します。webhook チェックでは、url 変数をたどり、pushConfig.url の形式の代入を確認してから、その変数を使う fetch() を検出します。また、認証情報チェックでは、Agent Card オブジェクト全体の範囲を抽出（波括弧を照合）してから、その内部でリテラルのシークレットを検索するため、ファイル内のどこにある apiKey: にも無差別にフラグを立てることはありません
• SARIF 2.1.0 形式で出力 — CI/CD 統合（GitHub Code Scanning など）に対応
• guardbee.yml による設定ファイルのサポート
• 単体テスト 18 件 — すべてのパターンについて、陽性シナリオと陰性（誤検知）シナリオを用意しています。開発中に見つかった実際のバグに対する回帰テストも含まれます（\bAgentCard は movieAgentCard 内に一致しません。小文字と大文字の間には単語境界がないためです。クラス名が接尾辞として一致するよう修正しました）。TypeScript と Python の両方にすべてのパターンを意図的に埋め込んだフィクスチャでエンドツーエンドの検証を行い、すべて検出しました。また、guardbee-mcp モノレポ全体（461 ファイル）でも検証し、実際のコードでの検出はゼロでした。一致したのは、このパッケージ独自のテスト用フィクスチャ、パターン定義のソース、マニフェストの説明文だけでした

---

クイックスタート

Claude Desktop / MCP クライアント

{
  "mcpServers": {
    "guardbee-a2a-auditor": {
      "command": "npx",
      "args": ["-y", "@guardbee/mcp-a2a-auditor"]
    }
  }
}

CLI（CI/CD）

npx @guardbee/mcp-a2a-auditor scan ./src --fail-on=high --format=sarif > results.sarif

---

MCP ツール

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

---

検出パターン

カテゴリー	パターン	深刻度
webhook-ssrf	webhook_url_direct_fetch_no_allowlist	critical
webhook-ssrf	webhook_url_indirect_fetch_no_allowlist	critical
missing-authentication	no_authentication_user_builder	critical
missing-authentication	empty_agent_card_security	high
missing-authentication	python_agent_card_no_auth	high
credential-exposure	agent_card_credential_in_metadata	high

---

設定（guardbee.yml）

a2a-auditor:
  fail-on: high       # any | critical | high | medium | none
  max-files: 5000
  exclude:
    - ".test.ts"

---

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

• ヒューリスティックであり、完全な A2A 適合性テストではありません。 実行中のエージェントに対してライブでプロトコル適合性を検証するのではなく、リファレンス SDK 自身のソースから抽出した特定のアンチパターンを検出します。A2A は登場して間もなく、仕様の変化も速いため、ここではまだカバーされていない新たな問題が今後発生する可能性があります。
• データフローチェック（間接的な webhook の fetch、Agent Card の認証情報範囲）では、制限付きのテキストウィンドウと括弧の照合を使用しており、実際のパーサーは使用していません。そのため、より間接的な連鎖で代入された url 変数（例：ヘルパー関数に渡される場合）は正しく追跡できません。また、1 つのリテラルではなく、複数の Object.assign() 形式のマージに分散した Agent Card オブジェクトも追跡できません。
• 命名規則に依存します。 チェックでは、pushConfig.url、*AgentCard、UserBuilder.noAuthentication のような識別子を探します。SDK 独自の規則から外れるように名前が変更されたコードは認識されません。これは、この系統のパターンベースのスキャナーすべてに共通する制限です。

---

開発

npm run build
npm test             # 18 unit tests

---

ライセンス

MIT — GuardBee

フィードバック

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