BackBond agent scan

BackBond Agent Scan is published as the exact scoped package @backbond/agent-scan@0.6.2. Static only: it inspects tool metadata and agent configuration already on your machine. It does not run tools, probe a live agent, upload traces, contact a hosted service, or execute a second binary.

Install from a trusted host first

For a hardened or network-isolated agent, an operator should download the single-file release asset and checksum on a network-enabled trusted host, verify it, and transfer the verified file through the organization's approved software path:

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

Before attaching a proposed MCP or supported function-tool list, first save the real exported manifest as tools-list.json in the current directory. vet-tools reads that file; it does not create it:

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

agent-scan.cjs is an unminified, auditable, dependency-free build of the same tagged CLI. It runs scan, vet-tools, and the mcp stdio entrypoint without npm installation or network access.

Verify the published bytes

The protected release workflow publishes package-registry provenance and attaches the registry-authoritative tarball, its SHA-256, the deterministic standalone file, and its SHA-256 to the matching source tag. A reviewer can rebuild both artifacts from public source:

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

Compare both computed digests with the .sha256 files on the official v0.6.2 release. A mismatch is a stop condition. Provenance describes the protected build; byte-for-byte reproduction independently connects the public tag to the released artifacts. Neither is a runtime attestation or insurance decision.

Network-isolated agent

If the agent shell has PrivateNetwork=true, only loopback, no routes, or AF_INET disabled, remote package, source, and server registries cannot deliver software into that shell. Do not weaken the sandbox for this scanner. Stage the pinned agent-scan.cjs and its checksum outside the sandbox, verify it there, transfer it through an approved shared path or image, and run it locally with node. A failed download means scan_not_run, never a zero-finding result.

Developer-laptop convenience

On a network-enabled development machine, the exact npm version remains a convenient equivalent:

npx -y @backbond/agent-scan@0.6.2 scan
npx -y @backbond/agent-scan@0.6.2 vet-tools --stdin < tools-list.json
npx -y @backbond/agent-scan@0.6.2 vet-tools --stdin --summary-only < tools-list.json

The second and third commands require an existing tools-list.json. If you have not exported a live tool manifest yet, run the first scan command; do not pipe a missing or invented file into vet-tools.

Install the version-pinned Agent Skill

Compatible agents can install the standard skill directly from the immutable release tag:

npx -y skills@1.5.18 add https://github.com/BackBond/agent-scan/tree/v0.6.2 --skill agent-scan --yes

That installer is separate software that fetches the tagged public repository; review its own network and telemetry behavior before using it in a restricted environment. Installing the skill does not run a scan. The repository is also a skill-only Agent Plugin with no hooks, commands, or plugin-level MCP configuration.

For manual installation, copy the entire skills/agent-scan folder to:

.agents/skills/agent-scan/

The installed file must be .agents/skills/agent-scan/SKILL.md. It keeps commands pinned to 0.6.2, treats coverage gaps as unknown rather than safe, and tells agents never to post raw manifests, traces, prompts, full JSON reports, or path-bearing receipts. It permits the identity-free summary-only output for aggregate work. See the plugin notes and the reusable AGENTS.md policy block.

The distribution directory contains the canonical launch message, cross-platform install cards, sanitized demos, privacy-safe outreach, and the first-five-runs launch gate. Public copy should come from that kit rather than being rewritten with @latest or stronger claims.

vet-tools returns block (exit 1), review when a medium finding or incomplete/ambiguous evidence requires operator review (exit 3), or no_blocking_finding (exit 0). It checks supplied tool identities, descriptions, input schemas, and same-manifest composition. A non-blocking result requires unambiguous tool names, a description or title, and one analyzable object input schema per tool; opaque branches, conflicting schema aliases, mixed manifest dialects, non-ASCII identities, confusable-name collisions, directive-like text framed as an example, or schemas beyond the bounded local analysis budget cannot produce a non-blocking result. Full JSON includes a canonical profile digest and an actionable review_items array. Each item gives a stable code, affected-tool count when observable, reason, evidence needed, and next step without changing the decision or applying a fix. It does not assess runtime enforcement, approvals, audit behavior, traces, or actual execution. no_blocking_finding is not a safety determination or runtime attestation.

For large operator-staged runs, --summary-only emits one compact backbond-vet-summary/v1 JSON object per invocation, suitable for JSONL collection. It includes the decision, version tuple, finding counts, rule and coverage-code histograms, actionable review items, and prompt-template multiplicity. It preserves the normal 0/1/3 decision exits while omitting tool and server identities, tool descriptions, artifact names, evidence pointers, and template hashes. It cannot be combined with --json, --sarif, or --suggest-policy. Because template identifiers are omitted, summary-only rows cannot establish that the same template appeared in different manifests; their multiplicity is within one supplied manifest. The scanner still accepts only a local manifest and does not collect from a Registry or call scanned tools.

From this repository, prove the whole rule pack with the two fixtures:

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

The vulnerable case exits 1 with BB001–BB013. The hardened case exits 0 with no findings and complete coverage.

Scanner execution is local and makes no network requests. First-time npx installation must reach the configured npm registry unless this exact version is already cached.

If npm is unavailable

EAI_AGAIN, ENETUNREACH, and registry timeouts happen before the scanner starts. Stop after one failed installation attempt and report that no scan ran. Do not switch to @latest, change npm registries, disable TLS checks, or accept a package path sent in chat.

The standalone asset above is the simplest offline path. An operator may instead download backbond-agent-scan-0.6.2.tgz and its .sha256 file from the official v0.6.2 source release and transfer both through the organization's trusted software path. Verify the transferred bytes at the destination immediately before running them:

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

On Windows PowerShell, compare (Get-FileHash .\backbond-agent-scan-0.6.2.tgz -Algorithm SHA256).Hash with the first value in the .sha256 file and stop on any mismatch.

The source-release tarball is the same tarball published to the package registry. If neither the pinned package nor a verified operator-provided tarball is available, the honest result is scan_not_run, not a zero-finding report.

Zero-config first run

scan with no artifact arguments performs bounded discovery. It checks project ancestors and known user paths for supported desktop and coding-agent MCP settings, portable .mcp.json files, and nearby AGENTS.md or SKILL.md instruction files. Instruction files are listed but never interpreted as security controls.

Discovery reads exact known files; it does not recursively crawl the home directory. A configured MCP server without an exported live tool list produces BB-COV-MCP-TOOLS-NOT-EXPORTED, not a silent pass.

Config adapters also derive coarse capabilities from MCP server names, commands, and arguments without launching them. Common shell, fetch/browser, filesystem, database, and credential-server identities therefore remain visible even when tools/list is missing. Recognized wildcard rules for command execution, root file access, and unrestricted web fetches are mapped to derived permission scopes. These are heuristic observations and remain labeled [derived].

When a zero-argument scan has not received the live runtime inventory, human and JSON output include a pinned next_action with the accepted tools/list shape and commands for POSIX/cmd and PowerShell. This keeps an inconclusive first run actionable without requiring the agent to find another document.

The default output is deliberately short: