agent-bom

<p align="center"> <img src="https://raw.githubusercontent.com/msaad00/agent-bom/main/docs/images/social-preview.svg" alt="agent-bom — Discover. Scan. Correlate. Act. Security evidence across repositories, software supply chains, AI and MCP, cloud, identity, and data." width="960" /> </p> <p align="center"> <a href="https://github.com/msaad00/agent-bom/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/msaad00/agent-bom/ci.yml?branch=main&style=flat&label=Build" 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&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" alt="Python 3.11 through 3.14"></a> <a href="https://hub.docker.com/r/agentbom/agent-bom"><img src="https://img.shields.io/docker/pulls/agentbom/agent-bom?style=flat&label=Docker%20pulls" alt="Docker pulls"></a> <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/msaad00/agent-bom"><img src="https://img.shields.io/ossf-scorecard/github.com/msaad00/agent-bom?style=flat&label=OpenSSF%20scorecard" alt="OpenSSF Scorecard"></a> <a href="https://glama.ai/mcp/servers/msaad00/agent-bom"><img src="https://img.shields.io/badge/MCP-Glama-7c3aed?style=flat" alt="Glama MCP server"></a> <a href="https://smithery.ai/servers/agentbom/agent-bom"><img src="https://img.shields.io/badge/MCP-Smithery-1f6feb?style=flat" alt="Smithery MCP server"></a> </p> <!-- mcp-name: io.github.msaad00/agent-bom --> <p align="center"><b>Open security scanner and self-hosted control plane for AI, MCP, and cloud infrastructure.</b></p> <p align="center"> <a href="#quick-start"><b>Quick start</b></a> · <a href="#self-host-in-your-environment"><b>Self-host</b></a> · <a href="#deployment-models">Deployment models</a> · <a href="#product-tour">Product tour</a> · <a href="https://msaad00.github.io/agent-bom/">Docs</a> </p> For security, AppSec and GRC teams, agent-bom inventories the AI agents, MCP servers, packages, credential references and infrastructure in a repository, container image, Kubernetes cluster or cloud account. It checks packages against vulnerability advisories and IaC and cloud configuration against security benchmarks, imports findings from the scanners you already run, and traces each finding to the agents, tools and credentials it can reach. The self-hosted control plane centralizes those findings, maps them to compliance frameworks and enforces policy on live MCP traffic. ## Quick start ```bash pip install agent-bom agent-bom scan . agent-bom scan --demo --offline ``` `agent-bom scan .` inventories the current project and checks its packages against advisories. `agent-bom scan --demo --offline` runs a bundled sample estate with no network access and exits `1` on purpose, because the sample trips the security gate. For CI, write SARIF with `agent-bom scan . -f sarif -o findings.sarif` and [upload it](docs/FIRST_RUN.md#5-gate-ci-on-the-result); check setup with `agent-bom doctor`. [First-run guide](docs/FIRST_RUN.md) To give an assistant the same evidence, run `agent-bom mcp server`. Start with eight focused tools, then select a graph, cloud, runtime or audit profile. The full catalog has 88 MCP tools, 7 resources, and 8 workflow prompts. [MCP workflows](docs/MCP_WORKFLOWS.md) <details> <summary>No project handy? Scan the bundled sample estate offline</summary> `agent-bom scan --demo --offline` lists sample agents, CVEs with recorded agent, MCP server and credential associations, and policy findings (excerpt from current source; installed-release output may differ): ```text Security posture: CRIT 7 HIGH 10 MED 6 · all finding categories 5 agents · 10 servers · 23 packages DISCOVER | Agents Agent Type Servers Pkgs Creds Vulns langchain-service custom 2 4 4 4 claude-desktop claude-desktop 2 6 3 5 ANALYZE | Critical Details CVE-2023-36258 · langchain@0.0.150 · CRITICAL Fix: upgrade to ≥ 0.0.247 Blast: langchain-service → llm-orchestrator-server → ANTHROPIC_API_KEY, OPENAI_API_KEY ANALYZE | Graph & Policy Findings (8 occurrences) CRIT COMBINATION AI agent can reach a credential or privileged tool: langchain-service HIGH PROMPT_SECURITY Agent calls MCP server without verified identity MED PROMPT_SECURITY Long-lived static credential on MCP server ``` For sample inventory with an exact graph link, run `agent-bom quickstart --run --offline` (it skips package-CVE lookup). [First-run guide](docs/FIRST_RUN.md#2-inspect-the-bundled-sample-project) <p align="center"> <img src="docs/images/demo-latest.gif" alt="Recorded agent-bom CLI showing sample findings and remediation guidance" width="920" /> </p> </details> <details> <summary>Developer gates and offline scans</summary> Use `uvx agent-bom scan .` without a global install, or `uvx agent-bom check requests@2.33.0 --ecosystem pypi` before adding a package. For automatic dependency and secret gates, see [pre-commit and CI setup](docs/DEPLOYMENT.md#pre-commit-hook). `agent-bom db update --osv-ecosystem PyPI` covers only the selected ecosystem; add the ecosystems you need before running `agent-bom scan . --offline`. The full `agent-bom db update --source osv` archive can exceed 1 GB; the command shows live progress. 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) </details> <p align="center"><a href="docs/images/context-map-horizontal-dark-live.png"><picture><source media="(prefers-color-scheme: light)" srcset="docs/images/context-map-horizontal-light-live.png"><img src="docs/images/context-map-horizontal-dark-live.png" alt="Recorded agent connections linking a role, agents, MCP servers, tool, credential reference, package and finding" width="960"></picture></a></p> Run it as a CLI, in CI, as an MCP server for your assistant, or as a self-hosted dashboard; Apache-2.0, and the control plane runs in your own environment. A recorded relationship is evidence to investigate; it does not prove execution or data access. The map above uses labeled sample data. To trace one vulnerable dependency to the affected agents and into remediation, [try the connected-BOM walkthrough](examples/connected-bom/README.md). ## Self-host in your environment **Your infrastructure, your identity, your database, your audit boundary.** From a [published release checkout](https://github.com/msaad00/agent-bom/releases): ```bash git clone --depth 1 --branch v0.108.4 https://github.com/msaad00/agent-bom.git && cd agent-bom AGENT_BOM_IMAGE_TAG=0.108.4 docker compose up -d ``` Open **http://localhost:3000**, then **Connections** or **New Scan**. For cloud accounts, add a scoped read-only connection, verify access, then start a scan. The pilot binds to loopback and retains state in a Docker volume. Use the authenticated deployment guide for a shared instance. ### Deployment models [Docker pilot](docs/DEPLOY_QUICKSTART.md) · [Authenticated deployment](site-docs/deployment/authenticated-hosted-instance.md) · [Compose with PostgreSQL](deploy/docker-compose.platform.yml) · [Helm](site-docs/deployment/control-plane-helm.md) · [EKS Terraform](deploy/terraform/platform-eks) · [Snowflake Native App preview](docs/snowflake-native-app/INSTALL.md) · [Air-gapped bundle](site-docs/deployment/airgapped-image-bundle.md) · [Choose a deployment](site-docs/deployment/overview.md) · [Enterprise configuration](docs/ENTERPRISE.md) · [Connect cloud accounts](docs/CLOUD_CONNECT.md) <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. [Integration capability matrix](docs/INTEGRATIONS.md) · [MCP client setup](docs/MCP_CLIENT_GUIDES.md) · [Proxy, gateway and fleet](site-docs/deployment/proxy-vs-gateway-vs-fleet.md) · [Smithery setup and manifest](site-docs/integrations/smithery.md) </details> ## Built for the teams that build, secure and govern AI | Your team | What you can do | |---|---| | **Developers & AI engineers** | Inspect repositories, dependencies and MCP configuration; bring findings into CI and coding assistants. | | **AppSec & cloud security** | Connect cloud accounts, trace findings through workloads and identities, and prioritize fixes by reachable impact. | | **Platform & DevOps** | Run a shared control plane, collect fleet evidence, and apply policy to MCP traffic through the proxy or gateway. | | **GRC & audit** | Open **Compliance** to review mappings and [export scan evidence](docs/GALLERY.md#scan-a-repository-before-shipping) with its source, freshness and assessment gaps. | | **Security & engineering leaders** | Open **Overview** to review posture, remediation priorities and tracked AI spend across connected sources. | | **AI assistants & automation** | Use [MCP workflows](docs/MCP_WORKFLOWS.md) to query evidence and inspect findings within the caller’s permissions. | ## Product tour ### Security, engineering and GRC: prioritize risk and assessment gaps Start with **Posture**, inspect evidence in **Top risks**, and scope inventory in **Assets & coverage**. **Compliance** separates evaluated-control pass rate from assessment coverage. OWASP and MITRE ATLAS risk mappings describe applicability, not control pass/fail. The offline synthetic enterprise estate includes evaluated checks; results do not establish certification or an audit opinion. <p align="center"><a href="docs/images/dashboard-live.png"><img src="docs/images/dashboard-live.png" alt="Posture and open findings with compliance and security-area disclosures collapsed in a labeled sample environment" width="1440"></a></p> Explore [expanded framework evidence](docs/images/dashboard-paths-live.png), [Top risks](docs/images/dashboard-risks-live.png), [scoped Inventory](docs/images/inventory-live.png), [recorded scan history](docs/GALLERY.md#compare-recorded-scan-history), [framework controls and evidence](site-docs/features/compliance.md), and the [per-agent BOM preview](docs/SCAN_EVIDENCE_JOURNEY.md). ### AppSec and cloud teams: explain why a finding matters Follow **CVE-2023-4863 in pillow@9.0.0** through recorded relationships between the service, container, tool, workload identity and modeled data asset. Inspect the source receipts and carry the selected finding into remediation. A recorded path does not by itself prove exploitation or successful data access. <a href="docs/images/correlation-graph-live.png"><img src="docs/images/correlation-graph-live.png" alt="Reference lab path linking a Pillow advisory, workload identity and modeled data asset" width="1440"></a> <details> <summary>Explore graph navigation, permissions and evidence</summary> Choose a scope in **Summary**, then **Inspect** an entity. Filter by type or severity, set direction and hop limits, and expand bounded pages; incomplete views are labeled. In **Context**, use **Focus here**, **Back**, or an exact identifier. Select a node or arrow to inspect its evidence, freshness and unknowns. **Investigate reach & permissions** opens permission receipts, CVE prerequisites and related activity; missing exploitability stays **not assessed**. [Investigation workflow](site-docs/architecture/security-graph-model.md#investigate-an-agent-from-context). **Connect data locations to security evidence.** Explore recorded stores and datasets alongside identities and findings. Distinguish storage, access evidence and collection sources; derived classifications do not prove contents or successful reads. [Data and evidence model](site-docs/architecture/security-graph-model.md#data-locations-access-and-evidence-sources). </details> ### Engineers and GRC: turn exposure into an accountable fix Connect the upgrade decision, the responsible owner and the evidence needed to close the risk. | Decision | Engineering and governance evidence | |---|---| | **What do we fix first?** | Prioritize package upgrades using severity, recorded agent and credential associations, and available fixes. | | **Who owns the work?** | Assign owners and SLAs, link tickets, and track remediation campaigns. | | **Did the fix hold?** | Re-scan the same scope, compare retained findings, and verify the campaign before closing it. | | **What supports the control review?** | Review evaluated checks, source receipts and assessment gaps; export scoped evidence. A control mapping alone is not a passing check. | <p align="center"><a href="docs/images/remediation-live.png"><img src="docs/images/remediation-live.png" alt="Sample remediation plan with package fixes, affected agents, credential associations and an owner/SLA verification workflow" width="1440"></a></p> [Run the before-and-after dependency example](examples/connected-bom/README.md) · [Review component control evidence](docs/images/component-controls-dark-live.png) · [Compliance evidence workflow](site-docs/features/compliance.md) These are application captures, not mockups. Overview, Findings and remediation use labeled sample data. The graph uses the reproducible reference lab: real parsers, a pinned advisory scan and authenticated gateway calls, with modeled infrastructure. A blocked call does not establish that the underlying package was fixed. [Discover and scan](docs/GALLERY.md) · [Runtime policy and agent workflows](site-docs/deployment/proxy-vs-gateway-vs-fleet.md) · [Run the reference evidence lab](examples/reference-evidence-lab/README.md) · [Evidence workflow](docs/HOW_IT_WORKS.md) · [Control-plane architecture](docs/ARCHITECTURE.md) ## Trust and evidence Discovery uses read-only access by default. Explicit disk side-scans create temporary cloud resources; runtime enforcement acts on selected tool calls. Missing evidence stays unavailable or partial. Control mappings are not audit certification. [Product boundaries](docs/PRODUCT_BOUNDARIES.md) · [Permissions](docs/PERMISSIONS.md) · [Threat model](docs/THREAT_MODEL.md) · [Security policy](SECURITY.md) · [Release verification](docs/RELEASE_VERIFICATION.md) · [Measured matcher proof](site-docs/features/scanning.md#reproducible-matching-evidence) · [Graph workload: command, receipt and limits](docs/perf/graph-mixed-load.md) ## Contributing and support [Contributing](CONTRIBUTING.md) · [Support](SUPPORT.md) · [Open issues](https://github.com/msaad00/agent-bom/issues) · [Apache-2.0 license](LICENSE) Source version: **v0.108.4** · Latest release: **v0.108.4** · [Changelog](CHANGELOG.md)