feat(ci): add sboms and cosign verification for official build artifacts

Author: aauren

.github/workflows/ci-container.yml

@@ -19,41 +19,58 @@ on:
 
 permissions:
   contents: read
+  id-token: write
+  attestations: write
 
 jobs:
-  # Builds Container only if a new push to main branch, a tag or a pull request from a source
-  # branch within the repository
+  # Builds and pushes the container image for branch pushes, PRs, and release tags.
+  # On tag events, also signs the image and attests a signed SBOM to DockerHub via cosign.
   ci-build-container:
     name: ci-build-container
     runs-on: ubuntu-latest
     steps:
+    # Check out the repository so the Dockerfile and source are available to the build.
     - name: Checkout
       uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
 
+    # Register QEMU emulators so Docker Buildx can build non-native architectures (arm, s390x, etc).
     - name: Set up QEMU
       uses: docker/setup-qemu-action@ce360397dd3f832beb865e1373c09c0e9f86d70a  # v4.0.0
 
+    # Create a multi-platform-capable Buildx builder instance on the runner.
     - name: Set up Docker Buildx
       uses: docker/setup-buildx-action@4d04d5d9486b7bd6fa91e7baf45bbb4f8b9deedd  # v4.0.0
 
+    # Authenticate to DockerHub so subsequent push steps and cosign attestation pushes succeed.
     - name: Login to DockerHub
       uses: docker/login-action@b45d80f862d83dbcd57f89517bcf500b2ab88fb2  # v4.0.0
       with:
         username: ${{ secrets.DOCKERHUB_USERNAME }}
         password: ${{ secrets.DOCKERHUB_TOKEN }}
 
+    # Install cosign once for all tag-based signing and attestation steps below.
+    # Uses keyless signing — no private key required; identity is proven via the GitHub Actions
+    # OIDC token issued to this workflow, rooted in Sigstore Fulcio and logged in Rekor.
+    - name: Install cosign
+      if: ${{ startsWith(github.ref, 'refs/tags/v') }}
+      uses: sigstore/cosign-installer@ba7bc0a3fef59531c69a25acd34668d6d3fe6f22  # v4.1.0
+
+    # Parse the branch name from GITHUB_REF for use as the image tag on non-tag branch pushes.
     - name: Extract branch from github ref - New Push
       if: ${{ startsWith(github.ref, 'refs/tags/v') != true && github.event_name != 'pull_request' }}
       shell: bash
       run: echo "branch=${GITHUB_REF#refs/heads/}" >> "$GITHUB_OUTPUT"
       id: extract_branch
 
+    # Parse the version tag from GITHUB_REF for use as the image tag on tag pushes.
     - name: Extract tag from github ref - New Release
       if: ${{ startsWith(github.ref, 'refs/tags/v') }}
       shell: bash
       run: echo "tag=${GITHUB_REF#refs/tags/}" >> "$GITHUB_OUTPUT"
       id: extract_tag
 
+    # Build and push a multi-arch image tagged with the branch name on direct pushes to tracked
+    # branches (master, v*, prep-v*). Not run on PRs or tag pushes.
     - name: Build and push - New Push
       uses: docker/build-push-action@d08e5c354a6adb9ed34480a06d141179aa583294  # v7.0.0
       if: ${{ startsWith(github.ref, 'refs/tags/v') != true && github.event_name != 'pull_request' }}
@@ -71,22 +88,30 @@ jobs:
           RUNTIME_BASE=${{ inputs.runtime-base }}
         tags: cloudnativelabs/kube-router-git:${{ steps.extract_branch.outputs.branch }}
 
+    # Build and push a single-arch (amd64) image tagged with the PR number for pull requests.
+    # Multi-arch is skipped here as it adds 30+ minutes to PR feedback time.
     - name: Build and push - New PR
       uses: docker/build-push-action@d08e5c354a6adb9ed34480a06d141179aa583294  # v7.0.0
       if: github.event_name == 'pull_request'
       with:
         context: .
