Agent Bom

Open security scanner and self-hosted control plane for AI, MCP, and cloud infrastructure. Headless agent primitives and human cockpit surfaces over one shared evidence model.

Docs · First Run · Self-host · GitHub Action · Docker · Changelog

What It Is

agent-bom scans AI infrastructure across local projects, agent fleets, and cloud estates (AWS, Azure, GCP, Snowflake), and builds one AI BOM of agents, MCP servers, tools, packages, credential references, non-human identities, models, datasets, and runtime. Every source converges into a unified Finding model and a unified ContextGraph, so blast radius, multi-hop exposure paths, and exposure scoring all read from the same evidence. That evidence is reachable through CLI/CI, a REST API, MCP tools, and a self-hosted dashboard; runtime proxy/gateway enforcement is optional and scoped to where it earns its cost.

How It Works

agent-bom is a read-only collection and evidence engine first: it discovers assets, matches and enriches risk signals, normalizes everything into one graph, then serves the same evidence through CLI, CI, API, UI, MCP, reports, and runtime controls.

Control-plane architecture — sources, backend, API, MCP, UI, and consumers

Scan pipeline — discover, match, enrich, evaluate, normalize, report

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 that server exposes, the credential environment names in reach, and the agents that can call it.

What It Scans

| Domain | Coverage | |---|---| | Supply chain | Package and OS risk across npm, PyPI, Maven, Go, Cargo, NuGet, Composer, RubyGems, conda, Swift, apk, deb, and rpm, with OSV/GHSA enrichment, transitive resolution, and dependency-confusion detection; Hex/Pub are advisory ecosystem identifiers, not first-class lockfile parsers yet | | Agents + MCP | MCP clients, servers, tools, transports, and trust posture with live introspection across 29 first-class client types | | AI models + datasets | Malicious-model detection via safe pickle-opcode disassembly (no deserialization), model/dataset cards, and target-scoped PII/PHI dataset-file scanning | | Cloud estate | Read-only, gated asset inventory and CIS posture across AWS, Azure, GCP, and Snowflake, plus AI/GPU provider posture | | Identity (NHI) | Non-human identity discovery (Okta/Entra, gated), credential-expiry posture, and access-review recertification | | LLM cost | Spend forecasting, budget runway, chargeback/allocation, and seasonal-aware spend-anomaly detection | | Containers + IaC | OCI images, Dockerfile, Terraform, CloudFormation, Helm, and Kubernetes; registry sweeps across ECR/ACR/GAR and agentless AWS EBS disk side-scan (read-only, snapshot-based) | | Secrets + runtime | Secret detection, MCP proxy/gateway, A2A and MCP auth-posture checks, inline firewall enforcement, and redaction | | Compliance | Mapped governance frameworks plus ZIP evidence bundles for auditors |

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. The graph adds correlation overlays on the same base: AppSec findings organized around their application, 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.

Current Coverage Boundaries

agent-bom is strongest today as a read-only CSPM/CIS, vuln/SCA, compliance, runtime-policy, and graph-posture product. Connected account scans can run on a schedule, so new or removed assets are picked up at the next scan and graph history can show appeared/removed evidence. It is not yet an event-streaming CDR product: CloudTrail/EventBridge, Azure Activity Log/Event Grid, and GCP Audit Log/Pub/Sub ingestion are roadmap work.

For DSPM, Snowflake has the deepest current support because agent-bom can read warehouse metadata, grants, tags, lineage, and governance activity visible to the configured role. Other cloud data-store sensitivity is posture and metadata based until classifier-backed content inspection, provider DLP/Macie wrapping, and object/table/column-level access mapping land.

Product Map

Use this map when you are deciding where to start. Every lane writes into the same Finding and ContextGraph model; the difference is the entry point, credential boundary, and operator surface.

| Need | Surface | First action | Auth / data boundary | Main artifact | |---|---|---|---|---| | Scan a repo, image, or local agent config | CLI / CI | agent-bom agents -p . | local files only unless an opt-in connector is enabled | JSON, SARIF, SBOM, HTML | | Connect cloud and selected data-estate evidence | Cloud and warehouse connectors | agent-bom connect aws then agent-bom cloud scan | read-only provider credentials; no secret values read or stored | cloud assets, CIS findings, Snowflake governance evidence, graph edges | | Review posture as a team | API + dashboard | pip install 'agent-bom[ui]' && agent-bom serve | API key/OIDC/SAML/SCIM where configured; tenant-scoped state | findings, graph, audit, compliance | | Give agents security tools | MCP server | agent-bom mcp server | read-mostly tools; Shield writes require admin role, scope, and audit reason | strict MCP tool responses | | Govern runtime tool calls | Proxy / gateway | configure proxy or gateway policy | inline policy checks; redacted, auditable decisions | allow/warn/block audit trail | | Package evidence for security and audit | Reports / exports | agent-bom agents -p . -f html -o report.html | caller-controlled export path | SARIF, CycloneDX, SPDX, OCSF, compliance bundle |

See [docs/PRODUCTMAP.md](docs/PRODUCTMAP.md) for the longer workflow map, including backend choices, auth modes, and where each capability lives in the CLI, API, MCP server, dashboard, and deployment docs.

Product proof — dashboard, graph, and identity surfaces

Captured from the packaged UI with bundled demo scan data and seeded control-plane records — synthetic data where needed, but the real scan, graph, fleet, identity, audit, and gateway routes.

Capture rules and the full manifest live in [docs/CAPTURE.md](docs/CAPTURE.md) and [docs/images/product-screenshots.json](docs/images/product-screenshots.json).

First Run

