docs: sharpen CI/CD and enterprise adoption paths (#1152)

msaad00 · web-flow · commit 3ee2a9a55334 · 2026-03-30T05:32:36.000Z
## Summary
- add clearer Trivy-style CI/CD quickstarts to the README
- strengthen enterprise deployment guidance for GitHub Action, Docker,
air-gapped, and rollout paths
- align Docker Hub and MCP container description metadata with current
positioning

## Validation
- UV_CACHE_DIR=/tmp/agent-bom-uv-cache uv run python
scripts/check_release_consistency.py
diff --git a/.github/workflows/publish-mcp.yml b/.github/workflows/publish-mcp.yml
@@ -63,7 +63,7 @@ jobs:
             org.opencontainers.image.version=${{ steps.version.outputs.version }}
             org.opencontainers.image.source=https://github.com/${{ github.repository }}
             org.opencontainers.image.title=agent-bom
-            org.opencontainers.image.description=Security scanner for AI infrastructure — MCP server (stdio)
+            org.opencontainers.image.description=Open security platform for agentic infrastructure — MCP server (stdio)
             org.opencontainers.image.created=${{ github.event.workflow_run.created_at || github.event.repository.updated_at }}
             org.opencontainers.image.revision=${{ github.sha }}
 
@@ -128,7 +128,7 @@ jobs:
             org.opencontainers.image.version=${{ steps.version.outputs.version }}
             org.opencontainers.image.source=https://github.com/${{ github.repository }}
             org.opencontainers.image.title=agent-bom-sse
-            org.opencontainers.image.description=Security scanner for AI infrastructure — MCP server (streamable HTTP)
+            org.opencontainers.image.description=Open security platform for agentic infrastructure — MCP server (streamable HTTP)
             org.opencontainers.image.created=${{ github.event.workflow_run.created_at || github.event.repository.updated_at }}
             org.opencontainers.image.revision=${{ github.sha }}
 
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -135,7 +135,7 @@ jobs:
             org.opencontainers.image.version=${{ steps.meta.outputs.version }}
             org.opencontainers.image.source=https://github.com/${{ github.repository }}
             org.opencontainers.image.title=agent-bom
-            org.opencontainers.image.description=AI security scanner for agents, MCP, containers, cloud, and runtime
+            org.opencontainers.image.description=Open security scanner for agentic infrastructure: agents, MCP, containers, cloud, and runtime.
             org.opencontainers.image.created=${{ github.event.head_commit.timestamp }}
             org.opencontainers.image.revision=${{ github.sha }}
 
@@ -158,7 +158,7 @@ jobs:
             "https://hub.docker.com/v2/repositories/agentbom/agent-bom/" \
             -H "Authorization: Bearer ${TOKEN}" \
             -H "Content-Type: application/json" \
-            -d "{\"full_description\": ${DESCRIPTION}, \"description\": \"AI security scanner for agents, MCP, containers, cloud, and runtime\"}"
+            -d "{\"full_description\": ${DESCRIPTION}, \"description\": \"Open security scanner for agentic infrastructure: agents, MCP, containers, cloud, and runtime.\"}"
 
       - name: Clean up old Docker Hub tags (keep last 10)
         env:
diff --git a/README.md b/README.md
@@ -185,6 +185,51 @@ docker run --rm agentbom/agent-bom agents    # Docker
 | Shield SDK | `from agent_bom.shield import Shield` | In-process protection |
 | Dashboard | `agent-bom serve` | API + Next.js UI (20 pages) |
 
+### CI/CD in 60 seconds
+
+Use the GitHub Action when you want Trivy-style adoption: one step, one gate, SARIF in the Security tab, and a clean exit code for CI.
+
+**Repo + MCP + instruction files**
+
+```yaml
+- uses: msaad00/agent-bom@v0.75.12
+  with:
+    scan-type: scan
+    severity-threshold: high
+    upload-sarif: true
+    enrich: true
+    fail-on-kev: true
+```
+
+**Container image gate**
+
+```yaml
+- uses: msaad00/agent-bom@v0.75.12
+  with:
+    scan-type: image
+    scan-ref: ghcr.io/acme/agent-runtime:sha-abcdef
+    severity-threshold: critical
+```
+
+**IaC gate**
+
+```yaml
+- uses: msaad00/agent-bom@v0.75.12
+  with:
+    scan-type: iac
+    iac: Dockerfile,k8s/,infra/main.tf
+    severity-threshold: high
+```
+
+**Air-gapped / pre-synced CI**
+
+```yaml
+- uses: msaad00/agent-bom@v0.75.12
+  with:
+    auto-update-db: false
+    enrich: false
+```
+
 <details>
 <summary><b>GitHub Action</b></summary>
 
@@ -200,6 +245,15 @@ docker run --rm agentbom/agent-bom agents    # Docker
 
 </details>
 
+### Enterprise rollout
+
+- `Developer endpoints`: run `agent-bom agents` locally or via MDM for workstation inventory and posture.
+- `CI/CD`: use the GitHub Action for PR gates, SARIF upload, image gates, and IaC checks.
+- `Central security team`: deploy `agent-bom serve` for fleet ingestion, posture, and audit exports.
+- `Air-gapped / isolated`: run the Docker image with `--offline` and `auto-update-db: false` using a pre-synced local DB.
+
+See [docs/ENTERPRISE_DEPLOYMENT.md](docs/ENTERPRISE_DEPLOYMENT.md) for rollout patterns, auth models, and storage backends.
+
 <details>
 <summary><b>Install extras</b></summary>
 
diff --git a/docs/ENTERPRISE_DEPLOYMENT.md b/docs/ENTERPRISE_DEPLOYMENT.md
@@ -17,6 +17,8 @@ agent-bom is built on four security principles:
 
 ### 1. CI/CD Pipeline — scan on every PR
 
+Start with the same adoption pattern teams expect from Trivy or Grype: a single CI step that fails on policy, uploads SARIF, and produces artifacts security teams can review.
+
 ```yaml
 # GitHub Actions
 - uses: msaad00/agent-bom@v0.75.12
@@ -32,6 +34,35 @@ agent-bom is built on four security principles:
 **What leaves the machine:** package names + versions only (to OSV API).
 **Credentials:** never accessed — scans manifest files, not environments.
 
+**Common CI/CD patterns**
+
+```yaml
+# Container image gate
+- uses: msaad00/agent-bom@v0.75.12
+  with:
+    scan-type: image
+    scan-ref: ghcr.io/acme/agent-runtime:sha-abcdef
+    severity-threshold: critical
+
+# IaC gate
+- uses: msaad00/agent-bom@v0.75.12
+  with:
+    scan-type: iac
+    iac: Dockerfile,k8s/,infra/main.tf
+    severity-threshold: high
+
+# Air-gapped or fully cached CI
+- uses: msaad00/agent-bom@v0.75.12
+  with:
+    auto-update-db: false
+    enrich: false
+```
+
+**Recommended rollout**
+1. Start with `severity-threshold: critical` and `upload-sarif: true`.
+2. Turn on `enrich: true` and `fail-on-kev: true` after the baseline is clean.
+3. Add `policy` or `warn-on-severity` once teams are comfortable with the signal.
+
 ### 2. Endpoint Fleet — MDM-pushed scan
 
 For discovering MCP servers and AI agents on employee workstations:
@@ -116,6 +147,11 @@ docker run --rm \
 
 Multi-arch: `linux/amd64` + `linux/arm64`. Non-root container. SHA-pinned base image.
 
+**Best uses**
+- Isolated scans in CI where you do not want to install Python or Node.
+- Air-gapped environments with a pre-synced local vulnerability DB.
+- Reproducible image scans across developer laptops and build runners.
+
 ## Output Integration
 
 | Target | Command | Format |
@@ -147,3 +183,12 @@ agent-bom protects its own supply chain:
 - **Releases:** SLSA L3 provenance attestation + Sigstore signing
 - **No eval/exec:** zero `eval()`, `exec()`, or `shell=True` in production code
 - **Self-scan:** agent-bom scans itself on every merge (post-merge-self-scan.yml)
+
+## Adoption path by team
+
+| Team | First rollout step | Next step |
+|------|--------------------|-----------|
+| Developers | `agent-bom agents -p .` | `agent-bom skills scan .` + local `agent-bom check` |
+| AppSec / security engineering | GitHub Action with SARIF | Fleet API + policy-as-code gates |
+| Platform / DevOps | Docker image gate + IaC scan | Air-gapped DB sync + runtime proxy |
+| Enterprise security | Central `agent-bom serve` | Postgres/Snowflake/ClickHouse + webhook integrations |
