BackBond Agent Scan

BackBond Agent Scan

BackBond Agent Scan 以精确的限定作用域包 @backbond/[email protected] 发布。仅进行静态检查：检查你机器上已有的工具元数据和 Agent 配置。它不会运行工具、探测在线 Agent、上传跟踪记录、联系托管服务，也不会执行第二个二进制文件。

如果此扫描器或 BackBond 发布的结果有误，请通过误报表单提交更正。我们会在 72 小时内回复。

试用浏览器预览

观看 50 秒的合成演示，然后试用合成示例。静音视频带有屏幕文字和文字稿。视频展示的是针对所提供元数据的已验证扫描器 0.6.3 结果，并非运行时行为。

在浏览器中试用 Agent Scan：三个合成 MCP 示例，随后对你自己的 tools/list JSON 进行本地检查。无需账号或安装。页面会在内存中处理清单，不会上传。

浏览器预览使用 Agent Scan 0.6.3，仅检查所提供的 MCP 工具元数据，最多支持 200 个工具和 256 KiB。它不会评估运行时行为，且非阻止性结果不代表安全判定或保险决定。对于其他支持的格式、较大的输入或离线工作流，请使用下方固定版本的 CLI。

静态检查 MCP 工具清单

BackBond Agent Scan 通过本地、确定性的静态 MCP 工具清单检查，帮助运营人员在连接前审查 MCP 工具。它会报告发现的问题和缺失的证据，不会执行拟议的工具。结果不能证明运行时安全。

在连接前审查 MCP 工具

导出拟议服务端实际的 tools/list 响应，然后使用下方固定版本的 vet-tools 指令检查所提供的清单。block 结果会阻止自动连接；review 需要运营人员审查；no_blocking_finding 表示所提供的元数据未触发任何已配置的阻止规则。扫描器本身不会强制连接，也不会创建保险保障。

首先从可信主机安装

对于现有 stdio MCP 连接上的运营人员强制检查，请参阅独立的 Agent Scan stdio gate。它会启动获授权的服务端，并对工具连接和调用进行门控；它不包含在扫描器 npm 包中，不会隔离启动过程，也不会验证运行时行为。以下校验和验证的独立扫描器和固定版本 npm 路径仍可用于手动检查。

对于经过强化或网络隔离的 Agent，运营人员应在启用网络的可信主机上下载单文件发布资产及其校验和，完成验证，然后通过组织批准的软件传输途径传送已验证的文件：

curl -fLO https://github.com/BackBond/agent-scan/releases/download/v0.6.3/agent-scan.cjs
curl -fLO https://github.com/BackBond/agent-scan/releases/download/v0.6.3/agent-scan.cjs.sha256
sha256sum --check agent-scan.cjs.sha256
node agent-scan.cjs scan

在连接拟议的 MCP 或受支持的函数工具列表之前，请先将实际导出的清单保存为当前目录中的 tools-list.json。vet-tools 会读取该文件，不会创建它：

node agent-scan.cjs vet-tools --stdin < tools-list.json

agent-scan.cjs 是同一标记版 CLI 的未压缩、可审计且无依赖的构建版本。无需安装 npm 或访问网络，即可运行 scan、vet-tools 和 mcp stdio 入口点。

验证已发布的字节

受保护的发布工作流会发布包注册表来源证明，并将注册表权威 tarball、其 SHA-256、确定性独立文件及其 SHA-256 附加到相应的源代码标签。审查者可以根据公开源代码重新构建这两个构件：

git clone --depth 1 --branch v0.6.3 https://github.com/BackBond/agent-scan.git
cd agent-scan
npm pack
sha256sum backbond-agent-scan-0.6.3.tgz
node scripts/build-standalone.js agent-scan.cjs
sha256sum agent-scan.cjs

将计算所得的两个摘要与官方 v0.6.3 发布版本中的 .sha256 文件进行比较。若不匹配，必须停止。来源证明描述的是受保护的构建；逐字节复现则独立地将公开标签与已发布构件关联起来。两者都不是运行时证明或保险决定。

网络隔离的 Agent