pip install agent-bom
agent-bom quickstart --run --offline    # write sample, scan, seed gateway policy, populate the cockpit
agent-bom agents -p . -f html -o agent-bom-report.html   # a real local scan

The demo uses bundled advisory-backed OSV/GHSA ranges against intentionally vulnerable sample packages, producing graph-ready inventory without touching your source tree. See [docs/FIRSTRUN.md](docs/FIRSTRUN.md) for the guided path from CLI output to the dashboard, and [docs/CAPTURE.md](docs/CAPTURE.md) to reproduce the dashboard screenshots from a clean local control-plane store.

Start Here

| Goal | Command | |---|---| | Local agent and MCP inventory | agent-bom agents | | Repo and lockfile scan | agent-bom agents -p . | | Connect a cloud (read-only) | agent-bom connect aws | | Cloud estate scan | agent-bom cloud scan | | Multi-hop exposure paths | agent-bom graph | | Report (HTML/SARIF/SBOM) | agent-bom agents -p . -f html -o report.html | | LLM cost forecast | agent-bom cost forecast | | Non-human identity posture | agent-bom identity credential-expiry | | Advisory remediation plan | agent-bom remediate -p . | | Gated-capability readiness | agent-bom capabilities | | CI gate | uses: msaad00/agent-bom@v0.89.2 | | Local API and dashboard | pip install 'agent-bom[ui]' && agent-bom serve |

The base wheel is the scanner and CLI path; optional runtime surfaces fail fast with install hints when their extras are missing. [PROJECTSTRUCTURE.md](PROJECTSTRUCTURE.md) is the repo map, [docs/STARTHERE.md](docs/STARTHERE.md) routes by role, and [docs/CLIMAP.md](docs/CLIMAP.md) groups every command by domain.

Connect a Cloud (Read-Only Auth)

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, and no data leaves your account. Each connector is opt-in and default-off behind a per-provider env flag; with the flag unset, agent-bom does zero cloud network I/O. agent-bom connect aws | azure | gcp | snowflake prints the exact read-only grant, the opt-in env var, and whether local credentials are detectable — without any network I/O until you opt in.

| Cloud | Read-only grant | Keyless / token auth | Enable | Scan | |---|---|---|---|---| | AWS | SecurityAudit managed policy | profile / SSO / instance role (boto3 chain) | AGENT_BOM_AWS_INVENTORY=1 | agent-bom cloud aws | | Azure | Reader (+ Security Reader) | az login / managed identity / cert SP | AGENT_BOM_AZURE_INVENTORY=1 | agent-bom cloud azure | | GCP | impersonated read-only service account | ADC / gcloud / workload identity | AGENT_BOM_GCP_INVENTORY=1 | agent-bom cloud gcp | | Snowflake | ABOM_READONLY role + key-pair user | RSA key-pair JWT (no password) | — | agent-bom agents --snowflake |

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

# Run every configured cloud at once (read-only, auto-detects what is connected):
agent-bom cloud scan --fail-on-severity high

AWS, Azure, GCP, and Snowflake setup, the full grant templates, per-cloud permission catalogs, and the "why read-only is enough" rationale live in [docs/CLOUDCONNECT.md](docs/CLOUDCONNECT.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 built for customer-controlled deployment across three tiers of one product: a laptop CLI, your own Kubernetes, or a hosted control plane you run.

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

• [Deploy anywhere guide](docs/DEPLOY_PLATFORM.md) — laptop, your Kubernetes, or hosted control plane
• [Helm chart](deploy/helm/agent-bom) and [one-apply EKS platform module](deploy/terraform/platform-eks)
• Docker Hub image
• [CloudFormation one-click](deploy/cloudformation) — a read-only cloud aws scan via CodeBuild, no local credentials handed to agent-bom

There is no managed cloud offering in this repository; lane boundaries are documented in [docs/PRODUCTBOUNDARIES.md](docs/PRODUCTBOUNDARIES.md).

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 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 client contract checks.

References: [Threat model](docs/THREATMODEL.md) · [Pentest readiness](docs/PENTESTREADINESS.md) · [Python client](docs/PYTHONAPI.md) · [Go client](sdks/go/README.md) · [Release verification](docs/RELEASEVERIFICATION.md)

Surfaces

| Surface | Primary user | Current boundary | |---|---|---| | CLI / CI | developers and release gates | local scans, SARIF/SBOM/HTML/JSON, deterministic exit codes | | REST API | control-plane integrations | scans, bulk findings, dataset versions, evaluation runs, graph evidence, audit, runtime summaries | | MCP tools | agents and assistants | strict arguments, read-mostly security queries, exposure paths, deploy decisions, audited Shield actions | | Dashboard | security teams and operators | inventory, findings, graph cockpit, compliance, evidence, runtime posture | | Runtime proxy/gateway | runtime operators | scoped MCP traffic inspection, policy decisions, redacted audit evidence | | Python / TypeScript clients | services and agent runtimes | typed helpers for stable REST endpoints |

MCP server mode advertises 70 MCP tools, 6 resources, and 6 workflow prompts. Most tools are read-only; Shield and identity write actions fail closed unless the MCP request is authenticated with AGENT_BOM_MCP_OPERATOR_TOKEN and the tool call includes the matching admin role, write scope, and audit reason. CLI scan commands run local scan pipelines today and share lower scanner and discovery libraries with the API, but they are not API wrappers yet. MCP registry presence is tracked through the committed Smithery manifest and other registry metadata; install and liveness checks live in the integration docs, not this front door.

Contributing

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

License: Apache-2.0.

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: msaad00
• Source: msaad00/agent-bom
• License: Apache-2.0
• Homepage: https://pypi.org/project/agent-bom/

Install and usage instructions live in the source repository linked above.