Skip to content

Commit d1d4e92

Browse files
feat(release): sign the release assets and attach a source SBOM (#4861)
## What this PR does Implements the release-asset part of #4759: a release cut from a tree that has this change gets an SBOM of its source and one keyless signature that covers all of its assets. These are the two CLOMonitor checks still failing for this repository, `sbom` and `signed_releases`, after #4757 and #4899 brought the project score to 96.69. `hack/upload-assets.sh` now collects its asset list into an array and hands it to the new `hack/sign-release-assets.sh` before the first upload. The script writes three files into `_out/assets`, and they are uploaded with the rest: | File | What it is | |---|---| | `cozystack-source-sbom.spdx.json` | SPDX 2.3 SBOM made with syft, over `git archive HEAD` (the committed release tree, without `_out/`, `.release-tooling` or runner leftovers) and the unpacked `cozypkg-*.tar.gz` binaries. It does **not** describe the container images that `packages/` pins by digest (their SBOMs are #2937, A2 in #3278) or the Talos ISO, disk, kernel and initramfs images. It is named by what it covers, so `cozystack-sbom` stays free for an SBOM of the release as a whole. CLOMonitor's `sbom` check matches `sbom` in an asset name. | | `cozystack-checksums.txt` | SHA-256 of every uploaded asset and of the SBOM. | | `cozystack-checksums.txt.sigstore.json` | Sigstore bundle of `cosign sign-blob` over the checksums, keyless, signed with the job's GitHub OIDC identity. | Before it returns, the script runs the same `cosign verify-blob` that `docs/release.md` gives users, with `--certificate-identity-regexp '^https://github\.com/cozystack/cozystack/\.github/workflows/(tags\.yaml@refs/tags/v|promote-rc\.yaml@refs/heads/main$)'`: `tags.yaml` on a `v*` tag push, `promote-rc.yaml` dispatched from `main`. A signature that check would reject therefore fails the job before anything is uploaded. It also refuses its own three outputs as inputs: `promote-rc.yaml` downloads every rc asset, and a stable release has to get freshly computed checksums and a fresh signature, since promotion restamps several assets. Workflows: `tags.yaml::prepare-release` and `promote-rc.yaml::promote`, the two jobs that call `make upload_assets`, get `id-token: write` and two setup steps: - syft v1.54.1 from its release tarball, checked against a committed SHA-256 (`c069905b…`, the release's checksums entry; the checksums file verifies against anchore/syft's keyless release signature). Not `anchore/sbom-action/download-syft`: pinned by commit, it still runs syft's `install.sh` fetched from a tag at run time, in a job that holds the app token, the GHCR login and `id-token: write`. v1.54.1 is past GHSA-mw2c-m758-9v5q (fixed in v1.52.0). `hack/ci-tool-installs-contract.bats` now fails on `anchore/sbom-action`, on a syft install script, on a syft download without `sha256sum -c` and on version or checksum drift between the two workflows. - `sigstore/cosign-installer` v4.1.2, pinned by SHA, with `cosign-release: v3.1.3`: the version `docs/release.md` asks users for, so the job checks its own signature the way they will. The action verifies that binary against cosign's keyless and KMS bundles with its digest-pinned bootstrap cosign. `hack/ci-tool-installs-contract.bats` holds the action commit and the release equal in both workflows and fails on a step without `cosign-release`. `docs/release.md` gets a "Release signatures and SBOM" section with the user-side verification: cosign v3.1.3 or later (v2.6.5 on the v2 line), the two commands joined with `&&`, what the SBOM covers and what the certificate identity proves. It now also says, at each place `promote-rc.yaml` is run, that it is dispatched from `main` only. ### Decisions for the release owners - **Fail closed.** If Fulcio or Rekor is down, the release job fails and nothing is uploaded. I chose that so that no release goes out unsigned. If you would rather publish unsigned than block, the change is a `|| echo ::warning::` around the call in `upload-assets.sh`. - **Promotion runs the rc tree's script.** `promote-rc.yaml` calls `make upload_assets` from the rc checkout, not from `.release-tooling`. The first signed stable release is therefore the promotion of the first rc tagged after this merges. `release-1.6` gets signatures only if this is backported. CLOMonitor reads the latest release, so the score moves only when that release carries the files. - **Certificate identity pins the refs** (decided in review): `tags.yaml@refs/tags/v…` and `promote-rc.yaml@refs/heads/main`. A `promote-rc.yaml` dispatched from another branch fails the job's own check at the upload step, after the staging branch, the `promotion-*` candidate and the empty draft release exist; nothing in `parse` refuses a non-`main` dispatch up front. Until the `v*` tag rulesets exist, a hand-pushed `v*` tag whose tree has an edited `tags.yaml` still signs, which `docs/release.md` says. - **Follow-ups after the first signed release** (#4759 stays open for them): - `project.documentation.signature-verification` in `security-insights.yml` (#4757); - the SBOM row in `docs/security/self-assessment.md`, which says "Not published at this time"; the image caveat above stays in it. I left both alone so that they do not describe releases that don't exist yet. ### How it was checked - Bats 1.14.0 (the version CI installs), with gh, syft and cosign stubbed: - `hack/sign-release-assets.bats`, 8 tests: what the checksums cover; that syft sees the committed tree and the cozypkg binaries but not untracked files; that the verify identity accepts `tags.yaml` on a `v*` tag and `promote-rc.yaml` on `main`, and rejects a fork, another workflow, `tags.yaml.evil`, `tags.yaml` on a branch, and `promote-rc.yaml` on `release-1.6`, on `main-evil` and on a tag; that `docs/release.md` shows the same regexp as the script; that a failed verification fails the script; that it refuses a missing asset, assets split over two directories (with a same-named file in both, so the test fails if the directory check is removed) and its own outputs as input. - `hack/upload-assets.bats`, 4 tests, new: the exact upload list and order (the assets, then the SBOM, the checksums and the bundle); that the checksums name every upload but the last two; zero `gh` calls when verification fails or an asset is missing. The old `upload-assets.sh` fails all four, a version that signs after uploading fails the last two. - `hack/ci-tool-installs-contract.bats`, 8 tests. Putting `download-syft` back, dropping the `sha256sum -c` line, letting `SYFT_VERSION` drift between the workflows, dropping `cosign-release` from one step, letting it drift, unpinning the installer or giving one step another installer commit each fails it. - Putting the old any-ref regexp back in the script fails the identity test and the docs tie; putting it back in the docs alone fails the tie. - The meta-suites `bats-strict-setup`, `bats-no-negated-assert`, `bats-no-exit-trap`, `bats-runner-coverage` and `bats-runner-contract` pass: 90 tests across these eight files. - The pinned regexp gives the same accept/reject results under `grep -E` and Go's `regexp` (what cosign uses). cosign-installer's install script at the pinned commit, run as written with `cosign-release: v3.1.3`, verifies the binary's keyless and KMS bundles and installs v3.1.3 (its SHA-256 matches `cosign_checksums.txt`). `--yes`, `--bundle`, `--certificate-identity-regexp` and `--certificate-oidc-issuer` are listed, not deprecated, in cosign v3.1.3's help. - The `Set up syft` step's script, run as written with `RUNNER_TEMP`/`GITHUB_PATH` set: the checksum passes and `syft version` reports 1.54.1. A real syft v1.54.1 run through `hack/sign-release-assets.sh` (cosign stubbed) over this tree and the v1.6.5 `cozypkg-linux-amd64.tar.gz` took 10 s and wrote an SPDX 2.3 document with 920 packages: 440 golang, 373 npm, 103 github, 4 without a purl; 60 come from the cozypkg binary. - cosign behaviour behind the docs, with a key-signed legacy bundle whose `cert` holds the bare public key, against the documented identity regexp (tlog ignored, since an attacker can upload their own entry): v2.6.4 and v3.1.2 print "Verified OK", v2.6.5 and v3.1.3 reject it. `--new-bundle-format` makes v2.6.4 reject it but not v3.1.2, so the docs give the minimum version and not the flag. A real keyless protobuf bundle (syft's) verifies on v2.6.5 and v3.1.3. - zizmor 1.26.1 `--offline` reports no findings. actionlint 1.7.12 (with `.github/actionlint.yaml`) reports the same 13 pre-existing info-level shellcheck notes in `tags.yaml`/`promote-rc.yaml` as before, nothing new. shellcheck passes on both scripts. `hack/check-commit-trailers.sh` passes. - Not checked: a real keyless signature. It needs the OIDC token of a job in this repository, so the first rc after the merge is the end-to-end test. Cutting an `-alpha.N` first would exercise it without touching an rc. ### Screenshots <!-- REQUIRED for UI changes: attach screenshots or screen recordings demonstrating the visual impact of your changes. PRs with UI changes without screenshots will not be merged. --> ### Downstream repositories - [x] No downstream repository is affected by this change - [ ] [cozystack/website](https://github.com/cozystack/website) - follow-up: - [ ] [cozystack/terraform-provider-cozystack](https://github.com/cozystack/terraform-provider-cozystack) - follow-up: - [ ] [cozystack/ansible-cozystack](https://github.com/cozystack/ansible-cozystack) - follow-up: - [ ] [cozystack/ccp](https://github.com/cozystack/ccp) - follow-up: - [ ] [cozystack/talm](https://github.com/cozystack/talm) - follow-up: - [ ] [cozystack/cozyhr](https://github.com/cozystack/cozyhr) - follow-up: - [ ] [cozystack/cozy-proxy](https://github.com/cozystack/cozy-proxy) - follow-up: - [ ] [cozystack/cozystack-telemetry-server](https://github.com/cozystack/cozystack-telemetry-server) - follow-up: - [ ] [cozystack/external-apps-example](https://github.com/cozystack/external-apps-example) - follow-up: - [ ] [cozystack/examples](https://github.com/cozystack/examples) - follow-up: - [ ] [cozystack/community](https://github.com/cozystack/community) - follow-up: I checked the trigger map file by file. The only entry `hack/upload-assets.sh` can trigger is renaming a release asset, because the website install pages hardcode asset names. This PR adds three assets and renames none of the released ones, `cozypkg-checksums.txt` included (the SBOM was renamed to `cozystack-source-sbom.spdx.json` in review, before any release carried it). The workflow and docs changes match no entry. ### Release note ```release-note feat(release): releases carry cozystack-source-sbom.spdx.json, an SPDX SBOM of the source tree and the cozypkg binaries (not of the container or Talos images), cozystack-checksums.txt with the SHA-256 of each asset, and cozystack-checksums.txt.sigstore.json, a keyless Sigstore signature over the checksums made by the release workflow; docs/release.md shows how to verify a download with cosign v3.1.3 or later. ``` Refs #4759 <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **New Features** * Releases now include an SPDX software bill of materials, SHA-256 checksums, and a keyless Sigstore signature bundle. * Release assets are verified against the expected workflow identity before upload; uploads stop if verification fails. * **Documentation** * Added guidance on release signatures, SBOM coverage, asset verification, and which branch dispatches release workflows. * **Tests** * Added coverage for generated release files, upload behavior, and signing and verification failures. <!-- end of auto-generated comment: release notes by coderabbit.ai -->
2 parents aed7fa8 + bc24b58 commit d1d4e92

8 files changed

Lines changed: 711 additions & 35 deletions

File tree

‎.github/workflows/promote-rc.yaml‎

Lines changed: 38 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -258,6 +258,7 @@ jobs:
258258
contents: write # push the release-X.Y.Z staging branch, stage the draft release
259259
packages: write # publish the temporary stable-candidate packages artifact
260260
pull-requests: write # reserved for parity; the PR is opened in open-pr
261+
id-token: write # keyless signing of the release checksums in hack/upload-assets.sh
261262

262263
# open-pr reads these from `promote`, which passes the parse job's validated
263264
# outputs straight through.
@@ -410,8 +411,8 @@ jobs:
410411
# installer values differently between two promotions of the same rc. The
411412
# version tracks packages/core/testing/images/e2e-sandbox/Dockerfile.
412413
#
413-
# yq is additionally pinned BY CONTENT, which nothing else in this repo
414-
# does. It earns the exception by being the one downloaded binary with
414+
# yq is additionally pinned BY CONTENT (syft further down is too, for
415+
# another reason). It earns that by being the one downloaded binary with
415416
# write authority over what a release contains: it is what stamps the
416417
# candidate digest into installer values. skopeo, helm and oras only move
417418
# bytes that are already digest-addressed, so a substituted one is caught
@@ -576,6 +577,41 @@ jobs:
576577
run: |
577578
make manifests assets-cozypkg openapi-json COZYSTACK_VERSION="${STABLE_VERSION}"
578579
580+
# The rc tree's hack/upload-assets.sh writes a fresh SBOM with syft and
581+
# signs the stable checksums with cosign, keylessly, as this job. An rc
582+
# tagged from a tree without hack/sign-release-assets.sh uploads neither,
583+
# and the two tools go unused.
584+
#
585+
# syft is pinned by content, like yq above. This job holds the app token,
586+
# the GHCR login and an OIDC token for the identity users are told to
587+
# trust, and anchore/sbom-action/download-syft, though pinned by commit,
588+
# runs syft's install.sh fetched from a tag at run time. SYFT_SHA256 is the
589+
# release's own checksums entry, whose keyless signature by anchore/syft's
590+
# release workflow was checked when the version was chosen. Bump both
591+
# together, here and in tags.yaml; hack/ci-tool-installs-contract.bats
592+
# holds them equal.
593+
- name: Set up syft
594+
env:
595+
SYFT_VERSION: "1.54.1"
596+
SYFT_SHA256: "c069905b391cc4c20a5ba65ad5c10be2a7ba074f8ea6ad203e24d14e303dad47"
597+
run: |
598+
syft_dir="${RUNNER_TEMP}/syft"
599+
mkdir -p "$syft_dir"
600+
curl -fsSL -o "$syft_dir/syft.tar.gz" \
601+
"https://github.com/anchore/syft/releases/download/v${SYFT_VERSION}/syft_${SYFT_VERSION}_linux_amd64.tar.gz"
602+
printf '%s %s\n' "$SYFT_SHA256" "$syft_dir/syft.tar.gz" | sha256sum -c -
603+
tar -xzf "$syft_dir/syft.tar.gz" -C "$syft_dir" syft
604+
rm -f "$syft_dir/syft.tar.gz"
605+
echo "$syft_dir" >> "$GITHUB_PATH"
606+
# cosign is the version docs/release.md asks users for, so the job checks
607+
# its own signature the way they will. The action verifies that binary
608+
# against cosign's keyless and KMS bundles with its digest-pinned
609+
# bootstrap cosign. Bump with tags.yaml; the contract test holds them equal.
610+
- name: Set up cosign
611+
uses: sigstore/cosign-installer@6f9f17788090df1f26f669e9d70d6ae9567deba6 # v4.1.2
612+
with:
613+
cosign-release: v3.1.3
614+
579615
- name: Create draft stable release and upload assets
580616
env:
581617
GH_TOKEN: ${{ steps.app-token.outputs.token }}

‎.github/workflows/tags.yaml‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -398,6 +398,7 @@ jobs:
398398
packages: write
399399
pull-requests: write
400400
actions: write
401+
id-token: write # keyless signing of the release checksums in hack/upload-assets.sh
401402

402403
steps:
403404
- name: Generate GitHub App token
@@ -532,6 +533,34 @@ jobs:
532533
533534
core.setOutput('upload_url', rel.upload_url);
534535
536+
# hack/upload-assets.sh writes the release SBOM with syft and signs the
537+
# checksums of every asset with cosign, keylessly, as this job. syft is
538+
# the release tarball checked against a committed SHA-256, for the reason
539+
# given at the same step in promote-rc.yaml: this job holds the app token,
540+
# the GHCR login and an OIDC token for the signing identity, so it runs no
541+
# install script fetched at run time. Bump with promote-rc.yaml.
542+
- name: Set up syft
543+
if: needs.build-amd64.outputs.release_exists == 'false'
544+
env:
545+
SYFT_VERSION: "1.54.1"
546+
SYFT_SHA256: "c069905b391cc4c20a5ba65ad5c10be2a7ba074f8ea6ad203e24d14e303dad47"
547+
run: |
548+
syft_dir="${RUNNER_TEMP}/syft"
549+
mkdir -p "$syft_dir"
550+
curl -fsSL -o "$syft_dir/syft.tar.gz" \
551+
"https://github.com/anchore/syft/releases/download/v${SYFT_VERSION}/syft_${SYFT_VERSION}_linux_amd64.tar.gz"
552+
printf '%s %s\n' "$SYFT_SHA256" "$syft_dir/syft.tar.gz" | sha256sum -c -
553+
tar -xzf "$syft_dir/syft.tar.gz" -C "$syft_dir" syft
554+
rm -f "$syft_dir/syft.tar.gz"
555+
echo "$syft_dir" >> "$GITHUB_PATH"
556+
# cosign is the version docs/release.md asks users for, as in
557+
# promote-rc.yaml. Bump with it.
558+
- name: Set up cosign
559+
if: needs.build-amd64.outputs.release_exists == 'false'
560+
uses: sigstore/cosign-installer@6f9f17788090df1f26f669e9d70d6ae9567deba6 # v4.1.2
561+
with:
562+
cosign-release: v3.1.3
563+
535564
# The assets were built by build-amd64; the operator manifests are
536565
# rendered here, from the tree pinned on the index digests.
537566
- name: Upload assets

0 commit comments

Comments
 (0)