github/slsa-verifier
1
0
Fork 0
mirror of https://github.com/slsa-framework/slsa-verifier.git synced 2026-08-26 09:37:19 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update README (#361)

Browse Source 
Signed-off-by: Ian Lewis <ianmlewis@gmail.com>

Signed-off-by: Ian Lewis <ianmlewis@gmail.com>
Co-authored-by: asraa <asraa@google.com>
This commit is contained in:
Ian Lewis
2022-11-28 16:20:13 +00:00
committed by GitHub
co-authored by asraa
parent 2cd857d928
commit 3162d85faf
1 changed files with 118 additions and 25 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+118 -25
View File
@@ -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)
<img align="right" src="https://slsa.dev/images/logo-mono.svg" width="140" height="140">
<!-- markdown-toc --bullets="-" -i README.md -->
<!-- toc -->
- [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)
<!-- tocstop -->
## 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 <options>
```
#### 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.