a2a-auditor

@guardbee/mcp-a2a-auditor

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

一个 MCP（Model Context Protocol）服务，用于扫描 Agent 自身的 Agent2Agent（A2A）协议实现，查找反模式——这些模式并非根据规范文本凭空杜撰，而是直接从参考 SDK（@a2a-js/sdk、a2a-sdk）及其官方示例代码中读取。

A2A 目前还没有类似 MCP 的“安全注意事项”章节可供引用。因此，本软件包没有猜测，而是从参考 SDK 源码本身发现了三种模式：官方推送通知发送器会获取客户端提供的 webhook URL，完全不检查主机；官方 示例 Agent 使用空安全方案和字面值为 noAuthentication 的请求处理器；Python SDK 的 AgentCard(...) 构造函数则将两个安全相关的 kwargs 都设为完全可选——如果不传入，就会默默表示“无身份验证”。

默认情况下，遥测功能处于关闭状态。设置 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)

---

为什么特别关注这三项

Webhook SSRF：参考实现中的 DefaultPushNotificationSender 会直接执行 const url = pushConfig.url; ... fetch(url, ...)——pushConfig.url 由订阅任务更新的客户端设置，而 SDK 获取该 URL 时完全不验证主机。调用者可以让运行此代码的服务访问内网服务、云元数据端点，或任何可从服务所在网络访问的目标。

缺少身份验证：SDK 自带的示例 Agent（src/samples/agents/movie-agent）使用 securitySchemes: {}、securityRequirements: [] 和 userBuilder: UserBuilder.noAuthentication——这是一种适合复制粘贴的形式，看起来像占位符，但实际上意味着“接受任何人的所有请求”。Python SDK 也有同样的问题，只不过表现为缺省而非显式空值：AgentCard(...) 不要求提供 security_schemes/security_requirements，因此按照参考示例构建的真实 Agent 可能完全没有身份验证，却不会收到任何错误提示。

凭据泄露：Agent Card 会公开提供——任何能访问 /.well-known/agent-card.json（或等效发现响应）的人都能读取它，获取卡片本身不需要身份验证。直接写在该 JSON 中的 API 密钥实际上是公开的。

---

功能

• 3 个类别：webhook-ssrf、missing-authentication、credential-exposure
• 同时支持 TypeScript 和 Python A2A 代码——SDK 对同一类故障采用不同的惯用写法（空对象与缺少 kwargs），因此两种语言都会检查，而不只检查其中一种
• 六项检查中有两项会跟踪跨越几行的数据流，而不是只匹配单个调用点：webhook 检查会将 url 变量追溯到形如 pushConfig.url 的赋值，然后标记使用该变量的 fetch()；凭据检查则会提取完整的 Agent Card 对象范围（通过匹配花括号），再在其中查找字面量密钥——因此不会仅因文件中任何位置出现 apiKey: 就触发标记
• 输出 SARIF 2.1.0——可集成 CI/CD（GitHub Code Scanning 等）
• 支持通过 guardbee.yml 配置文件进行配置
• 18 项单元测试——每种模式都有一个正向和一个负向（误报）场景，其中包括一项针对开发期间发现的真实 bug 的回归测试（\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 自身代码的特定反模式，而非针对运行中的 Agent 进行实时协议一致性检查。A2A 是一项较新且快速发展的规范，随着时间推移会出现目前尚未涵盖的新故障模式。
• 数据流检查（间接 webhook 请求、Agent Card 凭据范围）使用有界文本窗口和括号匹配，而非真正的解析器——通过更间接的链（例如传递给辅助函数）赋值的 url 变量无法被正确追踪；通过多个 Object.assign() 式合并而非单个字面量定义的 Agent Card 对象也无法被正确追踪。
• 依赖命名约定。 检查会查找形如 pushConfig.url、*AgentCard、UserBuilder.noAuthentication 的标识符——将这些标识符重命名为不符合 SDK 自身约定的代码将无法被识别，这是此类基于模式的扫描器共有的限制。

---

开发

npm run build
npm test             # 18 unit tests

---

许可证

MIT — GuardBee

反馈

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