如果 Agent shell 设置了 PrivateNetwork=true、仅允许 loopback、没有路由，或禁用了 AF_INET，远程包、源代码和服务注册表就无法将软件传入该 shell。不要为了这个扫描器削弱沙箱。请在沙箱外暂存固定版本的 agent-scan.cjs 及其校验和，在那里完成验证，通过获批的共享路径或镜像传输，然后在本地使用 node 运行。下载失败意味着 scan_not_run，绝不能视为未发现问题。

开发者笔记本上的便捷用法

在可联网的开发机器上，精确指定版本的 npm 命令仍是便捷的等效方式：

npx -y @backbond/[email protected] scan
npx -y @backbond/[email protected] vet-tools --stdin < tools-list.json
npx -y @backbond/[email protected] vet-tools --stdin --summary-only < tools-list.json

第二和第三条命令要求已存在 tools-list.json。如果你尚未导出实时工具清单，请运行第一条 scan 命令；不要将缺失或编造的文件通过管道传给 vet-tools。

安装固定版本的 Agent Skill

兼容的 Agent 可直接从不可变的发行标签安装标准 Skill：

npx -y [email protected] add https://github.com/BackBond/agent-scan/tree/v0.6.3 --skill agent-scan --yes

该安装程序是独立软件，会获取带标签的公共仓库；在受限环境中使用前，请先检查其自身的网络和遥测行为。安装 Skill 不会运行扫描。该仓库也是一个纯 Skill 的 Agent Plugin，不包含钩子、命令或插件级 MCP 配置。

如需手动安装，请将整个 skills/agent-scan 文件夹复制到：

.agents/skills/agent-scan/

安装后的文件必须为 .agents/skills/agent-scan/SKILL.md。它会将命令固定到 0.6.3，将覆盖缺口视为未知而非安全，并指示 Agent 切勿发布原始清单、跟踪记录、提示词、完整 JSON 报告或包含路径的凭据。它允许在汇总工作中输出不含身份信息的摘要。请参阅插件说明和可复用的 AGENTS.md policy block。

distribution 目录包含规范启动消息、跨平台安装卡片、已清理的演示、安全保护隐私的推广材料，以及首次五次运行的启动门槛。公开文案应取自该工具包，而不是改写成带有 @latest 的版本或更强的声明。

vet-tools 会返回 block（退出码 1）；当中等严重程度的发现或不完整／模糊的证据需要操作员审查时返回 review（退出码 3）；或返回 no_blocking_finding（退出码 0）。它会检查所提供的工具身份、描述、输入架构以及同一清单中的组合情况。要获得非阻断结果，每个工具都必须有明确无歧义的名称、描述或标题，以及一个可分析的对象输入架构；不透明分支、冲突的架构别名、混合清单方言、非 ASCII 身份、易混淆名称冲突、被包装成示例的指令式文本，或超出本地有界分析预算的架构，都无法得到非阻断结果。完整 JSON 包含规范配置文件摘要和可执行的 review_items 数组。每个条目都会提供稳定代码、可观察时受影响的工具数量、原因、所需证据和后续步骤，但不会更改判定或应用修复。它不会评估运行时强制执行、审批、审计行为、跟踪记录或实际执行。no_blocking_finding 并不代表安全判定或运行时证明。

对于由操作员暂存的大型运行，--summary-only 每次调用会输出一个精简的 backbond-vet-summary/v1 JSON 对象，适用于 JSONL 收集。它包含判定、版本元组、发现数量、规则和覆盖代码直方图、可执行的审查项以及提示词模板的出现次数。它保留常规的 0／1／3 判定退出码，同时省略工具和服务身份、工具描述、工件名称、证据指针以及模板哈希。此选项不能与 --json、--sarif 或 --suggest-policy 一起使用。由于省略了模板标识符，摘要模式的行无法证明同一模板出现在不同清单中；其出现次数仅针对单个所提供的清单。扫描器仍只接受本地清单，不会从 Registry 收集数据，也不会调用被扫描的工具。

在此仓库中，使用以下两个测试样例验证整套规则：

node bin/agent-scan.js scan --tool-schema fixtures/vulnerable/tool-schema.json --permissions fixtures/vulnerable/permissions.json --trace fixtures/vulnerable/trace.json
node bin/agent-scan.js scan --tool-schema fixtures/hardened/tool-schema.json --permissions fixtures/hardened/permissions.json --trace fixtures/hardened/trace.json

