feat: enterprise supply chain security — cosign keyless signing, SBOM attestation, SLSA provenance, Trivy scanning, Kyverno enforcement, ACT smoke validation

[Ryangr0]

Summary

This PR implements end-to-end software supply chain security for every container image published from this repository, targeting SLSA Build Level 2 and aligning with NIST SSDF (SP 800-218) and the CIS Software Supply Chain Security Guide.

No long-lived signing keys are required. Everything is driven by GitHub OIDC.

It also adds local ACT smoke-validation support so the supply-chain workflow shape can be validated before running in GitHub-hosted release jobs.

---

What this adds

🔐 Keyless image signing (cosign + GitHub OIDC)

Every released image is signed using cosign's keyless flow:

1. GitHub issues an OIDC token for the workflow invocation
2. cosign exchanges it with Sigstore's Fulcio CA for a short-lived X.509 certificate
3. The cert's SAN encodes the exact workflow identity: https://github.com/webgrip/infrastructure/.github/workflows/on_release_published.yml@refs/tags/<tag>
4. The signature + cert are stored in GHCR and recorded in the Rekor public transparency log

Forging this signature requires compromising GitHub's OIDC infrastructure, not just stealing a secret.

📦 SBOM generation + attestation (Syft + cosign)

Syft generates a full component inventory for every image in two formats:

• CycloneDX JSON — primary format; cosign-attested in the OCI registry; ingestible by Dependency-Track and GUAC
• SPDX JSON — ISO 5962:2021; NTIA minimum-element compliant; for license compliance tooling

Both SBOMs are also uploaded as 90-day workflow artifacts.

🏛️ SLSA Build Provenance (GitHub native attestations)

actions/attest-build-provenance records SLSA v1.0 Build Provenance in GitHub's attestation store and pushes it to the OCI registry. Verifiable with:

gh attestation verify oci://ghcr.io/webgrip/<image>@sha256:<digest> --owner webgrip

🛡️ Vulnerability scanning (Trivy)

Trivy scans every released image for OS and library CVEs:

• SARIF results uploaded to GitHub Security tab (Code scanning)
• Table summary printed in the build log
• Non-blocking by default (exit-code: 0) — findings are tracked, not release-blocking

🔒 Kyverno cluster enforcement policy

ops/kyverno/cluster-policies/verify-webgrip-images.yaml provides a ClusterPolicy for the homelab cluster that:

• Verifies the cosign signature at Pod admission time
• Verifies the CycloneDX SBOM attestation is present
• Mutates image tags to digest references (prevents tag-mutation attacks on running Pods)
• Ships in Audit mode — switch to Enforce once all images are signed

🧪 ACT local smoke validation

Adds ACT-focused validation support for the signing pipeline:

• Composite action now supports dry-run: 'true' to skip OIDC signing / registry mutation while still validating flow and outputs
• New ACT smoke workflow executes the composite action in dry-run mode
• Added ACT runner defaults and a sample release event payload for local simulation
• README now includes local ACT commands for both smoke and release-event simulation

---

Changed files

File	Change
.github/actions/cosign-sign-attest/action.yml	New/Updated — composite action for signing pipeline, now with ACT dry-run mode
.github/workflows/on_release_published.yml	Updated — release signing jobs
.github/workflows/act_supply_chain_smoke.yml	New — ACT smoke workflow for local validation
.github/act/release-published.event.json	New — sample release event payload for ACT
.actrc	New — local ACT runner defaults
README.md	Updated — ACT usage commands
ops/kyverno/cluster-policies/verify-webgrip-images.yaml	New — ClusterPolicy for homelab-cluster enforcement
docs/adrs/0002-supply-chain-security.md	New — ADR documenting the decision
docs/techdocs/docs/security/index.md	New — security section overview
docs/techdocs/docs/security/supply-chain-security.md	New — threat model, SLSA framework, NIST SSDF mapping
docs/techdocs/docs/security/image-signing.md	New — cosign keyless flow, verification commands
docs/techdocs/docs/security/sbom-attestations.md	New — SBOM formats, attestation inspection, GUAC/DT integration
docs/techdocs/docs/security/vulnerability-scanning.md	New — Trivy usage, remediation workflow
docs/techdocs/docs/security/kyverno-enforcement.md	New — cluster policy rollout strategy
docs/techdocs/mkdocs.yml	Updated — Security section added to nav

