Metadata-Version: 2.4
Name: agent-bom
Version: 0.68.1
Summary: Security scanner for AI infrastructure. Discover MCP configs (21 clients), scan for CVEs (OSV/NVD/EPSS/KEV), map blast radius to reachable credentials and tools, runtime proxy with 7 detectors, 30 MCP tools, CIS benchmarks (AWS/Azure/GCP/Snowflake), MITRE ATT&CK mapping, and 11-framework compliance.
Author-email: Wagdy Saad <andwgdysaad@gmail.com>
License: Apache-2.0
Project-URL: Homepage, https://github.com/msaad00/agent-bom
Project-URL: Repository, https://github.com/msaad00/agent-bom
Project-URL: Issues, https://github.com/msaad00/agent-bom/issues
Project-URL: Changelog, https://github.com/msaad00/agent-bom/releases
Project-URL: Documentation, https://github.com/msaad00/agent-bom#readme
Project-URL: Security Policy, https://github.com/msaad00/agent-bom/blob/main/SECURITY.md
Project-URL: Trust & Permissions, https://github.com/msaad00/agent-bom/blob/main/PERMISSIONS.md
Keywords: ai-bom,sbom,mcp,mcp-server,security,ai-agents,vulnerability,supply-chain,owasp,mitre-atlas,nist-ai-rmf,grype,syft,blast-radius,cve,llm-security,remediation,mcp-introspection,openclaw,ai-enrichment,credential-exposure,config-security,ai-supply-chain,ai-infrastructure,gpu-security,cuda,pytorch,openssf-scorecard,malicious-package-detection,runtime-monitoring,model-provenance
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Environment :: Console
Classifier: Topic :: Security
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
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
Requires-Dist: jinja2>=3.1.6
Requires-Dist: werkzeug>=3.1.6
Requires-Dist: requests>=2.32.4
Requires-Dist: nltk>=3.9.3
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"
Requires-Dist: protobuf>=3.20.2; extra == "otel"
Provides-Extra: ui
Requires-Dist: agent-bom[api]; extra == "ui"
Provides-Extra: aws
Requires-Dist: boto3>=1.34; extra == "aws"
Provides-Extra: azure
Requires-Dist: azure-identity>=1.15; extra == "azure"
Requires-Dist: azure-mgmt-cognitiveservices>=13.5; extra == "azure"
Requires-Dist: azure-mgmt-web>=7.2; extra == "azure"
Requires-Dist: azure-mgmt-containerinstance>=10.1; extra == "azure"
Requires-Dist: azure-mgmt-machinelearningservices>=1.0; extra == "azure"
Requires-Dist: azure-mgmt-containerservice>=30.0; extra == "azure"
Requires-Dist: azure-mgmt-resource>=23.0; extra == "azure"
Provides-Extra: gcp
Requires-Dist: google-cloud-aiplatform>=1.38; extra == "gcp"
Requires-Dist: google-cloud-functions>=1.16; extra == "gcp"
Requires-Dist: google-cloud-container>=2.36; extra == "gcp"
Requires-Dist: google-cloud-run>=0.10; extra == "gcp"
Requires-Dist: google-cloud-resource-manager>=1.12; extra == "gcp"
Provides-Extra: coreweave
Provides-Extra: databricks
Requires-Dist: databricks-sdk>=0.20; extra == "databricks"
Provides-Extra: snowflake
Requires-Dist: snowflake-connector-python>=3.6; extra == "snowflake"
Provides-Extra: nebius
Requires-Dist: requests>=2.32.4; extra == "nebius"
Provides-Extra: huggingface
Requires-Dist: huggingface-hub>=0.20; extra == "huggingface"
Provides-Extra: wandb
Requires-Dist: wandb>=0.16; extra == "wandb"
Provides-Extra: mlflow
Requires-Dist: mlflow>=2.10; extra == "mlflow"
Provides-Extra: openai
Requires-Dist: openai>=1.12; extra == "openai"
Provides-Extra: ai-enrich
Requires-Dist: litellm>=1.30; extra == "ai-enrich"
Provides-Extra: graph
Requires-Dist: networkx>=3.0; extra == "graph"
Provides-Extra: postgres
Requires-Dist: psycopg[binary]>=3.1; extra == "postgres"
Requires-Dist: psycopg-pool>=3.1; extra == "postgres"
Provides-Extra: watch
Requires-Dist: watchdog>=4.0; extra == "watch"
Provides-Extra: runtime
Requires-Dist: psutil>=5.9; extra == "runtime"
Provides-Extra: mcp-server
Requires-Dist: mcp>=1.26; extra == "mcp-server"
Requires-Dist: smithery>=0.4; extra == "mcp-server"
Provides-Extra: dashboard
Requires-Dist: streamlit>=1.37.0; extra == "dashboard"
Requires-Dist: plotly>=5.18; extra == "dashboard"
Requires-Dist: pillow>=10.4.0; extra == "dashboard"
Provides-Extra: snyk
Provides-Extra: oidc
Requires-Dist: PyJWT>=2.8; extra == "oidc"
Requires-Dist: cryptography>=41.0; extra == "oidc"
Provides-Extra: cloud
Requires-Dist: agent-bom[aws]; extra == "cloud"
Requires-Dist: agent-bom[azure]; extra == "cloud"
Requires-Dist: agent-bom[gcp]; extra == "cloud"
Requires-Dist: agent-bom[databricks]; extra == "cloud"
Requires-Dist: agent-bom[snowflake]; extra == "cloud"
Requires-Dist: agent-bom[nebius]; extra == "cloud"
Requires-Dist: agent-bom[huggingface]; extra == "cloud"
Requires-Dist: agent-bom[wandb]; extra == "cloud"
Requires-Dist: agent-bom[mlflow]; extra == "cloud"
Requires-Dist: agent-bom[openai]; extra == "cloud"
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"
Requires-Dist: pytest-cov>=4.1; extra == "dev"
Dynamic: license-file

    agent-bom

  Scan your AI infrastructure. Enforce it at runtime.
  CVEs, blast radius, credential exposure, 11 compliance frameworks — then proxy MCP traffic and enforce policy in real time.

