agent-bom

Who It's For

• AppSec / GRC — SARIF, compliance packs, and audit-ready exports from one scan.

• Platform / SRE — fleet sync, Helm deploy, CI gates, SBOM — no separate scanner stack.

• Agent builders — MCP inventory, Shield SDK, optional runtime proxy or gateway enforcement.

• Security engineers — findings queue, attack-path drilldown, blast-radius context in CLI, API, and UI.

MCP server mode

• Advertises 75 MCP tools, 6 resources, and 8 workflow prompts.

• Registry metadata lives in the committed Smithery manifest and Glama listing; install and liveness checks are in the integration docs.

Related MCP server: agent-audit

Architecture & how it works

One package, full stack: a React / Next.js cockpit and every headless caller hit the same FastAPI control plane, behind one middleware seam, over the same scan pipeline and stores. Everything normalizes into one Finding and one ContextGraph, so posture, blast radius, and enforcement read from a single evidence set. Deeper module and surface detail lives in docs/ARCHITECTURE.md.

The stack — UI ⇄ API + middleware ⇄ pipeline/enrichment ⇄ stores:

flowchart TB
    UI["React / Next.js UI<br/>exec single-pane · engineer drill"]
    HL["Headless<br/>CLI · MCP server · agents / CI"]
    MW["Middleware — one seam for every caller<br/>auth · tenant scope · RLS · rate-limit · audit"]
    API["FastAPI + uvicorn control plane<br/>REST API · MCP tools"]
    PIPE["Scan pipeline + scanners<br/>discover · OSV / advisories · reachability · cloud / CIS · IaC"]
    ENR["Enrichment<br/>NVD CVSS · EPSS · CISA KEV · distro advisories"]
    ST["Stores<br/>SQLite / Postgres + correlated graph store"]

    UI --> MW
    HL --> MW
    MW --> API
    API --> PIPE --> ENR --> ST
    API --> ST

The workflow — one read-only pipeline from source to answer:

flowchart LR
    C["connect<br/>read-only · brokered"] --> D["discover<br/>estate · agents · MCP"]
    D --> S["scan<br/>OSV · advisories · CIS · IaC"]
    S --> E["enrich<br/>CVSS · EPSS · KEV · reachability"]
    E --> R["correlate<br/>finding → asset → identity → config"]
    R --> G["graph<br/>blast radius · attack paths"]
    G --> X["serve<br/>exec read + engineer drill"]

Every stage is read-only and agentless; the dashboard shows live per-stage status rather than a black box.

• Next.js 16 · React 19 · Tailwind 4 (ui/), built with next build.

• Two altitudes in one pane: an exec single-pane read (posture, top risks, compliance evidence) that drills to engineer detail (reachability, path, fix).

• Inventory, findings, graph, compliance, and runtime views all render from the same API — no privileged "UI-only" data path.

• FastAPI + uvicorn, pure Python 3.11+ end to end (src/agent_bom/api/server.py).

• The scan pipeline (src/agent_bom/api/pipeline.py, ScanPipeline) runs on a bounded ThreadPoolExecutor — heavy scan/DB work is offloaded off the event loop so reads stay responsive.

• Stores scale without a rewrite: SQLite (default / single node) → Postgres (multi-replica), plus a correlated graph store.

• Headless parity: the MCP server and CLI expose the same evidence to agents and CI, not just the UI.

• Scanners emit raw findings (src/agent_bom/scanners/ — OSV batch, GHSA, distro and vendor advisories); src/agent_bom/enrichment.py layers NVD CVSS · EPSS · CISA KEV and distro advisory data on top.

• AST reachability (src/agent_bom/reachability_cve.py) resolves whether a vulnerable symbol is actually reachable — ranking by exploitability, not just CVSS.

• The result feeds severity, exploitability, and blast-radius scoring.

• Confidence tiers and the NVD key model are covered in the Accuracy model section below.

• ContextGraph / UnifiedGraph (src/agent_bom/context_graph.py) fuses assets → identities → configs/misconfigs → findings → attack paths into one connected model.

• A vulnerable package links to the MCP server that loads it, the tools it exposes, reachable credential references, and the agents that can call it — a reachable blast radius, not an isolated CVE row.

• Estate-scale CONTAINS roll-up keeps it readable and sargable at scale; the full contract is in docs/graph/CONTRACT.md.

Auth & Connections

The honest model — connect once, then every action runs through the stored connection. There is never a per-action credential prompt and no "paste your laptop login" to run a scan or push a result.

• 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 (AWS, Azure, GCP, Snowflake) 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). Setup and the exact grant per provider live in docs/CLOUD_CONNECT.md; the enterprise auth surface is in docs/ENTERPRISE.md.

Auth, tenant isolation, and audit are enforced once in middleware for the UI, agents, and SDKs alike — there is no privileged backdoor.

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

• Scanner + control plane — read-only, self-hosted, over local projects, agent fleets, MCP runtimes, and cloud estates (AWS, Azure, GCP, Snowflake).

• ContextGraph — the unified evidence graph across CLI, API, UI, MCP tools, reports, and gateway decisions. Findings, assets, packages, cloud resources, identities, agents, MCP servers, credentials, and runtime decisions all normalize into it, so posture, blast radius, and enforcement read from one evidence set.

• Blast radius — the core idea: a vulnerable package links to the MCP server that loads it, the tools it exposes, reachable credential references, and the agents that can call it — not just a CVE row.

Coverage depth and honest boundaries: AI infrastructure scanning · product boundaries

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

Run It Anywhere

Two ladders: how you consume the shared evidence model, and where you run the control plane. You run it in your own boundary — no managed public SaaS in this repo yet.

Surfaces — one real command each:

• CLI / CI — agent-bom agents -p . (or the GitHub Action).

• Self-hosted platform — pip install 'agent-bom[ui]' && agent-bom serve — dashboard + API on one host.

• Headless — agent-bom api + agent-bom mcp server for agents and CI.

• Runtime proxy / gateway — agent-bom gateway serve — allow/warn/block audit trail.

• Reports / exports — agent-bom agents -p . -f sarif -o findings.sarif.

Deploy targets — where the control plane runs, 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.

Start Here

Every lane writes into the same Finding and ContextGraph model. Pick the entry point that matches your role; see docs/PRODUCT_MAP.md for all entry points, auth boundaries, and surface detail.

Full command map: docs/CLI_MAP.md · role routing: docs/START_HERE.md · repo layout: PROJECT_STRUCTURE.md

First Run

pip install agent-bom
agent-bom db update                      # populate ~/.agent-bom vuln DB before --offline scans
agent-bom quickstart --run --offline    # sample scan, gateway policy seed, dashboard data
agent-bom agents -p . -f html -o agent-bom-report.html

Run agent-bom db update before --offline image or package scans. Guided path: docs/FIRST_RUN.md · UI screenshots: docs/CAPTURE.md

Synthetic seeded evidence for docs proof, captured from the real Next.js routes with a visible Demo data — sample environment label — not a claim these entities came from a buyer environment. Regenerate from the UI package with npm run capture:product-proof (see docs/CAPTURE.md). CLI demo GIF: bash scripts/render_demo_gif.sh.

Cloud, Deploy, Trust

Cloud (read-only). Four connectors — AWS, Azure, GCP, Snowflake — are opt-in, agentless, and default-off. No secret values are read or stored. agent-bom connect <provider> prints the grant template and enable flag without network I/O until you opt in. Full intake map: docs/DATA_SOURCES.md

Snowflake auth defaults to browser SSO (externalbrowser); use SNOWFLAKE_AUTHENTICATOR=snowflake_jwt with SNOWFLAKE_PRIVATE_KEY_PATH for CI. agent-bom authenticates through the Python connector — no snowsql session needed. Setup and grants: docs/CLOUD_CONNECT.md

Deploy. Run in your own boundary — the Run It Anywhere ladders above cover Compose, Helm, EKS, CloudFormation, and the Snowflake SPCS native app. Full deploy guides: Deploy anywhere · Hosted POC · Helm · EKS module · CloudFormation · Snowflake native app · Docker Hub

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.