agent-bom

CVE-2025-1234  (CRITICAL · CVSS 9.8 · CISA KEV)
  |── better-sqlite3@9.0.0  (npm)
       |── sqlite-mcp  (MCP Server · unverified · root)
            |── Cursor IDE  (Agent · 4 servers · 12 tools)
            |── ANTHROPIC_KEY, DB_URL, AWS_SECRET  (Credentials exposed)
            |── query_db, read_file, write_file, run_shell  (Tools at risk)

 Fix: upgrade better-sqlite3 → 11.7.0

agent-bom maps the blast radius: CVE → package → MCP server → AI agent → credentials → tools.

Package risk is only the start. agent-bom maps what it can reach across MCP servers, agents, credentials, tools, and runtime context. CWE-aware impact classification keeps a DoS from being reported like credential compromise.

agent-bom is now a real released product surface, not just a research repo: installable from PyPI, publishable through Docker, usable in GitHub Actions, deployable as an authenticated API and remote MCP service, and validated end to end through CLI, reports, API, dashboard, and policy gates.

For the canonical product brief and verified repo-derived metrics, see docs/PRODUCT_BRIEF.md and docs/PRODUCT_METRICS.md.

The GIF uses the built-in curated sample environment so the output stays reproducible across releases. For real scans, run agent-bom agents on your machine or agent-bom agents -p . in a project.

Quick start

pip install agent-bom                  # Standard CLI install
# pipx install agent-bom               # Isolated global install
# uvx agent-bom --help                 # Ephemeral run without installing

agent-bom agents                              # Discover + scan local AI agents and MCP servers
agent-bom agents -p .                         # Scan project lockfiles/manifests plus agent/MCP context
agent-bom mesh --project .                    # Show the live agent / MCP topology
agent-bom skills scan .                       # Scan CLAUDE.md, AGENTS.md, .cursorrules, skills/*
agent-bom check flask@2.0.0 --ecosystem pypi  # Pre-install CVE gate
agent-bom image nginx:latest                  # Container image scan
agent-bom iac Dockerfile k8s/ infra/main.tf   # IaC scan across one or more paths

agent-bom cloud aws                     # Cloud AI posture + CIS benchmarks
agent-bom agents -f cyclonedx -o bom.json  # AI BOM / SBOM export
agent-bom graph report.json                # Blast radius graph / graph HTML inputs
agent-bom proxy "npx @mcp/server-fs /ws"   # MCP security proxy
agent-bom secrets src/                  # Hardcoded secrets + PII
agent-bom verify requests@2.33.0        # Package integrity verification
agent-bom serve                         # API + Next.js dashboard

Why teams use it

• MCP-aware blast radius instead of flat package CVE lists
• AI-focused scanning across agents, instruction files, skills, runtime proxy traffic, and cloud AI surfaces
• Project lockfile and manifest inventory with direct/transitive dependency visibility in CLI and JSON output
• Model and weight supply-chain checks with signed-artifact detection, HuggingFace provenance, and hash-verification visibility in CLI and JSON output
• Real operator outputs: SARIF, CycloneDX, HTML, graphs, badges, JSON, API, dashboard, and MCP tools
• Works as local CLI, CI gate, authenticated remote service, and enterprise deployment base

Use it by environment

Update and release hygiene

• Releases are signed and published from tagged CI, not local ad hoc steps.
• Dependency updates are expected to carry release-note context when they are major or behavior-affecting.
• Remote package, API, and MCP deployment surfaces should all report the same version and health state after release.
• Automated freshness checks watch for deployment drift so stale Railway or registry surfaces do not go unnoticed.
• The repo monitors both JavaScript surfaces (ui/ and sdks/typescript/) with daily Dependabot, npm audit, and CI guards that fail if tracked or published source maps appear unexpectedly.

Use agent-bom itself as an MCP tool surface:

agent-bom mcp server

That lets Claude Desktop, Claude Code, Cortex CoCo, Cursor, Windsurf, and other MCP-capable clients call the scanner directly through the MCP server mode.

Claude Code

claude mcp add agent-bom -- uvx agent-bom mcp server

Cortex CoCo

Add to ~/.snowflake/cortex/mcp.json:

