Metadata-Version: 2.4
Name: agent-bom
Version: 0.5.0
Summary: AI Bill of Materials — map the full trust chain from AI agents and MCP servers to CVEs, credentials, and blast radius.
Author-email: agent-bom <security@agent-bom.dev>
License: Apache-2.0
Project-URL: Homepage, https://github.com/agent-bom/agent-bom
Project-URL: Repository, https://github.com/agent-bom/agent-bom
Project-URL: Issues, https://github.com/agent-bom/agent-bom/issues
Project-URL: Changelog, https://github.com/agent-bom/agent-bom/releases
Keywords: ai-bom,sbom,mcp,security,ai-agents,vulnerability,supply-chain
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.0
Requires-Dist: rich>=13.0
Requires-Dist: httpx>=0.28.1
Requires-Dist: pydantic>=2.0
Requires-Dist: cyclonedx-python-lib>=11.6
Requires-Dist: packageurl-python>=0.17
Requires-Dist: toml>=0.10
Requires-Dist: pyyaml>=6.0
Requires-Dist: jsonschema>=4.0
Provides-Extra: otel
Requires-Dist: opentelemetry-api>=1.20; extra == "otel"
Requires-Dist: opentelemetry-sdk>=1.20; extra == "otel"
Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.20; extra == "otel"
Provides-Extra: ui
Requires-Dist: streamlit>=1.35; extra == "ui"
Requires-Dist: plotly>=5.20; extra == "ui"
Requires-Dist: pandas>=2.0; extra == "ui"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Requires-Dist: pip-audit>=2.10; extra == "dev"
Requires-Dist: bandit>=1.9; extra == "dev"
Requires-Dist: safety>=3.7; extra == "dev"
Dynamic: license-file

# agent-bom