存在漏洞的情况会以 BB001–BB013 发现项和退出码 1 结束。经过加固的情况会以退出码 0 结束，不含发现项且覆盖完整。

扫描器在本地执行，不会发出网络请求。首次使用 npx 安装时，必须能够访问配置的 npm registry，除非该确切版本已缓存。

如果 npm 不可用

EAI_AGAIN、ENETUNREACH 和注册表超时都发生在扫描器启动之前。安装失败一次后就停止，并报告未运行扫描。不要切换到 @latest、更改 npm 注册表、禁用 TLS 检查，也不要接受聊天中发送的软件包路径。

上面的独立资源是最简单的离线路径。操作人员也可以从官方 v0.6.3 源代码发布版本下载 backbond-agent-scan-0.6.3.tgz 及其 .sha256 文件，并通过组织的可信软件渠道传输这两个文件。运行前，请立即在目标位置验证传输后的字节：

sha256sum --check backbond-agent-scan-0.6.3.tgz.sha256
npm exec --yes --offline --package=./backbond-agent-scan-0.6.3.tgz -- agent-scan scan

在 Windows PowerShell 中，将 (Get-FileHash .\backbond-agent-scan-0.6.3.tgz -Algorithm SHA256).Hash 与 .sha256 文件中的第一个值进行比较；如有任何不匹配，请停止。

源代码发布版 tarball 与发布到软件包注册表的 tarball 相同。如果既无法获取固定版本的软件包，也没有经过验证的操作人员提供的 tarball，那么应如实报告 scan_not_run，而不是生成零发现报告。

零配置首次运行

不带任何工件参数运行 scan 会执行有界发现。它会检查项目的上级目录和已知用户路径，查找受支持的桌面应用和编码 Agent 的 MCP 设置、便携式 .mcp.json 文件，以及附近的 AGENTS.md 或 SKILL.md 指令文件。指令文件只会列出，不会被解读为安全控制措施。

发现过程会读取确切的已知文件，不会递归遍历主目录。已配置但未导出实时工具列表的 MCP 服务会产生 BB-COV-MCP-TOOLS-NOT-EXPORTED，而不是静默通过。

配置适配器也会根据 MCP 服务名称、命令和参数推导粗略的能力，而不会启动这些服务。因此，即使缺少 tools/list，常见的 shell、fetch/浏览器、文件系统、数据库和凭据服务标识仍然可见。对于命令执行、根目录文件访问和不受限制的 Web fetch，适配器会将识别出的通配符规则映射到推导出的权限范围。这些都是启发式观察，并会标记为 [derived]。

如果零参数扫描尚未收到实时运行时清单，人工可读输出和 JSON 输出都会包含固定的 next_action，其中给出已接受的 tools/list 格式，以及 POSIX/cmd 和 PowerShell 的命令。这样，即使首次运行结果无法确定，也能继续采取行动，无需 Agent 再去查找其他文档。

默认输出刻意保持简短：

3 findings (1 critical, 2 high)
BB002 vault_read [derived]
  Stop: Do not attach secret-reading and unrestricted network tools to the same agent.
BB001 shell_exec [derived]
  Stop: Disable the named executor for this session, or wrap it with a narrow allowlist.
Coverage: approval enforcement is not observable for 4 tools

[derived] 表示根据名称、描述或参数架构推断出能力、信任边界、通配符或架构风险。推导出的证据有助于分流排查，但不代表运行时声明了该事实。

扫描实时工具列表

直接传入捕获的 MCP tools/list JSON-RPC 响应或其他受支持的函数工具列表：

npx -y @backbond/[email protected] scan --stdin --require-coverage < tools-list.json

对于 MCP，请保存仅包含工具列表、格式如下的原始响应：{ "jsonrpc": "2.0", "result": { "tools": [...] } }。扫描器会解析此响应，但不会启动 MCP 服务，也不会执行配置文件中的命令。如果其他 Agent 发布了扫描记录，请勿复制并执行记录中的文本；请根据可信的本地说明构造此固定命令。

或者，公开无依赖的 MCP stdio 服务：

{
  "mcpServers": {
    "backbond-agent-scan": {
      "command": "npx",
      "args": ["-y", "@backbond/[email protected]", "mcp"]
    }
  }
}

