diff --git a/README.md b/README.md index c2b98c0..7ea715e 100644 --- a/README.md +++ b/README.md @@ -1,32 +1,115 @@ # Verification of SLSA provenance -This repository contains the implementation for verifying [SLSA provenance](https://slsa.dev/). It currently supports verifying provenance generated by: + +[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/slsa-framework/slsa-verifier/badge)](https://api.securityscorecards.dev/projects/github.com/slsa-framework/slsa-verifier) +[![OpenSSF Best Practices](https://bestpractices.coreinfrastructure.org/projects/6729/badge)](https://bestpractices.coreinfrastructure.org/projects/6729) +[![Go Report Card](https://goreportcard.com/badge/github.com/slsa-framework/slsa-verifier)](https://goreportcard.com/report/github.com/slsa-framework/slsa-verifier) +[![Slack](https://slack.babeljs.io/badge.svg)](https://slack.com/app_redirect?team=T019QHUBYQ3&channel=slsa-tooling) +[![SLSA 3](https://slsa.dev/images/gh-badge-level3.svg)](https://slsa.dev) + + + + + + + +- [Overview](#overview) + - [What is SLSA?](#what-is-slsa) + - [What is provenance?](#what-is-provenance) + - [What is slsa-verifier?](#what-is-slsa-verifier) +- [Installation](#installation) + - [Compilation from source](#compilation-from-source) + - [Option 1: Install via go](#option-1-install-via-go) + - [Option 2: Compile manually](#option-2-compile-manually) + - [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) +- [Known Issues](#known-issues) + - [tuf: invalid key](#tuf-invalid-key) +- [Technical design](#technical-design) + - [Blog post](#blog-post) + - [Specifications](#specifications) + - [TOCTOU attacks](#toctou-attacks) + + + +## Overview + +### What is SLSA? + +[Supply chain Levels for Software Artifacts](https://slsa.dev), 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. + +### What is provenance? + +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](https://slsa.dev/provenance/) which can be used hold this +metadata. + +### What is slsa-verifier? + +slsa-verifier is a tool for verifying +[SLSA provenance](https://slsa.dev/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: + 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) + +- [Compilation from source](#compilation-from-source) +- [Download the binary](#download-the-binary) [Available options](#available-options) -- [Option list](#option-list) -- [Option details](#option-details) + +- [Option list](#option-list) +- [Option details](#option-details) [Verification for GitHub builders](#verification-for-github-builders) -- [Artifacts](#artifacts) -- [Containers](#containers) + +- [Artifacts](#artifacts) +- [Containers](#containers) [Verification for Google Cloud Build](#verification-for-google-cloud-build) -- [Artifacts](#artifacts-1) -- [Containers](#containers-1) + +- [Artifacts](#artifacts-1) +- [Containers](#containers-1) [Known Issues](#known-issues) [Technical design](#technial-design) -- [Blog posts](#blog-posts) -- [Specifications](#specifications) -- [TOCTOU attacks](#toctou-attacks) -________ + +- [Blog posts](#blog-posts) +- [Specifications](#specifications) +- [TOCTOU attacks](#toctou-attacks) + +--- ## Installation @@ -35,12 +118,14 @@ 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 ``` #### Option 2: Compile manually + ``` $ git clone git@github.com:slsa-framework/slsa-verifier.git $ cd slsa-verifier && git checkout v1.3.1 @@ -92,13 +177,13 @@ Flags: 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) +| 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 @@ -120,16 +205,18 @@ The verified in-toto statement may be written to stdout with the `--print-proven 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 container 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: @@ -139,16 +226,19 @@ $ 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 \ @@ -160,7 +250,7 @@ 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`. +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`. ## Known Issues @@ -168,7 +258,7 @@ Note that `--source-uri` supports GitHub repository URIs like `github.com/$OWNER 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 +**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: @@ -176,17 +266,20 @@ This will occur only when verifying provenance generated with GitHub Actions. 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](https://github.com/slsa-framework/slsa-verifier/issues/325). You *must* update to the newest patch versions of each minor release to fix this issue. +This issue is tracked by [issue #325](https://github.com/slsa-framework/slsa-verifier/issues/325). You _must_ update to the newest patch versions of each minor release to fix this issue. ## 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.