# agent-bom **AI supply-chain BOM: every agent, MCP server and AI package, and what each one can reach.** 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. [Try it in your browser](https://koda-ai-studio.github.io/agent-bom/demo/) first, no install. ```bash uvx agent-bom scan . -f html -o agent-bom-report.html ``` Open `agent-bom-report.html` to inspect inventory, findings, coverage and fix guidance. Run the same scan again later and agent-bom prints what changed since the last one. The scan stays inside the repository, including its secrets and personal data, and does not read agent configuration elsewhere on the machine. No MCP configuration? Package findings remain useful; agent/tool relationships require discovered configuration or an explicit inventory. [Measured matching accuracy on real repositories](features/real-repository-accuracy.md). | Where | Start with | You get | |---|---|---| | On your laptop | `uvx agent-bom scan .` and `claude mcp add agent-bom -- uvx agent-bom mcp server` | Findings with fixes, a delta on every rescan, agent-bom as a tool in your coding agent | | In your team | `uses: koda-ai-studio/agent-bom@v0` on pull requests plus a weekly `schedule:` ([GitHub Action](integrations/github-action.md)) | A PR gate with a findings comment and SARIF, and a weekly rescan for new CVEs | | Across your org | `agent-bom up`, then Docker Compose or the [Helm chart](deployment/control-plane-helm.md) | Retained scans, one graph of agents, servers, packages and credentials, SSO and audit in your infrastructure | `agent-bom` is also an open security data plane. It generates a reachability-backed AI BOM across agents, MCP servers, tools, packages, credential environment names, cloud estate, non-human identities, runtime, and skill surfaces, then exposes the same evidence — findings, compliance, LLM cost posture, and multi-hop attack paths — to humans and AI agents through CLI/CI, API/UI, MCP tools, and selected runtime controls. For source-by-source boundaries, see the [AI infrastructure coverage matrix](architecture/ai-infrastructure.md#coverage-matrix). The shared security graph connects packages, workloads, agents, tools, identities, and data assets through typed relationships with source evidence and explicit completeness. [Try the demo in your browser](https://koda-ai-studio.github.io/agent-bom/demo/): a read-only copy of the UI on labelled sample data. Nothing is installed and no request leaves the page's origin. ## What it does Follow an agent to its MCP server, the vulnerable package it uses, and the advisory finding. Inspect each relationship's source, review the proposed remediation, then rescan the changed input. Credential references are names, not secret values; a modeled path does not prove execution or successful access. Package risk is only the start. The committed **Reference evidence lab — modeled local infrastructure** correlates real parser and bundled-advisory output for `pillow@9.0.0` / `CVE-2023-4863` with exact image, Kubernetes, MCP, identity, and runtime receipts. It is local modeled proof, not customer or live-cloud evidence.  Start with the highest-ranked path, confirm why it is reachable, assign an owner and SLA, remediate, then verify against the next scan. ## Quick start With [uv installed](https://docs.astral.sh/uv/getting-started/installation/), scan the repository you want to inspect: ```bash uvx agent-bom scan . -f html -o agent-bom-report.html ``` Open `agent-bom-report.html` and review the affected package, recorded agent context, vulnerability and recommended fix. Check coverage warnings beside the verdict: incomplete evidence is not clean. Apply a reviewed fix and rerun the same command to verify what changed. [Read the first-run evidence boundaries](https://github.com/koda-ai-studio/agent-bom/blob/main/docs/FIRST_RUN.md#what-this-scan-does-and-does-not-establish). [Get started](getting-started/install.md){ .md-button .md-button--primary } [View on GitHub](https://github.com/koda-ai-studio/agent-bom){ .md-button } ## Start with one lane | Lane | First command | Artifact | |---|---|---| | **Bundled sample** | `agent-bom scan --demo --offline` | sample findings and graph-ready inventory; security-verdict exit `1` is expected | | **Repository scan** | `agent-bom scan . -f html -o agent-bom-report.html` | local HTML review plus exportable evidence | | **Cloud posture gate** | `agent-bom iac infra/ && agent-bom cloud aws --cis` | pre-cloud IaC findings plus point-in-time or scheduled posture evidence | | **CI evidence** | `uses: koda-ai-studio/agent-bom@v0` | SARIF, pull-request summary, optional code scanning | | **Assistant tools** | `agent-bom mcp server` | read-mostly security tools for MCP clients | | **Self-hosted control plane** | `docker compose -f deploy/docker-compose.pilot.yml up -d` (from a release checkout) | API and dashboard in your infrastructure | ## Shared evidence across product surfaces | Surface | Who uses it | What is shipped | |---|---|---| | **CLI / CI** | developers and pipelines | local scans, SARIF/SBOM/HTML/JSON, graph exports, deterministic gates | | **REST API** | security platforms, SIEM jobs, custom services | self-hosted control-plane routes for scans, normalized bulk findings, dataset versions, evaluation runs, graph evidence, audit, and governance | | **MCP tools** | AI agents and coding assistants | 8 default tools; explicit full catalog of 99 tools, strict args, `exposure_paths`, `graph_correlate`, runtime posture, audited write actions | | **TypeScript client** | services and agent runtimes calling the control plane | typed helper for stable REST endpoints; not a scanner SDK | | **TypeScript runtime detectors** | MCP/runtime enforcement integrations | local detector package for runtime policy checks; separate from the control-plane client | | **UI cockpit** | security teams and auditors | graph cockpit, compliance, audit, and evidence review over the same backend data | | **Runtime controls** | platform and runtime operators | proxy/gateway/Shield policy decisions, redacted audit, selected live evidence | The dashboard is not the only door into the product. It is the human cockpit over the same evidence that agents can request through MCP and platforms can consume through API, CLI, reports, and exports. Humans get a review surface; agents get strict-argument tools. Both work over the same security evidence and `ExposurePath` graphs. Cloud posture follows the same model: use `agent-bom iac` to block unsafe Terraform, CloudFormation, Kubernetes, or Docker changes before deployment, then use `agent-bom cloud aws --cis`, `agent-bom cloud azure --cis`, or `agent-bom cloud gcp --cis` to verify runtime state after drift and inherited provider settings exist. Snowflake uses `agent-bom scan --snowflake --snowflake-cis-benchmark`. ## Current graph and agent surfaces - `ExposurePath` is the shared investigation object for API, UI, reports, JSON, and MCP agent workflows. - Sigma.js and graphology provide the WebGL overview path for broad graph scenes; React Flow remains the focused path and evidence renderer. - The graph model includes time-versioned edges, semantic clusters, toxic-combo projection, identity taxonomy, and AWS IAM identity enrichment. - MCP exposes `exposure_paths` and `should_i_deploy` for headless agents that need ranked investigation context or deploy guidance. Neptune is an optional enterprise backend lane. The default self-hosted path remains SQLite/Postgres, and the docs do not claim a live Neptune production SLO or openCypher endpoint. ## Current boundaries - `@agent-bom/runtime` is a TypeScript runtime-detector package, while `@agent-bom/client` is the TypeScript control-plane API client; neither is a full scanner SDK. - CLI scan commands run local pipelines today; they do not delegate to the API, though CLI and API share lower scanner and discovery libraries. - Managed agent-bom Cloud, posture-event streaming connectors, and detection-as-code YAML are roadmap items, not shipped product in this repo. - Posture/event streaming is planned via webhook outbox and Kafka-style sinks. AWS cloud-log ingestion should start with CloudTrail S3/SQS and EventBridge; Kinesis/Firehose is a later adapter, not a release blocker. - AWS IAM identity enrichment is opt-in and read-only; it does not imply complete identity coverage across every provider. !!! info "Canonical docs tree" This MkDocs site is the source of truth for **getting-started and narrative documentation**. The **engineering/operator reference** lives in the repository's [`docs/`](https://github.com/koda-ai-studio/agent-bom/tree/main/docs) tree (architecture, threat model, deployment, graph contract, repo map). When a topic appears in both, this site is canonical for onboarding and `docs/` is canonical for the reference detail. ## Key capabilities | Capability | Description | |---|---| | **Discovery** | Auto-detect 29 first-class MCP client types plus dynamic/project surfaces | | **CVE scanning** | OSV + NVD CVSS v4 + EPSS + CISA KEV + GHSA | | **Blast radius** | Map CVE impact: package → vulnerability finding → MCP server (tools + credential env names) → connected agents | | **Registry** | 1320 MCP server security metadata entries | | **Compliance** | Framework applicability and evaluated controls; MITRE ATLAS associations are unscored | | **Runtime proxy** | Policy enforcement, credential leak detection, audit logging | | **SBOM** | CycloneDX 1.7, SPDX 3.0 output | | **Cloud** | CIS benchmarks for AWS, Azure, GCP, Snowflake and Kubernetes; Databricks security best practices. See [Supported sources](#supported-sources) | ## Supported sources Discovery and scanning read from these sources today; the last row lists where evidence can be sent. The list is generated from a code-backed manifest (`docs/images/integrations-manifest.json`); a test fails if it names anything without an implementation. | 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. ## Deploy In Your Infra `agent-bom` is not limited to one hosting model. The clean self-hosted story is: - **control plane**: API + UI + Postgres - **scan**: CI jobs, scheduled CronJobs, or one-off discovery runs - **fleet**: endpoint and collector inventory pushed into one control plane - **runtime**: selected `agent-bom proxy` sidecars or local proxy wrappers - **gateway**: central policy management for those proxy paths | Need | Recommended path | |---|---| | local scan or CI gate | CLI or GitHub Action | | self-hosted operator plane | API + UI + Postgres | | your own AWS / EKS rollout | Helm control plane + scheduled scan jobs + selected proxy sidecars | | developer workstation inventory | fleet sync | | live MCP enforcement | proxy + gateway | | assistant-facing tool server | `agent-bom mcp server` | [Deployment Overview](deployment/overview.md){ .md-button .md-button--primary } [Your Own AWS / EKS](deployment/own-infra-eks.md){ .md-button } [Product Boundaries](deployment/product-boundaries.md){ .md-button }