{
  "mcpServers": {
    "agent-bom": {
      "command": "uvx",
      "args": ["agent-bom", "mcp", "server"]
    }
  }
}

Runtime monitoring / proxy mode

Wrap a third-party MCP server with the proxy when you want runtime inspection instead of just scanning:

agent-bom proxy "npx @modelcontextprotocol/server-filesystem /workspace"

The proxy inspects MCP JSON-RPC traffic with drift, credential, argument, response, vector, rate, and sequence detectors before forwarding to the real server.

Guides:

• Major MCP client guides
• Claude Desktop / Claude Code
• Cortex CoCo / Cortex Code
• Codex CLI
• MCP server mode
• Runtime proxy and monitoring

How it works

flowchart LR
    DISCOVER["🔍 Discover\nMCP clients\nProjects · Images · Cloud"] --> SCAN["🛡️ Scan\nPackages · CVEs\nSecrets · IaC"]
    SCAN --> ANALYZE["📊 Analyze\nBlast radius\nCompliance · CWE impact"]
    ANALYZE --> OUTPUT["📤 Output\nCI/CD gates · SARIF · SBOM\nAPI · Dashboard · MCP tools"]
    DISCOVER -.-> PROTECT["🔒 Protect\nRuntime proxy\nShield SDK · policy"]

    style DISCOVER stroke:#58a6ff,stroke-width:2px
    style SCAN stroke:#f85149,stroke-width:2px
    style ANALYZE stroke:#d29922,stroke-width:2px
    style OUTPUT stroke:#3fb950,stroke-width:2px
    style PROTECT stroke:#f778ba,stroke-width:2px,stroke-dasharray: 5 5

Blast radius — what makes agent-bom different

flowchart LR
    CVE["🔴 CVE-2025-1234\nCRITICAL · CVSS 9.8\nCISA KEV · EPSS 94%"]
    PKG["📦 better-sqlite3\n@9.0.0"]
    SRV["🔧 sqlite-mcp\nMCP Server"]
    AGT["🤖 Cursor IDE\n4 servers · 12 tools"]
    CRED["🔑 ANTHROPIC_KEY\nDB_URL · AWS_SECRET"]

    CVE --> PKG --> SRV --> AGT --> CRED

    style CVE stroke:#f85149,stroke-width:2px
    style PKG stroke:#d29922,stroke-width:2px
    style SRV stroke:#58a6ff,stroke-width:2px
    style AGT stroke:#3fb950,stroke-width:2px
    style CRED stroke:#f85149,stroke-width:2px

Blast radius is CWE-aware: an RCE (CWE-94) shows full credential exposure, a DoS (CWE-400) does not. Impact categories: code-execution, credential-access, file-access, injection, ssrf, data-leak, availability, client-side.

Path to 1.0

agent-bom is already a serious OSS product. The path to 1.0 is focused, not vague:

• deepen scanner coverage so MCP-aware blast radius is paired with stronger lockfile and package-depth coverage
• harden enterprise deployment defaults across auth, tenant isolation, Helm, and remote service operation
• keep raising the MCP, runtime, and skills surfaces without letting CLI, API, dashboard, and report contracts drift
• preserve the open-core model while making the product operationally credible for real teams

That work is tracked in docs/ROADMAP.md.

Coverage at a glance