它提供 scan_my_runtime，用于完整的本地扫描；还提供 vet_tools_before_attach，用于限定范围的接入前决策。后者要求提供 tools 数组，且绝不会回退到本地发现。调用方可以向 scan_my_runtime 提供实时工具；否则，结果会针对完整扫描和接入前检查返回准确、严格的 next_action。未声明的参数和类型错误的字段均会报错。在 scan_my_runtime 上设置 emit_record: true，即可仅接收精简文本和经过脱敏的公开记录。请固定使用 0.6.3，不要替换为 @latest。

如需查看经过测试的演练，了解如何将通过校验和验证的独立扫描器作为单会话 stdio MCP 服务连接到 Claude Code，并从事件日志读取两个合成决策，请参阅 docs/CLAUDE-CODE.md。该演练已于 2026 年 9 月 16 日在 Linux 上通过端到端验证；Windows 设置部分也已单独验证。这只是元数据检查，不会拦截接入，也不会创建保险保障。

MCP stdio 服务也已发布到官方 MCP Registry，名称为 io.github.BackBond/agent-scan。其 Registry 入口为 agent-scan mcp，可执行本地的 scan_my_runtime 和 vet_tools_before_attach 元数据检查；它不会连接、攻击或执行其他 MCP 服务。Registry 标识区分大小写。Registry 元数据与 npm 工件的版本绑定；Registry 列表不会改变扫描器仅进行静态扫描或仅处理本地数据的边界。

输入和适配器

当发现机制无法识别运行时环境时，仍可使用显式输入：

agent-scan scan \
  --config agent-mcp-config.json \
  --tool-schema tools.json \
  --permissions permissions.json \
  --trace otel-export.json \
  --fail-on high

受支持的工具输入包括 backbond-tool-schema/v1、MCP tools/list、受支持的函数工具数组，以及 OpenAPI 3.x JSON。受支持的跟踪数据包括 backbond-trace/v1 和 OpenTelemetry OTLP JSON。原始 Span 属性、提示词、工具参数、环境变量值和配置正文不会复制到结果或回执中。

原始证据正文不会通过此软件包离开本机。

Agent 框架目前可以通过将运行时工具列表导出为某种通用格式或写入 stdin 来使用扫描器。版本 0.6.3 不会执行或导入任意框架代码来发现工具；特定于框架的代码提取器需要专用隔离环境，应放在此确定性输入处理步骤之后。

发现

公开的 backbond-local-rules/2.0.2 规则包包含：

• BB001 — 不可信输入可能到达代码或 Shell 执行环节；
• BB002 — 访问机密的能力与不受限制的出站通信相结合；
• BB003 — 具有重大影响的操作缺少强制审批；
• BB004 — 持久化写入接受不可信内容；同一清单中的网络入口会将该发现从需审查的中风险提升为高风险；
• BB005 — 特权操作缺少可观察的审计证据；
• BB006 — 文件系统、子进程、凭据或网络权限范围包含通配符；
• BB007 — 可执行工具接受不受约束的 Shell、代码、求值器或数据库解释器输入；
• BB008 — 活跃的网络工具接受未加入允许列表的类 URL 目标；
• BB009 — 工具描述直接指示 Agent 覆盖受保护的指令；
• BB010 — 工具描述直接要求 Agent 隐瞒工具行为；
• BB011 — 工具描述直接索取敏感数据；
• BB012 — 不可信的类获取工具与显式特权证据、带破坏性提示的特权证据、OpenAPI DELETE 或类操作特权证据位于同一 Agent 清单中；以及
• BB013 — 工具描述试图强制进行全局选择或调用。

每条发现都包含稳定 ID、严重级别、受影响的工具、证据指针、证据质量、finding_class、非数字的 precision_note、立即执行的 Stop 指令以及修复建议。人类可读输出和 JSON 输出会分别统计能力暴露和提示词注入指标，而不会将其归为同一风险类别。完整的本地 JSON 中，提示词复制类发现还包含经过规范化的元数据模板哈希及其出现次数，便于离线去重；收据和公开记录会省略这些哈希。请参阅 docs/RULES.md 或 /agent-scan/rules/#BB001 下稳定的网页永久链接。

