Metadata-Version: 2.4
Name: agent-bom
Version: 0.10.1
Summary: AI Bill of Materials (AI-BOM) generator — CVE scanning, blast radius, enterprise remediation plans, OWASP LLM Top 10 + MITRE ATLAS threat mapping, and MCP registry for AI agents.
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
Project-URL: Documentation, https://github.com/agent-bom/agent-bom#readme
Project-URL: Security Policy, https://github.com/agent-bom/agent-bom/blob/main/SECURITY.md
Project-URL: Trust & Permissions, https://github.com/agent-bom/agent-bom/blob/main/PERMISSIONS.md
Keywords: ai-bom,sbom,mcp,mcp-server,security,ai-agents,vulnerability,supply-chain,owasp,mitre-atlas,grype,syft,blast-radius,cve,llm-security,remediation
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: api
Requires-Dist: fastapi>=0.115; extra == "api"
Requires-Dist: uvicorn[standard]>=0.32; extra == "api"
Requires-Dist: sse-starlette>=2.1; extra == "api"
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

  Generate AI Bills of Materials. Scan AI agents and MCP servers for CVEs. Map blast radius. Enterprise remediation with named assets and risk narratives. OWASP LLM Top 10 + MITRE ATLAS.

    agent-bom architecture

    Blast radius attack surface

---

## Why agent-bom?

**Not just "this package has a CVE."**

agent-bom answers the question security teams actually need:

> *If this CVE is exploited, which AI agents are compromised, which credentials leak, and which tools can an attacker reach?*

- **AI-BOM generation** — structured inventory of agents, servers, packages, credentials, tools
- **Blast radius analysis** — maps CVEs to agents, credentials, and MCP tools
- **Enterprise remediation** — named assets, impact percentages, risk narratives per fix
- **OWASP LLM Top 10 + MITRE ATLAS** — dual threat framework tagging on every finding
- **100-server MCP registry** — risk levels, provenance, tool inventories
- **Policy-as-code** — block unverified servers, enforce risk thresholds in CI
- **Read-only** — never writes configs, never runs servers, never stores secrets
- **Works everywhere** — CLI, Docker, REST API, Cloud UI, CI/CD, Prometheus, Kubernetes

**What it scans:**

| Source | How |
|--------|-----|
| MCP configs | Auto-discover (8 clients) |
| Docker images | Grype / Syft / Docker CLI |
| Kubernetes | kubectl across namespaces |
| Terraform | Bedrock, Vertex AI, Azure |
| GitHub Actions | AI env vars + SDK steps |
| Python agents | 10 frameworks detected |
| Existing SBOMs | CycloneDX / SPDX import |

**What it outputs:**

Console, HTML dashboard, SARIF, CycloneDX 1.6, SPDX 3.0, Prometheus, OTLP, JSON, REST API

---

## Quick links

