Skip to main content
Glama
README.md
<p align="center">
  <a href="https://koda-ai-studio.github.io/agent-bom/demo/"><img src="docs/images/social-preview.svg" alt="agent-bom — AI supply-chain BOM: supported agents, MCP servers and AI packages, and what each one can reach." width="1280" /></a>
</p>

<p align="center">
  <a href="https://github.com/koda-ai-studio/agent-bom/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/koda-ai-studio/agent-bom/ci.yml?branch=main&style=flat&label=Build&logo=github" alt="Build"></a>
  <a href="https://pypi.org/project/agent-bom/"><img src="https://img.shields.io/pypi/v/agent-bom?style=flat&label=PyPI&logo=pypi&logoColor=white&cacheSeconds=60" alt="PyPI"></a>
  <a href="https://pypi.org/project/agent-bom/"><img src="https://img.shields.io/badge/Python-3.11%E2%80%933.14-blue?style=flat&logo=python&logoColor=white" alt="Python 3.11 through 3.14"></a>
</p>
<p align="center">
  <a href="LICENSE"><img src="https://img.shields.io/badge/License-Apache%202.0-blue?style=flat" alt="Apache-2.0 license"></a>
  <a href="https://securityscorecards.dev/viewer/?uri=github.com/koda-ai-studio/agent-bom"><img src="https://img.shields.io/ossf-scorecard/github.com/koda-ai-studio/agent-bom?style=flat&label=OpenSSF%20scorecard" alt="OpenSSF Scorecard"></a>
</p>
<!-- mcp-name: io.github.koda-ai-studio/agent-bom -->

<p align="center"><b>AI supply-chain BOM: <a href="#what-it-covers">supported</a> agents, MCP servers and AI packages, and what each one can reach.</b></p>

For AppSec teams and developers who run Claude Code, Cursor, Codex or any MCP
client: see which agents, MCP servers, tools and packages are installed, which
are vulnerable, and what each one can reach. Local scans need no account.

<p align="center">
  <a href="#quick-start"><b>Quick start</b></a> ·
  <a href="https://koda-ai-studio.github.io/agent-bom/demo/"><b>Try in browser</b></a> ·
  <a href="#from-laptop-to-team-to-org">Laptop → team → org</a> ·
  <a href="docs/GALLERY.md">Product tour</a> ·
  <a href="https://koda-ai-studio.github.io/agent-bom/">Docs</a>
</p>

## Quick start

