BackBond Agent Scan

BackBond Agent Scan

BackBond Agent Scan is published as the exact scoped package @backbond/agent-scan@0.6.3. 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.

If a result from this scanner or from a BackBond publication looks wrong, open a correction through the false-positive form. We respond within 72 hours.

Try the browser preview

Watch the 50-second synthetic walkthrough, then try the synthetic example. The silent video has on-screen text and a transcript. It shows a verified scanner 0.6.3 result for supplied metadata, not runtime behavior.

Try Agent Scan in your browser: three synthetic MCP examples, followed by a local check of your own tools/list JSON. No account or installation is required. The page processes the manifest in memory without uploading it.

The browser preview uses Agent Scan 0.6.3 and checks supplied MCP tool metadata only, up to 200 tools and 256 KiB. It does not assess runtime behavior, and a non-blocking result is not a safety determination or insurance decision. Use the pinned CLI below for other supported formats, larger inputs, or offline workflows.

Static MCP tool manifest inspection

BackBond Agent Scan helps operators vet MCP tools before attachment through local, deterministic static MCP tool manifest inspection. It reports findings and missing evidence without executing proposed tools. Results do not establish runtime safety.

Vet MCP tools before attachment

Export the proposed server's real tools/list response, then inspect that supplied manifest with the pinned vet-tools instructions below. A block result stops automatic attachment; review requires operator review; no_blocking_finding means no configured blocking rule fired on the supplied metadata. The scanner itself does not enforce attachment or create insurance coverage.

Install from a trusted host first

For operator-enforced checks on an existing stdio MCP connection, see the separate Agent Scan stdio gate. It starts the authorized server and gates tool attachment and calls; it is not included in the scanner npm package, does not sandbox startup, and does not verify runtime behavior. The checksum-verified standalone scanner and pinned npm paths below remain available for manual checks.

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.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

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.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

Compare both computed digests with the .sha256 files on the official v0.6.3 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.3 scan

npx -y @backbond/agent-scan@0.6.3 vet-tools --stdin < tools-list.json npx -y @backbond/agent-scan@0.6.3 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.3 --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.3, 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.3.tgz and its .sha256 file from the official v0.6.3 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.3.tgz.sha256

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

On Windows PowerShell, compare (Get-FileHash .\backbond-agent-scan-0.6.3.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 r