Verify releases

Check MAQPNA binaries, images and the Helm chart before you run them, with SHA-256 checksums, cosign keyless signatures and SBOM attestations.

Every MAQPNA release is signed. Binaries carry a cosign keyless signature from the release signing workflow, images and the Helm chart are signed by the release workflow, and every image has an SPDX SBOM attestation. maqpna verify checks all of them in one command; the install scripts check binaries for you.

flowchart LR
  A[Download binary<br/>+ .sigstore.json + checksums.txt] --> B[maqpna verify binary]
  C[Images and chart<br/>release registry] --> D[maqpna verify image / chart<br/>--sbom]
  B & D --> E[maqpna verify release V]
  E --> F[Pin image.digest<br/>in your values]

Goal#

Run only artefacts whose checksum and signature you checked, and pin the image digests you verified.

Prerequisites#

• cosign 2.x or later on PATH (maqpna verify calls it).
• Network access to the release assets and the registry, or the files copied next to you.

Where releases are published#

The release registry is listed on maqpna.com/download.

The signer identities are built into maqpna verify: binaries are signed by the signed-release workflow, images and the chart by the release workflow at the release tag, both with the OIDC issuer https://token.actions.githubusercontent.com. maqpna verify binary -h and maqpna verify image -h print the exact identities, which you can pass to cosign yourself.

Steps#

1. Let the installer verify the CLI#

curl -fsSL https://maqpna.com/install.sh | sh -s -- --version v0.1.1 --cosign

The script downloads checksums.txt and the raw binary, checks its SHA-256, then checks the cosign signature (when cosign is on PATH, or always with --cosign; --no-cosign skips it). Other options: --bin NAME (repeatable), --dir DIR, --mirror (dl.maqpna.com), --base URL. On Windows, install.ps1 takes the same options.

2. Verify a downloaded binary#

Download maqpna_linux_amd64, maqpna_linux_amd64.sigstore.json and checksums.txt from maqpna.com/releases, then:

maqpna verify binary maqpna_linux_amd64 --checksums checksums.txt

Real output for the v0.1.1 Linux binary:

ok    maqpna_linux_amd64                                           sha256
ok    maqpna_linux_amd64                                           signature
2 checks, 0 failed

A changed file fails, and the exit status is 3:

FAIL  maqpna_tampered                                              signature              error during command execution: failed to verify signature: could not verify message: invalid signature when validating ASN.1 encoded signature
1 checks, 1 failed

The same checks with standard tools (IDENTITY_REGEXP is the binary signer from maqpna verify binary -h):

grep ' maqpna_linux_amd64$' checksums.txt | sha256sum --check      # shasum -a 256 --check on macOS
cosign verify-blob maqpna_linux_amd64 --bundle maqpna_linux_amd64.sigstore.json \
  --certificate-identity-regexp "$IDENTITY_REGEXP" \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

maqpna_linux_amd64: OK
Verified OK

3. Verify images and the chart#

maqpna verify image "$REGISTRY/maqpna-gateway:0.1.1" --sbom
maqpna verify chart --version 0.1.1 --registry "$REGISTRY"

verify image checks the cosign signature against the release workflow at a v* tag (--identity or --identity-regexp override it) and, with --sbom, the SPDX SBOM attestation. Equivalent cosign commands (IDENTITY is the release workflow at the tag, from maqpna verify image -h):

cosign verify "$REGISTRY/maqpna-gateway:0.1.1" \
  --certificate-identity "$IDENTITY" \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com
cosign verify-attestation --type spdxjson "$REGISTRY/maqpna-gateway:0.1.1" \
  --certificate-identity "$IDENTITY" \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

4. Verify a whole release#

maqpna verify release v0.1.1 --sbom --binaries ./downloads

It verifies the 11 images and the chart signed by the release workflow at the tag, and every binary in --binaries (with their .sigstore.json files and checksums.txt). --no-images and --no-chart skip parts. It exits 3 when any check fails.

5. Pin what you verified#

image:
  digest: sha256:...     # the digest you verified; wins over the tag

6. Verify an air-gap bundle#

maqpna verify bundle ./maqpna-airgap-0.1.1 --require-signature --key cosign.pub

See Air-gapped install.

What a release contains#

Builds are reproducible: CGO_ENABLED=0, -trimpath, version and commit from -ldflags, file times pinned to the commit time.

Troubleshooting#

Next steps#

• Production install with Helm
• Air-gapped install
• Command reference: maqpna verify release, maqpna verify binary, maqpna verify image, maqpna verify chart, maqpna verify bundle.