Verifying releases
Every release of the bide command carries four independent kinds of evidence, so you can decide what to trust before you install it:
- A signature on
checksums.txt, on each archive and on each SBOM, made keyless with cosign using the release workflow's GitHub OIDC identity. There is no long-lived signing key to steal or rotate; the signature proves that the file was produced by therelease.ymlworkflow ofbide-ai/bidefor that tag, and the signing event is recorded in the public Sigstore transparency log (Rekor). - SBOMs (SPDX JSON, generated by syft): one per archive (
<archive>.sbom.json), listing the Go modules compiled into the binary, and one for the published Go module set (bide_X.Y.Z_modules.sbom.json), listing what an application gets withgo get. - Reproducibility: the binaries rebuild byte for byte from the tag (
scripts/repro.sh), which the release workflow checks on another operating system for every release. - Build provenance: a SLSA v1 provenance attestation for each archive, each archive SBOM,
checksums.txt,approve-page.SHA256SUMSand the module set SBOM, made by GitHub's artifact attestations in a reusable workflow of a separate repository, bide-ai/release-builder, that the release workflow calls. It records which builder workflow and commit, and which bide tag and commit, built the file, and on what kind of runner; you check it withgh attestation verify. It supports SLSA Build Level 3 (what that means here).
What is covered, precisely: the signatures cover the archives, every SBOM, checksums.txt and approve-page.SHA256SUMS; checksums.txt lists every archive and per-archive SBOM. The signature establishes where and when a file was built and by which workflow. It does not establish that the source is free of defects, and it does not cover the Go modules published for go get, which the Go module proxy and checksum database authenticate separately; the module set SBOM describes those modules, it does not authenticate them.
Build provenance covers the same files as the signatures except the *.sigstore.json bundles and bide.rb. It applies from v0.21.0: v0.20.0 and earlier releases have no provenance attestations, which gh attestation verify reports as none found, and are covered by the signatures, SBOMs and reproducibility check only. The signature identity did not change in v0.21.0: the signatures are still made by release.yml at the tag, and the provenance has its own identity, the release builder's.
Signing and SBOMs apply from the first release made after they were added to the release workflow. A release with no *.sigstore.json files was published before that. Per-archive SBOMs are signed on their own from v0.18.0; v0.17.0's per-archive SBOMs are covered by the signed checksums.txt only. The module set SBOM is published from the first release after v0.18.0: v0.18.0's was not attached, because the release script wrote it to a temporary directory (fixed in #343).
What a release contains
For a version X.Y.Z and each of linux, darwin, windows on amd64 and arm64:
| File | What it is |
|---|---|
bide_X.Y.Z_<os>_<arch>.tar.gz | The archive: bide, LICENSE, NOTICE, README.md |
bide_X.Y.Z_<os>_<arch>.tar.gz.sigstore.json | Cosign bundle for the archive: signature, certificate, transparency-log entry |
bide_X.Y.Z_<os>_<arch>.tar.gz.sbom.json | SBOM of the archive (SPDX JSON) |
bide_X.Y.Z_<os>_<arch>.tar.gz.sbom.json.sigstore.json | Cosign bundle for the archive's SBOM |
bide_X.Y.Z_modules.sbom.json | SBOM of the published Go module set (SPDX JSON) |
bide_X.Y.Z_modules.sbom.json.sigstore.json | Cosign bundle for the module set SBOM |
checksums.txt | SHA-256 of every archive and per-archive SBOM |
checksums.txt.sigstore.json | Cosign bundle for checksums.txt |
bide.rb | The Homebrew formula, generated from checksums.txt |
approve-page.SHA256SUMS | SHA-256 of each file of the approve page bundle (approvals/cmd/approvepage), in sha256sum -c format |
approve-page.SHA256SUMS.sigstore.json | Cosign bundle for approve-page.SHA256SUMS |
Verify a download
Install cosign (v2.4 or later, or v3), then, with the release's files in one directory:
VERSION=X.Y.Z # the version without the leading v
TAG=v$VERSION
ARCHIVE=bide_${VERSION}_linux_amd64.tar.gz
# 1. The checksum file was signed by bide's release workflow for this tag.
cosign verify-blob \
--bundle checksums.txt.sigstore.json \
--certificate-identity "https://github.com/bide-ai/bide/.github/workflows/release.yml@refs/tags/$TAG" \
--certificate-oidc-issuer https://token.actions.githubusercontent.com \
checksums.txt
# 2. The archive is the one the signed checksum file names.
sha256sum --ignore-missing --check checksums.txt # macOS: shasum -a 256 --ignore-missing --check checksums.txt
# 3. Optionally, the archive's own signature.
cosign verify-blob \
--bundle "$ARCHIVE.sigstore.json" \
--certificate-identity "https://github.com/bide-ai/bide/.github/workflows/release.yml@refs/tags/$TAG" \
--certificate-oidc-issuer https://token.actions.githubusercontent.com \
"$ARCHIVE"Each cosign verify-blob prints Verified OK and exits 0 on success; any other result means do not install. Pin the identity to the tag you intended to install: a signature for a different tag, repository or workflow does not match. To accept any release of bide rather than one tag, use --certificate-identity-regexp '^https://github.com/bide-ai/bide/\.github/workflows/release\.yml@refs/tags/v' instead of --certificate-identity, and know that it accepts every tag.
If your cosign is older and does not read the bundle format, upgrade it; the bundle is the Sigstore bundle format that current cosign writes and reads.
Homebrew users: the formula pins the archive checksums of the release (brew install bide-ai/tap/bide), so Homebrew verifies the archive against a checksum taken from the signed checksums.txt; you can still verify bide.rb's checksums against the signed file. go install github.com/bide-ai/bide/cmd/bide@vX.Y.Z builds from source and is verified by the Go checksum database, not by these signatures.
Verify the approve page bundle
An organization that hosts the approve page (human approval guide) serves files that sign approvers' decisions, so it checks them before it deploys. Subresource Integrity in the page's index.html pins its script and stylesheet, but no browser mechanism pins the entry document itself, so each release publishes the SHA-256 of every file of the bundle, signed like checksums.txt. The release workflow builds the bundle from the tag, and its repro job rebuilds it on macOS and fails unless the sums match byte for byte.
TAG=vX.Y.Z
gh release download "$TAG" -R bide-ai/bide -p 'approve-page.SHA256SUMS*'
# 1. The sums were signed by bide's release workflow for this tag.
cosign verify-blob \
--bundle approve-page.SHA256SUMS.sigstore.json \
--certificate-identity "https://github.com/bide-ai/bide/.github/workflows/release.yml@refs/tags/$TAG" \
--certificate-oidc-issuer https://token.actions.githubusercontent.com \
approve-page.SHA256SUMS
# 2. The bundle you deploy is the one the signed sums name, file for file.
go run github.com/bide-ai/bide/approvals/cmd/approvepage@$TAG -out ./site
cmp site/SHA256SUMS approve-page.SHA256SUMS
(cd site && sha256sum --check --strict SHA256SUMS) # macOS: shasum -a 256 --check --strict SHA256SUMSRun step 2 against the files you actually serve, at deploy time and whenever they are changed. config.json is the deployment's own file and is not in the sums; it is protected content (see the guide). The approve page first ships in v0.17.0, the first release that publishes these sums.
Verify build provenance
A signature says bide's release workflow published a file. A provenance attestation says how it was built: a signed in-toto statement, in the SLSA v1 provenance format, that names the file by SHA-256 and records the builder workflow and the commit of it that ran, the bide tag and commit that were built, and the kind of runner. GitHub stores it; gh attestation verify fetches it, checks the Sigstore signature and the certificate, and compares the file's digest with the statement's subject.
What makes it Build Level 3 rather than 2. SLSA v1.0 asks of a build platform that the provenance be unforgeable (the signing secret material is not accessible to the environment that runs the user-defined build steps, and the steps cannot alter the provenance) and that builds be isolated. GitHub documents artifact attestations made in a reusable workflow as the way to reach Level 3. bide does that with the workflow in its own repository, so that a change to bide cannot change it:
- The build runs in the release builder's
buildjob on a GitHub-hosted, ephemeral runner, with a read-only token and no OIDC token: goreleaser and the build steps that bide's repository defines (.goreleaser.yaml, its hooks, the Go sources) cannot request the identity the attestation is signed with. - The attestation is made by a second job that has that identity and runs none of bide's code: it downloads the files the build job uploaded and attests fixed file patterns.
- The certificate names the builder repository, workflow file and commit, which bide's
release.ymlpins by full commit SHA. The builder repository accepts changes only through reviewed pull requests, and itsv*tags are created by administrators and never moved or deleted. A verifier that requires that repository, workflow and commit therefore knows which steps made the provenance.
Install the GitHub CLI (logged in with gh auth login, or GH_TOKEN set; the lookup uses the GitHub API), then, with the release's files in one directory:
TAG=vX.Y.Z
VERSION=${TAG#v}
ARCHIVE=bide_${VERSION}_linux_amd64.tar.gz
gh attestation verify "$ARCHIVE" -R bide-ai/bide \
--signer-workflow bide-ai/release-builder/.github/workflows/build.yml \
--source-ref "refs/tags/$TAG" \
--predicate-type https://slsa.dev/provenance/v1 \
--deny-self-hosted-runnersIt prints Verification succeeded! and exits 0 on success. For the strictest check, also pin the builder commit and the bide commit. --signer-digest is the commit of a v* tag of the release builder, the one its README lists for the builder version this release uses (git show "$TAG:.github/workflows/release.yml" | grep -o 'release-builder/.github/workflows/build.yml@[0-9a-f]*' in a clone of bide shows which commit the release pinned; check that it is a listed tag's commit, git ls-remote https://github.com/bide-ai/release-builder 'refs/tags/v*^{}'). Do not accept a commit just because release.yml names it: GitHub runs any commit of a repository's fork network named by SHA, so a commit that exists only in a fork would otherwise pass. --source-digest is git rev-parse "$TAG^{commit}". The same command verifies checksums.txt, the SBOMs and approve-page.SHA256SUMS; the module set SBOM was made by the builder's other workflow, so use --signer-workflow bide-ai/release-builder/.github/workflows/module-sbom.yml for it. scripts/verify-provenance.sh [--workflow module-sbom.yml] TAG FILE... runs the strict form over a list, as the release workflow does, and also refuses a builder commit that is not on the builder repository's main. For a machine without network access to GitHub, fetch the attestation once with gh attestation download "$ARCHIVE" -R bide-ai/bide and verify with --bundle; we have not exercised that path.
What each check proves:
-R bide-ai/bide: the attestation is stored for a build of this repository.--signer-workflow(and--signer-digest): the attestation was made by the release builder's workflow (at that commit), not byrelease.ymlor any workflow in bide's repository, which cannot produce it. This is the check that separates Level 3 from Level 2; without it, any attestation from bide's repository passes.--source-ref refs/tags/$TAG(and--source-digest): the build ran for that tag (and commit), so an attestation from a branch build or another release does not pass.--predicate-type: the statement is SLSA v1 build provenance, not some other claim about the file.--deny-self-hosted-runners: the build ran on a GitHub-hosted runner.- The digest comparison (always on): the file you hold is byte for byte a subject of the statement.
What it does not prove:
- The check the release workflow runs on itself (
scripts/verify-provenance.shat the tag) is a safety net against builder or artifact tampering, not the Level 3 control: it runs from the tag's own checkout, so someone who can push a malicious tag can change it. The control is the verification you run, outside bide's repository, with the flags above. - The Level 3 claim is about the builder's steps: provenance made by them cannot be forged by anything in bide's repository. The Go version, whether a dry run attests, and the commit of the builder to run are the caller's choices (a build of a tag is always attested and cannot be a snapshot), so a release is trustworthy only if you require the attestation, the builder commit above and
--source-ref refs/tags/$TAG. - It does not show the source is free of defects or that bide's build steps are benign: they are defined in bide's repository at the tag, so the provenance says which commit was built, not that the commit is trustworthy. The reproducibility check above is the independent evidence for the binary.
- It rests on the platform and on the builder repository's controls: GitHub Actions and its hosted runners, the Sigstore public-good instance, and that only reviewed changes reach the builder and only administrators create its tags. An administrator of the builder repository or of GitHub is outside what it detects.
- A file attested as a subject is the file the builder produced; the cosign signature is what shows bide's release workflow published it, and both checks are worth running.
- The attestation lives in GitHub's store and the public Sigstore transparency log, not on the release page, so verifying it needs GitHub (or the downloaded bundle).
- slsa-verifier does not verify these attestations: they are GitHub artifact attestations, not provenance from the (now unmaintained)
slsa-github-generatorworkflows. Usegh attestation verify.
Reproduce the binary
Signatures prove who built a file; reproduction proves the binary matches the source.
git clone https://github.com/bide-ai/bide && cd bide
scripts/repro.sh vX.Y.Z # downloads the release, checks it against checksums.txt, rebuilds each binary, compares bytesIt exits non-zero if any binary differs. Together the checks (signature, checksum, provenance, reproduction) reduce trust in a downloaded bide to trust in the source at the tag and the Go toolchain.
bide-hsm (bide approve for keys in an HSM or a KMS) is not in the release archives, so none of this applies to it. It needs cgo, so a prebuilt binary would be only as reproducible as the C toolchain behind it, which the release does not pin for each operating system and architecture; the pure-Go bide binary keeps the guarantees above. Build bide-hsm from source, CGO_ENABLED=1 go install github.com/bide-ai/bide/cmd/bide/bide-hsm@vX.Y.Z, which the Go checksum database verifies. Two builds of it with -trimpath -buildvcs=false from copies of the tree at different paths with one toolchain were byte-identical when tried on one machine; without -trimpath (which a plain go install does not pass) they differ, and none of that is a claim about other toolchains.
Verify and use the SBOMs
An SBOM is evidence only if you know where it came from, so check its signature before you load it anywhere:
TAG=vX.Y.Z
VERSION=${TAG#v}
gh release download "$TAG" -R bide-ai/bide -p '*.sbom.json' -p '*.sbom.json.sigstore.json'
for f in bide_*.sbom.json; do
cosign verify-blob \
--bundle "$f.sigstore.json" \
--certificate-identity "https://github.com/bide-ai/bide/.github/workflows/release.yml@refs/tags/$TAG" \
--certificate-oidc-issuer https://token.actions.githubusercontent.com \
"$f" || echo "DO NOT USE: $f"
doneTwo kinds of SBOM, for two questions:
- What is in the
bidebinary I run?bide_<version>_<os>_<arch>.tar.gz.sbom.json: the Go modules recorded in the binary's build information, with versions. Use the one for the archive you install. - What does my application pull in when it depends on bide?
bide_<version>_modules.sbom.json: every module a consumer of all of bide's published modules resolves at that release (the core and every library, with the commands as tools), at the versions it selects, each with a package URL (pkg:golang/<module>@<version>) and the license syft finds in the module's files. The release workflow builds it from a scratch module resolved only through the public Go proxy and checksum database (scripts/module-sbom.sh), and it lists every published bide module at the release's version. Your application selects its own versions with its owngo.mod, so it is a reference for review, not your application's SBOM: generate that from your own build (for examplesyft scan dir:.in your module, or from your binary).
Consuming them:
jq -r '.packages[] | "\(.name) \(.versionInfo)"' "bide_${VERSION}_modules.sbom.json" # the inventory
grype sbom:"bide_${VERSION}_modules.sbom.json" # known vulnerabilities, if you use grype
syft convert "bide_${VERSION}_modules.sbom.json" -o cyclonedx-json=bide-modules.cdx.json # CycloneDX, for tools that take only that (Dependency-Track)A converted document is a new file the signature does not cover: verify the SPDX file first, convert it, and keep both. The SBOMs are SPDX 2.3 JSON. They are a point-in-time inventory of the release, not a statement that those dependencies are free of vulnerabilities: scan them again as advisories are published. The audit-only build (-tags bide_audit_only) has a much smaller dependency set (the standard library and the core module); if that is all you need, build it from source and compare (security model).
For maintainers
The signing identity is the release.yml workflow at the release tag, so it works only for releases made by that workflow with id-token: write. A release runs in this order. The build job calls the release builder (bide-ai/release-builder, pinned by full commit SHA in release.yml; Dependabot proposes a newer one, which is a change to the release's security and is reviewed as one), which builds with goreleaser (--skip=publish,sign) and attests. The release job downloads the files, checks them against checksums.txt, and verifies every archive's, SBOM's, checksums.txt's and the approve page sums' provenance with scripts/verify-provenance.sh (gh attestation verify, itself pinned by version and checksum in scripts/install-gh.sh, against the builder repository, workflow and the commit release.yml pins, which must also be on the builder repository's main) BEFORE it signs or publishes; a file that does not verify fails the run with nothing signed or published. It then signs with cosign and creates the release as a draft, uploads every file and publishes it last. The homebrew job pushes the formula. The module-sbom job calls the builder's second workflow for the module set SBOM, and module-sbom-publish verifies, signs and attaches it. After publishing, the verify-signatures job verifies every signature and, from the published files, the provenance again, and verify-module-sbom checks the module set SBOM; either fails the run if a check fails, which leaves a published release with a red run. A tag with a hyphen (vX.Y.Z-rc.N) is published as a GitHub pre-release with the same signatures, provenance and module set SBOM, and gets no Homebrew formula. To move to another builder commit, change the pin in release.yml; scripts/verify-provenance.sh reads the expected commit from that same line, so the pin and the check cannot drift. The manual dry run (workflow_dispatch) builds a snapshot with the per-archive SBOMs and, for the latest release, the module set SBOM, but skips signing and publishing, so it leaves nothing in the public transparency log unless its attest input is set: that also attests the snapshot files and verifies them, as a rehearsal of the provenance path (the attestations go to the public transparency log, named for a snapshot version). The builder's module SBOM workflow of a real release waits up to four hours for scripts/release.sh to push the nested module tags and for the Go proxy to serve them; verify-signatures does not wait for it, and verify-module-sbom then checks the module set SBOM's signature and that it lists the core and every published module at the release's version, as a job of its own. To build the module set SBOM of a release locally: scripts/module-sbom.sh vX.Y.Z out.json (needs syft and jq). To check the configuration locally: goreleaser check, and goreleaser release --snapshot --clean --skip=publish,sign (needs syft on the path).