---

Required job permissions

The new signing jobs require these permissions (scoped to the signing job only, not the build job):

permissions:
  contents: read
  packages: write       # push attestation OCI artifacts to GHCR
  id-token: write       # GitHub OIDC token for cosign keyless signing
  security-events: write # Trivy SARIF upload to Security tab
  attestations: write   # actions/attest-build-provenance

---

Verification after merge

Once a release is published after this PR merges:

# Verify cosign signature
cosign verify \
  --certificate-identity-regexp 'https://github.com/webgrip/infrastructure/.*on_release_published.*' \
  --certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \
  ghcr.io/webgrip/<image>@sha256:<digest>

# Download and inspect the SBOM
cosign download attestation ghcr.io/webgrip/<image>@sha256:<digest> \
  | jq -r 'select(.payload) | .payload' | base64 -d | jq '.predicate.metadata'

# Verify SLSA provenance
gh attestation verify oci://ghcr.io/webgrip/<image>@sha256:<digest> --owner webgrip

Local ACT smoke checks:

# smoke-test composite action without registry/OIDC side effects
act workflow_dispatch -W .github/workflows/act_supply_chain_smoke.yml

# simulate release payload locally
act release -W .github/workflows/on_release_published.yml -e .github/act/release-published.event.json

---

Rollout plan for the cluster

1. Merge this PR
2. Publish a new release for each image (or retag existing ones)
3. Apply ops/kyverno/cluster-policies/verify-webgrip-images.yaml to the homelab cluster in Audit mode
4. Monitor kubectl get policyreport -A for violations
5. Once all webgrip images show clean, switch policy to Enforce

---

Standards coverage

Standard	Coverage
SLSA Build L2	✅ Signed provenance, hosted build service
NIST SSDF DS.2.1	✅ Sign release artifacts
NIST SSDF DS.6.1	✅ SBOM for released software
NIST SSDF RV.1	✅ Vulnerability identification via Trivy
NTIA Minimum SBOM Elements	✅ Via CycloneDX + SPDX
CIS SSC 2.3.1	✅ All artifacts signed
CIS SSC 2.4.1	✅ SBOMs generated per release

[Ryangr0]

@copilot What other measures can I take for full security control over the supply chain? Feel free to suggest things

[Copilot]

@copilot What other measures can I take for full security control over the supply chain? Feel free to suggest things

A few high-impact next steps:

1. Move Trivy to blocking on critical/high for release tags (--exit-code 1 --severity CRITICAL,HIGH) with a short exception process.
2. Enforce digest-only images in manifests/Helm and disallow mutable tags org-wide.
3. Pin every GitHub Action to a full commit SHA and enable Dependabot updates for workflow actions.
4. Add policy checks in CI (Conftest/Kyverno CLI) so signature/SBOM/provenance rules are tested before deploy.
5. Harden builds toward SLSA L3 controls: ephemeral isolated runners, hermetic/reproducible builds, and stronger two-person controls on release workflows/tags.
6. Add runtime controls: admission + runtime detection (Falco/Tetragon), egress restrictions, and least-privilege container profiles.
7. Continuously verify attestations before deploy (e.g., in ArgoCD/Flux gate) rather than only at cluster admission.
8. Add secret and dependency risk controls: org-wide secret scanning push protection, dependency review gates, and regular SBOM drift monitoring.

[Ryangr0]

@copilot What other measures can I take for full security control over the supply chain? Feel free to suggest things

A few high-impact next steps:

1. Move Trivy to blocking on critical/high for release tags (--exit-code 1 --severity CRITICAL,HIGH) with a short exception process.
2. Enforce digest-only images in manifests/Helm and disallow mutable tags org-wide.
3. Pin every GitHub Action to a full commit SHA and enable Dependabot updates for workflow actions.
4. Add policy checks in CI (Conftest/Kyverno CLI) so signature/SBOM/provenance rules are tested before deploy.
5. Harden builds toward SLSA L3 controls: ephemeral isolated runners, hermetic/reproducible builds, and stronger two-person controls on release workflows/tags.
6. Add runtime controls: admission + runtime detection (Falco/Tetragon), egress restrictions, and least-privilege container profiles.
7. Continuously verify attestations before deploy (e.g., in ArgoCD/Flux gate) rather than only at cluster admission.
8. Add secret and dependency risk controls: org-wide secret scanning push protection, dependency review gates, and regular SBOM drift monitoring.

I agree with all of those points @copilot For the things that don't directly impact this repo, tell me how to do it

[Copilot]

@copilot What other measures can I take for full security control over the supply chain? Feel free to suggest things

A few high-impact next steps:
...

Great—here’s the fastest way to implement the non-repo controls:

1. Org-level secret protection

• GitHub org settings → Code security and analysis: enable Secret Scanning + Push Protection for all repos.
• Add custom patterns for internal token formats.

2. Release governance (2-person control)

• Protect v* tags in org/repo rulesets.
• Require pull request approvals + required checks before workflow files can change.
• Restrict who can create releases/tags.

3. Hardened runners

• Use ephemeral self-hosted runners (one job per VM/pod).
• Block outbound internet by default, allowlist only required registries/APIs.
• Rebuild runner images frequently and sign runner base images.

4. Pre-deploy attestation verification in GitOps

• In Argo CD/Flux, add a policy gate (Kyverno verifyImages / Ratify / Connaisseur) before sync.
• Require valid cosign signature + expected OIDC identity + required SBOM/provenance attestations.

5. Runtime detection and isolation

• Deploy Falco or Tetragon cluster-wide.
• Enforce seccomp/AppArmor, read-only root FS, drop all Linux capabilities by default.
• Apply namespace-level NetworkPolicies with deny-all baseline.

6. Dependency risk controls

• Enable Dependabot security updates and dependency review required checks org-wide.
• Add an exception SLA process (owner + expiry) for accepted risks.

7. SBOM operations

• Export attestations/SBOMs to Dependency-Track or GUAC.
• Set recurring drift checks (new CVEs against previously released digests) and alerting.

If you want, I can propose a phased rollout order (30/60/90 days) based on implementation effort and risk reduction.

[Ryangr0]

@copilot make ACT stuff for this. I want to make 100% sure this will work.

[Copilot]

@copilot make ACT stuff for this. I want to make 100% sure this will work.

Implemented in 412662d.

You now have ACT support for this flow:

• Added dry-run mode to .github/actions/cosign-sign-attest (dry-run: 'true') so ACT can validate the pipeline shape without OIDC signing or GHCR mutation.
• Added .github/workflows/act_supply_chain_smoke.yml to smoke-test the signing/attestation composite action.
• Added .actrc for runner defaults and .github/act/release-published.event.json for release-event simulation.
• Added README commands to run both checks.

Run locally:

act workflow_dispatch -W .github/workflows/act_supply_chain_smoke.yml
act release -W .github/workflows/on_release_published.yml -e .github/act/release-published.event.json

This gives you strong preflight validation with ACT; final cryptographic/OIDC behavior still must be confirmed in a real GitHub release run.

[webgrip-ci]

🎉 This PR is included in version 1.2.0 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀

[webgrip-ci]

🎉 This PR is included in version 1.2.0 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀

[webgrip-ci]

🎉 This PR is included in version 1.2.0 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀

[webgrip-ci]

🎉 This PR is included in version 1.3.0 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀

[webgrip-ci]

🎉 This PR is included in version 1.1.0 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀

[webgrip-ci]

🎉 This PR is included in version 1.2.0 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀

[webgrip-ci]

🎉 This PR is included in version 1.1.0 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