Agent Bom

Scan your project in two commands

pip install agent-bom
agent-bom scan .

. means the current project. The local CLI reads it directly and prints inventory, findings, reachable context, and fix-first actions; no control plane is required. Export evidence when another tool needs it: agent-bom scan . -f sarif -o findings.sarif. For scripts, --project . (short form: -p .) is equivalent.

-p/--project expects a directory, not a manifest file. For large monorepos, point it at the workspace or service under review and run one scan per CI workspace; the current CLI does not pretend to provide an arbitrary path-exclude language.

Three ways to use it

Discovery and static/cloud scanning are read-only. The self-hosted control plane stores evidence, and runtime modes make explicit policy decisions; those are separate operational boundaries, not all one read-only pipeline.

Who it is for

The product generates security and compliance evidence; it is not a replacement for a GRC system of record, IAM, SIEM, or a complete certification program.

Blast radius links package risk to the MCP servers that load it, exposed tools, credential references, and agents that can reach it. Coverage and boundaries: AI infrastructure scanning · product boundaries · first-run guide.

How it works

Local CLI and CI call the scanner directly and do not require a server. The self-hosted control plane adds an authenticated API and UI, tenant-scoped persistence, fleet jobs, attack paths, compliance, and audit. Gateway and proxy modes enforce live tool traffic at a separate runtime boundary.

Neptune is an optional graph backend and ClickHouse is optional analytics. Snowflake supports selected warehouse/store paths with documented parity limits. MCP server mode exposes 76 MCP tools, 6 resources, and 8 workflow prompts over strict arguments. Agent distribution includes a committed Smithery manifest; external catalog liveness is verified separately. The implementation-level diagram and component boundaries live in docs/ARCHITECTURE.md.

agent-bom normalizes advisory and distro evidence into canonical CVE findings with match-confidence tiers:

distro_confirmed > osv_range > osv_ecosystem > unfixed_distro > nvd_cpe_candidate

Distro-confirmed findings are treated as confirmed. Optional NVD CPE candidate matching widens long-tail OS/vendor software coverage, but remains review-grade and off by default.

NVD key model. End users do not need an NVD API key. CVE/CPE enrichment ships through the distributed vulnerability database. NVD_API_KEY is only an optional self-hosted freshness knob for operators rebuilding or refreshing the database.

Matching mechanics and release evidence: vulnerability matching · scanner accuracy baseline · graph contract · architecture deep dive

See the product

Try the live demo (read-only sandbox; if unreachable, run uvx agent-bom scan --demo --offline). These captures come from the shipped Next.js routes using explicitly labeled, synthetic demo evidence.

Prioritize an attack path, not just a CVE

The investigation lens connects identity and agent reachability to the MCP server, package, and finding that create the exposure. Operators can export the graph evidence or hand the path directly to remediation.

See every finding and its reach

Move from risk to owner-ready work

The demo is intentionally comprehensive, so it is kept collapsed at README display width. Its seeded requests typosquat produces an expected non-zero security-gate exit; that is a demonstrated finding, not a failed recording.

Full capture list and reproducible commands: docs/CAPTURE.md.

Run it anywhere

The surfaces share normalized finding and graph contracts while keeping their execution and authentication boundaries explicit. Pick the entry point that matches your role:

Beyond the basics — agent-bom graph (multi-hop exposure paths), agent-bom remediate -p . (advisory fix plan), agent-bom identity credential-expiry, agent-bom cost forecast, and the CI gate uses: msaad00/[email protected]. Full command map: docs/CLI_MAP.md · role routing: docs/START_HERE.md · all entry points and auth boundaries: docs/PRODUCT_MAP.md

Deploy targets — you run the control plane in your own boundary (no managed public SaaS in this repo yet), fastest → most-managed:

• Docker Compose — fastest; one file, loopback by default → pilot compose
• Helm / Kubernetes — cluster-native chart → chart
• EKS — opinionated Terraform module → module
• CloudFormation — one-click AWS stack → templates
• Snowflake (SPCS native app) — host entirely inside your own Snowflake account → install guide

curl -fsSL https://raw.githubusercontent.com/msaad00/agent-bom/main/deploy/docker-compose.pilot.yml -o docker-compose.pilot.yml
docker compose -f docker-compose.pilot.yml up -d
# Dashboard -> http://localhost:3000

Pilot compose binds to 127.0.0.1 with loopback CORS only. Use docker-compose.platform.yml or docs/HOSTED_POC.md before sharing a link. Full guides: Deploy anywhere.

Connected control plane

For brokered control-plane sources, connect once, then scheduled and operator actions use the stored connection reference—not a fresh credential prompt. Standalone CLI scans remain independent: they read local files or explicitly configured provider credentials and do not require a control-plane connection.

• Humans sign in via OAuth / OIDC / SAML SSO (standard providers plus a Snowflake OAuth authorization-code + PKCE flow), with SCIM for user and group provisioning (src/agent_bom/api/{oidc,saml,scim}.py, snowflake_oauth.py).
• Agents / CI authenticate with scoped API keys / tokens.
• Sources are onboarded once through read-only, agentless, brokered connectors — a single least-privilege managed role per source with short-lived, brokered credentials (e.g. AWS sts:AssumeRole); connection secrets are write-only (encrypted at rest, never read back).

Application-layer authentication, tenant isolation, rate limits, and audit are enforced in middleware for UI and API/SDK requests. Non-loopback deployments terminate HTTPS/TLS at Caddy, an ingress, an ALB, or an equivalent trusted edge; the API and UI remain on loopback or a private network. MCP server and gateway/proxy modes enforce their own documented transport authentication and policy boundaries; none receives a privileged UI-only path.

Cloud connectors are opt-in, default-off, and read no secret values. agent-bom connect <provider> prints the grant template and enable flag without network I/O until you opt in:

Snowflake auth defaults to browser SSO (externalbrowser); use SNOWFLAKE_AUTHENTICATOR=snowflake_jwt with SNOWFLAKE_PRIVATE_KEY_PATH for CI. Setup and the exact grant per provider: docs/CLOUD_CONNECT.md · intake map: docs/DATA_SOURCES.md · enterprise auth surface: docs/ENTERPRISE.md

Trust

• Read-only discovery by default; no mandatory telemetry.
• Credential values redacted; env names preserved for explainable exposure paths.
• Exports: JSON, SARIF, CycloneDX, SPDX, Parquet, CSV, Markdown, HTML, PDF, compliance bundles.
• Tenant scope, auth boundaries, and audit evidence on API/runtime paths.

Threat model · Pentest readiness · Python client · Go client · Release verification · MCP security model

Contributing

Contributions are welcome. Start with CONTRIBUTING.md, .agents/AGENTS.md, and the open issues.

License: Apache-2.0.