当现有发现构成可识别的组合时，输出还会包含 EP001–EP003 潜在暴露路径。这些只是基于相同 BB 发现生成的展示摘要，不会引入新规则、严重级别或阈值。它们描述的是静态共存，而非已观察到的污点、净化或运行时数据流。

fixtures/wild 中的 4 个匿名非 BackBond 示例证明，这些发现也适用于 MCP、工具描述投毒、通配符沙箱权限范围和可信工具配置文件，而不仅限于规范测试样例。fixtures/corpus-regression 中的 18 个用例（10 个合成边界用例，加上 8 个根据已保存输出差异审计得出的 BB001 脱敏用例）固定了 2026-08-31 语料库审查期间发现的阻止／需审查／不阻止区分。它们不保留任何服务名称或 URL。请参阅语料库回归测试与发布边界。

可供审查的修复建议

--suggest-policy 会添加一个机器可读的 backbond-policy-suggestion/v1 对象：

agent-scan scan --suggest-policy --json
agent-scan vet-tools --stdin --suggest-policy --json < tools-list.json

它会指出应禁用或包装的工具，并针对受支持的发现输出需要审查的 JSON Patch 模板。在预附件配置中，BB007 会收到一个不完整的允许列表模板，BB013 会收到一个基于事实改写描述的模板；扫描器不会臆造特定环境允许的操作，也不会悄悄改写工具行为。建议绝不会自动应用，也绝不会声称已强制执行。占位符补丁的 safe_to_apply_automatically: false 和 review_required: true。

CI 与 SARIF

退出码保持稳定：

• 0：没有符合 --fail-on 条件的问题；
• 1：至少有一个问题符合该条件（其优先级高于覆盖不完整）；
• 2：输入无效或扫描器失败；以及
• 3：请求了 --require-coverage，覆盖不完整，且没有问题已导致退出码为 1。

--fail-on 接受 critical、high、medium、low 或 none，默认值为 high，并针对运行时暴露问题 BB001–BB008 和 BB012 进行门控。工具描述问题 BB009–BB011 和 BB013 仍会显示，但不会触发该门控；当仓库希望提示词文案检查在 CI 中失败时，请使用单独的 --fail-on-prompt 阈值。CI 数据请使用 --json，SARIF 2.1.0 兼容的代码扫描和 IDE 使用者请使用 --sarif。

在 Action 的严格 vet-tools 模式下，可设置可选的仓库相对 sarif-path，以写入带有稳定规则帮助链接的相同命名问题。Action 不会上传此文件；任何上传或代码扫描步骤都仍需作为单独的显式工作流决策。

回执和权限门控

--receipt receipt.json 会写入输入哈希、规则集标识、问题和覆盖缺口。--signing-key 可选地使用 Ed25519 对回执签名。签名证明该回执在此密钥下的完整性；它不会让推断出的问题成为事实，也不能证明环境安全。

只有当覆盖状态为 complete、输入集与请求的操作匹配、确切的扫描器/规则集已获准，且签名密钥受到独立信任时，门控方才应接受零问题回执。覆盖不完整且没有问题时，结果报告为 inconclusive，而不是 no_findings。严格 CI 或权限门控请使用 --require-coverage。

agent-scan verify-receipt --input receipt.json

可分享的公开记录

写入经过删减、可粘贴的记录，不暴露路径、基本文件名、描述、参数、证据指针、工具名称或输入哈希：

npx -y @backbond/[email protected] scan --record-public scan-record.json

CLI 会打印一条由八行组成的简明记录，并写入采用 backbond-scan-record/v1 格式、保证级别为 self-run_unverified 的记录。它不是证书、命令已运行的证明，也不是 BackBond 证明。工具名称和输入指纹需要单独通过显式标志提供，因为二者都可能泄露内部拓扑或文件是否相同。

--record-commit 会添加由调用方提供的源引用。带引用的记录使用 backbond-scan-record/v2，并在简明卡片中包含完整提交 ID，但 CLI 不会检查 Git，也无法验证文件是否来自该提交：

npx -y @backbond/[email protected] scan --record-public scan-record.json --record-commit "$GITHUB_SHA"

