Agentic Workflow Matrix¶

Use this page to choose the first integration path for an AI-agent workflow. Each path should produce a concrete artifact before it moves into a control plane or runtime enforcement rollout.

Surface	Start with	Trust boundary	Evidence artifact	Move up to
Local CLI	`agent-bom scan --demo --offline`, then `agent-bom scan .`	Reads local agent and MCP configuration from the developer machine. No control-plane credentials required.	Terminal findings, JSON, SARIF, SBOM, HTML, graph export.	Scheduled scan, Docker, GitHub Action.
Claude, Cursor, Windsurf, VS Code, Cortex, Codex CLI	`agent-bom mcp server`	Exposes read-mostly security tools to the assistant. The assistant does not need direct scanner credentials beyond the local process boundary; Shield write actions require admin role, `shield:write` scope, and an audit reason.	MCP tool output, inventory, blast-radius answers, compliance checks, ranked `ExposurePath` JSON, deploy guidance.	Shared MCP configuration, skills, fleet sync.
GitHub Actions	`uses: msaad00/agent-bom@v0.98.3` with SARIF upload enabled	Runs in CI with repository-scoped token permissions. Fork PR behavior depends on GitHub security policy.	`agent-bom-results.sarif`, pull-request summary, code-scanning alert category.	Branch protection, required code scanning, artifact retention.
Skills and instruction files	`agent-bom skills scan . --policy skills-policy.yaml`	Reads repo-local instructions such as `AGENTS.md`, `CLAUDE.md`, `.cursorrules`, and `skills/*.md`.	Skill trust findings, referenced package and MCP inventory, credential-env names, policy warn/block result.	Signed skills, provenance verification, registry publishing.
Cloud and AI infrastructure	`agent-bom agents --preset enterprise` plus provider-specific flags only where credentials are approved.	Uses read-only provider APIs or local inventory files. Keep provider secrets in the operator boundary, not in repo docs.	Cloud, warehouse, GPU, model, dataset, and runtime package evidence.	Fleet sync, compliance exports, graph-backed findings.
Runtime proxy	`agent-bom proxy --no-isolate --log audit.jsonl --block-undeclared -- ...`	Wraps selected local MCP traffic. Policy can block before an upstream tool receives the call. Container containment requires a stdio MCP path plus a configured sandbox image or an existing container command.	Tier-A audit JSONL, policy decisions, runtime alerts, metrics, and sandbox posture when isolation is enabled.	Sidecar proxy, gateway policy pull, SIEM export.
Shared gateway	`agent-bom gateway serve --from-control-plane ...`	Centralizes auth, tenancy, routing, and policy for remote MCP upstreams.	Gateway health, policy evaluation, relay metrics, audit relay.	Helm/EKS gateway, tenant policies, autoscaling.
Shield SDK	`from agent_bom.shield import Shield`	Enforces allow/block decisions in-process where the application already sees tool calls.	Redacted alerts and application-local decisions.	Shared policy model, proxy/gateway parity, runtime monitoring.

Copy-Paste Workflows¶

Local Developer Scan¶

agent-bom scan --demo --offline
agent-bom scan . -f html -o agent-bom-report.html
agent-bom scan . -f sarif -o agent-bom-results.sarif

Produces local review artifacts without requiring a hosted service. Use this when the buyer or contributor needs to see the first finding path quickly.

CI Security Review¶

- uses: msaad00/agent-bom@v0.98.3
  with:
    scan-type: agents
    severity-threshold: high
    format: sarif
    upload-sarif: true
    pr-comment: true

Produces SARIF and pull-request evidence. If Code Scanning is empty, check the SARIF troubleshooting guide before changing scanner behavior.

Agent Decision Review¶

exposure_paths(tenant_id="default", limit=5, min_risk=70)
should_i_deploy(candidate="requests", tenant_id="default", block_risk=80)

Produces the same graph-backed investigation context a human sees in the UI, but as MCP tool output for an AI agent or coding assistant. should_i_deploy returns deploy guidance; it does not modify code, open pull requests, or mutate cloud resources.

Posture-change subscriptions are not shipped yet. The connector contract is tracked in Posture Event Streaming so future agent and SIEM push workflows share one event envelope.

Skills CI Gate¶

Fail the job on suspicious or malicious skills without authoring a policy file by setting skills-ci: true (equivalent to the CLI --ci flag, i.e. fail-on-verdict=suspicious):

- uses: msaad00/agent-bom@v0.98.3
  with:
    scan-type: skills
    scan-ref: .
    format: sarif
    output: agent-bom-skills.sarif
    upload-sarif: true
    skills-ci: true

For finer control, replace skills-ci with explicit gates and an optional policy file:

- uses: msaad00/agent-bom@v0.98.3
  with:
    scan-type: skills
    scan-ref: .
    format: sarif
    output: agent-bom-skills.sarif
    upload-sarif: true
    policy: skills-policy.yaml
    fail-on-verdict: suspicious
    warn-on-review-verdict: review
    fail-on-review-verdict: blocked

Locally, agent-bom skills scan . --ci (or AGENT_BOM_SKILLS_CI=1) produces the same non-zero exit on suspicious/malicious skills. Both produce skills SARIF with source locations, trust metadata, and policy results for GitHub code scanning. Discovery covers AGENTS.md, CLAUDE.md, .cursorrules, and *.md/*.mdc under skills/, prompts/, .cursor/rules, and .github/instructions — vendored trees (node_modules, .venv, …) are skipped. Use this lane for instruction files and skills; keep package, IaC, and SBOM gates in separate jobs when their policies or review owners differ.

Hosted Gateway Or Proxy Review¶

# Audit/policy only for a selected stdio MCP server.
agent-bom proxy --no-isolate --log audit.jsonl --block-undeclared -- npx @modelcontextprotocol/server-filesystem /workspace

# Add process containment by running the stdio MCP inside a pinned sandbox image.
agent-bom proxy \
  --sandbox-image ghcr.io/your-org/mcp-runtime:node20@sha256:<64-hex-digest> \
  --sandbox-image-pin-policy enforce \
  --sandbox-mount "$PWD:/workspace:ro" \
  --log audit.jsonl \
  --block-undeclared \
  -- npx @modelcontextprotocol/server-filesystem /workspace

agent-bom gateway serve \
  --from-control-plane https://agent-bom.example.com \
  --control-plane-token "$AGENT_BOM_CONTROL_PLANE_TOKEN" \
  --bearer-token "$AGENT_BOM_GATEWAY_BEARER_TOKEN"

Produces runtime audit and policy evidence for selected traffic. This is not a claim that all MCP traffic is governed; it proves the selected proxy or gateway path. Gateway policy governs remote MCP traffic; it does not containerize the upstream server.

Guardrails¶

Do not present roadmap integrations as shipped product.
Prefer read-only scan commands for first contact with a new environment.
Keep provider, gateway, and CI tokens in the operator boundary.
Record the command, artifact path, trust boundary, and next step in PRs and demos.
Runtime causality requires proxy, gateway, trace, or Shield evidence. Static scans show reachability and exposure, not live tool-call causality.
MCP server mode is read-mostly. Scanner and posture tools are read-only; use admin-gated Shield actions only when the question depends on selected live tool-call traffic.