From the repository you want to inspect, with [uv installed](https://docs.astral.sh/uv/getting-started/installation/):

```bash
uvx agent-bom scan . -f html -o agent-bom-report.html
```

Open `agent-bom-report.html` for inventory, findings and fix guidance. Run it
again later to see what changed. No MCP configuration in the project? Package
findings still apply.

No project handy? `uvx agent-bom scan --demo --offline` scans a bundled sample.
Exit `1` is expected there: the sample trips the security gate. Elsewhere, a
non-zero exit can mean a security gate or incomplete assessment; inspect the
report and coverage ([exit codes](site-docs/reference/exit-codes.md),
[first-run guide](docs/FIRST_RUN.md)).

<p align="center"><img src="docs/images/demo-latest.gif" alt="Recorded agent-bom CLI showing sample findings and remediation guidance; no fix executed" width="920" /></p>

<details>
<summary>What the scan reads and what it does not establish</summary>

The scan stays inside this repository: packages, MCP configuration, secrets and
personal data, skills and IaC. It does not read agent configuration elsewhere on
the machine. Missing evidence is reported as partial, not clean. See
[what a scan does and does not establish](docs/FIRST_RUN.md#what-this-scan-does-and-does-not-establish).

</details>

## From laptop to team to org

- **On your laptop:** `uvx agent-bom scan .` for findings with fixes and a delta
  on every rescan; `claude mcp add agent-bom -- uvx agent-bom mcp server` to use
  agent-bom as a tool inside your coding agent ([MCP server](docs/MCP_SERVER.md), [plugins](#integrations)).
- **In your team:** `uses: koda-ai-studio/agent-bom@v0` on pull requests and a
  weekly `schedule:` for a PR gate with a findings comment, SARIF in code
  scanning and a weekly rescan that catches new CVEs in unchanged code
  ([GitHub Action](site-docs/integrations/github-action.md)).
- **Across your org:** `agent-bom up` locally, then Docker Compose or the Helm
  chart from `oci://ghcr.io/koda-ai-studio/charts/agent-bom` for retained scans,
  one graph of agents, MCP servers, packages and credentials, SSO and audit in
  your own infrastructure ([self-host](#self-host-in-your-environment)).

All three are free under Apache-2.0 and are adoption paths, not editions. There
is no managed cloud offering today; community support runs on GitHub
([deployment chooser](site-docs/deployment/overview.md#choose-your-workflow),
[support model](docs/ENTERPRISE_SUPPORT_MODEL.md)).

## Why an AI supply-chain BOM

A CVE in an AI package, a poisoned tool description or an over-scoped
credential matters by what the agent that loads it can reach. A package SBOM
stops at packages; agent-bom records the chain, agent → MCP server → tool →
package → credential → data, and keeps the evidence for every edge.

<p align="center"><a href="docs/images/graph-environment-dark-live.png"><picture><source media="(prefers-color-scheme: light)" srcset="docs/images/graph-environment-light-live.png"><img src="docs/images/graph-environment-dark-live.png" alt="Sample production AI environment: Document Intake Agent uses a document-tools MCP server that depends on pillow 9.0.0, linked to KEV-listed CVE-2023-4863; Support Triage Agent uses a ticketing MCP server that references TICKETING_API_KEY, which can access a customer ticket archive" width="1100"></picture></a></p>

*Sample data.* [What the sample shows](docs/GALLERY.md#what-the-readme-sample-shows)

## What it covers

Agents and MCP servers, models and AI platforms, dependencies, code, containers
and IaC, cloud and data platforms, and a runtime MCP proxy and gateway. Exports
are SARIF, CycloneDX, SPDX, JSON and HTML.

<details>
<summary>Coverage by area</summary>

| Area | What you get |
|---|---|
| AI agents and MCP | Agents, MCP servers, tools and credentials from local configs and agent frameworks, linked to what they can reach. |
| Models and AI platforms | Supported OpenAI, Hugging Face, Ollama, MLflow and W&B assets, with available model provenance beside dependencies and agent context. |
| Runtime | An MCP proxy and gateway that alert on poisoned tools and injected results, or block them with `--injection-mode enforce`. |
| SBOM, AI-BOM and Agent-BOM | Software SBOMs in CycloneDX or SPDX. CycloneDX AI components carry collected model metadata. Native agent-bom JSON connects agents, MCP servers, tools, credential references and packages. |
| Dependencies | Lockfiles and manifests across Python, JavaScript, Go, Java, .NET, Rust and more, matched against OSV, GitHub advisories and NVD with KEV and EPSS. |
| Code | Findings imported from any SARIF producer, plus native analysis of AI code (prompt-injection sinks, guardrails, tool exposure) and whether your code reaches the vulnerable function. |
| Containers and IaC | Images scanned in bounded memory and time; Dockerfile, Terraform, Kubernetes, Helm and compose risks with exact lines in SARIF. |
| Cloud and data platforms | Read-only collection from AWS, Azure, GCP, Kubernetes, Databricks and Snowflake, with provider-specific posture checks and graph context. Per-lane rule counts are generated from code in the [capability matrix](docs/VENDOR_COVERAGE.md#capability-matrix). |
| GPU and AI infrastructure | AI workloads on CoreWeave, Nebius, Lambda, RunPod, Vast.ai and Crusoe; GPU containers and Kubernetes GPU nodes. Collection depth varies by provider. |

Findings map to
[OWASP LLM Top 10, OWASP Agentic Top 10, OWASP MCP Top 10, MITRE ATLAS, EU AI Act and NIST AI RMF](site-docs/features/compliance.md).

Generate a BOM from a project, or inspect an agent inventory with sample data:

```bash
agent-bom scan --project . -f cyclonedx -o sbom.cdx.json
agent-bom scan --project . -f spdx -o sbom.spdx.json
agent-bom scan --demo --offline -f json -o agent-bom.json
```

Model metadata appears when the source supplies it.

</details>

<details>
<summary>All supported sources and evidence destinations, by category</summary>

<!-- integrations:begin (generated by scripts/render_social_preview_svg.py; do not edit) -->
| Area | Integrations |
|---|---|
| AI clients + IDEs | Claude, Codex, Cursor, GitHub Copilot, Windsurf, Cortex Code, Gemini CLI, JetBrains AI, Junie, Amazon Q, Cline, Roo Code, Continue, Zed, Goose, Snowflake CLI, Docker MCP Toolkit, Tabnine, Sourcegraph Cody, Aider, Void, Aide, Trae, Pieces, OpenClaw, mcp-cli |
| AI platforms + model hubs | OpenAI, Hugging Face, Ollama, MLflow, W&B, Langfuse, LangSmith |
| GPU + neo clouds | CoreWeave, Nebius, Lambda, RunPod, Vast.ai, Crusoe, GPU containers + K8s GPU nodes |
| Hyperscalers + Kubernetes | AWS, Azure, GCP, Kubernetes |
| Data + vector stores | Snowflake, Databricks, Supabase, Pinecone, Qdrant, Weaviate, Chroma, Milvus |
| Identity + SaaS + dev | Okta, GitHub Actions, Vercel, Microsoft Entra ID, Jira, ServiceNow, Slack, Jamf |
| Evidence out | ClickHouse, BigQuery, S3, GCS, Azure Blob, Jira tickets, Slack alerts, Vanta, Drata, OCSF syslog |

Product names and logos are trademarks of their owners, used only to identify supported evidence sources. Their use does not imply endorsement or partnership.
<!-- integrations:end -->

</details>

## Investigate context and exposure

Select an agent such as Document Intake Agent, open CVE-2023-4863 (high,
KEV-listed) and follow each arrow back to its source evidence. Take the proposed
[remediation](docs/GALLERY.md#engineers-and-grc-fix-and-verify), then
[rescan the changed pin](examples/connected-bom/README.md) and compare
snapshots; the comparison verifies the changed input, not a running deployment.

<details>
<summary>Am I affected by a new CVE?</summary>

Match it against stored scans, including CVEs only NVD has published. You get
affected assets with their patch target, possibly affected distro packages to
verify, and the blast radius ([walkthrough](docs/RESPOND_TO_A_NEW_CVE.md)):

```bash
agent-bom db update                                   # refresh OSV, NVD, KEV and EPSS
agent-bom db advisory affected CVE-2026-109618        # most recent saved scan
agent-bom db advisory affected CVE-2026-109618 --report <scan-report.json> --format json   # a JSON report written by an earlier scan
```

From an MCP client, the read-only `affected_assets` tool (`graph` and `full`
profiles) takes the same `advisory_id`. In CI, run `uvx agent-bom db update`
before the GitHub Action step (its `auto-update-db` default only refreshes
feeds that missed the daily freshness target). To explain a finding to your team,
[create an impact brief](docs/operations/IMPACT_BRIEF.md).

</details>

<details>
<summary>More sample graphs: package evidence, repository and cloud (3)</summary>

**One package, three parsed inputs.** A repository pin, an image SBOM and a
modeled Kubernetes workload resolve to one `pillow@9.0.0`.

<p align="center"><a href="docs/images/graph-relationship-dark-live.png"><picture><source media="(prefers-color-scheme: light)" srcset="docs/images/graph-relationship-light-live.png"><img src="docs/images/graph-relationship-dark-live.png" alt="Repository pin, image inventory and Kubernetes deployment occurrence resolving to one pillow package linked to KEV-listed CVE-2023-4863, with the plain-language relationship evidence open" width="1100"></picture></a></p>

**Repository.** Source imports, deployment configuration and CI traced to a
published container and its vulnerable packages:

<p align="center"><a href="docs/images/graph-repository-dark-live.png"><picture><source media="(prefers-color-scheme: light)" srcset="docs/images/graph-repository-light-live.png"><img src="docs/images/graph-repository-dark-live.png" alt="Sample repository linking source, deployment configuration and a CI job to a container, vulnerable npm and PyPI packages, their advisories and a CI misconfiguration" width="1100"></picture></a></p>

**Cloud.** A public API gateway into a vulnerable workload, its role and a PII bucket:

<p align="center"><a href="docs/images/graph-cloud-dark-live.png"><picture><source media="(prefers-color-scheme: light)" srcset="docs/images/graph-cloud-light-live.png"><img src="docs/images/graph-cloud-dark-live.png" alt="Sample cloud account where a public API gateway exposes a workload with a critical advisory that authenticates as a role permitted to read a PII bucket" width="1100"></picture></a></p>

*Sample data.* [Context, correlation and reachability](docs/GALLERY.md#context-correlation-and-reachability) · [Run the reference lab](examples/reference-evidence-lab/README.md) · [Reproduce these screenshots](docs/GALLERY.md#reproduce-the-readme-screenshots)

</details>

## Open the sample graph

[Try the demo in your browser](https://koda-ai-studio.github.io/agent-bom/demo/)
on labelled sample data, with no install. To open the same graph locally:

```bash
pip install 'agent-bom[ui]==0.115.4'
agent-bom quickstart --run --offline
```

Run the server command it prints, then open its graph URL. Offline quickstart
skips package-CVE lookup, so zero CVEs is not a clean verdict; use the bundled
demo for advisory-backed findings or [populate the advisory database](docs/FIRST_RUN.md).

## Self-host in your environment

Your infrastructure, identity, database and audit boundary. Start a local pilot
from a [published release checkout](https://github.com/koda-ai-studio/agent-bom/releases):

```bash
git clone --depth 1 --branch v0.115.4 https://github.com/koda-ai-studio/agent-bom.git && cd agent-bom
AGENT_BOM_IMAGE_TAG=0.115.4 docker compose up -d
```

Open **http://localhost:3000**, then **Connections** or **New Scan**. The pilot
binds to loopback and retains state in a Docker volume. Before sharing access,
move to the [authenticated deployment](site-docs/deployment/authenticated-hosted-instance.md).

<details>
<summary>Deployment options (5): CLI, local dashboard, Compose pilot, authenticated host, Helm</summary>

| Deployment | First step | Result and next step |
|---|---|---|
| CLI or CI job | `agent-bom scan --demo --offline -o report.json` | Labelled sample findings in JSON; scan your own inventory or configure a [CI gate](docs/FIRST_RUN.md#pre-commit-hook). |
| Local API and dashboard | `agent-bom quickstart --run --offline` | Sample report and persisted graph; run the printed loopback server command and open its graph URL. |
| Docker Compose pilot | Release checkout and `docker compose up -d` above | Loopback API/UI with retained state; connect a read-only source and run a scan. |
| Authenticated single host | [Platform Compose setup](site-docs/deployment/authenticated-hosted-instance.md) | Login-gated API/UI and PostgreSQL; configure TLS, identity, secrets and backups before sharing access. |
| Kubernetes / EKS | [Helm deployment](site-docs/deployment/control-plane-helm.md) | Control plane in your cluster; provision role-separated secrets and storage, then validate authentication and health. |

For cloud accounts, add a scoped read-only connection, verify access, then start a scan.

</details>

<details>
<summary>Operating modes (5): scan, fleet inventory, MCP server, runtime proxy, runtime gateway</summary>

Modes can be combined:

| Mode | What it does | Start |
|---|---|---|
| Scan | Collect inventory and findings on demand or in CI; retain reports and graph evidence. | [First run](docs/FIRST_RUN.md) |
| Fleet inventory | Endpoints or collectors sync inventory to the control plane; review last-seen evidence. | [Fleet sync](site-docs/deployment/proxy-vs-gateway-vs-fleet.md#fleet) |
| MCP server | `agent-bom mcp server` exposes security tools to an MCP client. | [Tool profiles](docs/MCP_SERVER.md) |
| Runtime proxy | Wrap selected local stdio MCP servers to inspect tool calls; verify decisions in the audit trail. | [Proxy setup](site-docs/deployment/proxy-vs-gateway-vs-fleet.md#proxy) |
| Runtime gateway | Relay selected remote MCP traffic through a shared service; validate client auth, policy and upstream connectivity. | [Gateway setup](site-docs/deployment/proxy-vs-gateway-vs-fleet.md#gateway) |

</details>

<details>
<summary>Console terms: Sources, Assets, Findings, Issues</summary>

- **Sources** describes recorded evidence: local scans, fleet inventory, cluster
  scans, CI/CD, imported evidence, or mixed sources. It does not select a
  deployment type or enable runtime enforcement. **Demo data** marks labelled
  sample inventory.
- **Assets** are inventoried resources; **Findings** are detections on those
  resources; **Issues** group related findings for investigation or remediation.
- **Affected assets** counts distinct resources only when that count is
  available. One finding may belong to several security areas, so area counts
  must not be summed. Repeated observations across scans are shown separately.

Preview and community deployment paths have separate
[support boundaries](site-docs/deployment/product-boundaries.md).

</details>

[Docker pilot guide](docs/DEPLOY_PLATFORM.md) · [Compose with PostgreSQL](deploy/docker-compose.platform.yml) · [Choose a deployment](site-docs/deployment/overview.md) · [Enterprise controls](docs/TRUST.md) · [Connect cloud accounts](docs/CLOUD_CONNECT.md)

## Integrations

<details>
<summary><b>Claude Code and Codex plugins</b>: ask your coding agent instead of reading a report</summary>

In Claude Code:

```text
/plugin marketplace add koda-ai-studio/agent-bom
/plugin install agent-bom@agent-bom
```

In Codex, run `codex plugin marketplace add koda-ai-studio/agent-bom`, then
install **agent-bom-local** from the Plugins Directory. Both plugins run the
pinned agent-bom release locally and send nothing to an agent-bom service.

| Ask | Skill |
|---|---|
| "Is this project safe to ship?" | `checkup`: one verdict and the three fixes that matter most |
| "Am I affected by CVE-2025-29927?" | `affected`: affected or not found in what was scanned, never "safe" |
| "What have my agents been doing?" | `activity`: MCP usage, unused servers, risky commands from local session history |
| "Are my agent settings too permissive?" | `audit-mcp` and `audit-skills` |
| "Give me an AI-BOM" | `bom`: CycloneDX or SPDX for this machine, a project, an image or a cloud account |

Add `/plugin install agent-bom-guard@agent-bom` to block malicious and
typosquatted package installs before Claude runs them.
[All skills and their permissions](integrations/claude-code/README.md) ·
[Guard details](integrations/agent-bom-guard/README.md)

</details>

<details>
<summary>Work with your existing tools</summary>

Use **CLI or GitHub Action**, **REST API**, or **MCP**; export **SARIF, CycloneDX,
SPDX, JSON and HTML**. Cloud connectors and fleet sync collect inventory;
proxy and gateway deployments add runtime evidence.

For other MCP clients, run `agent-bom mcp server`.
Start with eight focused tools in the default profile.
[Choose an MCP profile](docs/MCP_SERVER.md) for graph, cloud, runtime or audit work.
[Try three investigations](docs/MCP_SERVER.md#investigation-workflows): affected agents, exposure receipts and a before/after scan comparison.
[Import existing scanner reports](docs/IMPORTERS.md) without replacing their source evidence.

Check a dependency before installing it with
`uvx agent-bom check requests@2.33.0 --ecosystem pypi`. Add
[pre-commit and CI setup](docs/FIRST_RUN.md#pre-commit-hook) for repeated checks.

[Proxy, gateway and fleet](site-docs/deployment/proxy-vs-gateway-vs-fleet.md) · [Integration capability matrix](docs/CLOUD_CONNECT.md) · [MCP client setup](docs/MCP_SERVER.md) · [Smithery migration](site-docs/integrations/smithery.md)

</details>

<details>
<summary>Show your scan status in your own README</summary>

The GitHub Action writes a job summary with severity counts, the top findings
and their fixes, and says when a scan was partial. To link your README to your
own workflow, add a standard GitHub workflow badge (replace `OWNER/REPO` and the
workflow file name); the Action's `badge:` input also writes shields.io badge JSON:

```markdown
[![agent-bom](https://github.com/OWNER/REPO/actions/workflows/agent-bom.yml/badge.svg)](https://github.com/OWNER/REPO/actions/workflows/agent-bom.yml)
```

</details>

## Trust and evidence

Discovery uses read-only access by default. Explicit disk side-scans create
temporary cloud resources. Missing evidence stays unavailable or partial;
control mappings are not audit certification.

<details>
<summary>What the graphs and mappings do and do not establish</summary>

- Screenshots use sample data; [what the sample shows](docs/GALLERY.md#what-the-readme-sample-shows)
  covers which links are modeled rather than observed.
- Retained scans correlate by exact, tenant-scoped identities.
- A graph path does not prove exploitation. Credential references are names,
  not secret values.
- Persisted runtime, proxy and gateway activity retains source receipts and
  bounded time windows in the graph. Exact inventory references can bind
  records; unresolved identities and collection gaps remain explicit. Recorded
  activity does not prove execution or grant access. See the
  [runtime evidence boundaries](docs/TRACE_CONNECTIONS.md).
- MITRE technique associations provide investigation context, not proof of an
  attack. [ATLAS mapping receipts](docs/ATLAS_COVERAGE.md) retain the weakness
  association and source catalog hashes.
- A BOM is an inventory, not proof of safe execution or complete collection.

</details>

[Measured matcher proof](site-docs/features/scanning.md#reproducible-matching-evidence) · [Product boundaries](docs/PRODUCT_BOUNDARIES.md) · [Permissions](docs/PERMISSIONS.md) · [Threat model](docs/THREAT_MODEL.md) · [Release verification](docs/RELEASE_VERIFICATION.md) · [Graph data model](docs/graph/DATA_MODEL.md)

## Contributing and support

[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/koda-ai-studio/agent-bom)

Start with the [first PR guide](CONTRIBUTING.md#your-first-pr-in-30-minutes)
or a [`good first issue`](https://github.com/koda-ai-studio/agent-bom/issues?q=is%3Aopen+label%3A%22good+first+issue%22).
Ask in [GitHub Discussions](https://github.com/koda-ai-studio/agent-bom/discussions) (or [Discord](https://discord.gg/3YmYPqKZh5)), share [feedback](https://github.com/koda-ai-studio/agent-bom/issues/new?template=feedback.yml),
or follow the [maintainer path](GOVERNANCE.md) ([review owners](MAINTAINERS.md)).

[Contributing](CONTRIBUTING.md) · [Capabilities and roadmap](docs/ROADMAP.md) · [Support](SUPPORT.md) · [Report an inaccurate finding](https://github.com/koda-ai-studio/agent-bom/issues/new?template=inaccurate_finding.yml) · [Apache-2.0](LICENSE)

Source version: **v0.115.4** · Latest release: **v0.115.4** · [Changelog](CHANGELOG.md)

TDQS

A3.9/5.0

Scored across 8 tools

Disambiguation4/5

Most tools target clearly distinct outputs: scan (full assessment), check (single package CVE lookup), compliance, policy_check, remediate, exposure_paths, intel_lookup. The main confusion is between scan and generate_sbom, since scan already returns an 'AI-BOM' and affected paths while generate_sbom returns a standards-compliant SBOM, plus mild overlap between check (OSV package CVEs) and intel_lookup (local advisories). Descriptions help but an agent could easily pick the wrong one for a 'give me an SBOM' request.

Naming Consistency3/5

Names are all snake_case (one word or two), so character style is uniform, but the verb/noun convention is mixed: bare verbs (scan, check, remediate), noun phrases (exposure_paths, compliance), and odd compounds (intel_lookup, policy_check). Readable in aggregate but not a predictable verb_noun pattern.

Tool Count4/5

Eight tools is a sensible scope for a supply-chain security server. Several tools (scan, remediation, policy_check, compliance, generate_sbom) internally re-run the same scan, so there is a bit of functional redundancy, but none feels wholly unjustified.

Completeness4/5

Covers discovery/scanning, package CVE check, SBOM export, compliance, attack-path ranking, policy gating, and remediation — a strong lifecycle. Gaps remain: no scan history/session listing, no diff/compare between scans, no finding suppression/waiver or credential inventory tool, and result paging is only reachable through scan.

Maintenance

ActivityActive
ResponsivenessUsually handled