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](https://github.com/BackBond/agent-scan/issues/new?template=false-positive.yml). We respond within 72 hours.

## Try the browser preview

[Watch the 50-second synthetic walkthrough](https://backbond.ai/agent-scan/#watch-demo), then [try the synthetic example](https://backbond.ai/agent-scan/try/?source=github-video). 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](https://backbond.ai/agent-scan/try/?source=github): 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](host-gate/README.md). 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:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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`](skills/agent-scan) folder to:

```text
.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](distribution/agent-plugin.md) and the reusable [`AGENTS.md` policy block](distribution/agent-policy.md).

The [`distribution`](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:

```bash
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