feat(security): deploy signed release image locks (#1565)

Author: FelixTJDietrich

.changeset/consume-release-image-lock.md

@@ -0,0 +1,5 @@
+---
+"hephaestus": minor
+---
+
+**Operators:** Install, upgrade, and roll back with the signed release image lock; production and staging now refuse mutable tags or any image digest that did not pass the release evidence gate.

.github/workflows/cd-staging.yml

@@ -23,6 +23,8 @@ jobs:
   validate:
     name: "Render compose stacks"
     runs-on: ubuntu-latest
+    env:
+      COMPOSE_ENV_FILES: .env,release-lock.env
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
@@ -42,6 +44,13 @@ jobs:
             -e 's|^HEPHAESTUS_AUTH_STATE_COOKIE_KEY=$|HEPHAESTUS_AUTH_STATE_COOKIE_KEY=Y2ktbm90LWEtcmVhbC1zdGF0ZS1jb29raWUta2V5|' \
             -e 's|^WEBHOOK_SECRET=$|WEBHOOK_SECRET=ci000000000000000000000000000000000|' \
             .env
+          while IFS= read -r image; do
+            name="HEPHAESTUS_IMAGE_${image^^}"
+            name=${name//-/_}
+            printf '%s=%s@sha256:%s\n' "$name" "example.invalid/${image}" "$(printf '0%.0s' {1..64})" >> release-lock.env
+          done < <(jq -r '.images[], .upstream[].name' ../../security/release-images.json)
+          printf 'IMAGE_TAG=0.0.0\nHEPHAESTUS_RELEASE=v0.0.0\nHEPHAESTUS_RELEASE_COMMIT=%s\n' \
+            "$(printf '0%.0s' {1..40})" >> release-lock.env
           docker compose config > /dev/null
           echo "Rendered services:"
           docker compose config --services | sort
@@ -81,16 +90,6 @@ jobs:
           [ "$published" = "80 443 " ] || {
             echo "::error::reverse-proxy publishes '$published', expected '80 443 ' — !override was ignored"; exit 1; }
 
-      - name: Assert the pinned release version has not drifted
-        run: |
-          set -euo pipefail
-          # scripts/sync-release-version.ts keeps these equal to the release on
-          # every Version PR; a mismatch means someone edited one by hand.
-          pkg=$(jq -r '.version' package.json)
-          env_tag=$(grep -m1 '^IMAGE_TAG=' docker/self-host/.env.example | cut -d= -f2)
-          [ "$pkg" = "$env_tag" ] || {
-            echo "::error::IMAGE_TAG=$env_tag in .env.example != package.json $pkg (run scripts/sync-release-version.ts)"; exit 1; }
-
       - name: Render the reference deployment
         working-directory: docker
         run: |
@@ -99,4 +98,4 @@ jobs:
           # still render, not that they are correct for production.
           docker compose \
             -f compose.proxy.yaml -f compose.core.yaml -f compose.app.yaml \
-            --env-file self-host/.env config --quiet
+            --env-file self-host/.env --env-file self-host/release-lock.env config --quiet

.github/workflows/ci-compose-validate.yml

@@ -25,11 +25,6 @@ on:
         required: false
         type: string
         default: "true"
-      release_pin_fetcher_changed:
-        description: "Whether release-pin-fetcher image inputs changed"
-        required: false
-        type: string
-        default: "true"
       postgres_image_changed:
         description: "Whether the PostgreSQL image inputs changed"
         required: false
@@ -133,32 +128,6 @@ jobs:
         org.opencontainers.image.licenses=MIT
         hephaestus.component=agent-pi
 
-  release-pin-fetcher-build:
-    name: "Release Pin Fetcher"
-    if: >-
-      inputs.should_skip != 'true' &&
-      (inputs.release_pin_fetcher_changed == 'true' || github.event_name != 'pull_request')
-    uses: ./.github/workflows/reusable-docker-build.yml
-    with:
-      image-name: "ls1intum/hephaestus/release-pin-fetcher"
-      docker-file: "./docker/release-pin-fetcher/Dockerfile"
-      docker-context: "./docker/release-pin-fetcher"
-      registry: "ghcr.io"
-      # amd64-only on PRs (main/release build both arches). See reusable-docker-build.yml.
-      single-arch: ${{ github.event_name == 'pull_request' }}
-      tags: |
-        ${{ github.ref_name }}
-        ${{ github.sha }}
-        ${{ github.event_name == 'pull_request' && github.event.pull_request.head.sha || '' }}
-        ci-${{ github.run_number }}
-        ${{ github.event_name == 'pull_request' && format('pr-{0}', github.event.number) || '' }}
-      labels: |
-        org.opencontainers.image.title=Hephaestus Release Pin Fetcher
-        org.opencontainers.image.description=Init container that downloads + cosign-verifies the signed release pin asset
-        org.opencontainers.image.vendor=AET TUM
-        org.opencontainers.image.licenses=MIT
-        hephaestus.component=release-pin-fetcher
-
   postgres-build:
     name: "Postgres (pg_partman)"
     if: >-
@@ -192,7 +161,7 @@ jobs:
     if: >-
       inputs.should_skip != 'true' && github.event_name == 'pull_request' &&
       (inputs.webapp_changed != 'true' || inputs.application_server_changed != 'true' ||
-       inputs.agent_images_changed != 'true' || inputs.release_pin_fetcher_changed != 'true' ||
+       inputs.agent_images_changed != 'true' ||
        inputs.postgres_image_changed != 'true')
     runs-on: ubuntu-latest
     outputs:
@@ -216,7 +185,6 @@ jobs:
           WEBAPP_CHANGED: ${{ inputs.webapp_changed }}
           APPLICATION_SERVER_CHANGED: ${{ inputs.application_server_changed }}
           AGENT_IMAGES_CHANGED: ${{ inputs.agent_images_changed }}
-          RELEASE_PIN_FETCHER_CHANGED: ${{ inputs.release_pin_fetcher_changed }}
           POSTGRES_IMAGE_CHANGED: ${{ inputs.postgres_image_changed }}
           PR_NUMBER: ${{ github.event.number }}
           BASE_SHA: ${{ github.event.pull_request.base.sha }}
@@ -260,5 +228,4 @@ jobs:
             echo "application-server-published=true" >> "$GITHUB_OUTPUT"
           fi
           [ "$AGENT_IMAGES_CHANGED" = "true" ] || tag_image agent-pi
-          [ "$RELEASE_PIN_FETCHER_CHANGED" = "true" ] || tag_image release-pin-fetcher
           [ "$POSTGRES_IMAGE_CHANGED" = "true" ] || tag_image postgres

.github/workflows/ci-docker-build.yml

@@ -163,7 +163,7 @@ jobs:
           if grep -rEnI "$NEEDLE" \
                 --exclude-dir=node_modules --exclude-dir=target --exclude-dir=.git \
                 . \
-              | grep -vE '^\./(MIGRATION\.md|docs/admin/agent-image-digests\.md):' ; then
+              | grep -vE '^\./(MIGRATION\.md|docs/admin/release-image-lock\.md):' ; then
             echo "::error::Legacy agent image is removed in issue #1076; relocate any new references to MIGRATION.md."
             exit 1
           fi
@@ -177,7 +177,7 @@ jobs:
           if grep -rEnI "$NEEDLE" \
                 --exclude-dir=node_modules --exclude-dir=target --exclude-dir=.git \
                 . \
-              | grep -vE '^\./(MIGRATION\.md|docs/admin/agent-image-digests\.md|docs/decisions/0031-.*\.md|server/application/src/test/java/de/tum/cit/aet/hephaestus/agent/sandbox/AgentImageReferenceGuardTest\.java):' ; then
+              | grep -vE '^\./(MIGRATION\.md|docs/admin/release-image-lock\.md|docs/decisions/0031-.*\.md|server/application/src/test/java/de/tum/cit/aet/hephaestus/agent/sandbox/AgentImageReferenceGuardTest\.java):' ; then
             echo "::error::A release-channel agent image tag resolves to another release's image (ADR 0031). Leave the reference unset so it follows this deployment's image tag, or pin a digest."
             exit 1
           fi
@@ -191,7 +191,7 @@ jobs:
           if grep -rEnI 'docker/agent-image-pin(\.local)?\.env' \
                 --exclude-dir=node_modules --exclude-dir=target --exclude-dir=.git \
                 . \
-              | grep -vE '^\./(MIGRATION\.md|docs/admin/agent-image-digests\.md):' \
+              | grep -vE '^\./(MIGRATION\.md|docs/admin/release-image-lock\.md):' \
               | grep -vE '^\./scripts/check-agent-instructions\.ts:[0-9]+:[[:space:]]*value: "docker/agent-image-pin(\.local)?\.env",$' ; then
             echo "::error::Legacy pin-file names are allowed only in migration history, the digest guide, and exact instruction-checker exceptions."
             exit 1

.github/workflows/ci-security-scan.yml

@@ -25,7 +25,6 @@ jobs:
       application-server-image: ${{ steps.filter.outputs.application-server-image }}
       e2e: ${{ steps.filter.outputs.e2e }}
       agent-images: ${{ steps.filter.outputs.agent-images }}
-      release-pin-fetcher: ${{ steps.filter.outputs.release-pin-fetcher }}
       postgres-image: ${{ steps.filter.outputs.postgres-image }}
       docs: ${{ steps.filter.outputs.docs }}
       ci-config: ${{ steps.filter.outputs.ci-config }}
@@ -138,8 +137,6 @@ jobs:
               - '.github/actions/setup-bun/**'
             agent-images:
               - 'docker/agents/**'
-            release-pin-fetcher:
-              - 'docker/release-pin-fetcher/**'
             postgres-image:
               - 'docker/postgres/**'
             docs:
@@ -324,7 +321,6 @@ jobs:
       webapp_changed: ${{ (needs.detect-changes.outputs.webapp-image == 'true' || needs.detect-changes.outputs.docker-config == 'true' || github.event_name != 'pull_request') && 'true' || 'false' }}
       application_server_changed: ${{ (needs.detect-changes.outputs.application-server-image == 'true' || needs.detect-changes.outputs.docker-config == 'true' || github.event_name != 'pull_request') && 'true' || 'false' }}
       agent_images_changed: ${{ (needs.detect-changes.outputs.agent-images == 'true' || needs.detect-changes.outputs.docker-config == 'true' || github.event_name != 'pull_request') && 'true' || 'false' }}
-      release_pin_fetcher_changed: ${{ (needs.detect-changes.outputs.release-pin-fetcher == 'true' || needs.detect-changes.outputs.docker-config == 'true' || github.event_name != 'pull_request') && 'true' || 'false' }}
       postgres_image_changed: ${{ (needs.detect-changes.outputs.postgres-image == 'true' || needs.detect-changes.outputs.docker-config == 'true' || github.event_name != 'pull_request') && 'true' || 'false' }}
 
   all-ci-passed: