agent-graph-auditor

@guardbee/mcp-agent-graph-auditor

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

マルチエージェントオーケストレーション全体の到達可能性グラフを構築し、推移的な過剰権限を検出するMCP（Model Context Protocol）サーバーです。危険なツールを直接与えられていないエージェントでも、委任が許可されている別のエージェントを経由して、そのツールに到達できることがあります。

mcp-server-auditorは、シェル／eval／SQLアクセスを独自のツールに直接許可しているMCPサーバーを検出します。ai-code-scannerは、execute_commandを含む単一エージェントのツール一覧を検出します。どちらも1ホップ、つまりエージェント→ツールの検出です。マルチエージェントフレームワークには、委任、グループチャット、関数実行のルーティングという2つ目の種類のエッジが加わります。web_searchツールしか持たない一見安全なエージェントでも、シェルツールを持つ同僚エージェントに作業を引き渡すことが許可された途端、危険になる可能性があります。この2ホップの経路は、一度に1つのエージェント自身のツール一覧だけを調べるスキャナーでは見つけられません。

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

Claude ──► agent-graph-auditor ──► Your multi-agent Python source
              │
              ├─ LangGraph   (add_node/add_edge — structural, read directly from the graph API)
              ├─ CrewAI      (Agent/tools/allow_delegation + Crew membership — heuristic)
              └─ AutoGen/ag2 (GroupChat membership, code_execution_config, register_function — heuristic)

---

グラフの構築方法

1. 抽出。 フレームワーク固有の正規表現エクストラクターが、ソースからエージェント／ツールのノードと関係エッジを抽出します。has_tool（エージェント自身のツールセット）、delegates_to（CrewAI の allow_delegation、LangGraph の add_edge）、group_member（AutoGen の GroupChat における共同メンバーシップ — マネージャーによって、任意のメンバーの出力を他の任意のメンバーにルーティングできます）、executes_via（AutoGen の register_function における呼び出し元／実行者の分離）です。
2. 分類。 すべてのツールノードを、名前ベースの機能カタログ（コード実行、プロセス実行、ファイルシステムへの書き込み、ネットワーク、認証情報へのアクセス）と照合します。これは ai-code-scanner の過剰な権限パターンで使われているものと同種のヒューリスティックで、単一サーバーのツールリストではなく、ツールのグラフに適用します。
3. 到達。 すべてのエージェントノードから幅優先探索を実行します。has_tool エッジのみを通って機能ツールに到達した場合は直接の検出結果として扱います（2つ目のエージェントが関与しない場合にも有用なため、引き続き報告されます）。delegates_to／group_member／executes_via エッジを少なくとも1つ通った後にのみ機能ツールに到達した場合は推移的な検出結果となります。これこそがこのパッケージの目的であり、そのツールを持つエージェントは直接監査されていないため、ツール自体の基本重大度にかかわらず、常に重大として報告されます。

LangGraph が最も確実な対象です。add_node／add_edge の呼び出しは、ソース内のオーケストレーショングラフそのものなので、推論は不要です。CrewAI と AutoGen では、コード内に明示的なエッジがなく、フレームワークのセマンティクス（allow_delegation、GroupChat のメンバーシップ）から委任を推論する必要があるため、これらはヒューリスティックとして扱ってください。詳しくは、以下の「制限事項」を参照してください。

---

機能

• 3つのフレームワーク：LangGraph（構造ベース）、CrewAI（ヒューリスティック）、AutoGen/ag2（ヒューリスティック）
• 5つのカテゴリにわたる7つの機能ルール（コード実行、プロセス実行、ファイルシステムへの書き込み、ネットワーク、認証情報へのアクセス）
• 直接（単一エージェント）と推移的（委任を経由する）な過剰な権限を区別します。このモノレポ内の単一エージェント向けスキャナーでは検出できないのが、推移的なケースです
• 複数ホップに対応しており、3つ以上のエージェントが連なる委任チェーンも、2エージェントの場合と同様に検出します
• SARIF 2.1.0 出力 — CI/CD 連携（GitHub Code Scanning など）
• guardbee.yml による設定ファイルのサポート
• 31件の単体テストに加え、3つのフレームワークすべてについて、現実的なフィクスチャを使ったエンドツーエンド検証

---

クイックスタート

Claude Desktop／MCP クライアント

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

CLI（CI/CD）

npx @guardbee/mcp-agent-graph-auditor scan ./agents --fail-on=high --format=sarif > results.sarif

---

MCP ツール

ツール	説明
scan_text	Python のコードスニペットをスキャンします
scan_file	単一の .py ファイルをスキャンします
scan_directory	ディレクトリ内の .py ファイルを再帰的にスキャンします
list_patterns	危険な機能のカタログをカテゴリ別に一覧表示します

---

例

researcher = Agent(role="Researcher", tools=[web_search_tool], allow_delegation=True)
ops = Agent(role="Ops Engineer", tools=[shell_tool], allow_delegation=False)
writer = Agent(role="Writer", tools=[], allow_delegation=False)
crew = Crew(agents=[researcher, ops, writer], tasks=[])

researcher は shell_tool を直接持っていません。しかし、allow_delegation=True が設定されており、ops と同じ Crew のメンバーであるため、作業を実行可能なエージェントに引き渡せます。このスキャナーは次のように報告します。

🔴 CRITICAL  Transitive excessive agency: reaches shell_tool
   Path: Researcher → Ops Engineer → shell_tool

🔴 CRITICAL  Direct excessive agency: reaches shell_tool
   Path: Ops Engineer → shell_tool

writer はツールも委任機能も持たないため、検出結果はありません。

---

設定（guardbee.yml）

agent-graph-auditor:
  fail-on: high       # any | critical | high | medium | none
  max-files: 2000
  exclude:
    - ".test.py"

---

制限事項（設計上）

• 単一ファイルの範囲です。 各ファイルのグラフは個別に抽出されるため、Python の変数参照はファイルをまたいで解決されません。ディレクトリ全体をスキャンする場合でも、Crew(agents=[researcher, ops]) の呼び出しが接続するのは、同じファイル内で見つかった Agent(...) 定義のみです。
• CrewAI/AutoGen の抽出はヒューリスティックであり、実際の Python パーサーではありません。 コンストラクター本体は正確な括弧対応ではなく、長さに上限のあるテキスト範囲を使って取得されます（ai-code-scanner のパターンウィンドウマッチングと同様のトレードオフです）。また、再代入、条件付きのエージェント構築、動的に作成されるツールリストは追跡しません。
• AutoGen の speaker_selection_method はモデル化されていません。 GroupChat の共所属は常に双方向の到達可能性エッジとして扱われます。これは保守的な仮定であり、範囲を広く取りすぎることはあっても、狭く取りすぎることはありません。
• 機能の分類は名前に基づきます。 内部でシェルを実行する search_tool にはフラグが付かず、shell_tool_disabled にはフラグが付きます。検出結果は確認し、絶対的な事実として扱わないでください。
• v1 では Python ソースのみをスキャンします。LangChain/LangGraph の JS/TS API はまだ対象外です。

---

開発

npm run build
npm test             # 31 unit tests

---

ライセンス

MIT — GuardBee

フィードバック

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