Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

ci(release): attest build provenance for the promoted image digest

Yudhi Armyndharis45c91be6e4f1
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 1acf18bbe..1430b0c48 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -678,14 +678,19 @@ jobs:
# promoted set is by construction the build's own tag set, never a re-derived pattern).
# `imagetools create` re-points tags at the existing manifest list without rebuilding, so the
# promoted image is bit-identical to the one tested on both registries, and its provenance and
- # SBOM attestations travel with it. If boot-smoke fails, this job never runs and the release
- # tags never appear anywhere.
+ # SBOM attestations travel with it. Before re-pointing anything, the job records a signed
+ # build-provenance attestation for that digest, which `gh attestation verify` checks against this
+ # repository; the id-token grant it needs lives on this job alone, not on the jobs that build or
+ # test the image. If boot-smoke fails, this job never runs and the release tags never appear
+ # anywhere.
promote:
name: Promote image to release tags
runs-on: ubuntu-latest
timeout-minutes: 15
permissions:
packages: write
+ id-token: write
+ attestations: write
needs: [docker, boot-smoke, image-scan]
steps:
- name: Set up Docker Buildx
@@ -707,6 +712,22 @@ jobs:
username: ${{ secrets.DOCKERHUB_USERNAME }}
password: ${{ secrets.DOCKERHUB_TOKEN }}
+ - name: Resolve the image name to attest
+ id: image
+ env:
+ REPO: ${{ github.repository }}
+ run: echo "name=ghcr.io/${REPO,,}" >> "$GITHUB_OUTPUT"
+
+ # Before any release tag moves, so a failed attestation publishes nothing. Keyed by digest in
+ # GitHub's attestation store, so it covers every tag promoted below on both registries, each of
+ # which must resolve to this digest. Not pushed to the registry, which would add an untagged
+ # package version per release.
+ - name: Attest build provenance for the tested digest
+ uses: actions/attest@1e69f48acb82d1966a394da916b4c1698aa569d6 # v4.2.2
+ with:
+ subject-name: ${{ steps.image.outputs.name }}
+ subject-digest: ${{ needs.docker.outputs.digest }}
+
- name: Tag the smoke-tested image with the release tags
env:
REPO: ${{ github.repository }}
@@ -837,6 +858,11 @@ jobs:
# best-effort job, so gate on promote rather than on its result.
needs: [docker, promote, cleanup-staging]
if: always() && needs.promote.result == 'success'
+ # attestations: read for `gh attestation verify` below. GH_TOKEN is an API credential for the
+ # attestation lookup, not a registry login: every pull here stays anonymous.
+ permissions:
+ contents: read
+ attestations: read
steps:
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@f87e5991a6d7451dcb8d9637bfbc97413f497069 # v4
@@ -846,6 +872,7 @@ jobs:
env:
TAGS: ${{ needs.docker.outputs.tags }}
EXPECTED_DIGEST: ${{ needs.docker.outputs.digest }}
+ GH_TOKEN: ${{ github.token }}
run: |
# Fail closed. A verification step that reports success because something upstream of the
# assertion broke is worse than no verification at all — `set -e` plus the checked-count
@@ -875,6 +902,15 @@ jobs:
echo "::error::$ref resolves to $digest, not the tested build digest $EXPECTED_DIGEST"
failed=1
fi
+ # The same pins as the operator checklist in docs/04: --repo alone accepts an attestation
+ # from any workflow in the repository on any ref.
+ if ! gh attestation verify "oci://$ref" --repo "$GITHUB_REPOSITORY" \
+ --signer-workflow "$GITHUB_REPOSITORY/.github/workflows/release.yml" \
+ --source-ref "$GITHUB_REF" > /tmp/attest.txt 2>&1; then
+ echo "::error::$ref has no build-provenance attestation from $GITHUB_REPOSITORY's release workflow at $GITHUB_REF"
+ cat /tmp/attest.txt
+ failed=1
+ fi
echo "$ref OK ($digest)"
checked=$((checked + 1))
echo "::endgroup::"
@@ -887,4 +923,4 @@ jobs:
echo "::error::The release is not usable. Re-point the missing tags before announcing it."
exit 1
fi
- echo "all $checked release tags are publicly pullable, multi-arch, and digest-identical to the tested build"
+ echo "all $checked release tags are publicly pullable, multi-arch, digest-identical to the tested build, and attested"
diff --git a/docs/04-security-design.md b/docs/04-security-design.md
index 5b1699935..0079f3568 100644
--- a/docs/04-security-design.md
+++ b/docs/04-security-design.md
@@ -542,6 +542,7 @@ flowchart TB
- [ ] CORS properly configured
- [ ] Firewall rules set
- [ ] Regular security updates
+- [ ] Release image (releases after 0.23.7; earlier images carry no attestation) verified as built by the release workflow at its tag: `gh attestation verify oci://ghcr.io/rmyndharis/openwa:<version> --repo rmyndharis/OpenWA --signer-workflow rmyndharis/OpenWA/.github/workflows/release.yml --source-ref refs/tags/v<version>` (the same digest, and so the same check, applies to `docker.io/rmyndharis/openwa`)
### Operations
diff --git a/src/common/release-gate-parity.spec.ts b/src/common/release-gate-parity.spec.ts
index caddb1395..4508a27dd 100644
--- a/src/common/release-gate-parity.spec.ts
+++ b/src/common/release-gate-parity.spec.ts
@@ -125,3 +125,69 @@ describe('the release and weekly audits fail when the audit cannot run', () => {
expect(steps.some(step => step.env?.CHECK_AUDIT_REQUIRED !== undefined)).toBe(false);
});
});
+
+/**
+ * BuildKit's provenance and SBOM travel inside the image index unsigned, so nothing a user could check
+ * tied a published image to this workflow. promote now records a signed build-provenance attestation
+ * for the tested digest, and verify-published checks it on every promoted tag of both registries.
+ */
+describe('released images carry a verifiable build-provenance attestation', () => {
+ type Perms = Record<string, string> | string | undefined;
+ type AttestStep = { uses?: string; run?: string; with?: Record<string, string> };
+ type AttestJob = { permissions?: Perms; steps?: AttestStep[] };
+ const jobs = (): Record<string, AttestJob> =>
+ (yaml.load(fs.readFileSync(path.join(workflowDir, 'release.yml'), 'utf8')) as { jobs?: Record<string, AttestJob> })
+ .jobs ?? {};
+ const grant = (perms: Perms, key: string): string | undefined =>
+ typeof perms === 'object' && perms !== null ? perms[key] : undefined;
+
+ // Attesting first means a failed attestation leaves no release tag published.
+ it('promote attests the tested digest before re-pointing the release tags', () => {
+ const promote = jobs().promote;
+ const steps = promote?.steps ?? [];
+ expect(steps.length).toBeGreaterThan(1);
+ const attest = steps.findIndex(step =>
+ /^actions\/attest(?:-build-provenance)?@[0-9a-f]{40}\b/.test(step.uses ?? ''),
+ );
+ const retag = steps.findIndex(step => executableLines(step.run ?? '').includes('imagetools create'));
+ expect(attest).toBeGreaterThan(-1);
+ expect(retag).toBeGreaterThan(attest);
+ expect(steps[attest].with?.['subject-digest']).toContain('needs.docker.outputs.digest');
+ expect(grant(promote?.permissions, 'id-token')).toBe('write');
+ expect(grant(promote?.permissions, 'attestations')).toBe('write');
+ });
+
+ // The signing grant stays on the one job that needs it, away from the build and test jobs.
+ it.each(['docker', 'boot-smoke', 'image-scan'])('%s cannot mint an OIDC token', job => {
+ expect(jobs()[job]).toBeDefined();
+ expect(grant(jobs()[job].permissions, 'id-token')).toBeUndefined();
+ });
+
+ it('verify-published checks the attestation of every promoted tag', () => {
+ const verify = jobs()['verify-published'];
+ const run = (verify?.steps ?? []).map(step => executableLines(step.run ?? '')).join('\n');
+ expect(run).toMatch(/gh attestation verify "oci:\/\/\$ref"/);
+ // The same pins the operator checklist below uses, so a green release proves what docs/04 promises.
+ expect(run).toContain('--signer-workflow "$GITHUB_REPOSITORY/.github/workflows/release.yml"');
+ expect(run).toContain('--source-ref "$GITHUB_REF"');
+ expect(grant(verify?.permissions, 'attestations')).toBe('read');
+ });
+
+ // Without the two pins, `gh attestation verify` accepts any workflow in the repository on any ref,
+ // which is less than the checklist promises. Image tags carry no `v`; release git tags do.
+ it('the operator checklist pins the release workflow and the tag it ran on', () => {
+ const doc = fs.readFileSync(path.join(__dirname, '..', '..', 'docs', '04-security-design.md'), 'utf8');
+ const command = /`(gh attestation verify [^`]*)`/.exec(doc)?.[1];
+ expect(command).toContain('oci://ghcr.io/rmyndharis/openwa:<version>');
+ expect(command).toContain('--signer-workflow rmyndharis/OpenWA/.github/workflows/release.yml');
+ expect(command).toContain('--source-ref refs/tags/v<version>');
+ });
+
+ // The attest step first ran after v0.23.7, so the check would reject every image published before it.
+ it('the operator checklist scopes the check to releases that carry an attestation', () => {
+ const doc = fs.readFileSync(path.join(__dirname, '..', '..', 'docs', '04-security-design.md'), 'utf8');
+ const item = doc.split('\n').find(line => line.includes('`gh attestation verify '));
+ expect(item).toMatch(/releases after 0\.23\.7/);
+ expect(item).toMatch(/earlier images carry no attestation/);
+ });
+});