From 771f8422448087660d48a85dbc5fba5172ea2424 Mon Sep 17 00:00:00 2001 From: Ian Lewis Date: Wed, 11 Jan 2023 11:34:50 +0900 Subject: [PATCH] docs: Add instructions for GHA container generator (#438) Signed-off-by: Ian Lewis --- README.md | 120 ++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 76 insertions(+), 44 deletions(-) diff --git a/README.md b/README.md index 8d80c77ed..0052c27be 100644 --- a/README.md +++ b/README.md @@ -12,30 +12,31 @@ -- [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](#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) + - [panic: assignment to entry in nil map](#panic-assignment-to-entry-in-nil-map) +- [Technical design](#technical-design) + - [Blog post](#blog-post) + - [Specifications](#specifications) + - [TOCTOU attacks](#toctou-attacks) @@ -83,31 +84,31 @@ It currently supports verifying provenance generated by: [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) --- @@ -230,7 +231,34 @@ The only requirement is that the provenance file covers all artifacts passed as ### Containers -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](#toctou-attacks). + +First set the image name: + +```shell +IMAGE=ghcr.io/ianlewis/actions-test:v0.0.86 +``` + +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}") +``` + +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. + +```shell +slsa-verifier verify-image "$IMAGE" \ + --source-uri github.com/ianlewis/actions-test \ + --source-tag v0.0.86 +``` + +You 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 +``` ## Verification for Google Cloud Build @@ -242,32 +270,36 @@ 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](#toctou-attacks). -Run the commands below: +First set the image name: -```bash -$ IMAGE=laurentsimon/slsa-gcb-v0.3:test +```shell +IMAGE=laurentsimon/slsa-gcb-v0.3:test ``` Download the provenance: ```shell -$ gcloud artifacts docker images describe $IMAGE --format json --show-provenance > provenance.json +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}") +IMAGE="${IMAGE}@"$(crane digest "${IMAGE}") ``` Verify the image: -```bash -$ slsa-verifier verify-image "$IMAGE" \ +```shell +slsa-verifier verify-image "$IMAGE" \ --provenance-path provenance.json \ --source-uri github.com/laurentsimon/gcb-tests \ --builder-id=https://cloudbuild.googleapis.com/GoogleHostedWorker +``` + +You should see that the verification passed in the output. +``` PASSED: Verified SLSA provenance ``` @@ -291,7 +323,7 @@ FAILED: SLSA verification failed: could not find a matching valid signature entr 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. -### panic: assignment to entry in nil map +### panic: assignment to entry in nil map This will occur only when verifying provenance against workflow inputs.