---

## Quick start

```bash
pip install agent-bom        # install
agent-bom scan               # auto-discover MCP configs + scan
agent-bom scan --enrich      # + NVD CVSS + EPSS + CISA KEV enrichment
```

That's it. agent-bom discovers your MCP client configs (Claude Desktop, Cursor, Windsurf, and 18 more), resolves every server's dependencies, checks them against OSV/NVD/GHSA, and maps the blast radius — which agents, credentials, and tools are affected by each vulnerability.

  agent-bom demo — scan, CVE check before/after, GPU infra scan

    agent-bom scan output with GPU infrastructure scan

---

## Why agent-bom?

> **Traditional scanners tell you a package has a CVE.**
> **agent-bom tells you which AI agents are compromised, which credentials leak, which tools an attacker reaches — and then blocks it in real time.**

Three capabilities, one tool: **scanner** (CVEs, blast radius, compliance, supply chain) + **proxy** (intercepts MCP traffic, enforces policy, detects 7 behavioral attack patterns) + **instruction file trust** (audits CLAUDE.md, .cursorrules, AGENTS.md, SKILL.md for malicious patterns, typosquatting, and Sigstore provenance). Read-only. Agentless. Open source.

```
CVE-2025-1234  (CRITICAL . CVSS 9.8 . CISA KEV)
  |-- better-sqlite3@9.0.0  (npm)
       |-- sqlite-mcp  (MCP Server . unverified . root)
            |-- Cursor IDE  (Agent . 4 servers . 12 tools)
            |-- ANTHROPIC_KEY, DB_URL, AWS_SECRET  (Credentials exposed)
            |-- query_db, read_file, write_file, run_shell  (Tools at risk)

 Fix: upgrade better-sqlite3 -> 11.7.0
```


    Blast Radius

