Agent Bom

agent-bom — AI Supply Chain Security Scanner

What it does

agent-bom is a read-only security scanner for AI agent and MCP server configurations. It discovers MCP client configs on your system, extracts package dependencies, and queries public vulnerability databases for known CVEs. It then maps blast radius (which credentials and tools are exposed if a package is compromised), generates SBOMs, and evaluates security policies.

Key capabilities:

• CVE scanning via OSV.dev (no API key required)
• NVD CVSS v4 enrichment, EPSS exploit probability, CISA KEV status
• Blast radius mapping: CVE → package → server → agent → credentials/tools
• SBOM generation: CycloneDX 1.6, SPDX 3.0, SARIF 2.1.0
• Policy-as-code engine for CI/CD security gates
• Threat intelligence registry of 427+ known MCP servers with risk metadata
• Docker image scanning (requires docker binary, optional)

Scope boundaries

agent-bom operates within a strictly bounded scope. Every file path, network endpoint, and data element is enumerated below and in the manifest metadata above.

Config files read (exhaustive list)

The following paths are the only files agent-bom reads. Each is a JSON/YAML MCP client config. If a file does not exist, it is silently skipped. No directory traversal, no glob patterns, no recursive walks.

Project-level configs (current working directory only): .mcp.json, mcp.json, .cursor/mcp.json, .vscode/mcp.json

Docker Compose files (current working directory only): docker-compose.yml, docker-compose.yaml, compose.yml, compose.yaml

Total: 31 specific file paths. All enumerated in metadata.openclaw.file_reads above.

What agent-bom extracts from these files

• Server names, commands, arguments
• Environment variable names only (values are never read, stored, or logged)
• Credential-like env var names are flagged: *KEY*, *TOKEN*, *SECRET*, *PASSWORD*, *CREDENTIAL*, *AUTH*
• Standard system vars (PATH, HOME, LANG) are excluded

What agent-bom CANNOT access

• Arbitrary files — only the 27 paths listed above
• Environment variable values — only names are extracted
• Private networks or internal APIs — all network calls go to public endpoints only
• Other processes — no IPC, no signals, no process inspection
• System configuration — no /etc, no system services, no kernel parameters
• Browser data — no cookies, history, bookmarks, or stored passwords
• SSH keys, GPG keys, or keychains — never accessed
• User documents — no access to Desktop, Documents, Downloads, or media files

Network endpoints (exhaustive list)

All network calls are read-only GET/POST to public vulnerability databases. Only package names and versions are sent. All enumerated in metadata.openclaw.network_endpoints above.

No telemetry, analytics, or tracking. Zero network calls unless scanning for vulnerabilities. Network calls can be completely disabled with --no-scan (inventory-only mode).

Data flow

[Local config files]  →  read server name, command, args, env var NAMES
                          ↓
[Package names+versions]  →  sent to OSV.dev, NVD, EPSS, KEV, npm, PyPI
                          ↓
[CVE results]  →  returned to local process, written to stdout or --output file

• Sent to APIs: package name + version only (e.g., express@4.17.1)
• Returned from APIs: CVE IDs, severity scores, advisory URLs
• Never sent: file paths, config contents, env var values, scan results, hostnames, IP addresses

User control over scope

Users can restrict or bypass auto-discovery entirely:

Recommended first run: agent-bom scan --dry-run to preview the access plan before any actual scanning.

Environment variables

agent-bom itself optionally uses:

• NVD_API_KEY — higher NVD rate limits (optional, never logged or transmitted beyond NVD)

This is declared in metadata.openclaw.optional_env above. No env vars are required.

Installation

Recommended: pipx (isolated environment)

pipx install agent-bom

Alternative: pip

pip install agent-bom

Alternative: uv (fastest)

uv tool install agent-bom

Verify installation

agent-bom --version
# Should print: agent-bom 0.32.0

Verify integrity and provenance

# One-command verification — checks RECORD hashes, PyPI digest, PEP 740 attestation
agent-bom verify

# JSON output for automation
agent-bom verify --json

This checks:

1. Every installed file against its RECORD hash (detects post-install tampering)
2. The release exists on PyPI with valid SHA-256 digests
3. PEP 740 / Sigstore attestation exists (proves the release was built by GitHub Actions CI)
4. Metadata consistency (version, license, source repo match between local install and PyPI)

Verify source

• PyPI: https://pypi.org/project/agent-bom/
• Source: https://github.com/msaad00/agent-bom
• Sigstore signatures: Each release wheel and sdist is signed with Sigstore OIDC. Manual verify: cosign verify-blob dist/agent_bom-*.whl --bundle dist/agent_bom-*.whl.bundle

When to use

• Before installing a new MCP server — run a pre-install check
• To audit your current agent setup for vulnerabilities
• To generate compliance documentation (SBOM)
• To understand blast radius of a specific CVE
• To enforce security policy gates in CI/CD

Workflows

1. Quick scan (auto-discover local MCP configs)

agent-bom scan --format json

Discovers all configured MCP clients on your system, extracts package dependencies, and queries OSV.dev for known CVEs. No API keys required.