-        # Don't build multi arch images for PR as they take more than 30 min to build
         platforms: linux/amd64
         push: true
         build-args: |
           BUILDTIME_BASE=${{ inputs.buildtime-base }}
           RUNTIME_BASE=${{ inputs.runtime-base }}
         tags: cloudnativelabs/kube-router-git:PR-${{ github.event.pull_request.number }}
 
-    # Tagging a release candidate, don't update latest
+    # -----------------------------------------------------------------------------------------
+    # Release Candidate tag (e.g. v2.8.0-rc1): build, sign, generate SBOM, and attest to registry.
+    # The `latest` tag is NOT updated for release candidates.
+    # -----------------------------------------------------------------------------------------
+
+    # Build and push the multi-arch release candidate image. The step id captures the digest
+    # so subsequent signing and attestation steps can reference the exact immutable image.
     - name: Build and push - New Tag (Release Candidate)
       uses: docker/build-push-action@d08e5c354a6adb9ed34480a06d141179aa583294  # v7.0.0
+      id: push_rc
       if: ${{ startsWith(github.ref, 'refs/tags/v') && contains(github.ref, '-rc') }}
       with:
         context: .
@@ -103,9 +128,51 @@ jobs:
         tags: |
           cloudnativelabs/kube-router:${{ steps.extract_tag.outputs.tag }}
 
-    # Tagging a proper release, update latest
+    # Sign the RC image digest with cosign (keyless). The signature is pushed to DockerHub as a
+    # sibling OCI artifact and the signing event is recorded in the Rekor transparency log.
+    # Verify with: cosign verify --certificate-identity-regexp "https://github.com/cloudnativelabs/.*"
+    #   --certificate-oidc-issuer "https://token.actions.githubusercontent.com"
+    #   cloudnativelabs/kube-router:<rc-tag>
+    - name: Sign container image - New Tag (Release Candidate)
+      if: ${{ startsWith(github.ref, 'refs/tags/v') && contains(github.ref, '-rc') }}
+      run: cosign sign --yes cloudnativelabs/kube-router@${{ steps.push_rc.outputs.digest }}
+
+    # Generate an SPDX-JSON SBOM for the RC image using Syft. The SBOM is written to a local
+    # file for the attestation step and also uploaded as a workflow artifact.
+    - name: Generate SBOM for container image - New Tag (Release Candidate)
+      uses: anchore/sbom-action@e22c389904149dbc22b58101806040fa8d37a610  # v0.24.0
+      id: sbom_rc
+      if: ${{ startsWith(github.ref, 'refs/tags/v') && contains(github.ref, '-rc') }}
+      with:
+        image: cloudnativelabs/kube-router@${{ steps.push_rc.outputs.digest }}
+        format: spdx-json
+        artifact-name: kube-router-${{ github.ref_name }}-image-sbom.spdx.json
+        output-file: ./container-sbom-rc.spdx.json
+
+    # Wrap the SBOM in a signed in-toto attestation and push it to DockerHub alongside the image.
+    # Users can retrieve and verify it with:
+    #   cosign verify-attestation --type spdxjson
+    #     --certificate-identity-regexp "https://github.com/cloudnativelabs/.*"
+    #     --certificate-oidc-issuer "https://token.actions.githubusercontent.com"
+    #     cloudnativelabs/kube-router:<rc-tag> | jq -r '.payload' | base64 -d | jq '.predicate'
+    - name: Attest SBOM to container image - New Tag (Release Candidate)
+      if: ${{ startsWith(github.ref, 'refs/tags/v') && contains(github.ref, '-rc') }}
+      run: |
+        cosign attest --yes \
+          --predicate ./container-sbom-rc.spdx.json \
+          --type spdxjson \
+          cloudnativelabs/kube-router@${{ steps.push_rc.outputs.digest }}
+
+    # -----------------------------------------------------------------------------------------
+    # Production release tag (e.g. v2.8.0): build, sign, generate SBOM, and attest to registry.
+    # Both the versioned tag and `latest` are updated.
+    # -----------------------------------------------------------------------------------------
+
+    # Build and push the multi-arch production release image. Updates both the versioned tag and
+    # `latest`. The step id captures the digest for signing and attestation.
     - name: Build and push - New Tag
       uses: docker/build-push-action@d08e5c354a6adb9ed34480a06d141179aa583294  # v7.0.0
