agent-bom-scan

intent

scan packages, container images, MCP configs, and agentic infrastructure for known CVEs, supply chain compromise, and blast radius impact. use this when the user asks to "check package", "scan image", "verify provenance", "is this safe", "scan dependencies", "CVE lookup", "blast radius", or "generate SBOM". runs fully local, requires zero credentials, and never exfiltrates config file contents or scan results.

inputs

required

• python 3.11 or higher
• installation: pipx install agent-bom, or pip install agent-bom, or docker run ghcr.io/msaad00/agent-bom:0.89.2

optional binaries (enhance scanning, not required)

• semgrep: source code static analysis
• kubectl: kubernetes manifest scanning (if present)

external network endpoints (all public, no auth required)

• https://api.osv.dev/v1 (OSV vulnerability database, batch CVE lookups)
• https://services.nvd.nist.gov/rest/json/cves/2.0 (NVD CVSS v4 enrichment, optional NVD API key via AGENT_BOM_NVD_API_KEY env var increases rate limit from 5 req/30sec to 50 req/30sec)
• https://api.first.org/data/v1/epss (EPSS exploit probability scores)
• https://api.github.com/advisories (GitHub Security Advisories supplemental lookup, optional GITHUB_TOKEN env var for higher rate limits)

config files read (agentic platform configs, MCP server definitions, no credentials extracted)

