Skip to content

Commit 1571346

Browse files
committed
feat(release): sign the release assets and attach a source SBOM
No release carried a signature or an SBOM, so users could verify none of the ISO, disk images, kernel, initramfs, manifests and cozypkg binaries they download, and the OpenSSF Scorecard Signed-Releases check and CLOMonitor's signed_releases and sbom checks failed. hack/upload-assets.sh now hands its asset list to the new hack/sign-release-assets.sh before the first upload. That script writes cozystack-source-sbom.spdx.json with syft over the committed tree and the cozypkg binaries, cozystack-checksums.txt with the SHA-256 of every asset and the SBOM, and cozystack-checksums.txt.sigstore.json with a keyless cosign signature over the checksums. The SBOM does not describe the container images or the Talos boot images, which is what its name says; image SBOMs are #2937. The script verifies the bundle against the tags.yaml and promote-rc.yaml identities before returning, so a bad signature fails the job with nothing uploaded, and hack/upload-assets.bats pins the upload list and that order. The two jobs that call make upload_assets get id-token: write, cosign from the SHA-pinned cosign-installer, and syft from its release tarball checked against a committed SHA-256, because anchore/sbom-action/download-syft runs an install script fetched at run time; hack/ci-tool-installs-contract.bats now covers syft. docs/release.md describes the files, what the SBOM covers, the minimum cosign version to verify a download with and what the certificate identity proves. Refs #4759 Assisted-by: LLM Signed-off-by: Marian Koreniuk <[email protected]>
1 parent 1d813c9 commit 1571346

8 files changed

Lines changed: 661 additions & 33 deletions

File tree

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

Lines changed: 32 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,35 @@ 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+
- name: Set up cosign
607+
uses: sigstore/cosign-installer@6f9f17788090df1f26f669e9d70d6ae9567deba6 # v4.1.2
608+
579609
- name: Create draft stable release and upload assets
580610
env:
581611
GH_TOKEN: ${{ steps.app-token.outputs.token }}

‎.github/workflows/tags.yaml‎

Lines changed: 25 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,30 @@ 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+
- name: Set up cosign
557+
if: needs.build-amd64.outputs.release_exists == 'false'
558+
uses: sigstore/cosign-installer@6f9f17788090df1f26f669e9d70d6ae9567deba6 # v4.1.2
559+
535560
# The assets were built by build-amd64; the operator manifests are
536561
# rendered here, from the tree pinned on the index digests.
537562
- name: Upload assets

‎docs/release.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -325,6 +325,32 @@ A stable `vX.Y.Z` is created only by **promoting an existing release-candidate**
325325

326326
So a commit on a supported `release-X.Y` line ships when a maintainer promotes the next rc for that line — not automatically within 24h. Pushing a stable `vX.Y.Z` tag by hand is **not** a supported path: `tags.yaml` fails fast on a stable tag that has no pre-existing draft ("stable tags come from promote-rc.yaml"), and even so the finalize step would refuse to move a pre-existing tag. Pre-releases (`vX.Y.Z-rc.N`, `-alpha.N`, `-beta.N`) are cut with the [`Cut Pre-release Tag`](../.github/workflows/cut-prerelease.yaml) workflow, which pushes the tag as the CI app; [`tags.yaml`](../.github/workflows/tags.yaml) then fires on that push, builds it, and publishes the pre-release. Cutting via the workflow (rather than a manual `git push`) is what lets repo admins lock `v*` tag creation to the CI app — see the tag-protection note below.
327327

328+
## Release signatures and SBOM
329+
330+
A release cut from a tree that has [`hack/sign-release-assets.sh`](../hack/sign-release-assets.sh) carries three files beside its other assets, which [`hack/upload-assets.sh`](../hack/upload-assets.sh) has that script write before it uploads anything. Releases cut before it have none of them, and neither does a maintenance line until the script is backported to it (see below).
331+
332+
- `cozystack-source-sbom.spdx.json` is an SPDX SBOM, made with syft, of the committed source tree (the Go modules, npm lockfiles, GitHub Actions references and other manifests syft reads in it) and of the `cozypkg` binaries in the `cozypkg-*.tar.gz` assets. It does not describe what runs in the cluster: neither the container images that `packages/` pins by digest, whose SBOMs are [#2937](https://github.com/cozystack/cozystack/issues/2937) (item A2 in [#3278](https://github.com/cozystack/cozystack/issues/3278)), nor the Talos ISO, disk, kernel and initramfs images. Its name says what it covers, so that `cozystack-sbom` stays free for an SBOM of the release as a whole.
333+
- `cozystack-checksums.txt` holds the SHA-256 of every other asset and of the SBOM.
334+
- `cozystack-checksums.txt.sigstore.json` is a Sigstore bundle with a keyless cosign signature over the checksums. Its certificate names the workflow that published the release: `tags.yaml` for a pre-release, `promote-rc.yaml` for a stable one.
335+
336+
One signature covers every asset through the checksums. To check a download, verify the checksums, then the file against them, with cosign v3.1.3 or later (v2.6.5 or later on the v2 line):
337+
338+
```sh
339+
cosign verify-blob cozystack-checksums.txt \
340+
--bundle cozystack-checksums.txt.sigstore.json \
341+
--certificate-identity-regexp '^https://github\.com/cozystack/cozystack/\.github/workflows/(tags|promote-rc)\.yaml@' \
342+
--certificate-oidc-issuer https://token.actions.githubusercontent.com &&
343+
sha256sum --check --ignore-missing cozystack-checksums.txt
344+
```
345+
346+
Older cosign accepts a legacy-format bundle that carries a bare public key in place of a certificate and skips the identity and issuer checks for it ([GHSA-fx35-mq7g-6g98](https://github.com/sigstore/cosign/security/advisories/GHSA-fx35-mq7g-6g98)), so a bundle swapped in next to the download, by a mirror or a proxy, passes there. The bundles this repository writes are in the new format, but cosign picks the format from the file, and `--new-bundle-format` does not stop that on the v3 line (v3.1.2 still accepts such a bundle with it), so the cosign version is what protects the check.
347+
348+
The regexp accepts any ref after the `@`. A passing check proves that the checksums were signed by a run of `tags.yaml` or `promote-rc.yaml` in `cozystack/cozystack`, not that the run was a release cut the way this document describes: anyone with write access can dispatch a `promote-rc.yaml` edited on a branch of their own, and until the `v*` [tag rulesets](#repo-side-enforcement-tag-protection-rulesets) restrict tag creation to the CI app, can push a `v*` tag whose tree carries an edited `tags.yaml`.
349+
350+
The script runs the same `cosign verify-blob` before it returns, so a signature this check would reject fails the job before the first upload, and the release is not published with assets but without a signature. Both jobs that call `make upload_assets`, `tags.yaml::prepare-release` and `promote-rc.yaml::promote`, hold `id-token: write` for the signing identity and install syft and cosign. They install syft from its release tarball, checked against a SHA-256 committed in the workflow, and not with `anchore/sbom-action/download-syft`, which runs an install script fetched at run time in a job that holds the release credentials; [`hack/ci-tool-installs-contract.bats`](../hack/ci-tool-installs-contract.bats) keeps it that way. A stable release gets its own three files rather than its rc's: promotion restamps several assets, so the checksums are recomputed and signed again.
351+
352+
`promote-rc.yaml` runs the `hack/upload-assets.sh` of the rc tree, not the dispatch ref's. A stable release is therefore signed only when its rc was tagged from a tree that has `hack/sign-release-assets.sh`, and a maintenance line starts carrying signatures once that script is backported to its `release-X.Y` branch.
353+
328354
## Nightly builds
329355

330356
A nightly is an **installable copy of `main` on GHCR — not a rebuild and not a release**. [`build-main.yaml`](../.github/workflows/build-main.yaml) already builds every push to `main` into the CI registry (OCIR); the nightly promotes that build to the public release registry (GHCR) and proves it installs.

‎hack/ci-tool-installs-contract.bats‎

Lines changed: 48 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,11 @@
11
#!/usr/bin/env bats
2-
# The flux CLI, yq and the helm-unittest plugin are build inputs like any image
3-
# or action, so they are pinned the same way: a fixed version, and for flux and
4-
# yq bytes checked against the release that version names. A floating install
5-
# comes back by copy-paste from an older step rather than by anyone deciding to
6-
# unpin one, which is why this scans every workflow instead of the steps that
7-
# happened to be fixed. Other downloaded tools are not covered here.
2+
# The flux CLI, yq, syft and the helm-unittest plugin are build inputs like any
3+
# image or action, so they are pinned the same way: a fixed version, and for
4+
# flux, yq and syft bytes checked against the release that version names. A
5+
# floating install comes back by copy-paste from an older step rather than by
6+
# anyone deciding to unpin one, which is why this scans every workflow instead
7+
# of the steps that happened to be fixed. Other downloaded tools are not
8+
# covered here.
89

910
load test_helper
1011

@@ -17,6 +18,27 @@ workflow_code() {
1718
| grep --invert-match --extended-regexp '^[^:]+:[0-9]+:[[:space:]]*#' || true
1819
}
1920

21+
# Prints file:line for every non-comment download matching the URL ERE that is
22+
# not followed within three lines by `sha256sum -c -` on the named variable.
23+
# Each download, not each file: one checked step must not cover another.
24+
unchecked_downloads() {
25+
awk -v url="$1" -v sum="$2" '
26+
FNR == 1 { if (pend) print pend; pend = "" }
27+
/^[[:space:]]*#/ { next }
28+
$0 ~ url { if (pend) print pend; pend = FILENAME ":" FNR; n = 0; next }
29+
pend && /sha256sum -c -/ && index($0, sum) { pend = ""; next }
30+
pend && ++n >= 3 { print pend; pend = "" }
31+
END { if (pend) print pend }
32+
' "$WORKFLOWS"/*.yaml "$WORKFLOWS"/*.yml 2>/dev/null
33+
}
34+
35+
# Fails unless every `KEY: "..."` in the workflows has the same value.
36+
one_value_of() {
37+
local values
38+
values="$(workflow_code "$1: \"" | grep --only-matching "$1: \"[0-9a-f.]*\"" | sort --unique)"
39+
[ "$(printf '%s\n' "$values" | grep --count .)" -eq 1 ] || { printf '%s\n' "$values"; false; }
40+
}
41+
2042
@test "no workflow executes the fluxcd.io install script" {
2143
# It runs as root whatever fluxcd.io serves at that moment; the binary it
2244
# checksums is not the exposure, the unpinned script is.
@@ -63,20 +85,27 @@ workflow_code() {
6385

6486
@test "every yq download is checksum-verified at one version" {
6587
[ -n "$(workflow_code 'mikefarah/yq/releases/download')" ]
66-
# Each download, not each file: the check has to follow within three lines.
67-
unchecked="$(awk '
68-
FNR == 1 { if (pend) print pend; pend = "" }
69-
/^[[:space:]]*#/ { next }
70-
/mikefarah\/yq\/releases\/download/ { if (pend) print pend; pend = FILENAME ":" FNR; n = 0; next }
71-
pend && /sha256sum -c -/ && /YQ_SHA256/ { pend = ""; next }
72-
pend && ++n >= 3 { print pend; pend = "" }
73-
END { if (pend) print pend }
74-
' "$WORKFLOWS"/*.yaml "$WORKFLOWS"/*.yml 2>/dev/null)"
88+
unchecked="$(unchecked_downloads 'mikefarah/yq/releases/download' YQ_SHA256)"
89+
[ -z "$unchecked" ] || { printf '%s\n' "$unchecked"; false; }
90+
one_value_of YQ_VERSION
91+
one_value_of YQ_SHA256
92+
}
93+
94+
@test "no workflow installs syft through a script fetched at run time" {
95+
# anchore/sbom-action and its download-syft action are pinned by commit, but
96+
# run syft's install.sh from a tag of another repository. The release jobs
97+
# that need syft hold the app token, the GHCR login and an OIDC token for the
98+
# identity release signatures are verified against.
99+
hits="$(workflow_code 'anchore/sbom-action|anchore/syft/.*install\.sh|get\.anchore\.io')"
100+
[ -z "$hits" ] || { printf '%s\n' "$hits"; false; }
101+
}
102+
103+
@test "every syft download is checksum-verified at one version" {
104+
[ -n "$(workflow_code 'anchore/syft/releases/download')" ]
105+
unchecked="$(unchecked_downloads 'anchore/syft/releases/download' SYFT_SHA256)"
75106
[ -z "$unchecked" ] || { printf '%s\n' "$unchecked"; false; }
76-
for key in YQ_VERSION YQ_SHA256; do
77-
values="$(workflow_code "$key: \"" | grep --only-matching "$key: \"[0-9a-f.]*\"" | sort --unique)"
78-
[ "$(printf '%s\n' "$values" | grep --count .)" -eq 1 ] || { printf '%s\n' "$values"; false; }
79-
done
107+
one_value_of SYFT_VERSION
108+
one_value_of SYFT_SHA256
80109
}
81110

82111
@test "every helm plugin install names a version" {

0 commit comments

Comments
 (0)