+      id: push_release
       if: ${{ startsWith(github.ref, 'refs/tags/v') && ! contains(github.ref, '-rc') }}
       with:
         context: .
@@ -122,3 +189,29 @@ jobs:
         tags: |
           cloudnativelabs/kube-router:${{ steps.extract_tag.outputs.tag }}
           cloudnativelabs/kube-router:latest
+
+    # Sign the production release image digest with cosign (keyless). Same verification command
+    # as the RC step above, using the production release tag.
+    - name: Sign container image - New Tag
+      if: ${{ startsWith(github.ref, 'refs/tags/v') && ! contains(github.ref, '-rc') }}
+      run: cosign sign --yes cloudnativelabs/kube-router@${{ steps.push_release.outputs.digest }}
+
+    # Generate an SPDX-JSON SBOM for the production release image using Syft.
+    - name: Generate SBOM for container image - New Tag
+      uses: anchore/sbom-action@e22c389904149dbc22b58101806040fa8d37a610  # v0.24.0
+      id: sbom_release
+      if: ${{ startsWith(github.ref, 'refs/tags/v') && ! contains(github.ref, '-rc') }}
+      with:
+        image: cloudnativelabs/kube-router@${{ steps.push_release.outputs.digest }}
+        format: spdx-json
+        artifact-name: kube-router-${{ github.ref_name }}-image-sbom.spdx.json
+        output-file: ./container-sbom-release.spdx.json
+
+    # Wrap the SBOM in a signed in-toto attestation and push it to DockerHub alongside the image.
+    - name: Attest SBOM to container image - New Tag
+      if: ${{ startsWith(github.ref, 'refs/tags/v') && ! contains(github.ref, '-rc') }}
+      run: |
+        cosign attest --yes \
+          --predicate ./container-sbom-release.spdx.json \
+          --type spdxjson \
+          cloudnativelabs/kube-router@${{ steps.push_release.outputs.digest }}

.github/workflows/ci-release.yml

@@ -12,12 +12,14 @@ permissions:
   contents: read
 
 jobs:
-  # Runs GoReleaser to publish binaries and create a GitHub release
+  # Runs GoReleaser to publish binaries, generate a binary SBOM, and produce SLSA provenance
   ci-goreleaser-tag:
     name: ci-goreleaser-tag
     runs-on: ubuntu-latest
     permissions:
       contents: write
+      id-token: write
+      attestations: write
     steps:
     # Check out the repository so GoReleaser has access to the full git history and source.
     - name: Check out code
@@ -29,6 +31,8 @@ jobs:
       with:
         go-version: ${{ inputs.go-version }}
 
+    # Build multi-arch binaries, create archives, generate checksums, and publish a GitHub release.
+    # The release is created as a draft (see .goreleaser.yml) pending manual review before publish.
     - name: Run GoReleaser
       uses: goreleaser/goreleaser-action@ec59f474b9834571250b370d4735c50f8e2d1e29  # v7.0.0
       with:
@@ -37,3 +41,21 @@ jobs:
         args: release --clean
       env:
         GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+    # Generate a CycloneDX SBOM covering all release binaries in dist/ and attach it
+    # to the GitHub release as a downloadable asset for binary consumers.
+    - name: Generate SBOM for release binaries
+      uses: anchore/sbom-action@e22c389904149dbc22b58101806040fa8d37a610  # v0.24.0
+      with:
+        path: ./dist
+        format: cyclonedx-json
+        artifact-name: kube-router-${{ github.ref_name }}-sbom.cyclonedx.json
+        upload-release-assets: true
+
+    # Generate SLSA Build Level 2 provenance for the release binaries.
+    # Uses GitHub's native attestation (first-party action, GA since June 2024).
+    # Consumers can verify with: gh attestation verify <binary> --repo cloudnativelabs/kube-router
+    - name: Generate SLSA provenance for release binaries
+      uses: actions/attest@59d89421af93a897026c735860bf21b6eb4f7b26  # v4.1.0
+      with:
+        subject-checksums: ./dist/checksums.txt

