agent-bom-scan

# agent-bom-scan — AI Supply Chain Vulnerability Scanner

Checks packages for CVEs, scans container images natively, verifies package
provenance via Sigstore, scans filesystems, and generates SBOMs.

## Install

```bash
pipx install agent-bom
agent-bom agents             # discover agents and scan dependencies
agent-bom check langchain==0.1.0  # check a specific package with version
agent-bom image nginx:1.25   # scan container image (native)
agent-bom fs .               # scan filesystem packages
agent-bom sbom .             # generate SBOM
agent-bom verify agent-bom   # verify Sigstore provenance
agent-bom where              # show all discovery paths
```

### As an MCP Server

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

## When to Use

- "check package" / "is this package safe"
- "scan image" / "scan container"
- "verify" / "check provenance"
- "is this safe" / "CVE lookup"
- "scan dependencies"
- "blast radius"
- "generate SBOM"

## Tools (8)

| Tool | Description |
|------|-------------|
| `check` | Check a package for CVEs (OSV, NVD, EPSS, KEV) |
| `scan` | Full discovery + vulnerability scan pipeline |
| `blast_radius` | Map CVE impact chain across agents, servers, credentials |
| `remediate` | Prioritized remediation plan for vulnerabilities |
| `verify` | Package integrity + SLSA provenance check |
| `diff` | Compare two scan reports (new/resolved/persistent) |
| `where` | Show MCP client config discovery paths |
| `inventory` | List discovered agents, servers, packages |

## Examples

```
# Check a package before installing
check(package="langchain", version="0.1.0", ecosystem="pypi")

# Map blast radius of a CVE
blast_radius(cve_id="CVE-2024-21538")

# Full scan
scan()

# Verify package provenance
verify(package="agent-bom")
```

## Agentic Workflows

Use tool chains, not isolated calls, when the user asks for a decision:

| User intent | Recommended sequence | Output |
|-------------|----------------------|--------|
| "Is this MCP safe to install?" | `registry_lookup` -> `check` -> `blast_radius` when a package/version is known | concise allow/warn/block recommendation with evidence |
| "Gate this PR" | `scan` with SARIF output and fail on high/critical findings | SARIF for code scanning plus non-zero gate result |
| "Audit my fleet inventory" | validate inventory -> `scan`/`agents` with JSON output -> `context_graph` | findings plus graph-ready JSON |
| "What changed since last run?" | current scan -> `diff` against prior JSON | new/resolved/persistent findings |
| "What should I fix first?" | `scan` -> `blast_radius` -> `remediate` plan | prioritized plan only; no file writes |

Pick output by consumer: SARIF for CI, JSON for automation/graph, HTML or
Markdown for human review, CycloneDX/SPDX for SBOM consumers.

For CLI gates, prefer:

```bash
agent-bom agents --format sarif --output agent-bom.sarif --fail-on-severity high
```

## Guardrails

- Show CVEs even when NVD analysis is pending or severity is `unknown` — a CVE ID is still a real finding.
- Treat `UNKNOWN` severity as unresolved, not benign — it means data is not yet available.
- Do not modify any files, install packages, or change system configuration.
- Only public package names and CVE IDs leave the machine for vulnerability database lookups.
- Ask before scanning paths outside the user's home directory.

## Privacy & Data Handling

```bash
# Step 1: Install
pip install agent-bom

# Step 2: Review redaction logic BEFORE scanning
# sanitize_env_vars() replaces ALL env var values with ***REDACTED***
# BEFORE any config data is processed or stored:
# https://github.com/msaad00/agent-bom/blob/main/src/agent_bom/security.py#L159

# Step 3: Verify package provenance (Sigstore)
agent-bom verify agent-bom

# Step 4: Only then run scans
agent-bom agents
```

## Verification

- **Source**: [github.com/msaad00/agent-bom](https://github.com/msaad00/agent-bom) (Apache-2.0)
- **Sigstore signed**: `agent-bom verify agent-bom@0.88.5`
- **7,100+ tests** with CodeQL + OpenSSF Scorecard
- **No telemetry**: Zero tracking, zero analytics