Verifying releases

Before you run a FerroEHR binary, image, or chart in a clinical environment, you should be able to answer two questions about the bytes you downloaded: did they arrive intact, and were they built by this project’s own release pipeline. This page is the operator’s procedure for both: one command per artifact kind, plus the deliberately-failing runs that prove your verification is actually checking something.

Every release publishes signed build provenance, a dependency SBOM, and a plain checksum alongside each artifact. Provenance is signed through Sigstore, so you can verify it yourself, and the signer identity is one you can pin to a single hardened workflow.

• What a release publishes
• A release binary
• Prove your verification can fail
• A container image
• The Helm chart
• Three SBOMs, three questions
• What SLSA level each artifact reaches
• The openehr-* crates
• Findings a scanner will report
• If verification fails

What a release publishes

Substitute the release tag you downloaded for <tag> (for example v4.3.1) and the architecture for <arch> (x86_64 or aarch64) throughout this page. Linux is the only published target.

Container images and the Helm chart are published to GHCR by their own lanes and carry their own attestations; see images and the chart below.

Note

The release lane refuses to publish a release whose asset set is incomplete. It creates the release as a draft, attaches every asset, checks the full expected set is present, and only then publishes, because a published release is immutable on this repository, so a missing asset could never be added afterwards. The remedy for a bad cut is a new patch version, never a retag.

A release binary

The floor: the checksum. Every tarball ships a .sha256sum beside it, and this is the only verification available with neither gh nor cosign installed , which is a realistic constraint in a locked-down clinical environment:

sha256sum -c ferroehr-<tag>-<arch>-unknown-linux-gnu.tar.gz.sha256sum

The file records the bare filename, so this works in whatever directory you put the two files in. On macOS, shasum -a 256 -c is the same check.

Warning

Be clear about what a checksum buys: it detects a corrupt or truncated download, not a substituted release, because anyone who could replace the tarball could replace the checksum beside it. Only the Sigstore bundle answers “who built this”. The checksum is a floor, not a substitute.

The real check: the provenance attestation.

gh attestation verify ferroehr-<tag>-<arch>-unknown-linux-gnu.tar.gz \
  -R rubentalstra/FerroEHR

Without reaching GitHub. Each release also carries its Sigstore bundles as assets, so verification needs nothing but the artifact and the bundle, useful on an air-gapped host, and the only form in which the signature travels with the download:

gh attestation verify ferroehr-<tag>-<arch>-unknown-linux-gnu.tar.gz \
  --bundle ferroehr-<tag>-<arch>-unknown-linux-gnu.tar.gz.sigstore.json \
  --repo rubentalstra/FerroEHR

The *.sbom.sigstore.json asset beside it is the same thing for the SBOM attestation, so “which dependency graph was this binary built from” is verifiable offline too. Verifying an SBOM attestation needs one extra flag: gh attestation verify enforces the SLSA provenance predicate by default, so a non-provenance attestation must name its predicate type explicitly:

gh attestation verify ferroehr-<tag>-<arch>-unknown-linux-gnu.tar.gz \
  -R rubentalstra/FerroEHR \
  --predicate-type https://cyclonedx.org/bom

Fully offline, with no call to GitHub at all: fetch the trusted key material once on a connected machine and carry it across with the bundle:

gh attestation trusted-root > trusted_root.jsonl        # on a connected host
gh attestation verify ferroehr-<tag>-<arch>-unknown-linux-gnu.tar.gz \
  --bundle ferroehr-<tag>-<arch>-unknown-linux-gnu.tar.gz.sigstore.json \
  --custom-trusted-root trusted_root.jsonl \
  --repo rubentalstra/FerroEHR

Require the hardened signer. Without a signer constraint you are trusting that some workflow in this repository signed the artifact. Pin the one that actually did:

gh attestation verify ferroehr-<tag>-<arch>-unknown-linux-gnu.tar.gz \
  -R rubentalstra/FerroEHR \
  --signer-workflow rubentalstra/FerroEHR/.github/workflows/release-build.yml

That workflow is the reusable release-build lane described under SLSA levels below.

The binary also describes itself. From v4.0.1 on, the shipped binary embeds its own compressed dependency list in a .dep-v0 linker section (built with cargo auditable; the section is allocated, so it survives the release lane’s strip). A scanner that reads binaries — syft, trivy, grype, osv-scanner — recovers the crate graph from the artifact itself, even when the release page’s SBOM never travelled with it:

syft ferroehr -o cyclonedx-json   # the extracted binary, not the tarball

Tip

gh attestation verify reports success by exiting zero and printing nothing in current gh versions. Check the exit status in scripts rather than grepping for a success message.

Prove your verification can fail

A check that cannot fail proves nothing, so do both of these once, by hand, before you trust a passing run:

# 1. Tamper with the artifact — verification must refuse it.
printf 'x' >> ferroehr-<tag>-<arch>-unknown-linux-gnu.tar.gz
gh attestation verify ferroehr-<tag>-<arch>-unknown-linux-gnu.tar.gz \
  --bundle ferroehr-<tag>-<arch>-unknown-linux-gnu.tar.gz.sigstore.json \
  --repo rubentalstra/FerroEHR
# → Error: verifying with issuer "sigstore.dev"; exit status 1

# 2. Name a repository that did not build it — also non-zero.
gh attestation verify … --repo someone-else/something

Re-download the tarball afterwards. Only once you have seen both refusals does a passing run mean something.

Cross-check the digest. The same digest is produced independently in three places, so they are worth comparing against each other rather than trusting any one of them:

# the published checksum file
cat ferroehr-<tag>-<arch>-unknown-linux-gnu.tar.gz.sha256sum

# the digest the provenance statement was signed over
jq -r '.payload' ferroehr-<tag>-<arch>-unknown-linux-gnu.tar.gz.intoto.jsonl \
  | base64 -d | jq -r '.subject[].digest.sha256'

# the bytes on your disk
sha256sum ferroehr-<tag>-<arch>-unknown-linux-gnu.tar.gz

A container image

The three images (ferroehr, ferroehr-viewer, ferroehr-postgres) each carry a Sigstore-signed SLSA provenance attestation, plus the SPDX SBOM and provenance the builder writes onto the image index itself.

gh attestation verify oci://ghcr.io/rubentalstra/ferroehr:4.3.1 \
  -R rubentalstra/FerroEHR

Important

Image tags carry no v prefix. A release publishes 4.0.0, 3.20 and latest (plus a sha-… tag per commit), while the release assets are named after the v4.0.1 git tag. Using v4.0.1 as an image reference will simply not resolve.

The development tags (ghcr.io/rubentalstra/ferroehr:main and its two siblings) are signed the same way, so you can rehearse the command against them before a release.

Add --signer-workflow rubentalstra/FerroEHR/.github/workflows/build-image.yml to require the hardened image-build lane specifically rather than any workflow in this repository.

Verify by digest where it matters. A tag is mutable, so anything that GATES on verification (admission control, a deploy script) should resolve the tag once and verify the digest it resolved — otherwise the bytes verified and the bytes pulled can differ:

digest=$(docker buildx imagetools inspect ghcr.io/rubentalstra/ferroehr:4.3.1 \
  | awk '/^Digest:/{print $2}')
gh attestation verify "oci://ghcr.io/rubentalstra/ferroehr@${digest}" \
  -R rubentalstra/FerroEHR

The attestation is also pushed to the registry itself, so a host with registry access but no GitHub API path can verify from the registry alone with --bundle-from-oci. And the SBOM the builder wrote onto the image index is readable without any verifier at all:

docker buildx imagetools inspect "ghcr.io/rubentalstra/ferroehr@${digest}" \
  --format '{{ json .SBOM }}'

Enforcing this at admission time in a Kubernetes cluster is a separate job with its own machinery; see Images: build, provenance, scanning.

The Helm chart

The chart carries a keyless cosign signature in addition to its provenance attestation. The two are not redundant: the attestation says what the chart was built from, the signature says who signed the artifact you pulled, and the signature is what Helm-ecosystem tooling looks for.

cosign verify ghcr.io/rubentalstra/charts/ferroehr:<chart-version> \
  --certificate-identity-regexp '^https://github\.com/rubentalstra/FerroEHR/\.github/workflows/build-chart\.yml@' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

Both flags are the point: without an identity and an issuer, cosign verify accepts a signature from anyone in the transparency log.

gh attestation verify oci://ghcr.io/rubentalstra/charts/ferroehr:<chart-version> \
  -R rubentalstra/FerroEHR \
  --signer-workflow rubentalstra/FerroEHR/.github/workflows/build-chart.yml

Note

The chart version is not the product version. The chart runs its own SemVer line, so a chart version and the appVersion it deploys move independently. Read the chart’s appVersion to learn which server release it defaults to.

The chart ships no PGP .prov file, so helm install --verify does not apply. That is deliberate: a .prov needs a long-lived private key in CI, and keyless Sigstore signing gives a consumer a stronger identity to pin without one.

The publishing lane refuses to overwrite a chart version that already exists, reads both the signature and the attestation back from the registry before reporting success, and checks that the appVersion image accepts the chart’s rendered defaults.

Three SBOMs, three questions

A release involves three SBOM documents. They are not redundant: they describe different things for different readers, and both kinds of review genuinely happen for a clinical deployment:

CycloneDX 1.5 is the highest version the generator emits (cargo-cyclonedx accepts 1.3, 1.4 or 1.5 and defaults to 1.3, so the release lane sets it explicitly); it carries everything 1.6 consumers read. The repository SPDX document is checked at publish time for being real SPDX, naming itself ferroehr, and listing at least one package: an SBOM that answers no question is worse than none.

What SLSA level each artifact reaches

The levels are the SLSA v1.2 Build track (the current spec; v1.0 is marked Retired, and the Build-track requirements are unchanged across those versions — GitHub’s own documentation still phrases the same construction against “SLSA v1.0”). They differ per artifact, so a table is the honest form:

Images and the chart reach L3 from the first publish after v4.0.1; earlier artifacts were attested at Build L2 (in the job that built them), and their attestations verify with the repository-scoped command, not the pinned signer.

Build L3’s distinguishing requirement is that secret material used for authenticating the provenance “MUST NOT be accessible to the environment running the user-defined build steps”. Every step of a GitHub Actions job shares one runner VM, so attesting inside the building job cannot satisfy it. The release lane therefore builds and signs inside a reusable workflow: it runs on its own VM, and a caller passes declared inputs; it cannot add steps. The calling job has no steps at all, which is what makes the property hard to lose by accident, and it is why --signer-workflow is worth passing.

What is still not claimed, in either lane: the isolation is GitHub’s rather than this project’s, and nothing here asserts a reproducible or hermetic build; those are separate SLSA tracks this project does not address. Provenance proves where an artifact was built, not that the source was good. Naming the boundary is worth more than rounding a level up.

The openehr-* crates

The eight specification crates publish to crates.io through Trusted Publishing: the workflow authenticates with a short-lived OIDC token, and no long-lived crates.io token exists anywhere. Be precise about what that does and does not give you: it is authentication, not provenance. crates.io records and displays nothing about how a crate was built, and the Rust RFC that introduced Trusted Publishing lists provenance verification as explicitly out of scope — there is no registry-side attestation to verify, from this project or any other. cargo checks the crate’s checksum against the registry index, and that is the whole registry-side story. The crates’ source of truth is this repository: the publishing lane, the tags, and the public history.

Findings a scanner will report

Run a scanner over a FerroEHR artifact and it will report findings. Every one this project has assessed and accepted is published as an OpenVEX document under security/vex/, carrying a controlled-vocabulary justification and an impact statement you can check, rather than an ignore entry that records only the verdict. Point your tooling at them (trivy --vex, and most SCA platforms take an OpenVEX feed).

The Rust document is generated from deny.toml (the gate that actually decides whether a build passes) joined with the published reasoning, and a CI job fails if the two disagree in either direction. So an advisory cannot be accepted without a justification reaching you, and a justification cannot claim something the gate does not do.

One asymmetry worth knowing, because it produces findings that are real reports of nothing. Cargo.lock records the union of every dependency any feature combination could pull, so a scanner reading the lock file alone reports crates this project’s feature set never compiles. cargo deny resolves features and does not. Where the two disagree in that direction the feature-resolving tool is the more precise instrument, and the VEX document carries that argument for the specific crate it applies to, so you do not have to take our word for it in prose.

The published images are additionally re-scanned on a weekly schedule at the tag an operator actually pulls, and a fixable high-or-critical finding both fails that run and files a tracker issue, because a red scheduled run nobody looks at is not a control.

If verification fails

A failing verification is a security report, not a support question. Do not run the artifact, and follow SECURITY.md: report privately, never as a public issue. Note that only the newest release receives fixes; there is no maintenance branch to backport to.