.github/workflows/ci.yml

@@ -18,8 +18,8 @@ permissions:
   contents: read
 
 env:
-  BUILDTIME_BASE: &buildtime_base "golang:1.25.7-alpine3.23"
-  RUNTIME_BASE: &runtime_base "alpine:3.23"
+  BUILDTIME_BASE: &buildtime_base "golang:1.25.7-alpine3.23@sha256:f6751d823c26342f9506c03797d2527668d095b0a15f1862cddb4d927a7a4ced"
+  RUNTIME_BASE: &runtime_base "alpine:3.23@sha256:25109184c71bdad752c8312a8623239686a9a2071e8825f20acb8f2198c3f659"
   GO_VERSION: &go_version "~1.25.7"
 
 jobs:
@@ -34,9 +34,15 @@ jobs:
   # Phase 2: Build and push the container image.
   # Only runs for non-fork PRs and direct pushes — skipped for dependabot and external fork PRs
   # to prevent secret exposure to untrusted code.
+  # id-token: write — required for keyless cosign signing via Sigstore OIDC
+  # attestations: write — required for pushing SBOM attestations to DockerHub
   container:
     needs: checks
     if: ${{ github.event_name != 'pull_request' || (github.event.pull_request.head.repo.full_name == github.repository && github.actor != 'dependabot[bot]') }}
+    permissions:
+      contents: read
+      id-token: write
+      attestations: write
     uses: ./.github/workflows/ci-container.yml
     with:
       buildtime-base: *buildtime_base
@@ -47,12 +53,17 @@ jobs:
 
   # Phase 3: Publish a versioned release via GoReleaser.
   # Only runs on tag pushes (v*) after the container build succeeds.
-  # contents: write is required here in the caller — called workflows cannot self-elevate permissions.
+  # contents: write — required for GoReleaser to create the GitHub release
+  # id-token: write — required for keyless cosign signing via Sigstore OIDC
+  # attestations: write — required for SLSA provenance and SBOM attestation on release binaries
+  # Called workflows cannot self-elevate permissions; all must be granted here in the caller.
   release:
     needs: container
     if: ${{ startsWith(github.ref, 'refs/tags/v') }}
     permissions:
       contents: write
+      id-token: write
+      attestations: write
     uses: ./.github/workflows/ci-release.yml
     with:
       go-version: *go_version

Makefile

@@ -18,14 +18,14 @@ MAKEFILE_DIR=$(dir $(realpath $(firstword $(MAKEFILE_LIST))))
 UPSTREAM_IMPORT_PATH=$(GOPATH)/src/github.com/cloudnativelabs/kube-router/
 BUILD_IN_DOCKER?=true
 # See Versions: https://hub.docker.com/_/golang
-DOCKER_BUILD_IMAGE?=golang:1.25.7-alpine3.23
+DOCKER_BUILD_IMAGE?=golang:1.25.7-alpine3.23@sha256:f6751d823c26342f9506c03797d2527668d095b0a15f1862cddb4d927a7a4ced
 ## These variables are used by the Dockerfile as the bases for building and creating the runtime container
 ## During CI these come from .github/workflows/ci.yaml below we define for local builds as well
 GO_CACHE?=$(shell go env GOCACHE)
 GO_MOD_CACHE?=$(shell go env GOMODCACHE)
 BUILDTIME_BASE?=$(DOCKER_BUILD_IMAGE)
 # See Versions: https://hub.docker.com/_/alpine
-RUNTIME_BASE?=alpine:3.23
+RUNTIME_BASE?=alpine:3.23@sha256:25109184c71bdad752c8312a8623239686a9a2071e8825f20acb8f2198c3f659
 # See Versions: https://hub.docker.com/r/golangci/golangci-lint/tags
 DOCKER_LINT_IMAGE?=golangci/golangci-lint:v2.8.0
 # See Versions: https://hub.docker.com/r/tmknom/markdownlint/tags