agent-bom

From evidence source to verified action

Security teams rarely lack scanners. They lack one trustworthy view of what was scanned, what was discovered, which findings are actually connected to critical systems, who owns the fix, and whether the fix held.

agent-bom closes that loop with two honest entry paths:

Both paths converge after collection: normalize evidence into the same Finding + UnifiedGraph contracts, correlate reachable risk, assign an owner and SLA, then re-scan to verify the result. Inventory is always the output of a named target or connected source—never unexplained preloaded data.

The product promise: start with one useful artifact today; keep the same evidence model as you add CI, connected sources, history, assignments, compliance exports, and runtime enforcement in your own environment.

Quick start · Evidence workflow · Integration capability matrix · Measured matcher proof · Control-plane architecture

Product proof: independent evidence, one verifiable path

The views below come from the committed Reference evidence lab — modeled local infrastructure. The credential-free run uses the real repository parser and bundled advisory scanner for pillow@9.0.0 / CVE-2023-4863, then correlates exact OCI digest, Kubernetes UID, MCP tool, workload identity, and runtime receipts. It is not customer evidence or a live-cloud claim.

The resulting path is confirmed only because every directed hop is traversable and provenance-backed: exposed service → workload → digest-pinned container → pillow@9.0.0 / CVE-2023-4863 → MCP capability → workload identity → modeled sensitive object store. The same lab records an observed gateway call and a separate strict opt-in block before the remediation handoff.

Regenerate the reference lab · Open the full product gallery · See the capture protocol

Related MCP server: agent-audit

Value by role

Security engineering and GRC remain separate workflows: findings and reachability are not presented as audit certification. See product boundaries. GitHub Actions collection and credential requirements are documented in permissions; scenario truth boundaries are defined by the graph contract.

Quick start

Choose the smallest path that proves value. No account or control plane is required for repository, image, SBOM, workstation, or MCP configuration scans.

Path A — scan now, no connection

The offline sample completes without downloading an advisory database and shows the inventory, finding, reachable path, and remediation output shape.

pip install agent-bom
agent-bom scan --demo --offline

The sample intentionally contains a known-malicious package, so exit status 1 is expected and the printed report is complete. Scan a repository next:

agent-bom scan .

The repository scan shows inventory, findings, and reachable impact. agent-bom scan . and agent-bom scan -p . are the same command; PATH is an alias for --project.

Path B — connect a source, then scan

Use this path when the source is an account or platform rather than a local target. Start the customer-controlled control plane, open Connections, add the provider's read-only grant, and run the first scan. The browser flow defaults to an explicit first scan after verification; scheduled scans are an explicit operator opt-in.

pip install 'agent-bom[ui]'
AGENT_BOM_NO_AUTH_ROLE=analyst agent-bom serve --persist ~/.agent-bom/control-plane.db

The explicit SQLite path keeps scan jobs, findings, compliance history, and graph inventory available together after a restart. Omit --persist only for an intentionally ephemeral process. The explicit local analyst role permits this loopback operator to run scans; the server's default anonymous role remains read-only.

For headless onboarding, agent-bom connect <provider> prints the exact grant, credential boundary, verification step, and next scan command. The cloud connection guide documents AWS, Azure, GCP, and Snowflake, including organization scope and scheduler behavior.

Need a disconnected scan? Seed the smallest package-advisory database first:

agent-bom db update --osv-ecosystem PyPI
agent-bom scan . --offline

If that database is missing or unreadable, the scan writes a partial artifact when -o is set and exits 1; CI therefore cannot mistake unavailable advisory coverage for a clean scan.

On a fresh database, that command covers only the selected ecosystem; packages from other ecosystems remain explicit offline coverage gaps. Repeat --osv-ecosystem for a polyglot repository, or use agent-bom db update --source osv for OSV's all-ecosystems archive. The full archive can exceed 1 GB, may take several minutes, and shows live progress with the exact total when the server supplies it. Run the broader agent-bom db update when you also need distro, exploit-probability, and known-exploited-vulnerability feeds.

A non-zero exit is a verdict, not a crash. scan exits 0 when nothing matched a gate, and 1 when one did — a --fail-on-* threshold you set, a known-malicious package, or a scan that did not complete. The report is printed in full either way, and the last line names the gate that matched. Full exit-code contract.

Save an artifact with agent-bom scan . -f sarif -o findings.sarif, or follow the first-run guide for formats and CI use.

Daily developer loop

Try the scanner without installing it, then check a package before adding it:

uvx agent-bom scan .
uvx agent-bom check requests@2.33.0 --ecosystem pypi

check returns an allow/unsafe/incomplete pre-install verdict; scan covers the repository plus discovered AI/MCP configuration. To make both dependency and secret gates automatic for a team, pin the shipped consumer hooks:

repos:
  - repo: https://github.com/msaad00/agent-bom
    rev: v0.103.1
    hooks:
      - id: agent-bom-secrets
      - id: agent-bom-scan

Run pre-commit install once. The hooks install agent-bom into their own isolated environment, so contributors do not need a separate global install. Hook behavior and CI examples.

Use the curated, explicitly synthetic sample when you only want to inspect the output shape:

agent-bom scan --demo --offline

The sample intentionally contains a known-malicious package, which fails closed.

Self-host

The control plane is the growth path, not a prerequisite. Use it when one-off artifacts need to become a durable team workflow: registered sources, scheduled scans, history, inventory snapshots, finding ownership, graph investigation, compliance evidence, and runtime policy—all inside the customer's cloud, cluster, database, identity, and audit boundary.

Start the loopback evaluation profile:

pip install 'agent-bom[ui]'
AGENT_BOM_NO_AUTH_ROLE=analyst agent-bom serve --persist ~/.agent-bom/control-plane.db

Then open Connections to add a source or New Scan to target a repository, image, SBOM, MCP configuration, or IaC path. A scan produces the inventory; inventory is not populated merely by starting the server.

For a shared deployment, use the production-shaped Docker or Helm path and configure real identity, TLS, PostgreSQL, encryption, and audit keys before exposing it.

Examples target this release candidate; confirm release availability before copying an exact pin. Otherwise, use the latest version shown on PyPI.

Deployment overview · Enterprise configuration · Cloud connections

MCP server mode exposes 86 MCP tools, 6 resources, and 8 workflow prompts, all read-first: discovery and analysis never mutate a scanned target.

Set YDC_API_KEY to enable the optional youcom_search MCP tool for live web and news context alongside the local threat-intel database. It is the only tool that sends your query to a third party, it is off unless the key is set, and the request is pinned to the You.com origin over TLS — so the key cannot be redirected to another host by configuration.

The CLI, Docker, API, Helm chart, MCP server, gateway, and SDK are distribution surfaces of the same product. The Snowflake SPCS / Native App lane runs inside the customer's Snowflake account; it is a customer-owned deployment target, not an agent-bom-hosted service. Snowflake and Snowpark also remain connector and runtime integrations for the other deployment profiles.

Trust

• Read-only discovery by default; runtime write decisions are separate and explicit.

• Credentials are write-only where stored, encrypted at rest, and never returned by API responses.

• API and control-plane routes are tenant scoped and auth protected outside explicit local mode.

• Missing evidence is shown as unavailable or partial, never converted into a factual zero.

• Public examples and screenshots use deterministic synthetic identifiers only.

Threat model · Release verification · Security policy · MCP security model

Contributing and support

Stuck, or not sure where a question belongs? SUPPORT.md has the routing and an honest statement of what response to expect.

To contribute, start with CONTRIBUTING.md, AGENTS.md, and the open issues.

Apache-2.0 licensed.