chore(build): digest-pin base images and SHA-pin workflow actions (kairos#4203) (#24)

Supply-chain hardening: make the image build and CI reproducible and
tamper-evident by content-addressing every external dependency.

- Dockerfile + Makefile: digest-pin all base images (hadron, kairos-init,
  golang static+alpine builders, alpine) as image:tag@sha256:<index-digest>.
  The multi-arch INDEX digest is used so cross-arch builds still resolve the
  right manifest. KAIROS_BASE_IMAGE/KAIROS_INIT_IMAGE are pinned in BOTH the
  Dockerfile ARG defaults and the Makefile defaults, since CI's make image passes
  the Makefile value (closing the override path).
- ci.yml + release.yml: SHA-pin the remaining GitHub Actions (checkout, setup-go,
  setup-buildx, login, golangci-lint) with a # vN comment, matching the already
  SHA-pinned attest/sbom actions. No floating action tags remain.
- make verify-pins (wired into the CI gates job): fails loud if a base-image
  digest drifts between Dockerfile and Makefile, or is not digest-pinned, so a
  two-site re-pin mistake cannot land silently.

Reviewed by security-architect (gate passed, no blockers). The crane download
stays version+sha256-verified (consistent with the other binary downloads); the
control-plane image crane pull digest-pinning remains tracked as ADR-16 P5,
explicitly out of scope here.

Signed-off-by: William Rizzo <william.rizzo@gmail.com>
Co-authored-by: Claude <noreply@anthropic.com>

Author: wrkode

.github/workflows/ci.yml

@@ -24,14 +24,17 @@ jobs:
     timeout-minutes: 15
     steps:
       - name: Checkout
-        uses: actions/checkout@v5
+        uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
 
       - name: Set up Go
-        uses: actions/setup-go@v6
+        uses: actions/setup-go@924ae3a1cded613372ab5595356fb5720e22ba16 # v6
         with:
           go-version-file: go.mod
           check-latest: false
 
+      - name: verify base-image pins (no digest drift)
+        run: make verify-pins
+
       - name: gofmt -s (check only)
         run: make fmt-check
 
@@ -45,7 +48,7 @@ jobs:
         run: make build
 
       - name: golangci-lint
-        uses: golangci/golangci-lint-action@v9
+        uses: golangci/golangci-lint-action@ba0d7d2ec06a0ea1cb5fa41b2e4a3ab91d21278a # v9
         with:
           # Pin to the version validated locally against the v2 config.
           version: v2.12.2
@@ -61,7 +64,7 @@ jobs:
       minors: ${{ steps.minors.outputs.minors }}
     steps:
       - name: Checkout
-        uses: actions/checkout@v5
+        uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
 
       - name: Extract SupportedMinors -> JSON matrix
         id: minors
@@ -97,10 +100,10 @@ jobs:
         minor: ${{ fromJSON(needs.discover.outputs.minors) }}
     steps:
       - name: Checkout
-        uses: actions/checkout@v5
+        uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
 
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v4
+        uses: docker/setup-buildx-action@d7f5e7f509e45cec5c76c4d5afdd7de93d0b3df5 # v4
 
       - name: Resolve Kubernetes patch + commit + crictl versions
         id: ver
@@ -254,16 +257,16 @@ jobs:
         minor: ${{ fromJSON(needs.discover.outputs.minors) }}
     steps:
       - name: Checkout
-        uses: actions/checkout@v5
+        uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
 
       - name: Set up Go
-        uses: actions/setup-go@v6
+        uses: actions/setup-go@924ae3a1cded613372ab5595356fb5720e22ba16 # v6
         with:
           go-version-file: go.mod
           check-latest: false
 
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v4
+        uses: docker/setup-buildx-action@d7f5e7f509e45cec5c76c4d5afdd7de93d0b3df5 # v4
 
       - name: Resolve Kubernetes patch + commit + crictl versions
         id: ver

.github/workflows/release.yml

@@ -41,7 +41,7 @@ jobs:
       latest_minor: ${{ steps.minors.outputs.latest_minor }}
     steps:
       - name: Checkout
-        uses: actions/checkout@v5
+        uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
 
       - name: Extract SupportedMinors -> JSON matrix
         id: minors
@@ -78,13 +78,13 @@ jobs:
         minor: ${{ fromJSON(needs.discover.outputs.minors) }}
     steps:
       - name: Checkout
-        uses: actions/checkout@v5
+        uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
 
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v4
+        uses: docker/setup-buildx-action@d7f5e7f509e45cec5c76c4d5afdd7de93d0b3df5 # v4
 
       - name: Log in to ghcr.io
-        uses: docker/login-action@v4
+        uses: docker/login-action@650006c6eb7dba73a995cc03b0b2d7f5ca915bee # v4
         with:
           registry: ghcr.io
           username: ${{ github.actor }}
@@ -216,10 +216,10 @@ jobs:
       attestations: write # write provenance + SBOM attestations
     steps:
       - name: Checkout
-        uses: actions/checkout@v5
+        uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
 
       - name: Set up Go
-        uses: actions/setup-go@v6
+        uses: actions/setup-go@924ae3a1cded613372ab5595356fb5720e22ba16 # v6
         with:
           go-version-file: go.mod
 

Dockerfile

@@ -20,25 +20,30 @@
 # (https://kairos.io/docs/reference/auroraboot/). See samples/README.md.
 
 # ----------------------------------------------------------------------------
-# Versions: pinned by default. Bump together via build args; CI should pin via
-# image digest as well once a release pipeline lands.
+# Versions: pinned by default. Bump together via build args. Base images are
+# digest-pinned below (kairos#4203) for a reproducible, tamper-evident supply chain.
 # ----------------------------------------------------------------------------
 # Pure upstream Hadron base (musl). kairos-init transforms it into a Kairos OS in
 # the final stage, exactly as the canonical Kairos image build does.
-ARG KAIROS_BASE_IMAGE=ghcr.io/kairos-io/hadron:v0.4.0
+# All base images are DIGEST-pinned (image:tag@sha256:...) for a reproducible,
+# tamper-evident supply chain (kairos#4203). The tag is kept for readability; the
+# digest is the multi-arch index digest, so cross-arch builds still resolve the
+# right manifest. When bumping a tag, re-resolve the digest
+# (docker buildx imagetools inspect <image:tag>) and update both here and in the
+# Makefile defaults that override these ARGs.
+ARG KAIROS_BASE_IMAGE=ghcr.io/kairos-io/hadron:v0.4.0@sha256:1e19d9cd5a70dfc6940f58d899e72f6776f4d64934cd6f402f4a4186ccc40d4d
 # kairos-init that matches the version Kairos itself uses to build Hadron. Older
 # pins (e.g. v0.6.0) cannot regenerate Hadron's initramfs (dracut -f ... fails).
-ARG KAIROS_INIT_IMAGE=quay.io/kairos/kairos-init:v0.14.6
-ARG GO_BUILDER_IMAGE=golang:1.26.4-alpine
+ARG KAIROS_INIT_IMAGE=quay.io/kairos/kairos-init:v0.14.6@sha256:e53eb7e5ada035e7e192f072f9e041ca5d60440ecf8c766c32e7d95253b293e7
+ARG GO_BUILDER_IMAGE=golang:1.26.4-alpine@sha256:3ad57304ad93bbec8548a0437ad9e06a455660655d9af011d58b993f6f615648
 ARG TARGETARCH=amd64
 
 # containerd and kubelet are ALWAYS built fully static from source: Hadron is
 # musl, so the glibc-linked official releases cannot exec. A fully static binary
 # runs on musl AND glibc. STATIC_BUILDER is the from-source toolchain (Debian Go,
 # matching the validated recipe); patch-pinned (matches GO_BUILDER_IMAGE's pin
 # level) so the from-source compiler is reproducible across Go patch releases.
-# Digest-pinning all base images remains a tracked backlog item.
-ARG STATIC_BUILDER_IMAGE=golang:1.26.4
+ARG STATIC_BUILDER_IMAGE=golang:1.26.4@sha256:f96cc555eb8db430159a3aa6797cd5bae561945b7b0fe7d0e284c63a3b291609
 
 # Kubernetes (must be within the supported window the provider enforces at
 # runtime: 1.34 / 1.35 / 1.36 as of 2026).
@@ -93,7 +98,7 @@ RUN go build \
 # kubeadm/kubectl/crictl are already static and run on musl unchanged. kubelet is
 # NOT downloaded here -- it is built static from source (see kubelet-build).
 # ----------------------------------------------------------------------------
-FROM alpine:3.21 AS k8s-binaries
+FROM alpine:3.21@sha256:48b0309ca019d89d40f670aa1bc06e426dc0931948452e8491e3d65087abc07d AS k8s-binaries
 ARG KUBERNETES_VERSION
 ARG CRICTL_VERSION
 ARG TARGETARCH
@@ -127,7 +132,7 @@ RUN set -eux; \
 # (runc, CNI). containerd is built static from source (see containerd-build);
 # runc and the CNI plugins are already static and run on musl unchanged.
 # ----------------------------------------------------------------------------
-FROM alpine:3.21 AS runtime-binaries
+FROM alpine:3.21@sha256:48b0309ca019d89d40f670aa1bc06e426dc0931948452e8491e3d65087abc07d AS runtime-binaries
 ARG RUNC_VERSION
 ARG CNI_PLUGINS_VERSION
 ARG TARGETARCH
@@ -231,7 +236,7 @@ RUN set -eux; \
 # image and imported into containerd at boot, so a first boot converges with NO
 # registry access (air-gap). CNI is intentionally NOT bundled (operator's choice).
 # ----------------------------------------------------------------------------
-FROM alpine:3.21 AS image-bundler
+FROM alpine:3.21@sha256:48b0309ca019d89d40f670aa1bc06e426dc0931948452e8491e3d65087abc07d AS image-bundler
 ARG KUBERNETES_VERSION
 ARG TARGETARCH
 # Pinned; crane is a static Go binary that runs on musl.

Makefile

@@ -25,10 +25,12 @@ CNI_PLUGINS_VERSION ?= v1.8.0
 # Kairos OS base the image is built FROM. Defaults to the pure upstream Hadron
 # (musl) OS, which kairos-init transforms into a Kairos system in the final stage
 # (mirroring the canonical Kairos image build). Override to test another base.
-KAIROS_BASE_IMAGE  ?= ghcr.io/kairos-io/hadron:v0.4.0
+# DIGEST-pinned (kairos#4203); must match the Dockerfile ARG defaults. Re-resolve
+# with `docker buildx imagetools inspect <image:tag>` when bumping the tag.
+KAIROS_BASE_IMAGE  ?= ghcr.io/kairos-io/hadron:v0.4.0@sha256:1e19d9cd5a70dfc6940f58d899e72f6776f4d64934cd6f402f4a4186ccc40d4d
 # kairos-init image used in the final stage. Defaults to the Dockerfile's pin
 # (the version Kairos itself uses to build Hadron); override for testing.
-KAIROS_INIT_IMAGE  ?= quay.io/kairos/kairos-init:v0.14.6
+KAIROS_INIT_IMAGE  ?= quay.io/kairos/kairos-init:v0.14.6@sha256:e53eb7e5ada035e7e192f072f9e041ca5d60440ecf8c766c32e7d95253b293e7
 IMAGE              ?= kairos-kubeadm:$(VERSION)
 
 # e2e (ADR-13). The node image FROM-derives the kairos-kubeadm base so it reuses
@@ -39,7 +41,7 @@ BASE_IMAGE       ?= kairos-kubeadm:$(KUBERNETES_VERSION)
 E2E_NODE_IMAGE   ?= kairos-kubeadm-e2e-node:$(KUBERNETES_VERSION)
 E2E_TIMEOUT      ?= 40m
 
-.PHONY: all build test vet fmt fmt-check lint tidy image clean e2e-node-image e2e
+.PHONY: all build test vet fmt fmt-check lint tidy verify-pins image clean e2e-node-image e2e
 
 all: build
 
@@ -71,6 +73,22 @@ lint:
 tidy:
 	$(GO) mod tidy
 
+## verify-pins: fail if a digest-pinned base image drifts between Dockerfile and
+## Makefile, or is not digest-pinned at all (kairos#4203 supply-chain guard).
+verify-pins:
+	@fail=0; \
+	for var in KAIROS_BASE_IMAGE KAIROS_INIT_IMAGE; do \
+	  df="$$(sed -n "s/^ARG $$var=//p" Dockerfile | head -1)"; \
+	  mk="$$(sed -n "s/^$$var[[:space:]]*?=[[:space:]]*//p" Makefile | head -1)"; \
+	  case "$$df" in *@sha256:*) : ;; *) echo "FAIL: Dockerfile $$var is not digest-pinned: '$$df'"; fail=1 ;; esac; \
+	  if [ "$$df" != "$$mk" ]; then \
+	    echo "FAIL: $$var drift:"; echo "  Dockerfile: $$df"; echo "  Makefile:   $$mk"; fail=1; \
+	  else \
+	    echo "ok: $$var = $$df"; \
+	  fi; \
+	done; \
+	if [ "$$fail" != 0 ]; then echo "re-resolve with: docker buildx imagetools inspect <image:tag>"; exit 1; fi
+
 ## image: build the Kairos image bundling provider + kubeadm + containerd
 ## (requires Docker; supply-chain-verified downloads inside the Dockerfile).
 image: