Quick Start¶

Install¶

pip install agent-bom

Scan your local AI environment¶

agent-bom scan .

This auto-discovers local MCP clients and AI agent configs, extracts configured servers and packages, and scans for CVEs.

Scan a project plus local agent context¶

agent-bom scan -p .

Use this when you want one scan to cover both: - project manifests and lockfiles in the current repo - local MCP / agent context on your machine

Scan instruction and skill files¶

agent-bom skills scan .
agent-bom skills verify .

This covers CLAUDE.md, AGENTS.md, .cursorrules, and supported skills/* instruction surfaces.

Check a specific package before installing¶

agent-bom check langchain@0.2.17 --ecosystem pypi
agent-bom check express@4.18.2 --ecosystem npm
agent-bom check tensorflow@2.17.0 --ecosystem pypi

Export machine-readable output¶

agent-bom scan -f json -o report.json
agent-bom scan -f sarif -o findings.sarif
agent-bom scan -f cyclonedx -o bom.json

On an empty or offline dashboard, use Preview a saved report to choose report.json. The browser checks every agent and exposure entry, validates finding totals, and rejects files larger than 10 MB before previewing them. Rejected reports leave the current view intact. This preview does not upload evidence or populate the control-plane graph; use Return to live overview to leave it, or ingest the report's evidence through a supported control-plane workflow.

Ingest external scanner or SARIF evidence¶

When an SCA, SBOM, or SAST tool already produced a report, run full local scan depth without a control plane:

agent-bom scan --external-scan trivy.json -f json -o report.json
agent-bom scan --external-scan findings.sarif -f json -o report.json  # tool-agnostic import; no producer execution

For bulk push into a running control plane instead, use agent-bom findings push <file>. See docs/INGEST_PATHS.md for the VM/registry matrix and push vs --external-scan tradeoff.

LLM FinOps (cost forecast)¶

Project LLM burn rate from OpenTelemetry GenAI spans (read-only, no secret values):

agent-bom cost forecast

Price model and OTel ingest path: docs/COST_MODEL.md.

Run compliance mapping¶

agent-bom scan . --compliance
agent-bom scan . --compliance --compliance-export owasp-llm
agent-bom scan . --compliance --compliance-export eu-ai-act

--compliance adds all mapped framework tags to findings. Use --compliance-export <framework> when you also need one framework-specific evidence bundle.

Scan a container image¶

agent-bom image python:3.12-slim

Scan infrastructure as code¶

agent-bom iac Dockerfile k8s/ infra/main.tf

iac accepts one or more paths in a single run, so the example above scans: - a Dockerfile - a Kubernetes directory - a Terraform file

Inspect discovery paths¶

agent-bom where
agent-bom mcp inventory

agent-bom mcp where still works when you want the grouped MCP subcommand form.

Output formats¶

agent-bom scan -f console  # terminal output (default)
agent-bom scan -f json     # JSON report
agent-bom scan -f html     # HTML dashboard
agent-bom scan -f sarif    # SARIF for GitHub Code Scanning
agent-bom scan -f csv      # CSV export
agent-bom check requests@2.33.0 -e pypi -f json   # single-package JSON verdict
agent-bom report history -f json                  # saved scan metadata for CI

If a GitHub Action produces SARIF but no Code Scanning alert appears, check the SARIF upload troubleshooting guide for token permissions, fork PR behavior, report paths, and category settings.