Agent Verify

Agent Verify

在部署前，了解你的 AI Agent 能做什么。

Agent Verify 会检查 AI Agent 或 Agent 软件包的权限、工具、MCP 连接、执行控制、密钥、运行时配置和依赖项，并在 Agent 进入生产环境前，根据证据给出 已验证 或 未验证 的结果。

传统安全工具会扫描软件。Agent Verify 还会检查 AI Agent 连接到哪些对象，以及这些连接实际上可能让它执行哪些操作——合法凭证、有效的 API 访问权限和获批工具仍可能组合成 Agent 绝不应执行的操作。

Agent Verify 提供开源的命令行、CI、Web 集成和 API 工具，并由专有验证引擎提供支持——请参阅隐私与专有扫描器边界。

架构

Dashboard ─┐
CLI ───────┼──► Worker API ──► server-side entitlement & scan quota ──► private scanner engine
API ───────┘         │
                      └──► D1 (billing/quota) · Firestore (reports, orgs, audit log)

每次扫描——无论来自仪表板、命令行还是直接的 API 调用——都会经过同一个经过身份验证的 Worker 路由，并使用同一个由服务端管理的月度配额；产品中没有任何仅由客户端或基于本地存储的扫描计数器，也没有任何浏览器代码会直接运行检测引擎。有关如何强制执行和验证这一边界，请参阅 Web 应用和隐私与专有扫描器边界。

此仓库包含的内容——开源与专有部分

组件	位置	许可证
Web 应用（仪表板、报告、落地页）	apps/web	开源（此仓库，MIT）
命令行 / SDK（npm 上的 agentverify）	packages/cli	开源（此仓库，MIT）
Cloudflare Worker API	workers/api	开源（此仓库，MIT）
检测引擎（@agentverify/scanner）	packages/scanner	专有——不在此仓库中

快速入门——命令行

npm install -g agentverify
agentverify scan ./agents --key av_your_key

登录 https://aimodularity.com/agentverify/ 后，在 仪表板 → API 访问 中获取 API 密钥。完整文档（包括 API 合约、CI/CD 集成和 JSON 输出格式）请参阅：https://aimodularity.com/agentverify/docs/

agentverify --help
agentverify --version
agentverify scan ./agents --key av_your_key           # scan a directory
agentverify scan --file agent.json --key av_your_key   # scan a single file
agentverify scan ./agents --key av_your_key --ci        # CI mode, strict exit codes
agentverify scan ./agents --key av_your_key --ci --policy standard  # + policy evaluation

CI 退出代码可区分真正的安全故障与执行问题：

代码	含义
0	所有已扫描文件均已验证
1	NOT_VERIFIED——真正的安全/验证失败
2	NOT_ASSESSED——证据不足，无法得出结论
3	执行错误——API 密钥错误或缺失、网络故障、文件缺失（并非安全发现）

GitHub Action

- uses: AI-Blockchain-Ventures/[email protected]
  with:
    path: ./agents
    api-key: ${{ secrets.AGENTVERIFY_API_KEY }}

完整参考文档请参阅 docs/github-action.md，其中介绍了 Markdown/JSON 输出模式、发布 PR 评论、分支保护以及 CI 中的策略评估。

Web 应用

仪表板（apps/web）基于与命令行相同的 Worker API，提供扫描历史记录、报告共享、检查目录、策略配置和组织/团队管理（角色：Owner/Admin/Member/Viewer）——仪表板中的每次扫描都由服务端计量，与命令行或 API 扫描完全相同，绝不会在客户端运行或计数。

Agent Verify 的分析内容

权限与工具访问、MCP 服务连接及其暴露的内容、执行/授权控制、密钥与凭证处理、运行时配置和依赖项——这是对提交内容进行静态分析，并非在实时沙箱中执行。

验证结果

• VERIFIED — 已评估充分的执行上下文，且通过了必需的信任控制。
• NOT VERIFIED — 已评估充分的执行上下文，但一项或多项安全或协议控制未通过。
• NOT ASSESSED — 提交的内容不包含足够的 Agent 执行上下文，无法作出判断。这不代表安全失败，且绝不能将其视为 VERIFIED。

每项发现还会标注其推导方式：definite（匹配到了具体模式）、heuristic（根据上下文推断，可能产生误报或漏报）或 informational（中性观察）。Agent Verify 执行静态分析，不会执行提交的代码，因此会如实说明其无法检测到的内容：请参阅下方的限制。

