slsa-verifier

README

Verification of SLSA provenance

This repository contains the implementation for verifying SLSA provenance. It currently supports verifying provenance generated by:

1. SLSA generator
2. Google Cloud Build (GCB).

---

Installation

• Compilation from source
• Download the binary

Available options

• Option list
• Option details

Verification for GitHub builders

• Artifacts
• Containers

Verification for Google Cloud Build

• Artifacts
• Containers

Technical design

• Blog posts
• Specifications
• TOCTOU attacks

---

Installation

You have two options to install the verifier.

Compilation from source

Option 1: Install via go

$ go install github.com/slsa-framework/slsa-verifier/cli/slsa-verifier@v1.3.1
$ slsa-verifier <options>

Option 2: Compile manually

$ git clone git@github.com:slsa-framework/slsa-verifier.git
$ cd slsa-verifier && git checkout v1.3.1
$ go run ./cli/slsa-verifier <options>

Download the binary

Download the binary from the latest release at https://github.com/slsa-framework/slsa-verifier/releases/tag/v1.3.1

Download the SHA256SUM.md.

Verify the checksum:

$ sha256sum -c --strict SHA256SUM.md
  slsa-verifier-linux-amd64: OK

Available options

We currently support artifact verification (for binary blobs) and container images.

Option list

Below is a list of options currently supported for binary blobs and container images. Note that signature verification is handled seamlessly without the need for developers to manipulate public keys. See Available options for details on the options exposed to validate the provenance.

$ git clone git@github.com:slsa-framework/slsa-verifier.git
$ go run ./cli/slsa-verifier/ verify-artifact --help
Verifies SLSA provenance on an artifact blob

Usage:
  slsa-verifier verify-artifact [flags]

Flags:
      --build-workflow-input map[]    [optional] a workflow input provided by a user at trigger time in the format 'key=value'. (Only for 'workflow_dispatch' events). (default map[])
      --builder-id string             the unique builder ID who created the provenance
  -h, --help                          help for verify-artifact
      --print-provenance              print the verified provenance to stdout
      --provenance-path string        path to a provenance file
      --source-branch string          [optional] expected branch the binary was compiled from
      --source-tag string             [optional] expected tag the binary was compiled from
      --source-uri string             expected source repository that should have produced the binary, e.g. github.com/some/repo
      --source-versioned-tag string   [optional] expected version the binary was compiled from. Uses semantic version to match the tag

Option details

The following options are available:

Option	Description	Support
source-uri	Expects a source, for e.g. github.com/org/repo.	All builders
source-branch	Expects a branch like main or dev. Not supported for all GitHub Workflow triggers.	GitHub builders
source-tag	Expects a tag like v0.0.1. Verifies exact tag used to create the binary. Supported for new tag and release triggers.	GitHub builders
source-versioned-tag	Like tag, but verifies using semantic versioning.	GitHub builders
build-workflow-input	Expects key-value pairs like key=value to match against inputs for GitHub Actions workflow_dispatch triggers.	GitHub builders

Verification for GitHub builders

Artifacts

To verify an artifact, run the following command:

$ slsa-verifier verify-artifact slsa-test-linux-amd64 \
  --provenance-path slsa-test-linux-amd64.intoto.jsonl \
  --source-uri github.com/slsa-framework/slsa-test \
  --source-tag v1.0.3
Verified signature against tlog entry index 3189970 at URL: https://rekor.sigstore.dev/api/v1/log/entries/206071d5ca7a2346e4db4dcb19a648c7f13b4957e655f4382b735894059bd199
Verified build using builder https://github.com/slsa-framework/slsa-github-generator/.github/workflows/builder_go_slsa3.yml@refs/tags/v1.2.0 at commit 5bb13ef508b2b8ded49f9264d7712f1316830d10
PASSED: Verified SLSA provenance

The verified in-toto statement may be written to stdout with the --print-provenance flag to pipe into policy engines.

Containers

This is WIP and currently not supported.

Verification for Google Cloud Build

Artifacts

This is WIP and currently not supported.

Containers

To verify a contaimer image, you need to pass a container image name that is immutable by providing its digest, in order to avoid TOCTOU attacks.

Run the commands below:

$ IMAGE=laurentsimon/slsa-gcb-v0.3:test

Download the provenance:

$ gcloud artifacts docker images describe $IMAGE --format json --show-provenance > provenance.json

Get the digest for your container without pulling it using the crane command:

$ IMAGE="${IMAGE}@"$(crane digest "${IMAGE}")

Verify the image:

$ slsa-verifier verify-image "$IMAGE" \
  --provenance-path provenance.json \
  --source-uri github.com/laurentsimon/gcb-tests \
  --builder-id=https://cloudbuild.googleapis.com/GoogleHostedWorker

PASSED: Verified SLSA provenance

The verified in-toto statement may be written to stdout with the --print-provenance flag to pipe into policy engines.

Technical design

Blog post

Find our blog post series here.

Specifications

For a more in-depth technical dive, read the SPECIFICATIONS.md.

TOCTOU attacks

As explained on Wikipedia, a "time-of-check to time-of-use (TOCTOU) is a class of software bugs caused by a race condition involving the checking of the state of a part of a system and the use of the results of that check".

In the context of provenance verification, imagine you verify a container refered to via a mutable image image:tag. The verification succeeds and verifies the corresponding hash is sha256:abcdef.... After verification, you pull and run the image using docker run image:tag. An attacker could have altered the image between the verification step and the run step. To mitigate this attack, we ask users to always pass an immutable reference to the artifact they verify.