• claude desktop: ~/Library/Application Support/Claude/claude_desktop_config.json, ~/.config/Claude/claude_desktop_config.json
• claude code: ~/.claude/settings.json, ~/.claude.json
• cursor: ~/.cursor/mcp.json, ~/Library/Application Support/Cursor/User/globalStorage/cursor.mcp/mcp.json
• windsurf: ~/.windsurf/mcp.json
• cline: ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
• vs code copilot: ~/Library/Application Support/Code/User/mcp.json
• codex CLI: ~/.codex/config.toml
• gemini CLI: ~/.gemini/settings.json
• goose: ~/.config/goose/config.yaml
• continue: ~/.continue/config.json
• zed: ~/.config/zed/settings.json
• roo code: ~/Library/Application Support/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/cline_mcp_settings.json
• amazon Q: ~/Library/Application Support/Code/User/globalStorage/amazonwebservices.amazon-q-vscode/mcp.json
• jetbrains AI: ~/Library/Application Support/JetBrains/*/mcp.json, ~/.config/github-copilot/intellij/mcp.json
• junie: ~/.junie/mcp/mcp.json
• github copilot CLI: ~/.copilot/mcp-config.json
• tabnine: ~/.tabnine/mcp_servers.json
• cortex code (snowflake): ~/.snowflake/cortex/mcp.json, ~/.snowflake/cortex/settings.json, ~/.snowflake/cortex/permissions.json, ~/.snowflake/cortex/hooks.json
• snowflake CLI: ~/.snowflake/connections.toml, ~/.snowflake/config.toml
• project configs: .mcp.json, .vscode/mcp.json, .cursor/mcp.json
• user-provided SBOM files: CycloneDX or SPDX JSON formats

no credentials required

• zero API keys required for basic operation
• zero env vars required for basic operation
• optional env vars (AGENT_BOM_NVD_API_KEY, GITHUB_TOKEN) are never auto-discovered, inferred, or transmitted
• credential policy: env var values are sanitized (replaced with REDACTED) before any config data is processed or stored; only structural data (server names, URLs, commands) passes through

procedure

1. install agent-bom (one-time setup)

   • input: system with python 3.11+, pip or pipx
   • run: pipx install agent-bom or pip install agent-bom
   • output: agent-bom CLI available in $PATH, version 0.89.2 or higher

2. verify package provenance (optional, recommended before first scan)

   • input: installed agent-bom package
   • run: agent-bom verify agent-bom
   • output: Sigstore validation result (pass/fail), confirms package integrity and SLSA provenance
   • note: if verification fails, stop and reinstall from official PyPI source

3. discover agents and MCP servers in environment

   • input: user's home directory and project directories
   • run: agent-bom agents to auto-discover, or agent-bom where to show all discovery paths
   • output: JSON or human-readable list of discovered agents, MCP servers, their package dependencies

4. check a specific package for CVEs

   • input: package name, version (optional), ecosystem (pypi/npm/go/rust/maven/etc., defaults to pypi)
   • run: agent-bom check langchain==0.1.0 or agent-bom check langchain
   • calls: OSV, NVD, EPSS, GitHub Advisories APIs with package name and version
   • output: vulnerability list with CVE ID, CVSS score, EPSS percentile, severity, CWE, references
   • note: shows CVEs even if NVD analysis is pending or severity is unknown; UNKNOWN severity is treated as unresolved, not benign

5. scan container image for vulnerabilities

   • input: container image name and tag (local or registry URL)
   • run: agent-bom image nginx:1.25
   • output: layer-by-layer package inventory, CVEs per layer, total risk summary
   • note: native scanning, no external scanner required, no docker daemon required if using containerd

6. scan filesystem for package vulnerabilities

   • input: filesystem path (defaults to current directory)
   • run: agent-bom fs . or agent-bom fs /path/to/scan
   • output: discovered packages (Python, Node, Go, Rust, Java, etc.), CVE matches
   • note: ask before scanning paths outside user's home directory

7. map blast radius of a CVE

   • input: CVE ID, or discovered agents/servers context
   • run: agent-bom blast_radius CVE-2024-21538 or agent-bom blast_radius (scans environment first)
   • output: impact chain showing which agents, servers, and credentials are exposed if CVE is exploited
   • note: requires prior scan or explicit CVE ID

8. generate or scan SBOM

   • input: filesystem path or existing SBOM file (CycloneDX/SPDX JSON)
   • run: agent-bom sbom . to generate, or agent-bom check --sbom=/path/to/sbom.json to scan existing
   • output: CycloneDX or SPDX JSON SBOM, or vulnerability report against SBOM components

9. generate remediation plan

   • input: scan results (JSON format) or run scan inline
   • run: agent-bom remediate (after scan) or agent-bom scan --format json | agent-bom remediate
   • output: prioritized list of fixes ordered by CVSS + EPSS, includes upgrade paths and available patches
   • note: no file writes, plan only

10. diff two scan reports

    • input: prior JSON scan report, current scan report (file path or inline)
    • run: agent-bom diff prior.json current.json
    • output: new vulnerabilities, resolved vulnerabilities, persistent vulnerabilities, version changes

11. gate a CI/CD pipeline

    • input: scan results in SARIF format, severity threshold (high/critical)
    • run: agent-bom agents --format sarif --output agent-bom.sarif --fail-on-severity high
    • output: SARIF file for code scanning integration, non-zero exit code if threshold breached
    • note: exit code 0 if all findings below threshold, non-zero if threshold exceeded

12. output in format of choice

    • input: scan results
    • run: add --format sarif|json|html|markdown|cyclonedx|spdx flag to any command
    • output: SARIF for CI/code scanning, JSON for automation/graphing, HTML/Markdown for human review, CycloneDX/SPDX for SBOM consumers

decision points

if user asks "is this safe to install":

• run agent-bom check <package> <version> first (does a quick CVE check)
• if CVEs found and severity high/critical, recommend block
• if CVEs found but low/medium and no exploits in KEV, recommend conditional (review before install)
• if no CVEs found, run blast_radius to check if this package is trusted upstream (no compromise in dependency chain)
• output: concise allow/warn/block recommendation with evidence (CVE list, EPSS scores, KEV presence)

if user asks "scan my fleet" or "audit all agents":

• run agent-bom agents first to discover all MCP servers and agents in the environment
• then run agent-bom scan --format json --output inventory.json to scan all discovered dependencies
• output: JSON report with agents, servers, packages, CVE findings
• if user wants graph-ready output for visualization, use --format json and pass to graphing tool

if NVD API returns rate limit error:

• fallback to OSV and GitHub Advisories (both have higher default limits, or provide GITHUB_TOKEN)
• if OSV also rate-limited, cache results locally (agent-bom caches automatically)
• if user has NVD API key, set AGENT_BOM_NVD_API_KEY env var and retry
• note: rate limits reset after 30 seconds (NVD) or 1 hour (GitHub)

if network endpoint is unreachable:

• attempt retry with exponential backoff (max 3 retries over 10 seconds)
• if all retries fail and scan is "check" only (not gate), report findings from OSV/local cache only
• if scan is gating a CI/CD pipeline (fail-on-severity flag set) and network unavailable, fail closed (non-zero exit) to prevent bypassing
• display warning that some findings may be incomplete due to network unavailability

if scan finds UNKNOWN severity CVEs:

• treat as unresolved, not benign
• display the CVE ID and available metadata (references, CWE, EPSS if present)
• recommend reviewing references until NVD analysis is published
• do not suppress from output

if user provides path outside home directory:

• ask for explicit confirmation before scanning
• example: "scan filesystem at /etc/? this is outside your home directory. confirm [y/n]"

if Sigstore verification fails:

• stop execution, do not scan
• display verification error and official source URL
• user must reinstall from official PyPI before proceeding

if user asks to modify files or install packages:

• always refuse
• clarify that agent-bom is read-only, scanning and reporting only
• recommend using output (remediation plan, SBOM) as input to a separate automation tool

output contract

data format by use case:

• CVE lookups (check, scan): JSON with CVE ID, CVSS v3.1 + v4.0 scores, EPSS percentile, severity, CWE, references, is-in-KEV boolean
• blast radius: JSON or Markdown graph showing agents -> servers -> credentials -> CVE impact path
• SBOM: CycloneDX or SPDX JSON, includes package name, version, hash (purl), component type, license
• remediation plan: JSON with priority score (CVSS + EPSS weighted), upgrade version, available patches, effort estimate
• scan report: JSON with discovery timestamp, total packages, total CVEs found, breakdowns by severity, per-package details
• CI/CD gate: SARIF (Static Analysis Results Format) for code scanning integrations, includes file location, line, CVE ID, severity
• human review: HTML (interactive dashboard) or Markdown (static report)

file locations:

• output files written to current directory or specified via --output flag
• no files written to user home directory or config directories
• cache stored in ~/.cache/agent-bom/ (metadata only, never config contents or results)

success indicators:

• exit code 0: scan completed, findings reported, severity threshold not breached (if gating)
• exit code non-zero: scan completed but threshold breached, or error occurred (network, invalid input, verification failed)

outcome signal

• user knows it worked if:

  • command completes and outputs JSON/SARIF/HTML/Markdown with CVE findings (or "no CVEs found" if clean)
  • if gating: exit code 0 (all findings below threshold) or non-zero (threshold breached or error)
  • if verifying: "Sigstore verification passed" message, exit code 0
  • if discovering: list of agents, servers, MCP configs with file paths shown
  • remediation plan includes upgrade versions and effort estimates
  • blast radius shows connected agents/servers/credentials in human-readable graph or JSON

• user knows something failed if:

  • "network error" or "timeout" message displayed; retry with --retry-attempts 5 flag
  • "rate limit exceeded" message; wait 30 seconds (NVD) or 1 hour (GitHub) or set API key env var
  • "Sigstore verification failed" message, exit code non-zero; reinstall from official source
  • "permission denied" reading config file; check file permissions, or exclude path with --exclude flag
  • no findings reported despite user expectation; confirm scan ran with verbose output --verbose flag