工件指纹 / 签名证明

每次扫描都会针对精确的扫描内容计算 SHA-256 工件指纹；相同内容始终会生成相同指纹，与扫描时间或规则集是否发生变化无关。配置了服务端签名后，扫描结果可以附带针对判定结果、评分和指纹的 签名证明（ECDSA P-256 / ES256），任何第三方只需使用已发布的公钥即可独立验证，无需共享密钥，也无需在验证时信任 Agent Verify 的 API。

策略

内置策略配置文件（standard、high-security、financial-agent、production-infrastructure）可以根据扫描证据进行评估，作为基础判定结果的补充，而绝不能取代基础判定结果：扫描可以是 VERIFIED，但仍未通过更严格的策略；策略也绝不能将 NOT_VERIFIED 扫描变为通过。在 CLI 中传入 --policy <id>，或在 GitHub Action 中使用 policy 输入项。

安全模型

计费、配额和身份验证由服务端权威控制，完整架构请参阅 docs/billing-setup.md。Webhook 负载会经过签名验证并以幂等方式处理，组织变更由服务端通过 RBAC 强制执行（绝不信任客户端提供的角色），Firestore Security Rules 会独立于 UI 强制实施逐用户访问控制。完整详情以及问题报告方式，请参阅 SECURITY.md。

隐私与专有扫描器边界

检测引擎（即决定风险内容的实际规则）是 Agent Verify 的核心 IP，且有意不纳入此 git 仓库的跟踪范围（packages/scanner/ 已被 gitignore）。CLI 和 Worker 会通过 HTTPS 或私有构建调用它；此公开仓库中的任何内容都不会打包或暴露其源代码，也没有任何随浏览器发布的代码会导入它——只有 Worker 端（仅服务端）的代码会导入。每次变更都会运行永久性 CI 检查（npm run check:private-boundary），构建 Web 应用并静态检查所有生成的客户端包，查找已知专有标记，从而防止此边界在不知情的情况下被破坏。公共 CI 会使用与扫描器类型兼容的存根（参见 scripts/create-ci-scanner-stub.mjs）验证 Web 应用、CLI 和 Worker，因此即使私有引擎从未出现，公开构建也仍可验证。

计划

Free（每月 10 次扫描、基础发现、私有报告历史记录）、Pro（每月 $19.99 — 完整修复指导、修正后的代码片段、A2SPA 实施指导、PDF 导出、每月 100 次扫描）、Team（即将推出）、Enterprise（请联系我们）。定价仅在 apps/web/src/lib/pricing.ts 中定义一次，并镜像同步到 Worker 的配额表（workers/api/src/billing.ts）——当前权威来源请参阅这些文件。

文档

• 应用文档：https://aimodularity.com/agentverify/docs/
• GitHub Action 参考：docs/github-action.md
• 计费/权益架构：docs/billing-setup.md
• 专有扫描器边界：docs/private-scanner-boundary.md
• 路线图：ROADMAP.md
• 更新日志：CHANGELOG.md

开发

npm install
npm run dev              # apps/web dev server
npm run build             # apps/web production build
npm run build:cli         # packages/cli
npm run build:worker      # workers/api
npm run lint               # apps/web
npm run check:web          # apps/web typecheck
npm run check:worker       # workers/api typecheck
npm run test:worker        # workers/api tests
npm run test --workspace=packages/cli
npm run test:rules         # Firestore Security Rules against the real emulator
npm run check:private-boundary  # proprietary-boundary regression check

完整的贡献者指南（包括可修改和不可修改的内容以及 PR 预期）请参阅 CONTRIBUTING.md。

局限性

Agent Verify 会对提交的内容进行静态分析。它不会执行你的 Agent，也无法查看：仅在运行时出现的行为、部署时动态授予的权限/凭据、在代码库之外强制执行的远程策略、生产环境网络 ACL、外部身份提供商策略，或在源代码之外注入的运行时密钥。每份报告都会针对本次扫描明确说明这一点，并包含一个“Agent Verify 无法确定的内容”部分。分析结果基于证据和启发式方法，并非正式的安全性证明——报告未发现问题并不保证安全，发现问题也不代表已遭到利用。

许可证

MIT — AI Blockchain Ventures LLC — [email protected]

MIT 适用于上述列出的本仓库组件（Web 应用、CLI、Worker API）。检测引擎为专有软件，不在此许可证的授权范围内，也未包含在本仓库中。