fix: address PR review — sign by digest, tighten identity, fix docs

- Sign images by immutable digest from build-push-action output
  instead of mutable tags to eliminate TOCTOU risk
- Tighten cosign certificate identity to the specific release
  workflow path and tag refs
- Parameterize IMAGE in Makefile verify-image target to support
  both initium and initium-jyq variants
- Clarify docs: SBOM attestations are cosign-signed, provenance
  is generated by BuildKit (not cosign-signed)
- Use version tags instead of :latest in doc examples

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: mikkeldamsgaard

.github/workflows/release.yml

@@ -39,6 +39,7 @@ jobs:
         id: version
         run: echo "VERSION=${GITHUB_REF#refs/tags/v}" >> "$GITHUB_OUTPUT"
       - uses: docker/build-push-action@v6
+        id: build-main
         with:
           context: .
           platforms: linux/amd64,linux/arm64
@@ -53,13 +54,14 @@ jobs:
           sbom: true
           provenance: true
       - name: Sign initium image
-        run: |
-          cosign sign --yes ghcr.io/kitstream/initium:${{ steps.version.outputs.VERSION }}
-          cosign sign --yes ghcr.io/kitstream/initium:latest
+        run: cosign sign --yes ghcr.io/kitstream/initium@${{ steps.build-main.outputs.digest }}
       - name: SBOM attestation for initium image
         run: |
-          cosign attest --yes --predicate <(docker buildx imagetools inspect ghcr.io/kitstream/initium:${{ steps.version.outputs.VERSION }} --format '{{json .SBOM.SPDX}}') --type spdx ghcr.io/kitstream/initium:${{ steps.version.outputs.VERSION }}
+          cosign attest --yes --type spdx \
+            --predicate <(docker buildx imagetools inspect ghcr.io/kitstream/initium@${{ steps.build-main.outputs.digest }} --format '{{json .SBOM.SPDX}}') \
+            ghcr.io/kitstream/initium@${{ steps.build-main.outputs.digest }}
       - uses: docker/build-push-action@v6
+        id: build-jyq
         with:
           context: .
           file: Dockerfile.jyq
@@ -75,9 +77,9 @@ jobs:
           sbom: true
           provenance: true
       - name: Sign initium-jyq image
-        run: |
-          cosign sign --yes ghcr.io/kitstream/initium-jyq:${{ steps.version.outputs.VERSION }}
-          cosign sign --yes ghcr.io/kitstream/initium-jyq:latest
+        run: cosign sign --yes ghcr.io/kitstream/initium-jyq@${{ steps.build-jyq.outputs.digest }}
       - name: SBOM attestation for initium-jyq image
         run: |
-          cosign attest --yes --predicate <(docker buildx imagetools inspect ghcr.io/kitstream/initium-jyq:${{ steps.version.outputs.VERSION }} --format '{{json .SBOM.SPDX}}') --type spdx ghcr.io/kitstream/initium-jyq:${{ steps.version.outputs.VERSION }}
+          cosign attest --yes --type spdx \
+            --predicate <(docker buildx imagetools inspect ghcr.io/kitstream/initium-jyq@${{ steps.build-jyq.outputs.digest }} --format '{{json .SBOM.SPDX}}') \
+            ghcr.io/kitstream/initium-jyq@${{ steps.build-jyq.outputs.digest }}

Makefile

@@ -1,21 +1,23 @@
 BINARY   := initium
 VERSION  ?= dev
+IMAGE    ?= ghcr.io/kitstream/initium
+COSIGN_IDENTITY := https://github.com/KitStream/initium/.github/workflows/release.yml@refs/tags/v*
 .PHONY: all build test lint clean verify-image
 all: lint test build
 build:
-cargo build --release
-cp target/release/$(BINARY) bin/$(BINARY)
+	cargo build --release
+	cp target/release/$(BINARY) bin/$(BINARY)
 test:
-cargo test
+	cargo test
 lint:
-cargo clippy -- -D warnings
-cargo fmt --check
+	cargo clippy -- -D warnings
+	cargo fmt --check
 clean:
-cargo clean
-rm -rf bin/
+	cargo clean
+	rm -rf bin/
 docker-build:
-docker build -t ghcr.io/kitstream/initium:$(VERSION) .
+	docker build -t ghcr.io/kitstream/initium:$(VERSION) .
 docker-push:
-docker push ghcr.io/kitstream/initium:$(VERSION)
+	docker push ghcr.io/kitstream/initium:$(VERSION)
 verify-image:
-cosign verify --certificate-oidc-issuer https://token.actions.githubusercontent.com --certificate-identity-regexp '^https://github\.com/KitStream/initium/' ghcr.io/kitstream/initium:$(VERSION)
+	cosign verify --certificate-oidc-issuer https://token.actions.githubusercontent.com --certificate-identity '$(COSIGN_IDENTITY)' $(IMAGE):$(VERSION)

docs/security.md

@@ -78,38 +78,39 @@ If your cluster still uses PSPs, the same security context fields apply. Initium
 
 ## Image Verification
 
-Release images are signed with [cosign](https://github.com/sigstore/cosign) using keyless signing (Sigstore OIDC via GitHub Actions). SBOM and provenance attestations are also signed and attached to each image.
+Release images are signed with [cosign](https://github.com/sigstore/cosign) using keyless signing (Sigstore OIDC via GitHub Actions). SBOM attestations are signed and attached to each image. Provenance attestations are generated by Docker BuildKit and can be inspected with `docker buildx imagetools`.
 
 ### Verify image signature
 
 ```bash
 # Verify signature (requires cosign)
 cosign verify \
   --certificate-oidc-issuer https://token.actions.githubusercontent.com \
-  --certificate-identity-regexp '^https://github\.com/KitStream/initium/' \
-  ghcr.io/kitstream/initium:latest
+  --certificate-identity 'https://github.com/KitStream/initium/.github/workflows/release.yml@refs/tags/v*' \
+  ghcr.io/kitstream/initium:1.3.1
 
-# Or use the Makefile target
-make verify-image VERSION=latest
+# Or use the Makefile target (also supports IMAGE=ghcr.io/kitstream/initium-jyq)
+make verify-image VERSION=1.3.1
 ```
 
-### Verify attestations
+### Verify SBOM attestation
 
 ```bash
-# Verify provenance
-cosign verify-attestation \
-  --type https://slsa.dev/provenance/v0.2 \
-  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
-  --certificate-identity-regexp '^https://github\.com/KitStream/initium/' \
-  ghcr.io/kitstream/initium:latest
-
-# Verify SBOM attestation
 cosign verify-attestation \
   --type spdx \
   --certificate-oidc-issuer https://token.actions.githubusercontent.com \
-  --certificate-identity-regexp '^https://github\.com/KitStream/initium/' \
-  ghcr.io/kitstream/initium:latest
+  --certificate-identity 'https://github.com/KitStream/initium/.github/workflows/release.yml@refs/tags/v*' \
+  ghcr.io/kitstream/initium:1.3.1
+```
+
+### View provenance and SBOM
+
+Provenance and SBOM attestations are generated by Docker BuildKit during the image build:
+
+```bash
+# View provenance
+docker buildx imagetools inspect ghcr.io/kitstream/initium:1.3.1 --format '{{json .Provenance}}'
 
 # View SBOM
-docker buildx imagetools inspect ghcr.io/kitstream/initium:latest --format '{{json .SBOM}}'
+docker buildx imagetools inspect ghcr.io/kitstream/initium:1.3.1 --format '{{json .SBOM}}'
 ```