• Auto-detected MCP client configs across mainstream local agent surfaces, including Claude Desktop, Claude Code, Cursor, Windsurf, VS Code, Codex CLI, and Gemini CLI
• MCP servers, tools, transports, trust posture, and capability risk scoring
• Instruction files and skills: CLAUDE.md, AGENTS.md, .cursorrules, .windsurfrules, skills/*
• Deterministic skill bundle identity, trust analysis, and tool-poisoning detection

• Multiple language, OS, and agent package ecosystems
• OSV, NVD, GHSA, EPSS, and CISA KEV enrichment
• Blast radius mapping: CVE → package → MCP server → agent → credentials → tools
• CycloneDX 1.6 with ML BOM extensions, SPDX 3.0, VEX, SARIF, HTML, graph, JSON, and more

• Native OCI parser for images and running containers
• IaC coverage for Dockerfile, Terraform, CloudFormation, Helm, and Kubernetes manifests
• Cloud AI and infra discovery across AWS, Azure, GCP, Databricks, Snowflake, GPU/DCGM probes, and vector data stores
• Secrets and PII scanning across source, config, lockfiles, and environment-adjacent files

• Runtime protection engine plus a lighter MCP proxy path for inline JSON-RPC inspection
• Capability-aware risk, drift detection, credential redaction, and kill-switch controls
• Compliance mapping across OWASP, MITRE, NIST, ISO, SOC 2, CIS, CMMC, FedRAMP, PCI DSS, and the EU AI Act

Read-only. Agentless. No secrets leave your machine.

Runtime protection

MCP security proxy with inline detector chaining, PII redaction, and kill-switch controls:

agent-bom proxy "npx @mcp/server-filesystem /workspace"

Shield SDK — drop-in Python middleware:

from agent_bom.shield import Shield
shield = Shield(deep=True)
alerts = shield.check_tool_call("exec", {"command": "rm -rf /"})
safe = shield.redact(response_text)  # [REDACTED:OpenAI API Key]

Compliance and evidence

Every finding is tagged with mapped control coverage across 14 surfaced compliance frameworks, with MITRE ATT&CK Enterprise kept as separate threat-mapping context:

MITRE ATT&CK Enterprise remains available as separate threat-mapping context rather than part of the 14-framework compliance surface.

Install & deploy

pip install agent-bom                        # CLI
docker run --rm agentbom/agent-bom agents    # Docker

CI/CD in 60 seconds

Use the GitHub Action when you want a fast CI gate: one step, one gate, SARIF in the Security tab, and a clean exit code for CI.

Repo + MCP + instruction files

- uses: msaad00/agent-bom@v0.75.15
  with:
    scan-type: scan
    severity-threshold: high
    upload-sarif: true
    enrich: true
    fail-on-kev: true

Container image gate

- uses: msaad00/agent-bom@v0.75.15
  with:
    scan-type: image
    scan-ref: ghcr.io/acme/agent-runtime:sha-abcdef
    severity-threshold: critical

IaC gate

- uses: msaad00/agent-bom@v0.75.15
  with:
    scan-type: iac
    iac: Dockerfile,k8s/,infra/main.tf
    severity-threshold: high

Air-gapped / pre-synced CI

- uses: msaad00/agent-bom@v0.75.15
  with:
    auto-update-db: false
    enrich: false

- uses: msaad00/agent-bom@v0.75.15
  with:
    scan-type: scan
    severity-threshold: high
    upload-sarif: true
    enrich: true
    fail-on-kev: true

Enterprise rollout

• Developer endpoints: run agent-bom agents locally or via MDM for workstation inventory and posture.
• CI/CD: use the GitHub Action for PR gates, SARIF upload, image gates, and IaC checks.
• Central security team: deploy agent-bom serve for fleet ingestion, posture, and audit exports.
• Air-gapped / isolated: run the Docker image with --offline and auto-update-db: false using a pre-synced local DB.

See docs/ENTERPRISE_DEPLOYMENT.md for rollout patterns, auth models, and storage backends.

JSON, SARIF, CycloneDX 1.6 (with ML BOM), SPDX 3.0, HTML, Graph JSON, Graph HTML, GraphML, Neo4j Cypher, JUnit XML, CSV, Markdown, Mermaid, SVG, Prometheus, Badge, OCSF, Attack Flow, plain text.

MCP server

36 security tools available inside any MCP-compatible AI assistant:

{
  "mcpServers": {
    "agent-bom": {
      "command": "uvx",
      "args": ["agent-bom", "mcp", "server"]
    }
  }
}

Also on Glama, Smithery, MCP Registry, and OpenClaw.

Trust & transparency

No source code, config contents, or credential values are sent. No telemetry or analytics. Sigstore-signed releases. See SECURITY_ARCHITECTURE.md and PERMISSIONS.md for the full trust model.

Contributing

git clone https://github.com/msaad00/agent-bom.git && cd agent-bom
pip install -e ".[dev]"
pytest && ruff check src/

See CONTRIBUTING.md | SECURITY.md | CODE_OF_CONDUCT.md

Apache 2.0 — LICENSE