zeroclaw/docs/operations/ghcr-vulnerability-policy.md

GHCR Vulnerability Gate Policy

This document defines the vulnerability scanning gate contract for GHCR release publishes.

Policy Source

• Machine policy: .github/release/ghcr-vulnerability-policy.json
• Enforcement script: scripts/ci/ghcr_vulnerability_gate.py
• Workflow integration: .github/workflows/pub-docker-img.yml (publish job)

Scope

For each stable release publish, Trivy scan evidence must exist for all required tag classes:

1. release (vX.Y.Z)
2. sha (sha-<12>)
3. latest

The policy requires these scan reports to be machine-readable and validated before publish is considered complete.

Publish flow also runs a pre-push Trivy gate on a local release-candidate image:

• CRITICAL findings block image publish
• HIGH findings are reported as advisory warnings

Blocking Rule

Policy field blocking_severities defines which severities are merge-blocking for publish.

Default policy:

• CRITICAL

max_blocking_findings_per_tag is 0, so any blocking finding fails the gate.

HIGH findings are still collected and published in Trivy artifacts and run summaries, but are advisory-only to avoid blocking urgent patch releases on non-critical CVEs.

Parity Rules

To keep tags consistent and auditable, the gate can enforce parity checks:

• blocking finding count parity across required tags
• artifact ID parity across required tags

If parity is broken, gate validation fails and publish traceability is marked not ready.

Artifacts and Retention

Publish run emits:

• ghcr-vulnerability-gate.json
• ghcr-vulnerability-gate.md
• audit-event-ghcr-vulnerability-gate.json
• Trivy reports (.sarif, .txt, .json) for release/sha/latest references

Retention defaults:

• Trivy scan artifacts: 14 days
• Vulnerability gate audit artifacts: 21 days

These values are defined in .github/release/ghcr-vulnerability-policy.json.