Skip to main content
View as Markdown

SLSA Provenance

info

The English user guide is currently in beta preview. Most of the documents have been automatically translated from the Japanese version. Should you find any inaccuracies, please reach out to Flatt Security.

Each image includes a SLSA provenance statement as a signed attestation. It records the build inputs: which source revisions were built and which workflow execution built them. Verification therefore confirms not only the image contents, but also the build the image came from.

info

Takumi Images is currently in beta. Specifications and behavior may change without prior notice.

Recorded contents​

The predicate records the build invocation, the materials used as build inputs, and the builder identity, including the workflow path and ref. The predicate type is SLSA v1 slsaprovenance1. These fields are information the release workflow had at execution time; they are not added after the fact.

The structure looks like this, with some fields omitted.

{
  "_type": "https://in-toto.io/Statement/v1",
  "subject": [
    {
      "name": "takumi/curl",
      "digest": { "sha256": "<image tar sha256>" }
    }
  ],
  "predicateType": "https://slsa.dev/provenance/v1",
  "predicate": {
    "buildDefinition": {
      "externalParameters": {
        "image": "takumi/curl",
        "arch": "arm64",
        "nixpkgs": {
          "uri": "https://github.com/NixOS/nixpkgs/archive/<rev>.tar.gz",
          "sha256": "<sha256>"
        }
      },
      "resolvedDependencies": ["<direct derivation inputs for the image>"]
    }
  }
}

The subject digest is the hash of the uncompressed image tar verified at release time. externalParameters contains the pin that fully determines the build, including the nixpkgs revision and hash. The predicate is therefore a record for later checking which inputs and which workflow produced the image with that hash.

Relationship with reproducible builds​

The inputs recorded in provenance are still a claim unless they are backed by the build system. Takumi Images backs that claim with reproducible builds. Each image is built as a Nix expression whose result is determined only by declared inputs, and CI verifies that rebuilding from the same inputs produces a bit-for-bit identical image. By verifying the provenance and signature, users can confirm which inputs and release workflow are linked to the published image. See Build Pipeline Overview for how the build produces reproducible results.

Verification​

Provenance differs by architecture, like SBOMs, so it is attached to the architecture-specific child image. First extract the child digest for the target architecture from the index, then verify the provenance with --type slsaprovenance1.

CHILD_DIGEST=$(crane manifest images.flatt.tech/takumi/busybox:latest \
  | jq -r '.manifests[] | select(.platform.architecture=="amd64").digest')

cosign verify-attestation \
  --certificate-oidc-issuer=https://token.actions.githubusercontent.com \
  --certificate-identity-regexp 'https://github.com/flatt-security/takumi-images/.github/workflows/release.yml@.*' \
  --type slsaprovenance1 \
  "images.flatt.tech/takumi/busybox@${CHILD_DIGEST}" \
  | jq -r '.payload' | base64 -d | jq '.predicate'

See Attestation for the signing model that makes this attestation trustworthy.

Last updated on