[![CI](https://github.com/agent-bom/agent-bom/actions/workflows/ci.yml/badge.svg)](https://github.com/agent-bom/agent-bom/actions/workflows/ci.yml)
[![PyPI version](https://img.shields.io/pypi/v/agent-bom)](https://pypi.org/project/agent-bom/)
[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](https://github.com/agent-bom/agent-bom/blob/main/LICENSE)
[![Docker Pulls](https://img.shields.io/docker/pulls/agentbom/agent-bom)](https://hub.docker.com/r/agentbom/agent-bom)

**AI Bill of Materials (AI-BOM) for AI agents, MCP servers, containers, and IaC.**

`agent-bom` maps the full trust chain from every source of AI workloads — local configs, Docker images, Kubernetes pods, Terraform, GitHub Actions, and Python agent frameworks — through MCP servers and packages to known CVEs, answering the question traditional SBOMs can't:

> *"If this package is compromised, which agents are affected, what credentials are exposed, and what tools can an attacker reach?"*

---

## The AI Supply Chain — Full Picture

```
  SOURCES                 AGENTS                MCP SERVERS            PACKAGES → VULNS
  ───────                 ──────                ───────────            ────────────────

  agent-bom scan     ──▶  Claude Desktop   ──▶  filesystem-server ──▶  @modelcontextprotocol/
  (local configs)         Cursor                  tools: [read,          server-filesystem
                          Windsurf                        write]         0.6.2  ──▶ CVE HIGH
                          Cline                   creds: [API_KEY]
                          VS Code Copilot                           ──▶  express@4.18.2
                          Continue / Zed    ──▶  database-server         ──▶ CVE CRITICAL
                                                  tools: [query,
  --inventory        ──▶  custom-agent             execute]        ──▶  axios@1.6.0
  agents.json             openai-app              creds: [DB_PASS]       ──▶ CVE HIGH
                          langchain-app
                                                                   ──▶  langchain@0.2.0
  --image nginx:1.25 ──▶  img:nginx        ──▶  (image packages)        ──▶ CVE MEDIUM
  --image redis:7    ──▶  img:redis               extracted from
  (Syft or Docker CLI)                            all layers       ──▶  transformers@4.x
                                                                         ──▶ CVE HIGH
  --k8s              ──▶  k8s:prod/api-pod ──▶  (pod image pkgs)
  --all-namespaces        k8s:prod/worker        via kubectl
                          k8s:staging/...        get pods -o json

  --tf-dir infra/    ──▶  tf:bedrock       ──▶  terraform:aws     ──▶  github.com/hashicorp/
  (HCL parser)            tf:vertex-ai            provider              terraform-provider-aws
                          tf:azure-openai         Go module              5.31.0 ──▶ CVE HIGH
                          [+ hardcoded            (OSV Go scan)
                           secret detection]

  --gha /repo        ──▶  gha:ci.yml       ──▶  (AI SDK pkgs)    ──▶  openai@1.x
  (workflow YAML)         gha:deploy.yml        openai, anthropic       ──▶ CVE MEDIUM
                          [+ credential          langchain in
                           exposure flags]       run: steps

  --agent-project .  ──▶  langchain:agent  ──▶  (framework pkgs) ──▶  langchain@0.2.0
  (Python scanner)        openai:my-bot         tools, model,           ──▶ CVE HIGH
  10 frameworks           crewai:pipeline        cred refs              pydantic-ai@0.x
                                                                         ──▶ CVE MEDIUM

  --sbom sbom.json   ──▶  (ingest existing CycloneDX / SPDX from Syft, Grype, Trivy)
  ─────────────────────────────────────────────────────────────────────────────────────
  BLAST RADIUS  CVE-2024-XXXX (critical, CVSS 9.8, KEV, EPSS 0.94)
    ├─ 4 agents affected    (Claude Desktop, cursor-ai, k8s:prod/api, gha:ci.yml)
    ├─ 3 credentials exposed  (OPENAI_API_KEY, DB_PASSWORD, AWS_SECRET_KEY)
    └─ 7 tools reachable    (query_database, write_file, execute_code, ...)
```

---

## Get Started in 30 Seconds

```bash
pip install agent-bom

# Scan local AI agents (Claude Desktop, Cursor, Windsurf, Cline, VS Code...)
agent-bom scan

# HTML dashboard — severity donut, blast radius chart, smart risk graph
agent-bom scan -f html -o report.html && open report.html

# CI gate — fail if any critical/high CVE is found
agent-bom scan --fail-on-severity high -q
```

No config needed. Auto-discovers agent configs on macOS, Linux, and Windows.

---

## Install

```bash
pip install agent-bom                  # core
pip install agent-bom[ui]              # + Streamlit dashboard (agent-bom serve)
pip install agent-bom[otel]            # + OpenTelemetry OTLP export
```

Docker:

```bash
docker run --rm -v ~/.config:/root/.config:ro agentbom/agent-bom:latest scan
```

---

## What It Scans

| Source | Flag | What's detected |
|--------|------|-----------------|
| Local MCP configs | *(auto)* | Claude Desktop, Cursor, Windsurf, Cline, VS Code, Continue, Zed, Snowflake Cortex Code |
| Manual inventory | `--inventory agents.json` | Any agent/MCP server you describe in JSON |
| Existing SBOM | `--sbom sbom.json` | Ingest CycloneDX / SPDX from Syft, Grype, Trivy, cdxgen |
| Docker image | `--image nginx:1.25` | Packages from all layers (Syft preferred, Docker CLI fallback) |
| Kubernetes pods | `--k8s` | Running container images via `kubectl get pods` — all packages |
| Terraform / IaC | `--tf-dir infra/` | Bedrock, Vertex AI, Azure OpenAI resources; provider CVEs; hardcoded API keys |
| GitHub Actions | `--gha /repo` | AI credentials in `env:`, openai/anthropic/langchain SDK in `run:` steps |
| Python agent project | `--agent-project .` | LangChain, OpenAI Agents SDK, CrewAI, AutoGen, Google ADK, Pydantic AI + 4 more |

All sources produce the same output pipeline: packages → OSV CVE scan → enrichment → blast radius → report.

---

## Start Here — Pick Your Use Case

| I want to scan... | Command | What you get |
|-------------------|---------|--------------|
| My local AI tools (Claude Desktop, Cursor, Windsurf, Cline, VS Code...) | `agent-bom scan` | Auto-discovered MCP servers, packages, CVEs |
| A Python project using LangChain / OpenAI Agents / CrewAI / AutoGen... | `agent-bom scan --agent-project .` | Agent defs, tools, credential refs, CVEs from requirements |
| A Docker image | `agent-bom scan --image myapp:latest` | All packages in image layers → CVE scan |
| All containers running in a Kubernetes cluster | `agent-bom scan --k8s --all-namespaces` | Package inventory of every pod image → CVE scan |
| Terraform infrastructure (Bedrock, Vertex AI, Azure OpenAI...) | `agent-bom scan --tf-dir infra/` | AI resource inventory, provider CVEs, hardcoded secrets |
| GitHub Actions workflows | `agent-bom scan --gha .` | AI credentials in `env:`, SDK usage in `run:` steps |
| An existing Syft / Grype / Trivy SBOM | `agent-bom scan --sbom sbom.cdx.json` | Blast radius on top of existing SBOM |
| A JSON inventory of custom/cloud agents | `agent-bom scan --inventory agents.json` | CVE scan + blast radius for any agent you describe |
| Everything at once | `agent-bom scan --k8s --tf-dir infra/ --gha . --agent-project .` | Full AI supply chain snapshot |

**Common next steps after scanning:**

```bash
agent-bom scan --enrich                          # add NVD CVSS + EPSS + CISA KEV data
agent-bom scan -f html -o report.html            # open dashboard in browser
agent-bom scan -f sarif -o results.sarif         # upload to GitHub Security tab
agent-bom scan --fail-on-severity high -q        # CI gate — exit 1 on high+ CVEs
agent-bom serve                                  # interactive Streamlit dashboard
```

---

## Key Commands

```bash
# Discovery
agent-bom scan                                          # auto-discover local agents
agent-bom scan --inventory agents.json                  # manual inventory
agent-bom scan --image myapp:latest --image redis:7     # Docker images
agent-bom scan --k8s --all-namespaces                   # Kubernetes cluster
agent-bom scan --tf-dir infra/prod --tf-dir infra/staging
agent-bom scan --gha /path/to/repo
agent-bom scan --agent-project /path/to/python-project  # Python agent frameworks
agent-bom scan --sbom syft-output.cdx.json --inventory agents.json

# Enrichment & CI gates
agent-bom scan --enrich                                 # NVD + EPSS + CISA KEV
agent-bom scan --fail-on-severity high -q               # exit 1 on high+
agent-bom scan --fail-on-kev --enrich                   # exit 1 on KEV findings
agent-bom scan --fail-if-ai-risk                        # exit 1 on AI vuln + creds
agent-bom scan --policy policy.json                     # declarative policy rules

# Output formats
agent-bom scan -f html      -o report.html              # Grafana-style dashboard
agent-bom scan -f json      -o report.json              # machine-readable
agent-bom scan -f cyclonedx -o bom.cdx.json             # CycloneDX 1.6
agent-bom scan -f sarif     -o results.sarif            # GitHub Security tab
agent-bom scan -f spdx      -o bom.spdx.json            # SPDX 3.0 AI-BOM JSON-LD
agent-bom scan -f prometheus -o metrics.prom             # Prometheus / node_exporter

# Dashboard & utilities
agent-bom serve                                         # Streamlit dashboard (pip install agent-bom[ui])
agent-bom check express@4.18.2 -e npm                  # pre-install CVE check
agent-bom diff baseline.json                            # diff vs saved baseline
agent-bom inventory                                     # list agents, no CVE scan
agent-bom validate agents.json                          # validate inventory JSON
agent-bom where                                         # show config search paths
```

---

## Inventory Format

For agents not auto-discovered, provide a JSON inventory:

```json
{
  "agents": [{
    "name": "my-production-agent",
    "agent_type": "custom",
    "mcp_servers": [{
      "name": "database-server",
      "command": "npx",
      "args": ["-y", "@my-org/mcp-database-server"],
      "env": { "DB_PASSWORD": "...", "API_KEY": "..." },
      "tools": [{"name": "query_database"}, "list_tables"],
      "packages": [
        {"name": "express", "version": "4.18.2", "ecosystem": "npm"},
        "axios@1.6.0"
      ]
    }]
  }]
}
```

```bash
agent-bom validate agents.json   # validate before scanning
agent-bom scan --inventory agents.json --enrich -f html -o report.html
```

See [example-inventory.json](https://github.com/agent-bom/agent-bom/blob/main/example-inventory.json) and [examples/inventory.schema.json](https://github.com/agent-bom/agent-bom/blob/main/examples/inventory.schema.json) for full schema.

---

## CI Integration

```yaml
# Option A — standalone AI-BOM scan
- name: Generate AI-BOM
  run: |
    pip install agent-bom
    agent-bom scan --inventory agents.json --enrich --fail-on-severity high \
      -f sarif -o results.sarif

- name: Upload to GitHub Security tab
  uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: results.sarif

# Option B — pipe Syft/Grype SBOM into agent-bom
- name: Generate SBOM with Syft
  uses: anchore/sbom-action@v0
  with:
    image: myapp:latest
    format: cyclonedx-json
    output-file: sbom.cdx.json

- name: Blast radius analysis
  run: |
    pip install agent-bom
    agent-bom scan --sbom sbom.cdx.json --inventory agents.json \
      --enrich --fail-on-kev -f sarif -o results.sarif
```

---

## Observability

```bash
# Prometheus Pushgateway
agent-bom scan --push-gateway http://localhost:9091

# node_exporter textfile collector
agent-bom scan -f prometheus -o /var/lib/node_exporter/textfile/agent-bom.prom

# OpenTelemetry OTLP
pip install agent-bom[otel]
agent-bom scan --otel-endpoint http://localhost:4318
```

One-command monitoring stack (Prometheus + Pushgateway + Grafana):

```bash
docker compose -f docker-compose-monitoring.yml up -d
agent-bom scan --push-gateway http://localhost:9091
open http://localhost:3000   # import grafana-dashboard.json
```

---

## Roadmap

- [ ] AWS Bedrock — live agent + action group discovery via boto3
- [ ] Snowflake Cortex — query history scanning for `CREATE MCP SERVER` / `CREATE OR REPLACE AGENT`
- [ ] Google Vertex AI — agent + extension discovery
- [ ] Jupyter notebook scanning — detect AI library usage in `.ipynb` files
- [ ] Live MCP server introspection — enumerate tools/resources dynamically
- [ ] MITRE ATLAS mapping for AI/ML threats

---

## Contributing

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

See [CONTRIBUTING.md](https://github.com/agent-bom/agent-bom/blob/main/CONTRIBUTING.md) for guidelines. To report a vulnerability, see [SECURITY.md](https://github.com/agent-bom/agent-bom/blob/main/SECURITY.md).

---

Apache 2.0 — see [LICENSE](https://github.com/agent-bom/agent-bom/blob/main/LICENSE).

*Not affiliated with Anthropic, Cursor, or any MCP client vendor.*
