agent-graph-auditor

@guardbee/mcp-agent-graph-auditor

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

一个 MCP（Model Context Protocol）服务，可构建多 Agent 编排中的可达性图，并发现传递性过度授权——某个 Agent 从未被直接授予危险工具，却仍可通过另一个获准委派任务的 Agent 访问该工具。

mcp-server-auditor 可检测自身工具直接获得 shell/eval/SQL 访问权限的 MCP 服务。ai-code-scanner 可检测单个 Agent 的工具列表中包含 execute_command。这两种情况都只有一跳：Agent → 工具。多 Agent 框架还会增加另一类边——委派、群聊、函数执行路由。一个看似安全、仅有 web_search 工具的 Agent，一旦可以把工作交给拥有 shell 工具的同事，就可能变得危险。只逐一检查单个 Agent 自身工具列表的扫描器，无法发现这条两跳路径。

默认情况下，遥测功能处于关闭状态。设置 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. 提取。 特定框架的正则表达式提取器从源代码中提取 Agent/工具节点和关系边：has_tool（Agent 自有的工具集）、delegates_to（CrewAI 的 allow_delegation、LangGraph 的 add_edge）、group_member（AutoGen GroupChat 的共同成员关系——管理器可以将任一成员的输出路由给其他任一成员）、executes_via（AutoGen register_function 的调用方/执行方拆分）。
2. 分类。 根据基于名称的能力目录检查每个工具节点（代码执行、进程执行、文件系统写入、网络、凭据访问）——这与 ai-code-scanner 的过度代理能力模式使用的启发式方法相同，只不过应用于工具图谱，而不是单个服务的工具列表。
3. 追踪。 从每个 Agent 节点开始进行广度优先搜索。通过直接的 has_tool 边到达的能力工具属于直接发现项（仍会报告——即使图中没有第二个 Agent，这也很有用）。只有在跨越至少一条 delegates_to/group_member/executes_via 边之后才到达的能力工具属于传递发现项——这正是本软件包要解决的问题。无论工具自身的基础严重程度如何，这类发现项始终会被报告为严重，因为持有该工具的 Agent 从未针对它接受过直接审计。

LangGraph 是最可靠的目标：源代码中的 add_node/add_edge 调用就是编排图，无需推断。CrewAI 和 AutoGen 则需要根据框架语义（allow_delegation、GroupChat 成员关系）推断委派，而不是依赖代码中的显式边，因此应将这些结果视为启发式判断——请参阅下文的“局限性”。

---

功能

• 3 种框架：LangGraph（结构化）、CrewAI（启发式）、AutoGen/ag2（启发式）
• 7 条能力规则，涵盖 5 个类别（代码执行、进程执行、文件系统写入、网络、凭据访问）
• 区分直接（单个 Agent）与传递（跨越委派边）的过度代理能力——本 monorepo 中没有其他单 Agent 扫描器能发现传递情况
• 支持多跳——3 个或更多 Agent 的委派链与 2 个 Agent 的链一样都能被发现
• SARIF 2.1.0 输出——支持 CI/CD 集成（GitHub Code Scanning 等）
• 支持通过 guardbee.yml 使用配置文件
• 31 个单元测试，另有针对所有三个框架的真实场景 fixture 端到端验证

---

快速开始

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，意味着它可以把工作交给拥有该工具的 Agent。此扫描器会报告：

🔴 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 的模式窗口匹配采用相同的权衡）；此外，它不会跟踪重新赋值、条件式 Agent 构造或动态构建的工具列表。
• AutoGen 的 speaker_selection_method 未建模——GroupChat 中的共同成员关系始终被视为双向可达边，这是一种保守假设（宁可多包含，也不漏掉）。
• 能力分类基于名称。 名为 search_tool 的工具如果暗中在内部执行 shell 命令，不会被标记；名为 shell_tool_disabled 的工具则会被标记。请审查检查结果，不要将其视为绝对事实。
• v1 仅扫描 Python 源码——尚未覆盖 LangChain/LangGraph 的 JS/TS API。

---

开发

npm run build
npm test             # 31 unit tests

---

许可证

MIT — GuardBee

反馈

有疑问、想法或发现误报？请在 GitHub Discussions 中发起讨论，或提交问题。如果 GuardBee 对你有帮助，请在代码仓库点个 ⭐，帮助其他人发现它。