- **[Install](#install)** — `pip install agent-bom` or Docker
- **[Get started](#get-started)** — scan in 30 seconds
- **[AI-BOM export](#ai-bom-export)** — CycloneDX, SPDX, JSON, SARIF, HTML
- **[Remediation plan](#enterprise-remediation-plan)** — named assets, risk narratives
- **[Cloud UI](#cloud-ui)** — enterprise aggregate dashboard
- **[CI integration](#ci-integration)** — GitHub Actions + SARIF upload
- **[REST API](#rest-api)** — FastAPI on port 8422
- **[MCP Registry](data/mcp-registry.yaml)** — 100 known servers with metadata
- **[PERMISSIONS.md](PERMISSIONS.md)** — auditable trust contract
- **[Roadmap](#roadmap)** — what's coming next

---

## Get started

```bash
pip install agent-bom

# Auto-discover and scan local AI agents
agent-bom scan

# HTML dashboard with severity donut + blast radius chart
agent-bom scan -f html -o report.html && open report.html

# CI gate — fail on critical/high CVEs
agent-bom scan --fail-on-severity high -q
```

No config needed. Auto-discovers Claude Desktop, Cursor, Windsurf, Cline, VS Code Copilot, Continue, Zed, and Cortex Code on macOS, Linux, and Windows.

---

## Install

| Mode | Command |
|------|---------|
| Core CLI | `pip install agent-bom` |
| REST API | `pip install agent-bom[api]` |
| Dashboard | `pip install agent-bom[ui]` |
| OpenTelemetry | `pip install agent-bom[otel]` |
| Everything | `pip install agent-bom[api,ui,otel]` |
| Docker | `docker run --rm -v ~/.config:/root/.config:ro agentbom/agent-bom scan` |

---

## Core capabilities

### CVE scanning + blast radius

```bash
agent-bom scan --enrich                    # OSV + NVD CVSS + EPSS + CISA KEV
agent-bom scan --image myapp:latest        # Docker image (all ecosystems via Grype)
agent-bom scan --k8s --all-namespaces      # Every pod in the cluster
agent-bom scan --sbom syft-output.cdx.json # Pipe in existing SBOMs
```

Every vulnerability is mapped to: **which agents** are affected, **which credentials** are exposed, **which MCP tools** an attacker can reach.

### OWASP LLM Top 10 tagging

| Code | Triggered when |
|------|---------------|
| **LLM05** | Any package CVE (always) |
| **LLM06** | Credential env var exposed alongside CVE |
| **LLM08** | Server with >5 tools + CRITICAL/HIGH CVE |
| **LLM02** | Tool with shell/exec semantics |
| **LLM07** | Tool that reads files or prompts |
| **LLM04** | AI framework + HIGH+ CVE |

### MITRE ATLAS threat mapping

Every finding is also mapped to [MITRE ATLAS](https://atlas.mitre.org/) adversarial ML techniques:

| Technique | Triggered when |
|-----------|---------------|
| **AML.T0010** | Any package CVE (always — supply chain compromise) |
| **AML.T0062** | Credentials exposed alongside vulnerability |
| **AML.T0061** | >3 tools reachable through compromised path |
| **AML.T0051** | Tools can access prompts/context (injection surface) |
| **AML.T0056** | Tools can read files (meta prompt extraction) |
| **AML.T0043** | Tools with shell/exec capability (adversarial data) |
| **AML.T0020** | AI framework + HIGH+ CVE (training data poisoning) |
| **AML.T0058** | AI framework + creds + HIGH+ (agent context poisoning) |

### Threat framework coverage matrix

After every scan, agent-bom shows which OWASP + ATLAS categories were triggered — and how many findings per category:

**CLI** — `print_threat_frameworks()` renders two Rich tables with bar charts:

```
┌───────────── OWASP LLM Top 10 ──────────────┐
│ LLM05  Supply Chain Vulnerabilities    12 ████│
│ LLM06  Sensitive Information Disclosure 4 ██  │
│ LLM08  Excessive Agency                2 █   │
│ LLM01  Prompt Injection                —     │
│ ...                                          │
└──────────────────────────────────────────────┘
```

**JSON** — `threat_framework_summary` section with per-category counts:

```json
{
  "threat_framework_summary": {
    "owasp_llm_top10": [{"code": "LLM05", "name": "Supply Chain Vulnerabilities", "findings": 12, "triggered": true}],
    "mitre_atlas": [{"technique_id": "AML.T0010", "name": "ML Supply Chain Compromise", "findings": 12, "triggered": true}],
    "total_owasp_triggered": 4,
    "total_atlas_triggered": 5
  }
}
```

**Cloud UI** — two-column threat matrix grid with hit/miss indicators and finding counts per category.

### AI-BOM export

Every scan produces a complete **AI Bill of Materials** — a structured document listing all agents, MCP servers, packages, credentials, tools, and vulnerabilities. Export in any standard format:

```bash
agent-bom scan -f cyclonedx -o ai-bom.cdx.json   # CycloneDX 1.6
agent-bom scan -f spdx -o ai-bom.spdx.json       # SPDX 3.0
agent-bom scan -f json -o ai-bom.json             # Full AI-BOM (document_type: "AI-BOM")
agent-bom scan -f sarif -o results.sarif           # GitHub Security tab
agent-bom scan -f html -o report.html              # Interactive HTML dashboard
```

The JSON output includes `"document_type": "AI-BOM"` and `"spec_version": "1.0"` at the top level for programmatic identification. Console output shows an export hint panel after every scan.

### Enterprise remediation plan

Each remediation tells you exactly **what will be protected** when you fix it:

```
 3. upgrade python 3.11.14 → 3.13.10
    clears 2 vuln(s) • impact score: 14
    agents:       claude-desktop-agent (100%)
    credentials:  YOUTUBE_API_KEY (100%)
    tools:        read_file, execute_command, web_search (3 of 8 — 38%)
    mitigates:    LLM05 LLM06 AML.T0010 AML.T0062
    ⚠ if not fixed: attacker exploiting CVE-2025-1234 can reach
      claude-desktop-agent → YOUTUBE_API_KEY → execute_command
```

- **Named assets** — which specific agents, credentials, and tools are at risk
- **Percentages** — what fraction of your total inventory each fix protects
- **Threat tags** — which OWASP LLM + MITRE ATLAS categories are mitigated
- **Risk narratives** — plain-text explanation of what happens if you don't remediate

### Policy-as-code

```bash
agent-bom scan --policy policy.json --fail-on-severity high
```

```json
[
  {"id": "no-unverified-high", "unverified_server": true, "severity_gte": "HIGH", "action": "fail"},
  {"id": "warn-excessive-agency", "min_tools": 6, "action": "warn"},
  {"id": "block-kev", "severity_gte": "CRITICAL", "action": "fail"}
]
```

### MCP Server Registry (100 servers)

Ships with a curated registry of 100 known MCP servers — 58 verified. Each entry includes: package name + version pin, ecosystem, risk level, tool names, credential env vars, license, and source URL.

Unverified servers in your configs trigger a warning. Policy rules can block them in CI.

---

## Deployment models

| Mode | Command | Best for |
|------|---------|----------|
| Developer CLI | `agent-bom scan` | Local audit, pre-commit checks |
| Pre-install check | `agent-bom check express@4.18.2 -e npm` | Before running any MCP server |
| CI/CD gate | `agent-bom scan --fail-on-severity high -q` | Block PRs on critical CVEs |
| Docker | `docker run agentbom/agent-bom scan` | Isolated, reproducible scans |
| REST API | `agent-bom api` | Dashboards, SIEM, scripting |
| Dashboard | `agent-bom serve` | Team-visible security dashboard |
| Prometheus | `--push-gateway` or `--otel-endpoint` | Continuous monitoring |
| K8s CronJob | Helm chart + CronJob | Cluster-wide auditing |

---

## CI integration

```yaml
- name: AI supply chain scan
  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
```

SARIF output includes OWASP LLM tags in `result.properties` — visible directly in GitHub Advanced Security.

---

## REST API

```bash
pip install agent-bom[api]
agent-bom api   # http://127.0.0.1:8422  →  /docs for Swagger UI
```

| Endpoint | Description |
|----------|-------------|
| `GET /health` | Liveness + `X-Agent-Bom-Read-Only: true` header |
| `POST /v1/scan` | Start async scan (returns `job_id`) |
| `GET /v1/scan/{job_id}` | Poll status + results |
| `GET /v1/scan/{job_id}/stream` | SSE real-time progress |
| `GET /v1/registry` | Full MCP server registry |
| `GET /v1/registry/{id}` | Single registry entry |

---

## Cloud UI

The Next.js dashboard (`ui/`) provides an enterprise-grade web interface on top of the REST API:

- **Security posture dashboard** — fleet-wide severity distribution, scan source breakdown, top vulnerable packages across all scans
- **Vulnerability explorer** — group by severity, package, or agent with full-text search
- **Scan detail** — per-job blast radius table, threat framework matrix, remediation plan with impact bars
- **Severity chart** — stacked bar chart with critical/high/medium/low percentage breakdown
- **Source tracking** — each finding tagged by source (MCP agents, container images, K8s pods, SBOMs)

```bash
cd ui && npm install && npm run dev   # http://localhost:3000
```

Requires the REST API backend running on port 8422.

---

## agent-bom vs ToolHive

These tools solve different problems and are **complementary**.

| | agent-bom | ToolHive |
|---|---|---|
| **Purpose** | Scan + audit AI supply chain | Deploy + manage MCP servers |
| **CVE scanning** | OSV, NVD, EPSS, CISA KEV, Grype | No |
| **Blast radius** | Agents, credentials, tools | No |
| **OWASP LLM Top 10** | Auto-tagged on every finding | No |
| **MCP server isolation** | No (scanner only) | Yes (containers + seccomp) |
| **Secret injection** | No | Yes (Vault, AWS SM) |
| **Read-only** | Yes | No (manages processes) |

**Together:** ToolHive runs your MCP servers securely. agent-bom audits whether the packages they depend on have known CVEs and what the blast radius would be.

---

## Trust & permissions

- **`--dry-run`** — shows every file and API URL that would be accessed, then exits
- **[PERMISSIONS.md](PERMISSIONS.md)** — auditable contract: what is read, what APIs are called, what is never done
- **API headers** — every response includes `X-Agent-Bom-Read-Only: true`
- **Sigstore signing** — releases v0.7.0+ signed via [cosign](https://www.sigstore.dev/)
- **Credential redaction** — only env var **names** appear in reports as `***REDACTED***`

---

## Roadmap

- [x] MITRE ATLAS adversarial ML threat mapping
- [x] SLSA provenance + SHA256 integrity verification
- [x] Threat framework coverage matrix (CLI + JSON + UI)
- [x] Enterprise remediation plan with named assets + risk narratives
- [x] Enterprise aggregate dashboard (Cloud UI)
- [x] AI-BOM export identity (CycloneDX, SPDX, JSON, SARIF)
- [ ] AWS Bedrock live agent + action group discovery
- [ ] Snowflake Cortex `CREATE MCP SERVER` scanning
- [ ] Google Vertex AI agent discovery
- [ ] Jupyter notebook AI library scanning
- [ ] Live MCP server introspection (tool enumeration without execution)
- [ ] ToolHive integration (`--toolhive` flag for managed server scanning)

---

## 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](CONTRIBUTING.md) | [SECURITY.md](SECURITY.md)

---

Apache 2.0 — [LICENSE](LICENSE)


[release-img]: https://img.shields.io/pypi/v/agent-bom?style=flat&label=Latest%20version
[ci-img]: https://img.shields.io/github/actions/workflow/status/agent-bom/agent-bom/ci.yml?style=flat&logo=github&label=Build
[license-img]: https://img.shields.io/badge/License-Apache%202.0-blue?style=flat
[docker-img]: https://img.shields.io/docker/pulls/agentbom/agent-bom?style=flat&label=Docker%20pulls
[stars-img]: https://img.shields.io/github/stars/agent-bom/agent-bom?style=flat&logo=github&label=Stars
[ossf-img]: https://api.securityscorecards.dev/projects/github.com/agent-bom/agent-bom/badge
