Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
ci(release): attest build provenance for the promoted image digest
Yudhi Armyndharis45c91be6e4f1
diff --git a/.github/workflows/release.yml b/.github/workflows/release.ymlindex 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 tagsruns-on: ubuntu-latesttimeout-minutes: 15permissions:packages: write+ id-token: write+ attestations: writeneeds: [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 tagsenv: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: readsteps:- name: Set up Docker Buildxuses: 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=1fi+ # 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+ fiecho "$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 1fi- 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.mdindex 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`)### Operationsdiff --git a/src/common/release-gate-parity.spec.ts b/src/common/release-gate-parity.spec.tsindex 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/);+ });+});