---

## MCP server

30 tools available to any MCP-compatible AI assistant.

```bash
pip install 'agent-bom[mcp-server]'
agent-bom mcp-server
```

Add to your MCP client config (Claude Desktop, Cursor, etc.):

```json
{
  "mcpServers": {
    "agent-bom": {
      "command": "agent-bom",
      "args": ["mcp-server"]
    }
  }
}
```

Also available on [Glama](https://glama.ai/mcp/servers/@msaad00/agent-bom), [Smithery](smithery.yaml), [MCP Registry](integrations/mcp-registry/server.json), and [OpenClaw](integrations/openclaw/SKILL.md).

---

## Docker

```bash
docker run --rm -v ~/.config:/root/.config:ro agentbom/agent-bom scan
docker run --rm agentbom/agent-bom scan --image nginx:latest
docker run --rm agentbom/agent-bom mcp-server   # MCP server mode
```

---

## Instruction file trust

AI agents run on instruction files — CLAUDE.md, .cursorrules, AGENTS.md, SKILL.md. A malicious or compromised instruction file is a supply chain attack that executes with full agent permissions. agent-bom audits every instruction file it finds.

```
agent-bom scan --skill-only

CLAUDE.md  →  SUSPICIOUS (high confidence)
  [CRITICAL] Credential/secret file access
             "cat ~/.aws/credentials" detected — reads secret files
  [HIGH]     Safety confirmation bypass
             "--dangerously-skip-permissions" found — disables all guardrails
  [HIGH]     Typosquatting risk: server name "filessystem" (→ filesystem)
  [MEDIUM]   External URL in instructions: https://malicious-cdn.com/hook.js

  Trust categories
    Purpose & Capability  WARN  — description vs. actual tool mismatch
    Instruction Scope     FAIL  — file reads outside home directory
    Install Mechanism     FAIL  — unverified install source, no Sigstore sig
    Credentials           WARN  — 3 env vars undocumented
    Persistence/Privilege PASS  — no persistence, no privilege escalation
```

Five trust categories, 17 behavioral risk patterns, Sigstore signature verification. No network calls — fully local static analysis.

---

## How it works

1. **Discover** -- auto-detect MCP configs, Docker images, K8s pods, cloud resources, model files
2. **Scan** -- send package names + versions to public APIs (OSV.dev, NVD, EPSS, CISA KEV). No secrets leave your machine.
3. **Analyze** -- blast radius mapping, tool poisoning detection, compliance tagging, posture scoring
4. **Track** -- persistent asset database records first_seen, last_seen, resolved status, and MTTR per vulnerability across scans
5. **Report** -- JSON, SARIF, CycloneDX, SPDX, HTML, Mermaid, or console. Alert dispatch to Slack/webhooks.

    Scan pipeline

**Read-only guarantee.** Never writes configs, never runs servers, never stores secrets. `--dry-run` previews everything. Every release is [Sigstore-signed](PERMISSIONS.md).

---

## CLI reference

Scanning options

```bash
agent-bom scan                                     # auto-discover + scan
agent-bom scan --enrich                            # + NVD CVSS + EPSS + CISA KEV
agent-bom scan -f html -o report.html              # HTML dashboard
agent-bom scan --enforce                           # tool poisoning detection
agent-bom scan --fail-on-severity high -q          # CI gate
agent-bom scan --image myapp:latest                # Docker image scanning
agent-bom scan --k8s --all-namespaces              # K8s image scanning (cluster-wide)
agent-bom scan --k8s-mcp                           # Discover MCP pods + CRDs in Kubernetes
agent-bom scan --include-processes                 # Scan running host MCP processes (psutil)
agent-bom scan --include-containers                # Scan Docker containers for MCP servers
agent-bom scan --health-check                      # Probe discovered servers for liveness
agent-bom scan --siem splunk --siem-url https://...  # Push findings to SIEM
agent-bom scan --aws --snowflake --databricks      # Multi-cloud
agent-bom scan --hf-model meta-llama/Llama-3.1-8B  # model provenance
agent-bom scan --vector-db-scan                    # Scan self-hosted + Pinecone cloud vector DBs
agent-bom scan --gpu-scan                          # Discover GPU containers + K8s nodes, detect unauthenticated DCGM exporters
agent-bom scan --browser-extensions               # Scan Chrome/Edge/Firefox extensions for dangerous permissions
agent-bom scan --skill-only                       # Audit AI instruction files (CLAUDE.md, .cursorrules, AGENTS.md)
agent-bom scan --save report.json                  # Save + track assets (first_seen, resolved, MTTR)
agent-bom graph report.json --format dot           # Export dependency graph (DOT/Mermaid/JSON)
agent-bom proxy-configure --apply                  # Auto-wrap MCP configs with security proxy
```


Runtime enforcement

Sit between your MCP client and server, enforce policy in real time:

```bash
# Wrap a single server — intercept every tool call
agent-bom proxy --command "uvx mcp-server-filesystem /" --policy policy.yml

# Protect mode — run standalone detector engine
agent-bom protect --mode http

# Watch MCP configs for drift — alert on changes
agent-bom watch --webhook https://hooks.slack.com/...

# Introspect a live MCP server — list tools, detect drift
agent-bom introspect --command "uvx mcp-server-filesystem /"
agent-bom introspect --all                                         # auto-discover all configured servers
agent-bom introspect --all --baseline baseline.json               # exit 1 on new/removed tools

# Policy file — 17 conditions, zero code required
# policy.yml:
#   blocked_tools: [run_shell, exec_command]
#   require_agent_identity: true
#   rate_limit: {threshold: 50, window_seconds: 60}
```


Auto-discovers 21 MCP clients: Claude Desktop, Claude Code, Cursor, Windsurf, Cline, VS Code Copilot, Continue, Zed, Cortex Code, Codex CLI, Gemini CLI, Goose, Snowflake CLI, OpenClaw, Roo Code, Amazon Q, ToolHive, Docker MCP Toolkit, JetBrains AI, Junie, and custom paths.

    MCP Topology

---

## What it covers

agent-bom vs. traditional scanners

| | Traditional scanners | agent-bom |
|---|---|---|
| Package CVE detection | Yes | Yes (OSV + NVD + EPSS + CISA KEV + GHSA + NVIDIA CSAF) |
| SBOM generation | Yes | Yes (CycloneDX 1.6, SPDX 3.0, SARIF) |
| **AI agent discovery** | -- | 21 MCP clients + Docker Compose + running processes + containers + K8s pods/CRDs |
| **GPU/ML package scanning** | -- | NVIDIA CSAF advisories for CUDA, cuDNN, PyTorch, TensorFlow, JAX, vLLM + AMD ROCm via OSV |
| **AI supply chain** | -- | Model provenance (pickle risk, digest, gating), HuggingFace Hub, Ollama, MLflow, W&B |
| **AI cloud inventory** | -- | Coreweave, Nebius, Snowflake, Databricks, OpenAI, HuggingFace Hub — config discovery + CVE tagging |
| **Blast radius mapping** | -- | CVE -> package -> server -> agent -> credentials -> tools |
| **Credential exposure** | -- | Which secrets leak per vulnerability, per agent |
| **Tool poisoning detection** | -- | Description injection, capability combos, drift detection |
| **Privilege detection** | -- | root, shell access, privileged containers, per-tool permissions |
| **11-framework compliance** | -- | OWASP LLM + MCP + Agentic + AISVS v1.0, MITRE ATLAS, NIST AI RMF + CSF, EU AI Act, SOC 2, ISO 27001, CIS |
| **MITRE ATT&CK mapping** | -- | Dynamic technique lookup by tactic phase (no hardcoded T-codes) |
| **Posture scorecard** | -- | Letter grade (A-F), 6 dimensions, incident correlation (P1-P4) |
| **Policy-as-code + Jira** | -- | 17 conditions, CI gate, auto-create Jira tickets for violations |
| **SIEM push** | -- | Splunk HEC, Datadog Logs, Elasticsearch — raw or OCSF format |
| **Proxy auto-configure** | -- | Wrap every MCP server config with `agent-bom proxy` in one command |
| **Server health checks** | -- | Lightweight liveness probe — reachable, tool count, latency, protocol |
| **Lateral movement analysis** | -- | Agent context graph, shared credentials, BFS attack paths |
| **427+ server MCP registry** | -- | Risk levels, tool inventories, auto-synced weekly |
| **Cloud vector DB scanning** | -- | Pinecone index inventory, risk flags, replica counts via API key |
| **Dependency graph export** | -- | DOT, Mermaid, JSON — agent → server → package → CVE graph |
| **OIDC/SSO authentication** | -- | JWT verification (Okta, Google, Azure AD, Auth0) for REST API |
| **Instruction file trust** | -- | SKILL.md/CLAUDE.md/.cursorrules — 17 behavioral patterns, typosquat detection, Sigstore provenance verification |
| **Browser extension scanning** | -- | Chrome/Edge/Firefox manifest.json — nativeMessaging, dangerous permissions, AI assistant domain access |
| **Persistent asset tracking** | -- | SQLite DB — first_seen/last_seen/resolved/reopened per vulnerability, MTTR calculation, scan-over-scan diff |

What it scans

| Source | How |
|--------|-----|
| MCP configs | Auto-discover (21 clients + Docker Compose) |
| Docker images | Grype / Syft / Docker CLI fallback |
| Kubernetes | kubectl across namespaces |
| Cloud providers | AWS, Azure, GCP, Databricks, Snowflake, Coreweave, Nebius |
| AI cloud services | OpenAI, HuggingFace Hub, W&B, MLflow, Ollama |
| GPU/ML packages | PyTorch, TF, JAX, vLLM, CUDA toolkit, cuDNN, TensorRT, ROCm |
| Terraform / GitHub Actions | AI resources + env vars |
| Jupyter notebooks | AI library imports + model refs |
| Model files | 13 formats (.gguf, .safetensors, .pkl, ...) |
| Skill files | CLAUDE.md, .cursorrules, AGENTS.md — behavioral audit, typosquat detection, Sigstore trust verification |
| Browser extensions | Chrome, Brave, Edge, Firefox — dangerous permission detection (nativeMessaging, cookies, AI host access) |
| Existing SBOMs | CycloneDX / SPDX import |

What it outputs

Console, HTML dashboard, SARIF, CycloneDX 1.6, SPDX 3.0, Prometheus, OTLP, JSON, Mermaid, Cytoscape graph JSON, REST API.

```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 sarif -o results.sarif           # GitHub Security tab
agent-bom scan -f html -o report.html              # Interactive dashboard
agent-bom scan -f graph -o graph.json              # Cytoscape-compatible
```


    Compliance coverage

---

## Deployment

| Mode | Command | Best for |
|------|---------|----------|
| CLI | `agent-bom scan` | Local audit |
| GitHub Action | `uses: msaad00/agent-bom@v0.68.1 | CI/CD + SARIF |
| Docker | `docker run agentbom/agent-bom scan` | Isolated scans (linux/amd64, linux/arm64) |
| REST API | `agent-bom api` | Dashboards, SIEM |
| MCP Server | `agent-bom mcp-server` (30 tools) | Inside any MCP client |
| Dashboard | `agent-bom serve` · [Full deploy guide](docs/DEPLOYMENT.md) | API + Next.js UI (15 pages) · Postgres/Supabase |
| Runtime proxy | `agent-bom proxy` | Intercept + enforce MCP traffic in real time |
| Protect engine | `agent-bom protect` | 7 behavioral detectors (rug pull, injection, exfil, credential leak) |
| Config watcher | `agent-bom watch` | Filesystem watch on MCP configs, alert on drift |
| Pre-install guard | `agent-bom guard pip install <pkg>` | Block vulnerable installs |
| Snowflake | [DEPLOYMENT.md](DEPLOYMENT.md) | Snowpark + SiS |

Install extras

| Mode | Command |
|------|---------|
| Core CLI | `pip install agent-bom` |
| Cloud (all) | `pip install 'agent-bom[cloud]'` |
| REST API | `pip install 'agent-bom[api]'` |
| MCP server | `pip install 'agent-bom[mcp-server]'` |
| OIDC/SSO auth | `pip install 'agent-bom[oidc]'` |
| Dashboard | `pip install 'agent-bom[ui]'` |
| Docker | `docker run --rm -v ~/.config:/root/.config:ro agentbom/agent-bom scan` |

GitHub Action

```yaml
- uses: msaad00/agent-bom@v0.68.1
  with:
    severity-threshold: high
    upload-sarif: true
    enrich: true
    fail-on-kev: true
```


REST API

```bash
pip install agent-bom[api]
agent-bom api --api-key $SECRET --rate-limit 30   # http://127.0.0.1:8422/docs
```

| Endpoint | Description |
|----------|-------------|
| `POST /v1/scan` | Start async scan |
| `GET /v1/scan/{id}` | Results + status |
| `GET /v1/scan/{id}/attack-flow` | Per-CVE blast radius graph |
| `GET /v1/registry` | 427+ server registry |
| `GET /v1/compliance` | Full 11-framework compliance posture |
| `GET /v1/posture` | Enterprise posture scorecard (A-F) |
| `GET /v1/posture/credentials` | Credential risk ranking |
| `GET /v1/posture/incidents` | Incident correlation (P1-P4) |
| `POST /v1/traces` | OpenTelemetry trace ingestion |
| `GET /v1/scan/{id}/context-graph` | Lateral movement paths |
| `GET /v1/malicious/check` | Malicious package check |
| `GET /v1/proxy/status` | Live proxy metrics (tool calls, blocked, latency p95) |
| `GET /v1/proxy/alerts` | Runtime behavioral alerts from audit log |
| `GET /v1/audit` | Query JSONL audit trail (HMAC integrity verified) |
| `WS /ws/proxy/metrics` | Live metrics push every second (tool_calls, blocked, latency_p95) |
| `GET /v1/assets` | Persistent vulnerability asset inventory (first_seen, resolved, MTTR) |
| `GET /v1/assets/stats` | Aggregate asset statistics — open/resolved/critical counts |
| `WS /ws/proxy/alerts` | Real-time alert stream — new alerts arrive as they happen |

Pre-install guard

Scan packages against OSV and NVD **before** they are installed. Blocks installs when critical/high CVEs are found.

```bash
agent-bom guard pip install requests flask   # scan then install
agent-bom guard npm install express          # same for npm

# Shell alias — intercept every install automatically
alias pip='agent-bom guard pip'
alias npm='agent-bom guard npm'
```

Options:
- `--min-severity` — minimum severity to block (`critical`, `high`, `medium`; default: `high`)
- `--allow-risky` — warn but proceed instead of blocking

Cloud providers

| Provider | Depth | Install |
|----------|-------|---------|
| **Snowflake** | Deep (Cortex, MCP, governance, observability) | `pip install 'agent-bom[snowflake]'` |
| **AWS** | Standard (Bedrock, Lambda, EKS, ECS, SageMaker) | `pip install 'agent-bom[aws]'` |
| **Azure** | Standard (OpenAI, Functions, AI Foundry, Container Apps) | `pip install 'agent-bom[azure]'` |
| **GCP** | Standard (Vertex AI, Cloud Functions, GKE, Cloud Run) | `pip install 'agent-bom[gcp]'` |
| **Databricks** | Preview (Cluster packages, model serving) | `pip install 'agent-bom[databricks]'` |
| **Nebius** | Preview (Managed K8s, containers) | `pip install 'agent-bom[nebius]'` |
| **CoreWeave** | Via K8s | `--k8s --context=coreweave-cluster` |

Docker platform support

Docker images are published for **linux/amd64** and **linux/arm64**. Both architectures are validated in CI on every PR.

| Platform | Method | Notes |
|----------|--------|-------|
| Linux x64 / arm64 | Docker | Native support |
| macOS (Intel / Apple Silicon) | Docker Desktop | Runs Linux containers via virtualization |
| Windows x64 | Docker Desktop (WSL 2) | Runs Linux containers; mount `%APPDATA%` paths for MCP config discovery |
| Windows Server | Python CLI | `pip install agent-bom` -- no Docker Desktop required |

Windows-specific volume mount examples and GPU scanning notes: [docs/WINDOWS_CONTAINERS.md](docs/WINDOWS_CONTAINERS.md)

Upgrade / Uninstall

```bash
pip install --upgrade agent-bom          # upgrade
pip uninstall agent-bom                  # uninstall
rm -rf ~/.agent-bom                      # remove local data
```


---

## Ecosystem

| Platform | Link |
|----------|------|
| PyPI | `pip install agent-bom` |
| Docker | `docker run agentbom/agent-bom scan` |
| GitHub Action | `uses: msaad00/agent-bom@v0.68.1 |
| Glama | [glama.ai/mcp/servers/@msaad00/agent-bom](https://glama.ai/mcp/servers/@msaad00/agent-bom) |
| MCP Registry | [server.json](integrations/mcp-registry/server.json) |
| ToolHive | [registry entry](integrations/toolhive/server.json) |
| OpenClaw | [SKILL.md](integrations/openclaw/SKILL.md) |
| Smithery | [smithery.yaml](smithery.yaml) |
| Railway | [Dockerfile.sse](Dockerfile.sse) |

---

## Architecture

    Architecture stack

Engine internals

    Engine internals

See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for full diagrams: data flow pipeline, blast radius propagation, compliance framework mapping, integration architecture, and deployment topology.

---

## Trust & permissions

- **Read-only** -- never writes configs, runs servers, provisions resources, or stores secrets
- **Credential redaction** -- only env var **names** in reports; values never read or logged
- **No shell injection** -- subprocess uses `asyncio.create_subprocess_exec`; command + args validated before every spawn
- **No SSRF** -- all outbound URLs hardcoded or validated; DNS rebinding defense blocks private/loopback/cloud-metadata ranges
- **No path traversal** -- `validate_path(restrict_to_home=True)` on all user-supplied paths; MCP tool inputs sanitized
- **No SQL injection** -- all database queries use parameterized statements
- **Proxy size guard** -- messages >10 MB dropped before parsing; protects against DoS
- **Audit integrity** -- JSONL audit logs stored at `0600`, HMAC-signed (SHA-256). Set `AGENT_BOM_AUDIT_HMAC_KEY` in production for cross-restart verifiability.
- **API security** -- scrypt KDF for API keys, RBAC (admin/analyst/viewer), OIDC/JWT (RS256/ES256, `none` algorithm rejected), constant-time comparison
- **`--dry-run`** -- preview every file and API URL before access
- **Sigstore signed** -- releases v0.7.0+ signed via cosign OIDC
- **OpenSSF Scorecard** -- [automated supply chain scoring](https://securityscorecards.dev/viewer/?uri=github.com/msaad00/agent-bom)
- **OpenSSF Best Practices** -- [passing badge (100%)](https://www.bestpractices.dev/projects/12114) — 67/67 criteria
- **Continuous fuzzing** -- [ClusterFuzzLite](https://github.com/msaad00/agent-bom/blob/main/.github/workflows/cflite-pr.yml) fuzzes SBOM parsers, policy evaluator, and skill parser
- **[PERMISSIONS.md](PERMISSIONS.md)** -- full auditable trust contract

---

Roadmap

**GPU / AI compute**
- [x] GPU container discovery (Docker — NVIDIA images, CUDA labels, `--gpus` runtime)
- [x] Kubernetes GPU node inventory (nvidia.com/gpu capacity/allocatable, CUDA driver labels)
- [x] Unauthenticated DCGM exporter detection (port 9400 metrics leak)
- [ ] Remote Docker host scanning (currently local daemon only)
- [ ] NVIDIA GPU CVE feed — CUDA/cuDNN specific advisories beyond OSV
- [ ] GPU utilization and memory anomaly detection

**AI supply chain**
- [x] OSV + GHSA + NVD + EPSS + CISA KEV vulnerability enrichment
- [x] ML model file scanning (.gguf, .safetensors, .onnx) + SHA-256 + Sigstore
- [x] HuggingFace model provenance and dataset card scanning
- [ ] Dataset poisoning detection
- [ ] Training pipeline scanning (MLflow DAGs, Kubeflow pipelines)
- [ ] Model card authenticity verification (beyond hash/sigstore)

**Asset tracking / posture**
- [x] Persistent SQLite asset database — first_seen, last_seen, resolved, reopened per vulnerability
- [x] MTTR (Mean Time To Remediate) calculation across scans
- [x] Scan-over-scan diff — new, resolved, reopened, unchanged counts
- [x] REST API: `/v1/assets` + `/v1/assets/stats` for dashboard integration
- [ ] SLA enforcement — time-to-fix deadlines per severity (critical < 7d, high < 30d)
- [ ] Trend analytics — vulnerability count over time, resolution velocity

**Agents / MCP**
- [x] 21 MCP client config discovery paths, live introspection, tool drift detection
- [x] Runtime proxy with 7 behavioral detectors (rug pull, injection, credential leak, exfil sequences, response cloaking, vector DB injection, semantic injection scoring)
- [x] Semantic injection scoring — weighted 10-signal model, 0.0–1.0 risk score, MEDIUM/HIGH alerts
- [ ] Agent memory / vector store content scanning for injected instructions
- [ ] LLM API call tracing (which model was called, with what context)

**Identity / access**
- [x] OIDC/JWT auth for REST API (Okta, Google Workspace, Azure AD, Auth0, GitHub OIDC)
- [x] Agent-level identity — JWT/opaque token in `_meta.agent_identity`, tracked on every audit log entry, `require_agent_identity` policy enforcement
- [ ] MCP server identity attestation — cryptographic proof of server identity at runtime
- [ ] Agent-to-agent permission boundary enforcement

**Compliance / standards**
- [x] 11 frameworks: OWASP LLM, OWASP MCP, OWASP Agentic, OWASP AISVS v1.0, ATLAS, NIST AI RMF, EU AI Act, NIST CSF, ISO 27001, SOC 2, CIS Controls
- [ ] CIS AI benchmarks (pending CIS publication)
- [ ] License compliance engine (OSS license risk flagging)
- [ ] Workflow engine scanning (n8n, Zapier, Make)

**Ecosystem coverage**
- [ ] Maven / Go ecosystem — test coverage thin (PyPI, npm, cargo, pip best covered)
- [x] Windows platform docs + Docker Desktop guidance ([WINDOWS_CONTAINERS.md](docs/WINDOWS_CONTAINERS.md))
- [ ] Windows-native container images (nanoserver/servercore)

See the full list of [shipped features](https://github.com/msaad00/agent-bom/releases).

---

## Contributing

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

See [CONTRIBUTING.md](CONTRIBUTING.md) | [SECURITY.md](SECURITY.md) | [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)

---

Apache 2.0 -- [LICENSE](LICENSE)
