mirror of
https://github.com/slsa-framework/slsa-verifier.git
synced 2026-05-08 17:46:35 +00:00
27597feff8
* Update README.md Add missing [optional] indicators to the "verify-artifact" --help example. Signed-off-by: Wietse Venema <72045954+wietse-gmail@users.noreply.github.com> * Add missing [optional] indicators to the verify-artifact help message Signed-off-by: Wietse Venema <72045954+wietse-gmail@users.noreply.github.com> Signed-off-by: Wietse Venema <72045954+wietse-gmail@users.noreply.github.com>
175 lines
8.9 KiB
Markdown
175 lines
8.9 KiB
Markdown
# Verification of SLSA provenance
|
|
This repository contains the implementation for verifying [SLSA provenance](https://slsa.dev/). It currently supports verifying provenance generated by:
|
|
1. [SLSA generator](https://github.com/slsa-framework/slsa-github-generator)
|
|
1. [Google Cloud Build (GCB)](https://cloud.google.com/build/docs/securing-builds/view-build-provenance).
|
|
|
|
________
|
|
[Installation](#installation)
|
|
- [Compilation from source](#compilation-from-source)
|
|
- [Download the binary](#download-the-binary)
|
|
|
|
[Available options](#available-options)
|
|
- [Option list](#option-list)
|
|
- [Option details](#option-details)
|
|
|
|
[Verification for GitHub builders](#verification-for-github-builders)
|
|
- [Artifacts](#artifacts)
|
|
- [Containers](#containers)
|
|
|
|
[Verification for Google Cloud Build](#verification-for-google-cloud-build)
|
|
- [Artifacts](#artifacts-1)
|
|
- [Containers](#containers-1)
|
|
|
|
[Technical design](#technial-design)
|
|
- [Blog posts](#blog-posts)
|
|
- [Specifications](#specifications)
|
|
- [TOCTOU attacks](#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](https://github.com/slsa-framework/slsa-verifier/releases/tag/v1.3.1)
|
|
|
|
Download the [SHA256SUM.md](https://github.com/slsa-framework/slsa-verifier/blob/main/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](#available-options) for details on the options exposed to validate the provenance.
|
|
|
|
```bash
|
|
$ 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 [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 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](https://github.com/slsa-framework/slsa-github-generator#generation-of-provenance)
|
|
| `source-tag` | Expects a `tag` like `v0.0.1`. Verifies exact tag used to create the binary. Supported for new [tag](https://github.com/slsa-framework/example-package/blob/main/.github/workflows/e2e.go.tag.main.config-ldflags-assets-tag.slsa3.yml#L5) and [release](https://github.com/slsa-framework/example-package/blob/main/.github/workflows/e2e.go.release.main.config-ldflags-assets-tag.slsa3.yml) triggers. | [GitHub builders](https://github.com/slsa-framework/slsa-github-generator#generation-of-provenance)
|
|
| `source-versioned-tag` | Like `tag`, but verifies using semantic versioning. | [GitHub builders](https://github.com/slsa-framework/slsa-github-generator#generation-of-provenance)
|
|
| `build-workflow-input` | Expects key-value pairs like `key=value` to match against [inputs](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#onworkflow_dispatchinputs) for GitHub Actions `workflow_dispatch` triggers. | [GitHub builders](https://github.com/slsa-framework/slsa-github-generator#generation-of-provenance)
|
|
|
|
## Verification for GitHub builders
|
|
|
|
### Artifacts
|
|
|
|
To verify an artifact, run the following command:
|
|
|
|
```bash
|
|
$ 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.
|
|
|
|
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.
|
|
|
|
|
|
### 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](#toctou-attacks).
|
|
|
|
Run the commands below:
|
|
|
|
```bash
|
|
$ IMAGE=laurentsimon/slsa-gcb-v0.3:test
|
|
```
|
|
|
|
Download the provenance:
|
|
```shell
|
|
$ gcloud artifacts docker images describe $IMAGE --format json --show-provenance > provenance.json
|
|
```
|
|
|
|
Get the digest for your container _without_ pulling it using the [crane](https://github.com/google/go-containerregistry/blob/main/cmd/crane/doc/crane.md) command:
|
|
```shell
|
|
$ IMAGE="${IMAGE}@"$(crane digest "${IMAGE}")
|
|
```
|
|
|
|
Verify the image:
|
|
```bash
|
|
$ 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.
|
|
|
|
Note that `--source-uri` supports GitHub repository URIs like `github.com/$OWNER/$REPO` when the build was enabled with a Cloud Build [GitHub trigger](https://cloud.google.com/build/docs/automating-builds/github/build-repos-from-github). 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](https://cloud.google.com/build/docs/running-builds/submit-build-via-cli-api#running_builds)). 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`.
|
|
|
|
## Technical design
|
|
|
|
### Blog post
|
|
Find our blog post series [here](https://security.googleblog.com/2022/04/improving-software-supply-chain.html).
|
|
|
|
### Specifications
|
|
For a more in-depth technical dive, read the [SPECIFICATIONS.md](https://github.com/slsa-framework/slsa-github-generator/blob/main/SPECIFICATIONS.md).
|
|
|
|
### TOCTOU attacks
|
|
As explained on [Wikipedia](https://en.wikipedia.org/wiki/Time-of-check_to_time-of-use), 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.
|