# Supply chain

What a release holds, how to verify its signatures and the macOS pkg's Developer ID signature and notarization, how to rebuild its binaries from source, and what CI checks before a tag.

In short: A GitHub Actions job builds each release from a version tag and signs its checksums and image with keyless cosign. You verify a download by that signature, then its checksum, and `make verify-release` rebuilds every binary from the tag to compare it bit for bit. The macOS pkg also carries a Developer ID signature and Apple's notarization.


A reviewer reads this page to check that a release is what the project built. Straza releases are built by a GitHub Actions job from a version tag, signed with keyless cosign under that job's identity, and reproducible from the source tree with one make target. The question of who built a binary therefore has a checkable answer.

## What a release contains

A release is a set of files on its release page and an image in the registry.

| Artifact | What it holds |
|---|---|
| One archive per platform, for Linux, Windows and macOS on amd64 and arm64 | The three static binaries `strazad`, `strazactl` and `straza`, both license files, `NOTICE`, `TRADEMARKS.md`, `THIRD_PARTY_NOTICES.txt`, the README and the standalone quickstart |
| One deb and one rpm package of the `straza` client for Linux on amd64 and arm64, from 2.0.0 | The `straza` binary at `/usr/bin/straza` with the symlink `/usr/bin/git-remote-straza` to it, the systemd units `straza-service.socket` and `straza-service.service`, a sysusers file for the straza-service OS account, the install and remove scripts, and under `/usr/share/doc/straza` both license files, `NOTICE` and `THIRD_PARTY_NOTICES.txt`. The `straza` binary is the same one as in the Linux archive of that architecture, whose bill of materials lists the binary's modules. The packages carry no OpenPGP signature. |
| One MSI of the `straza` client for Windows on amd64, from 2.0.0 | `straza.exe` at `C:\ProgramData\straza\bin` with its copy `git-remote-straza.exe` beside it, an entry for that folder in the machine PATH, the Windows service straza-service with its restart after a failure, its Application event log source, and under `C:\ProgramData\straza` both license files, `NOTICE` and `THIRD_PARTY_NOTICES.txt`. The `straza.exe` is the same one as in the Windows amd64 zip, whose bill of materials lists the binary's modules, so the MSI gets none of its own. The MSI carries no Authenticode signature. A prerelease tag gets no MSI. |
| One pkg of the `straza` client for macOS, from 2.0.0 | One universal `straza` for Apple silicon and Intel Macs at `/opt/straza/bin/straza`, the launchd daemon ai.straza.service with its log rotation rule, the install scripts that create the hidden _straza-service OS account, its folders and the links `/usr/local/bin/straza` and `/usr/local/bin/git-remote-straza`, and under `/opt/straza/share/doc` both license files, `NOTICE` and `THIRD_PARTY_NOTICES.txt`. The binary is signed with the Developer ID Application identity of SynapTech s. r. o., team WMPWM57KYK, with the hardened runtime and a secure timestamp, and the pkg with its Developer ID Installer identity. Apple notarized the pkg, and its ticket is stapled to it. Each slice of the binary is the `straza` of the darwin archive of its architecture in every byte but the code signature, so the bills of materials of those archives cover it and the pkg gets none of its own. `checksums.txt` covers the pkg. A prerelease tag gets no pkg. |
| `checksums.txt` | Checksums of the release files |
| `checksums.txt.sig` and `checksums.txt.pem` | The cosign signature of `checksums.txt`, and the certificate that signed it |
| A software bill of materials for every archive | The components of that archive, generated by syft |
| The container image `ghcr.io/strazahq/straza`, for linux/amd64 and linux/arm64 | Built from scratch, with the `strazad` and `strazactl` binaries, a bundle of public certificate authorities, and under `/licenses/` both license files, `NOTICE`, `THIRD_PARTY_NOTICES.txt` and the license terms of the certificate bundle. It runs as an unprivileged user. |
| The image's signature and certificate | A signature over the image's digest, stored in the registry next to the image |

`THIRD_PARTY_NOTICES.txt` carries the copyright notices and license texts of every third-party component. It is generated from the Go modules the binaries link on every release platform and from what the console build bundles.

A tag first lands as a draft release, which the maintainer publishes by hand. The release workflow fails when a component carries no license text, when the committed console notices are stale, or when an archive, a package, the MSI or the pkg lacks the notices, and the image is then never built. The image job pushes the image by its digest with no name, checks the notices in it and signs it, and only then gives it the version tag and `latest`. A pull by name therefore always gets a checked and signed image.

## How you verify one

Every binary in a release is reachable from `checksums.txt`, and that one file is what cosign signs, so verifying takes two steps. First you verify the signature on the checksums file against the identity of the release workflow, under the issuer `https://token.actions.githubusercontent.com`. Then you verify your download against the checksums file. The two commands are in the [Install](https://docs.straza.ai/guides/operate/install/index.md) guide.

The identity pattern pins the repository `Strazahq/straza`, its release workflow `.github/workflows/release.yml` and a version tag. It spells the organization `Strazahq` as GitHub writes it into the certificate, and the match is case-sensitive, so a pattern in lowercase fails. A certificate from another repository, another workflow or a branch does not match. The container image verifies with the same identity:

```sh
cosign verify ghcr.io/strazahq/straza:2.2.0 \
  --certificate-identity-regexp '^https://github\.com/Strazahq/straza/\.github/workflows/release\.yml@refs/tags/v[0-9]+\.[0-9]+\.[0-9]+$' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com
```

The cosign commands on this page were run against the published release 1.1.2, with 1.1.2 where the image command now names 2.2.0: they verified the checksums file and the container image, and a check that expected the identity of another tag failed as it should. `make verify-release` rebuilt all 18 binaries of the published release 2.0.1 and each matched its published checksum. Releases from 1.1.2 and earlier carry the archives only, and the packages, the MSI and the pkg come from 2.0.0. Keyless signing records every signature in the public Rekor transparency log together with the repository identity, which is intended for an open source project and means a signature can be audited later. A key-based fallback exists for a signing outage, and it is never automated, because a long-lived private key whose compromise forges releases is worse than a delayed release.

### The macOS pkg

The pkg also carries Apple's signatures, which a reviewer checks on a Mac beside the checksum. `pkgutil` reads the pkg's signature and its notarization, `spctl` asks Gatekeeper whether it would install the file, and `stapler` checks the stapled ticket.

```sh
pkgutil --check-signature straza_*_darwin_universal.pkg
spctl -a -vvv -t install straza_*_darwin_universal.pkg
xcrun stapler validate straza_*_darwin_universal.pkg
```

`pkgutil` names `Developer ID Installer: SynapTech s. r. o. (WMPWM57KYK)` as the first certificate of the chain, says that the Apple notary service trusts the pkg, and prints the time of the trusted timestamp. `spctl` answers `accepted`, with `source=Notarized Developer ID` and that identity as the origin, and `stapler` reports that the validate action worked. On a Mac where the pkg is installed, `codesign -dv --verbose=4 /opt/straza/bin/straza` shows the binary's signature: `Identifier=ai.straza.straza`, `TeamIdentifier=WMPWM57KYK`, the `runtime` flag of the hardened runtime and a `Timestamp` line. `codesign --verify --strict /opt/straza/bin/straza` exits with status 0.

Apple's signature proves who signed the pkg, and it says nothing about which source the binary came from. That proof comes from the next section.

## Why the pkg's binary is the archives' binary

codesign rewrites part of a binary when it signs it, so the pkg's `straza` cannot have the same SHA-256 as an archive's. The release workflow proves instead that the signature is the only difference, in two links.

1. The macOS job builds the darwin arm64 and amd64 `straza` from the tag with the flags of the goreleaser build and the toolchain that `go.mod` names, and joins them into one file. After codesign signs that file, `build-pkg.sh` runs `tools/machocmp` on it and the two builds from before the signing. For each slice and its build, machocmp removes the code signature the way Go's own gorebuild does, which drops the signature's load command and its data and resets the sizes codesign changed, and then compares the rest byte for byte. A slice that differs stops the job before the pkg is made.
2. The goreleaser job downloads those two builds with the pkg. A post hook on its `straza` build, `deploy/macos/check-release-binary.sh`, compares each darwin binary that goreleaser builds byte for byte with the macOS job's build of that architecture, and a difference stops the build before any draft release exists.

Each slice of the pkg's binary is therefore the darwin archive's `straza` of its architecture in every byte but the code signature, and the bills of materials of those archives list its modules. goreleaser accepts a pattern for extra files that matches nothing, so the goreleaser job also checks before it runs that a version tag has exactly one pkg of its own version, and afterwards that `checksums.txt` lists it.

## Reproducing a release from source

`make verify-release` proves that a release's binaries came from the source tree you have, with no key and no CI, so it survives any signing outage. To run it:

1. Check out the release tag.
2. Download the archives and `checksums.txt` into `dist/`.
3. Unpack each archive into its own directory under `dist/`, because the script compares the binaries themselves and reads the version from the checked-out tag.
4. Run `make verify-release`.

The script checks `checksums.txt` against the artifacts on disk, then rebuilds every release binary from the current source and compares the SHA-256 of each rebuild with the shipped file. The rebuild replays the build information embedded in each shipped binary, the operating system, the architecture and the CGO setting, rather than this machine's defaults. It refuses to compare when the toolchain differs, because a distribution-patched Go of the same version does not produce the same bytes as the upstream one.

It exits 1 on any mismatch or when `dist/` holds no release binary, and 0 only when every binary reproduces bit for bit. A mismatch usually means a different toolchain, different version flags or a dirty tree, and the script names those three in order.

The script rebuilds binaries and never a deb or rpm package or the MSI. For a package or the MSI in `dist/`, it proves that the file matches `checksums.txt`. The `straza` binary inside a package is the one in the Linux archive of the same architecture, and the `straza.exe` inside the MSI is the one in the Windows amd64 zip, and the rebuild covers both. The package's units, account file and scripts, and the MSI's service and custom action tables, are checked only against the checksums. They come from `deploy/linux` and `deploy/windows` in the tagged tree.

A pkg in `dist/` gets one more check on a Mac. The script expands it into a temporary folder of its own and splits its `straza` into the two slices. It rebuilds each slice from the tree after it checks this machine's toolchain against the slice's build information, then compares the slice with its rebuild through machocmp, so that only the code signature may differ. On Linux, where `pkgutil` cannot expand a pkg, the script says that the pkg matched `checksums.txt` and that its binary is compared only on a Mac. The pkg's scripts, daemon definition and log rule are checked against the checksums only, and they come from `deploy/macos` in the tagged tree.

## What runs on every pull request, and what a tag needs

Every pull request, and every push to `main` that changes more than the docs, runs the CI workflow in `.github/workflows/ci.yml`. It runs these checks:

- golangci-lint with gosec enabled.
- govulncheck over the module graph and the standard library.
- `go vet`.
- The file-length ratchet.
- The complete test suite under the race detector, without the test cache.
- A coverage floor of 75 percent.
- The end-to-end journey suite.
- The Python kit's tests.
- A render of the Helm chart and the compose file, with an image build.
- The console build and its tests.

A release needs a tag of the form `v*` pushed to the repository. That push runs the whole release workflow, with permission to create the release, push the image and mint the OIDC token that keyless signing needs. A manual dispatch of the workflow runs only its macOS job and publishes nothing, so no event but a tag push makes a release. The archive binaries are built with the Go toolchain that `go.mod` names, CGO off and `-trimpath`, with version and commit stamped in. The image binaries are built the same way inside the `golang:1.26-bookworm` build image, and `make verify-release` checks the archive binaries only. Every action the workflow uses is pinned by commit hash rather than by tag.

The macOS job runs first, on a macOS 26 runner that GitHub hosts and discards after the job, with read access to the repository only and a limit of 60 minutes. Its signing keys are secrets of the GitHub environment macos-signing, whose rule admits a run on a `v*` tag and no other ref. The environment holds five secrets: one `.p12` file with the Developer ID Application and Developer ID Installer identities, its password, and the App Store Connect API key that notarytool uses, with its key ID and issuer ID. Each secret reaches only the step that reads it. The job imports the identities into a keychain of its own with a random password, opens their keys to codesign and productbuild only, and checks Apple's G2 intermediate certificate against a pinned SHA-256. `build-pkg.sh` stops when a certificate comes from Apple's older Developer ID authority or has expired, and warns when one expires within 30 days. A last step deletes the keychain and every key file, whether the job passed or failed. No third-party action runs in that job.

The manual dispatch exists to rehearse the Apple steps once before the first release that carries the pkg. Because the environment admits version tags only, a dispatch from `main` can open the keys only while an administrator has added a rule for `main` to the environment by hand, together with a required reviewer, for that one run. The dispatch signs and notarizes a test pkg, keeps it with the two builds from before the signing for one day as a workflow artifact, and skips the goreleaser and image jobs, so it publishes nothing and cosign signs nothing.



