agent-bom

agent-bom scans local and fleet AI infrastructure, builds an AI BOM across agents, MCP servers, tools, packages, credential environment names, cloud estate, non-human identities, runtime, and skills, then turns that inventory into findings, compliance evidence, LLM cost posture, and graph-backed multi-hop exposure paths.

The same evidence is available through CLI/CI, REST API, MCP tools, and a self-hosted dashboard. Runtime proxy/gateway controls — including inline firewall enforcement and a secure-by-default gateway — are optional and scoped to environments where enforcement is worth the operational cost.

package
  -> vulnerability finding
  -> MCP server
  -> tools + credential refs
  -> agent

Blast radius is the core idea. A vulnerable package is not just a CVE row; it is linked to the MCP server that loads it, the tools exposed by that server, the credential environment names in reach, and the agents that can call it.

What It Scans

Findings converge on one unified Finding model and a unified ContextGraph, so multi-hop attack-path fusion, blast radius, and exposure scoring all read from the same evidence. The graph adds correlation overlays on top of that base: an ASPM layer that organizes AppSec findings around the application they belong to, LLM cost fused onto the resources that incur it, read-only cloud audit-trail activity as behavioral edges, and an estate-scale CONTAINS roll-up with drill-down so large clouds stay readable instead of one sprawling canvas.

First Run

pip install agent-bom
agent-bom quickstart --dry-run --offline   # print the onboarding plan
agent-bom quickstart --run --offline        # write sample, scan, seed gateway policy, populate the cockpit
agent-bom agents --demo --offline

The demo uses bundled advisory-backed OSV/GHSA ranges against intentionally vulnerable sample packages and produces graph-ready inventory without touching your source tree. For a real local scan:

agent-bom agents -p . -f html -o agent-bom-report.html

Want an inspectable sample stack first?

agent-bom samples first-run
agent-bom agents --inventory agent-bom-first-run/inventory.json -p agent-bom-first-run --enrich

See docs/FIRST_RUN.md for the guided path from CLI output to the dashboard.

To reproduce the dashboard screenshots from a clean local control-plane store:

make build-ui
uv run agent-bom serve --persist /tmp/agent-bom-demo.db --allow-insecure-no-auth
uv run agent-bom agents --demo --offline --no-auto-update-db -f json -o /tmp/agent-bom-demo.json
curl -sS -H 'content-type: application/json' --data-binary @/tmp/agent-bom-demo.json \
  http://127.0.0.1:8422/v1/results/push

Product Proof

The dashboard screenshots below are captured from the packaged UI with bundled demo scan data and seeded control-plane records, not static mockups. The data is synthetic where needed, but the routes are the real scan, graph, fleet, identity, audit, and gateway surfaces. The README keeps the first screen focused; expand the gallery when you want to inspect the control-plane surfaces.

The graph proof set is intentionally split across modes: fix-first exposure paths, root-centered lineage, lateral context, and package risk distribution. That keeps each view readable instead of forcing every relationship into one sprawling canvas.

Fleet and identity views use the same control-plane APIs that operators use for customer-owned deployments. The sample below seeds environment, owner, lifecycle state, and agent identity events so the screenshots show how local scan evidence connects to reviewable governance records.

Screenshot capture rules and the full manifest live in docs/CAPTURE.md and docs/images/product-screenshots.json.

Start Here

The base wheel is the scanner and CLI path. Optional runtime surfaces fail fast with install hints when their extras are missing.

New to the repo? PROJECT_STRUCTURE.md is the repo map, docs/START_HERE.md routes you by role, and docs/CLI_MAP.md groups every command by domain.

MCP registry publishing is tracked through the committed Smithery manifest and other registry metadata; install and liveness checks stay in the linked integration docs instead of this front door.

Shipped Surfaces

MCP server mode advertises 70 MCP tools, 6 resources, and 6 workflow prompts. Most tools are read-only. The three Shield write actions fail closed unless the caller supplies operator_role=admin, operator_scopes=shield:write, and an audit reason.

CLI scan commands run local scan pipelines today. They share lower scanner and discovery libraries with the API, but they are not API wrappers yet.

Runtime enforcement is explicit. Proxy mode either wraps a target MCP server for audit and policy decisions, or runs that server through Docker/Podman isolation when a sandbox image is supplied:

agent-bom proxy --no-isolate --policy policy.json --detect-credentials --block-undeclared -- npx @mcp/server-github
agent-bom proxy --sandbox-image ghcr.io/acme/mcp-runtime@sha256:<digest> \
  --sandbox-image-pin-policy enforce --block-undeclared -- npx @mcp/server-postgres

Connect a Cloud (Read-Only)

agent-bom reads four clouds — AWS, Azure, GCP, and Snowflake — through one connection model. Every connector is read-only, agentless, and keyless by default: only control-plane list/get (or SHOW/SELECT) APIs, no writes, no secret values, no data leaves your account. Each connector is opt-in and default-off, gated by a per-provider env flag; with the flag unset, agent-bom does zero cloud network I/O.

The only thing that differs per cloud is the line that mints the read-only role — because each platform's grant primitive is different. Everything else is identical: enable with AGENT_BOM_<PROVIDER>_INVENTORY=1, authenticate with the cloud's own identity (never a secret handed to agent-bom), get the same graph and findings out.

agent-bom connect aws | azure | gcp | snowflake prints the exact read-only setup for each source — the Terraform module, the opt-in inventory env var, and whether local credentials are already detectable — without doing any network I/O until you opt in.

# AWS — attach SecurityAudit to the principal, then:
export AGENT_BOM_AWS_INVENTORY=1
export AWS_PROFILE=<readonly-profile>
agent-bom cloud aws --cis

# Azure — assign Reader (+ Security Reader), then:
export AGENT_BOM_AZURE_INVENTORY=1
az login
agent-bom cloud azure --cis

# GCP — grant a read-only SA and impersonate it (no key file):
export AGENT_BOM_GCP_INVENTORY=1
export AGENT_BOM_GCP_IMPERSONATE_SA=<sa-email>      # e.g. abom-readonly@<project-id>.iam.gserviceaccount.com
gcloud auth application-default login
agent-bom cloud gcp --project <project-id> --cis

# Snowflake — create ABOM_READONLY + a key-pair user (see CLOUD_CONNECT.md), then:
export SNOWFLAKE_ACCOUNT=<org-account>
export SNOWFLAKE_USER=ABOM_SCANNER
export SNOWFLAKE_AUTHENTICATOR=snowflake_jwt
export SNOWFLAKE_PRIVATE_KEY_PATH=/path/to/abom_key.p8
agent-bom agents --snowflake

A read-only estate inventory across the enabled clouds (reference only, no findings):

agent-bom cloud inventory --provider all        # or aws | azure | gcp

Or run one cloud-aware scan across every configured provider at once — --provider all (the default) auto-detects which clouds are connected and skips the rest:

agent-bom cloud scan                            # all configured clouds, read-only
agent-bom cloud scan --provider aws --cis --show-passed
agent-bom cloud registry-scan --provider ecr --region us-east-1   # sweep an ECR/ACR/GAR registry

CIS misconfigurations and graph toxic-combinations converge into the same Finding stream and exit-code gate as package vulnerabilities, so a real exposure can fail a pipeline:

agent-bom agents --aws --azure --gcp --snowflake --fail-on-severity high
agent-bom graph                                 # multi-hop exposure paths
agent-bom identity credential-expiry            # non-human identity posture
agent-bom db freshness                          # confirm vuln data is current before gating

The full grant templates, per-cloud permission catalogs, and the "why read-only is enough" rationale live in docs/CLOUD_CONNECT.md. agent-bom is a scanner, not a platform — it reads inventory and posture, normalizes it into one graph, and emits findings; it never writes, never reads secret contents, and never moves data out of your account.

Deploy In Your Boundary

agent-bom is designed for customer-controlled deployment: local CLI, Docker, GitHub Action, Helm, EKS, Postgres, and optional runtime proxy/gateway.

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

Production self-hosting starts with the deployment chooser:

• Deploy anywhere guide — one product, three tiers (laptop, your Kubernetes, hosted control plane)
• Deployment overview
• Helm chart
• One-apply EKS platform module — terraform apply the full control plane (cluster, Postgres, secrets, ingress)
• EKS reference installer
• Docker Hub image

For a zero-install AWS scan, deploy the CloudFormation one-click template — it runs a read-only agent-bom cloud aws scan in your account via CodeBuild, no local credentials handed to agent-bom.

There is no managed cloud offering in this repository today. Product lane boundaries are documented in docs/PRODUCT_BOUNDARIES.md.

Pre-commit Hook

Block secrets, PII, and vulnerable dependencies before they are committed. agent-bom ships consumer-facing pre-commit hooks; add them to your repository's .pre-commit-config.yaml:

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

pip install pre-commit && pre-commit install

pre-commit installs the agent-bom package into an isolated environment, so no separate install step is needed. See docs/DEPLOYMENT.md for details.

Trust Model

• Read-only discovery by default for cloud and local inventory.
• No mandatory telemetry.
• Credential values are redacted; credential environment names are preserved as evidence so exposure paths stay explainable.
• Findings can export as JSON, SARIF, CycloneDX, SPDX, OCSF, Markdown, HTML, and compliance evidence bundles.
• API and runtime paths are designed for tenant scope, auth boundaries, and audit evidence.
• OpenAPI artifacts are committed for SDK and client contract checks.

Security and release references:

• Threat model
• Pentest readiness
• Python API and control-plane client
• Go control-plane client
• Product metrics
• Release verification
• GitHub Action

Product Views

The docs site carries the deployment-oriented walkthroughs behind those screenshots:

• Dashboard and graph capture protocol
• Documentation site
• Deployment overview

Contributing

Contributions are welcome. Start with:

• CONTRIBUTING.md
• .agents/AGENTS.md
• Open issues

License: Apache-2.0.