2. Scan with enrichment (NVD CVSS + EPSS + CISA KEV)

agent-bom scan --enrich --format json

Adds CVSS v4 scores from NVD, exploit probability from EPSS, and CISA Known Exploited Vulnerability status to each finding. Set NVD_API_KEY for higher NVD rate limits (optional).

3. Check a specific MCP server before installing

agent-bom check <package-name>@<version> -e <ecosystem>

Example:

agent-bom check @modelcontextprotocol/server-filesystem@2025.1.14 -e npm

4. Generate SBOM

agent-bom scan --format cyclonedx --output sbom.json

Supported formats: cyclonedx (CycloneDX 1.6), spdx (SPDX 3.0), sarif (SARIF 2.1.0)

5. Scan Docker image (requires docker binary)

agent-bom scan --image nginx:1.25 --format json

Uses Grype/Syft if available, otherwise falls back to Docker CLI for package extraction. This workflow requires the docker binary to be installed.

6. Evaluate security policy

agent-bom scan --policy policy.json --enrich

7. Generate remediation plan

agent-bom scan --enrich --remediate remediation.md

Output interpretation

• critical/high severity: Immediate action required — upgrade or remove package
• blast_radii: Shows CVE → package → server → agent → credentials/tools chain
• exposed_credentials: Env var names at risk if CVE is exploited (values are never shown)
• risk_score: 0-10 contextual score based on severity + reach + credential exposure
• owasp_tags/atlas_tags/nist_ai_rmf_tags: OWASP LLM Top 10, MITRE ATLAS, NIST AI RMF mappings

Guardrails

• Read-only: agent-bom never writes, modifies, or deletes any file on your system
• No execution: It never runs MCP servers, spawns processes, or executes discovered commands
• No credential access: Only env var names appear in reports — values are never read
• No data exfiltration: Scan results stay local. Only package names/versions are sent to public APIs
• No persistence: No background processes, daemons, cron jobs, or system modifications
• No privilege escalation: Runs as current user, no sudo/root required
• No telemetry: No analytics, crash reports, or usage tracking of any kind
• Deterministic: Same input always produces the same output (modulo upstream API data freshness)
• Auditable: Full source code at https://github.com/msaad00/agent-bom (Apache-2.0 license)
• Signed releases: Every PyPI release is signed with Sigstore OIDC
• CI-verified: Every commit passes 1000+ automated tests including security scanning
• Docker non-root: All container images run as unprivileged abom user (USER directive in every Dockerfile)

Verification & provenance

You can independently verify every claim in this manifest:

Source code evidence

The following are actual code excerpts from the agent-bom source that enforce the claims above. These can be verified at the linked source files.

Credential names only — values never read (models.py:222-233):

@property
def credential_names(self) -> list[str]:
    """Return names of env vars that look like credentials."""
    sensitive_patterns = [
        "key", "token", "secret", "password", "credential",
        "api_key", "apikey", "auth", "private",
        "connection", "conn_str", "database_url", "db_url",
    ]
    return [
        k for k in self.env  # self.env is dict of {name: value} but only KEYS are returned
        if any(pat in k.lower() for pat in sensitive_patterns)
    ]

Config parsing extracts structure only (discovery/init.py:160-167):

def parse_mcp_config(config_data: dict, config_path: str) -> list[MCPServer]:
    """Parse MCP server definitions from a config file.
    Supports multiple config formats:
    - Standard: {"mcpServers": {"name": {"command": ..., "args": [...]}}}
    - VS Code:  {"servers": {"name": {"type": "stdio", "command": ...}}}
    """
    # Only extracts: server name, command, args, env var keys

All file reads are enumerated — no dynamic paths (discovery/init.py:30-107):

CONFIG_LOCATIONS: dict[AgentType, dict[str, list[str]]] = {
    AgentType.CLAUDE_DESKTOP: {
        "Darwin": ["~/Library/Application Support/Claude/claude_desktop_config.json"],
        "Linux": ["~/.config/Claude/claude_desktop_config.json"],
    },
    # ... 10 more clients, each with hardcoded paths
}
# No dynamic path construction, no user input in paths, no glob patterns

Binary behavior audit

The simplest way to verify the installed binary matches the published source:

# One-command integrity + provenance check
agent-bom verify

# Preview what files and APIs would be accessed (no actual reads)
agent-bom scan --dry-run

agent-bom verify checks:

1. Every installed file against its RECORD hash (detects post-install tampering)
2. The release exists on PyPI with valid SHA-256 digests
3. PEP 740 / Sigstore attestation (proves CI built this release from the source repo)
4. Metadata consistency (version, license, source repo match)

For maximum assurance, install from source instead of PyPI:

git clone https://github.com/msaad00/agent-bom && cd agent-bom
pip install -e .
agent-bom scan --dry-run

The --dry-run output includes a Data Audit section that shows:

• Exactly which data elements are extracted from config files (server names, commands, env var NAMES only)
• Exactly what data is sent to each API (package name + version only)
• What is explicitly NOT sent (file paths, config contents, env var values, hostnames)

Runtime dependencies