- Overview
- Installation
- Available options
- Option list
- Verification for GitHub builders
- Verification for Google Cloud Build
- Known Issues
- Technical design
Supply chain Levels for Software Artifacts, or SLSA (salsa), is a security framework, a check-list of standards and controls to prevent tampering, improve integrity, and secure packages and infrastructure in your projects, businesses or enterprises.
SLSA defines an incrementially adoptable set of levels which are defined in terms of increasing compliance and assurance. SLSA levels are like a common language to talk about how secure software, supply chains and their component parts really are.
Provenance is information, or metadata, about how a software artifact was created. This could include information about what source code, build system, and build steps were used, as well as who and why the build was initiated. Provenance can be used to determine the authenticity and trustworthiness of software artifacts that you use.
As part of the framework, SLSA defines a provenance format which can be used hold this metadata.
slsa-verifier is a tool for verifying SLSA provenance that was generated by CI/CD builders. slsa-verifier verifies the provenance by verifying the cryptographic signatures on provenance to make sure it was created by the expected builder. It then verifies that various values such as the builder id, source code repository, ref (branch or tag) matches the expected values.
It currently supports verifying provenance generated by:
Verification for GitHub builders
Verification for Google Cloud Build
You have two options to install the verifier.
If you want to install the verifier, you can run the following command:
$ go install github.com/slsa-framework/slsa-verifier/v2/cli/[email protected]
$ slsa-verifier <options>Tools like dependabot or renovate use your project's go.mod to identify the version of your Go dependencies.
If you install the verifier binary in CI, we strongly recommend you create a placeholder go.mod containing slsa-verifier as a dependency to receive updates and keep the binary up-to-date. Use the following the steps:
- Create a tooling/tooling_test.go file containing the following:
//go:build tools
// +build tools
package main
import (
_ "github.com/slsa-framework/slsa-verifier/v2/cli/slsa-verifier"
)- Run the following commands in the tooling directory. (It will create a go.sum file.)
$ go mod init <your-project-name>-tooling
$ go mod tidy- Commit the tooling folder (containing the 3 files tooling_test.go, go.mod and go.sum) to the repository.
- To install the verifier in your CI, run the following commands:
$ cd tooling
$ grep _ tooling_test.go | cut -f2 -d '"' | xargs -n1 -t go installAlternatively, if your project does not rely on additional tools and only uses slsa-verifier, you can instead run the following commands:
$ cd tooling
$ go install github.com/slsa-framework/slsa-verifier/v2/cli/slsa-verifier$ git clone [email protected]:slsa-framework/slsa-verifier.git
$ cd slsa-verifier && git checkout v2.1.0
$ go run ./cli/slsa-verifier <options>If you need to install the verifier to run in a GitHub workflow, use the installer Action as described in actions/installer/README.md.
Download the binary from the latest release at https://github.com/slsa-framework/slsa-verifier/releases/tag/v2.1.0
Download the SHA256SUM.md.
Verify the checksum:
$ sha256sum -c --strict SHA256SUM.md
slsa-verifier-linux-amd64: OKWe currently support artifact verification (for binary blobs) and container images.
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 [email protected]:slsa-framework/slsa-verifier.git
$ go run ./cli/slsa-verifier/ verify-artifact --help
Verifies SLSA provenance on artifact blobs given as arguments (assuming same provenance)
Usage:
slsa-verifier verify-artifact [flags] artifact [artifact..]
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 on GitHub Actions). (default map[])
--builder-id string [optional] the unique builder ID who created the provenance
-h, --help help for verify-artifact
--print-provenance [optional] 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 tagMultiple artifacts can be passed to verify-artifact. As long as they are all covered by the same provenance file, the verification will succeed.
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 |
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 provenanceThe verified in-toto statement may be written to stdout with the --print-provenance flag to pipe into policy engines.
Only GitHub URIs are supported with the --source-uri flag. A tag should not be specified, even if the provenance was built at some tag. If you intend to do source versioning validation, use --print-provenance and inspect the commit SHA of the config source or materials.
Multiple artifacts built from the same GitHub builder can be verified in the same command, by passing them in the same command line as arguments:
$ slsa-verifier verify-artifact \
--provenance-path /tmp/demo/multiple.intoto.jsonl \
--source-uri github.com/mihaimaruseac/example \
/tmp/demo/fib /tmp/demo/hello
Verified signature against tlog entry index 9712459 at URL: https://rekor.sigstore.dev/api/v1/log/entries/24296fb24b8ad77a1544828b67bb5a2335f7e0d01c504a32ceb6f3a8814ed12c8f1b222d308bd9e8
Verified build using builder https://github.com/slsa-framework/slsa-github-generator/.github/workflows/generator_generic_slsa3.yml@refs/tags/v1.4.0 at commit 11fab87c5ee6f46c6f5e68f6c5378c62ce1ca77c
Verifying artifact /tmp/demo/fib: PASSED
Verified signature against tlog entry index 9712459 at URL: https://rekor.sigstore.dev/api/v1/log/entries/24296fb24b8ad77a1544828b67bb5a2335f7e0d01c504a32ceb6f3a8814ed12c8f1b222d308bd9e8
Verified build using builder https://github.com/slsa-framework/slsa-github-generator/.github/workflows/generator_generic_slsa3.yml@refs/tags/v1.4.0 at commit 11fab87c5ee6f46c6f5e68f6c5378c62ce1ca77c
Verifying artifact /tmp/demo/hello: PASSED
PASSED: Verified SLSA provenanceThe only requirement is that the provenance file covers all artifacts passed as arguments in the command line (that is, they are a subset of subject field in the provenance file).
To verify a container image, you need to pass a container image name that is immutable by providing its digest, in order to avoid TOCTOU attacks.
First set the image name:
IMAGE=ghcr.io/ianlewis/actions-test:v0.0.86Get the digest for your container without pulling it using the crane command:
IMAGE="${IMAGE}@"$(crane digest "${IMAGE}")To verify a container image, run the following command. Note that to use ghcr.io you need to set the GH_TOKEN environment variable as well.
slsa-verifier verify-image "$IMAGE" \
--source-uri github.com/ianlewis/actions-test \
--source-tag v0.0.86You should see that the verification passed in the output.
Verified build using builder https://github.com/slsa-framework/slsa-github-generator/.github/workflows/generator_container_slsa3.yml@refs/tags/v1.4.0 at commit d9be953dd17e7f20c7a234ada668f9c8c4aaafc3
PASSED: Verified SLSA provenance
This is WIP and currently not supported.
To verify a container image, you need to pass a container image name that is immutable by providing its digest, in order to avoid TOCTOU attacks.
First set the image name:
IMAGE=laurentsimon/slsa-gcb-v0.3:testDownload the provenance:
gcloud artifacts docker images describe $IMAGE --format json --show-provenance > provenance.jsonGet 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/GoogleHostedWorkerYou should see that the verification passed in the output.
PASSED: Verified SLSA provenance
The verified in-toto statement may be written to stdout with the --print-provenance flag to pipe into policy engines.
Note that --source-uri supports GitHub repository URIs like github.com/$OWNER/$REPO when the build was enabled with a Cloud Build GitHub trigger. Otherwise, the build provenance will contain the name of the Cloud Storage bucket used to host the source files, usually of the form gs://[PROJECT_ID]_cloudbuild/source (see Running build). We recommend using GitHub triggers in order to preserve the source provenance and valiate that the source came from an expected, version-controlled repository. You may match on the fully-qualified tar like gs://[PROJECT_ID]_cloudbuild/source/1665165360.279777-955d1904741e4bbeb3461080299e929a.tgz.
This will occur only when verifying provenance generated with GitHub Actions.
Affected versions: v1.3.0-v1.3.1, v1.2.0-v1.2.1, v1.1.0-v1.1.2, v1.0.0-v1.0.4
slsa-verifier will fail with the following error:
FAILED: SLSA verification failed: could not find a matching valid signature entry: got unexpected errors unable to initialize client, local cache may be corrupt: tuf: invalid key: unable to fetch Rekor public keys from TUF repository
This issue is tracked by issue #325. You must update to the newest patch versions of each minor release to fix this issue.
This will occur only when verifying provenance against workflow inputs.
Affected versions: v2.0.0
slsa-verifier will fail with the following error:
panic: assignment to entry in nil map
This is fixed by PR #379. You must update to the newest patch versions of each minor release to fix this issue.
Find our blog post series here.
For a more in-depth technical dive, read the SPECIFICATIONS.md.
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.