对于经过提交验证的 CI 运行，请使用包含显式仓库构件的官方 Action。它会验证 HEAD == github.sha，要求每个输入均已跟踪且未偏离该提交，使用所选 Action 版本中捆绑的扫描器代码运行（不使用 npx），保留扫描器退出码，并写入经过删减的记录和作业摘要：

permissions:
  contents: read

steps:
  - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
  - id: agent-scan
    uses: BackBond/[email protected]
    with:
      tool-schema: security/tools.json
      permissions: security/permissions.json
      trace: security/trace.json

Action 输出 record-path 可传递给单独固定版本的构件上传步骤。CI 运行只能向独立信任该仓库、工作流、Action 引用和运行的使用者证明工作流实际执行的内容。可下载记录有意保持为 self-run_unverified；它不是 BackBond 证明。

严格架构检查和状态徽章

MCP 服务作者可以将同一个 Action 用作固定的挂载前清单门禁。mode: vet-tools 只接受一个已提交的 tool-schema 输入，将提示词检查视为阻断项，元数据不完整或存在歧义时返回退出码 3，且不会创建公开记录：

name: BackBond Schema Check

on:
  pull_request:
    paths:
      - 'tools-list.json'
      - '**/tools-list.json'
      - 'mcp.json'
      - '**/mcp.json'
      - '.mcp.json'
      - '**/.mcp.json'
  push:
    branches: [main]
    paths:
      - 'tools-list.json'
      - '**/tools-list.json'
      - 'mcp.json'
      - '**/mcp.json'
      - '.mcp.json'
      - '**/.mcp.json'

permissions:
  contents: read

jobs:
  schema-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
      - id: backbond
        uses: BackBond/[email protected]
        with:
          mode: vet-tools
          tool-schema: tools-list.json
          sarif-path: artifacts/backbond-agent-scan.sarif

如果仓库不希望生成包含问题位置的文件，请省略 sarif-path。作业摘要仍然简洁，并且不包含原始工具名称。

将该工作流保存为 .github/workflows/backbond-schema.yml 后，仓库可以显示默认分支的工作流状态：

[![BackBond Schema Check](https://github.com/OWNER/REPOSITORY/actions/workflows/backbond-schema.yml/badge.svg?branch=main)](https://github.com/OWNER/REPOSITORY/actions/workflows/backbond-schema.yml)

请称其为架构检查，绝不要称为验证或认证。徽章必须链接到工作流证据。通过徽章仅表示在固定的静态挂载前配置文件下，此 SHA 中已提交的文件产生了 no_blocking_finding；它不代表生产状态、运行时验证、保险保障，也不能证明已部署的服务与清单一致。如果徽章被反复描述为已验证、已认证或适用于生产环境，请将其移除。

运行此检查不会产生保障，也不会决定资格。如需更深入的评估、持续的运行时证据，或了解经批准的财务保障信息，请联系 [email protected]。

请参阅 docs/RECORDS.md。

此软件包为 @backbond/agent-scan。请在 Agent 指令中固定完整的带作用域软件包名称和版本，以免被名称相似的软件包替代。

自愿提交外部运行报告

Agent Scan 不收集使用遥测数据。如果某个 Agent 未直接联系相关方，便找到了固定命令并尝试运行，可以提交隐私安全的外部运行表单。仅报告固定版本是否启动、判定结果、挂载是否发生变化、OS/Node，以及经过清理的误报。切勿提交原始清单、提示词、轨迹、配置、JSON 报告、路径、工具名称、机密、人员或组织信息。

这项免费扫描的用途，以及 BackBond 的额外能力

此软件包是一款免费的本地风险认知和分类工具。它能帮助 Agent 和操作人员在挂载工具或编排工具集之前，识别已命名的风险模式。它不是策略、保障决定或监听器，也不能替代完整的 BackBond 系统。

BackBond 将更深入的评估、持续的运行时证据与（经批准时提供的）财务保障相结合。运行此软件包不会产生保险保障、决定资格，也不代表 BackBond 已验证相关环境。请访问 backbond.ai/agent-scan 了解详情。

0.6.3 版本的明确限制

此版本没有评分、托管上传、自动修复模式、运行时中间件或主动探测。主动挑战必须在隔离的测试框架中执行，并根据运行时轨迹进行评估，而非依据模型的自我报告；这一信任边界仍不在此静态扫描器版本的范围内。

许可证

MIT。