Add build provenance attestations for published Docker images (#45)

* Initial plan

* Add attestation support for published Docker images

Co-authored-by: brabster <[email protected]>

* Fix digest capture to occur after push operation

Co-authored-by: brabster <[email protected]>

* Extract digest from docker push output instead of docker inspect

Co-authored-by: brabster <[email protected]>

* Extract digest handling to script with comprehensive tests

Co-authored-by: brabster <[email protected]>

* Update checkout action to v4 for consistency

Co-authored-by: brabster <[email protected]>

* Revert script complexity - return to inline digest extraction

Co-authored-by: brabster <[email protected]>

* Update CHANGELOG to reference PR #45

Co-authored-by: brabster <[email protected]>

* Update .github/workflows/docker-publish.yml

Co-authored-by: Copilot <[email protected]>

* Apply code review feedback: add set -euo pipefail, fix comment, remove stderr redirect

Co-authored-by: brabster <[email protected]>

* Fix pull request links in CHANGELOG.md

Updated pull request references in CHANGELOG.md for accuracy.

---------

Co-authored-by: copilot-swe-agent[bot] <[email protected]>
Co-authored-by: brabster <[email protected]>
Co-authored-by: Paul Brabban <[email protected]>
Co-authored-by: Copilot <[email protected]>

Author: 3 people

.github/workflows/docker-publish.yml

@@ -131,6 +131,14 @@ jobs:
     runs-on: ubuntu-latest # maintained by GitHub
     permissions:
       packages: write
+      # id-token: write is required for generating attestations using GitHub's OIDC token
+      # This allows the workflow to prove its identity to the attestation service
+      # Reference: https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect
+      id-token: write
+      # attestations: write is required to publish attestations to the repository
+      # This permission allows the workflow to write attestation data associated with the published artifacts
+      # Reference: https://github.com/actions/attest-build-provenance#permissions
+      attestations: write
     needs:
       - build_and_load
       - osv_scan
@@ -147,14 +155,53 @@ jobs:
     - name: Log in to the Container registry
       run: echo "${{ secrets.GITHUB_TOKEN }}" | docker login ghcr.io -u ${{ github.actor }} --password-stdin
 
+    # Push the image and capture its digest for attestation
+    # The digest uniquely identifies the image content and is required for attestation
     - name: Push tagged image
+      id: push
       env:
         DOCKER_SHA_TAG: ghcr.io/${{ github.repository }}:${{ github.sha }}
         DOCKER_LATEST_TAG: ghcr.io/${{ github.repository }}:latest
       run: |
+        set -euo pipefail
         docker load -i ${{ runner.temp }}/candidate_image.tar
-        for tag in $DOCKER_SHA_TAG $DOCKER_LATEST_TAG; do
-          docker tag candidate_image:latest $tag
-          docker push $tag
-        done
+        # Tag and push the SHA-tagged version first, capturing the digest from push output
+        # docker push outputs the digest in the format "digest: sha256:... size: ..."
+        # We extract the digest directly from this output without depending on docker inspect
+        docker tag candidate_image:latest $DOCKER_SHA_TAG
+        PUSH_OUTPUT=$(docker push $DOCKER_SHA_TAG)
+        DIGEST=$(echo "$PUSH_OUTPUT" | grep -oP 'digest: \K(sha256:[a-f0-9]{64})')
+        if [ -z "$DIGEST" ]; then
+          echo "::error::Failed to extract digest from docker push output"
+          echo "Push output was: $PUSH_OUTPUT"
+          exit 1
+        fi
+        echo "digest=$DIGEST" >> $GITHUB_OUTPUT
+        # Push the latest tag (same image, so same digest)
+        docker tag candidate_image:latest $DOCKER_LATEST_TAG
+        docker push $DOCKER_LATEST_TAG
+
+    # Generate build provenance attestations for the published Docker images
+    # This creates cryptographically signed attestations that prove:
+    # 1. The image was built by this specific GitHub Actions workflow
+    # 2. The image digest matches what was produced by the workflow
+    # 3. Build metadata including workflow, repository, and commit information
+    #
+    # The attestation is signed using GitHub's Sigstore infrastructure and stored
+    # in the repository's attestations, allowing consumers to verify the provenance
+    # of the image before use.
+    #
+    # Consumers can verify the attestation using:
+    # gh attestation verify oci://ghcr.io/brabster/terraform-bootstrap-gcp:latest --owner brabster
+    #
+    # Reference: https://github.com/actions/attest-build-provenance
+    - name: Attest build provenance
+      uses: actions/attest-build-provenance@v2 # maintained by GitHub
+      with:
+        # Attest the image by its name and digest
+        # Using the digest ensures the attestation is tied to the exact image content
+        # rather than a mutable tag
+        subject-name: ghcr.io/${{ github.repository }}
+        subject-digest: ${{ steps.push.outputs.digest }}
+        push-to-registry: true
 

CHANGELOG.md

@@ -4,7 +4,34 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
-## [[#41](https://github.com/brabster/terraform-bootstrap-gcp/pull/42)] - Remove dbt-bigquery cache warming
+## [[#45](https://github.com/brabster/terraform-bootstrap-gcp/pull/45)] - Add attestation to published Docker images
+
+### Added
+
+- Build provenance attestations for all published Docker images using GitHub's `actions/attest-build-provenance` action.
+- Documentation in README explaining attestation benefits and how consumers can verify image provenance.
+- Instructions for verifying attestations using the GitHub CLI.
+
+### Changed
+
+- Updated the publish job in the docker-publish.yml workflow to include `id-token: write` and `attestations: write` permissions.
+- Modified the image push step to capture the image digest for use in attestation.
+
+### Rationale
+
+Build provenance attestations provide cryptographic proof of an artifact's origin and build process. This enables consumers to verify that images were built by the official GitHub Actions workflow and have not been tampered with. The attestation includes metadata such as the commit SHA, workflow, and build environment, creating an auditable trail for supply chain security.
+
+### Security
+
+- Attestations enable consumers to verify image authenticity before use, reducing the risk of supply chain attacks.
+- Signed attestations create an auditable trail linking published images to their source code and build process.
+- The attestation signature is created using GitHub's OIDC token, which proves the workflow's identity without requiring long-lived credentials.
+- Consumers can integrate attestation verification into their CI/CD pipelines to enforce supply chain security policies.
+
+  - **Supply Chain Posture Impact:** This change significantly improves the supply chain security posture by providing cryptographic proof of provenance for all published artifacts. Attestations enable consumers to verify that images were built by the expected workflow, detect tampering, and establish trust in the build process. This addresses a critical gap in software supply chain security by making the build process transparent and verifiable. The attestations are signed using GitHub's Sigstore infrastructure, which follows industry best practices for artifact signing and verification.
+  - **Security Posture Impact:** Positive
+
+## [[#42](https://github.com/brabster/terraform-bootstrap-gcp/pull/42)] - Remove dbt-bigquery cache warming
 
 ### Removed
 
@@ -28,7 +55,7 @@ The cache warming provided minimal benefit while adding complexity to the build
   - **Supply Chain Posture Impact:** This change improves the project's supply chain security posture by removing unnecessary dependencies from the base image. Users now explicitly install only the Python packages they need, reducing the number of packages that must be monitored for vulnerabilities. This aligns with the principle of minimal dependencies and reduces the image's attack surface.
   - **Security Posture Impact:** Positive
 
-## [[#35](https://github.com/brabster/terraform-bootstrap-gcp/pull/36)] - Add git CLI completion support
+## [[#36](https://github.com/brabster/terraform-bootstrap-gcp/pull/36)] - Add git CLI completion support
 
 ### Added
 

README.md

@@ -37,6 +37,32 @@ The image has two types of tags:
 - **`latest`**: This tag always points to the most recent daily build.
 - **git SHA**: A tag with the git SHA of the commit that triggered the build is created for each build. This allows for pinning to a specific version of the image should the need arise.
 
+## Supply chain security
+
+Each published image includes a cryptographically signed attestation that provides build provenance information. This attestation proves that the image was built by this repository's GitHub Actions workflow and allows you to verify the image before use.
+
+### Benefits of attestation
+
+- **Authenticity**: Verify that the image was built by the official workflow, not by an unauthorised party.
+- **Integrity**: Confirm that the image content has not been tampered with since it was built.
+- **Transparency**: Access build metadata including the exact commit, workflow, and build environment that produced the image.
+- **Compliance**: Meet supply chain security requirements for your organisation or regulatory framework.
+
+### Verifying attestations
+
+You can verify the attestation using the GitHub CLI:
+
+```sh
+gh attestation verify oci://ghcr.io/brabster/terraform-bootstrap-gcp:latest --owner brabster
+```
+
+This command checks that:
+1. The attestation signature is valid and was created by GitHub Actions.
+2. The image digest matches the attested content.
+3. The attestation was created by a workflow in this repository.
+
+For automated verification in your CI/CD pipeline, see [GitHub's attestation documentation](https://docs.github.com/en/actions/security-for-github-actions/using-artifact-attestations/using-artifact-attestations-to-establish-provenance-for-builds).
+
 ## How to use
 
 ### GitHub container registry