Guide

Verify an image

Check that a file was built by our public CI and has not been altered since, before you boot it. It takes one command and no key management.

What a signature proves

Images are signed with Sigstore cosign in keyless mode. At build time GitHub Actions issues a short-lived OIDC identity for the exact workflow that runs; Sigstore's certificate authority binds the signature to that identity and records it in the public Rekor transparency log.

The file is byte-for-byte what our build produced.
It was produced by one of the reusable build workflows in open-img-cloud/.github, not by a person or another repository.
The signing event is publicly logged, so it cannot be issued silently.

1. Install cosign

Any recent cosign 2.x or 3.x release works. See the installation guide, or use a package manager:

Homebrew (macOS, Linux)

brew install cosign

2. Download

Fetch the image, its signature bundle and its manifest. They sit side by side under the same versioned path. Example with alpine-3.24.1-bios-x86_64.qcow2:

bash

curl -fLO https://images.openimages.cloud/alpine-linux/3.24.1/alpine-3.24.1-bios-x86_64.qcow2
curl -fLO https://images.openimages.cloud/alpine-linux/3.24.1/alpine-3.24.1-bios-x86_64.qcow2.bundle
curl -fLO https://images.openimages.cloud/alpine-linux/3.24.1/MANIFEST-bios.json

3. Verify the signature

bash

cosign verify-blob alpine-3.24.1-bios-x86_64.qcow2 \
  --bundle alpine-3.24.1-bios-x86_64.qcow2.bundle --new-bundle-format \
  --certificate-identity-regexp '^https://github.com/open-img-cloud/\.github/\.github/workflows/build-(libguestfs|dib|nix-flake|freebsd)-image\.yml@' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

The output must be Verified OK. The identity pattern matches our three build workflows (libguestfs, diskimage-builder and Nix) on the open-img-cloud/.github repository: a signature from anywhere else is rejected.

4. Inspect provenance

The manifest records what was built, from which commit, by which CI run and with which builder container digest. Open the CI run to read the full build log.

bash

jq '{version, sha256, built_at, commit, build_url, builder}' MANIFEST-bios.json

Checksums only

Without cosign you can still detect a corrupted download. Checksums alone don't prove who built the file, so prefer the signature when you can.

bash

curl -fsSL https://images.openimages.cloud/alpine-linux/3.24.1/alpine-3.24.1-bios-x86_64.qcow2.sha256 | sha256sum -c -