diff --git a/README.md b/README.md index 666e22406..fb613c8c9 100644 --- a/README.md +++ b/README.md @@ -28,12 +28,13 @@ - [Verification for GitHub builders](#verification-for-github-builders) - [Artifacts](#artifacts) - [Containers](#containers) + - [npm packages](#npm-packages) + - [The verify-npm-package command](#the-verify-npm-package-command) + - [npm packages built using the SLSA3 Node.js builder](#npm-packages-built-using-the-slsa3-nodejs-builder) + - [npm packages built using the npm CLI](#npm-packages-built-using-the-npm-cli) - [Verification for Google Cloud Build](#verification-for-google-cloud-build) - [Artifacts](#artifacts-1) - [Containers](#containers-1) -- [Verification for npm packages](#verification-for-npm-packages) - - [The verify-npm-package command](#the-verify-npm-package-command) - - [Verify npm packages built using the SLSA3 Node.js builder](#verify-npm-packages-built-using-the-slsa3-nodejs-builder) - [Known Issues](#known-issues) - [tuf: invalid key](#tuf-invalid-key) - [panic: assignment to entry in nil map](#panic-assignment-to-entry-in-nil-map) @@ -282,59 +283,11 @@ Verified build using builder https://github.com/slsa-framework/slsa-github-gener PASSED: Verified SLSA provenance ``` -## 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). - -First set the image name: - -```shell -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: - -```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 -``` - -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`. - -## Verification for npm packages +### npm packages Verification of npm packages is currently an experimental feature. -### The verify-npm-package command +#### The verify-npm-package command ```bash $ slsa-verifier verify-npm-package --help @@ -357,26 +310,26 @@ Flags: --source-versioned-tag string [optional] expected version the binary was compiled from. Uses semantic version to match the tag ``` -### Verify npm packages built using the SLSA3 Node.js builder +#### npm packages built using the SLSA3 Node.js builder This section describes how to verify packages built using the SLSA Build L3 [Node.js builder](https://github.com/slsa-framework/slsa-github-generator/blob/main/internal/builders/nodejs/README.md). -To verify a npm packages, first download the package tarball and attestations. +To verify an npm package, first download the package tarball and attestations. ```shell -curl -Sso attestations.json $(npm view @ianlewis/actions-test@0.1.126 --json | jq -r '.dist.attestations.url') && \ -curl -Sso actions-test.tgz "$(npm view @ianlewis/actions-test@0.1.126 --json | jq -r '.dist.tarball')" +curl -Sso attestations.json $(npm view @ianlewis/actions-test@0.1.127 --json | jq -r '.dist.attestations.url') && \ +curl -Sso actions-test.tgz "$(npm view @ianlewis/actions-test@0.1.127 --json | jq -r '.dist.tarball')" ``` You can then verify the package by running the following command: ```shell -$ SLSA_VERIFIER_EXPERIMENTAL=1 slsa-verifier verify-npm-package actions-test.tgz \ +SLSA_VERIFIER_EXPERIMENTAL=1 slsa-verifier verify-npm-package actions-test.tgz \ --attestations-path attestations.json \ --builder-id "https://github.com/slsa-framework/slsa-github-generator/.github/workflows/builder_nodejs_slsa3.yml" \ --package-name "@ianlewis/actions-test" \ - --package-version 0.1.126 \ + --package-version 0.1.127 \ --source-uri github.com/ianlewis/actions-test ``` @@ -390,6 +343,90 @@ release tag and `--package-version` to validate the package version. For commit SHA validation, use `--print-provenance` and inspect the commit SHA of the config source or materials. +#### npm packages built using the npm CLI + +This section describes how to verify packages built using the npm CLI on GitHub. + +To verify an npm package, first download the package tarball and attestations. + +```shell +curl -Sso attestations.json $(npm view @ianlewis/actions-test@0.1.132 --json | jq -r '.dist.attestations.url') && \ +curl -Sso actions-test.tgz "$(npm view @ianlewis/actions-test@0.1.132 --json | jq -r '.dist.tarball')" +``` + +You can then verify the package by running the following command: + +```shell +SLSA_VERIFIER_EXPERIMENTAL=1 slsa-verifier verify-npm-package actions-test.tgz \ + --attestations-path attestations.json \ + --builder-id "https://github.com/actions/runner/github-hosted" \ + --package-name "@ianlewis/actions-test" \ + --package-version 0.1.132 \ + --source-uri github.com/ianlewis/actions-test +``` + +If the package was built with self-hosted runners, replace +"https://github.com/actions/runner/github-hosted" with +"https://github.com/actions/runner/self-hosted". + +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, you can use `--source-tag` to validate the +release tag and `--package-version` to validate the package version. For commit +SHA validation, use `--print-provenance` and inspect the commit SHA of the +config source or materials. + +## 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). + +First set the image name: + +```shell +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: + +```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 +``` + +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`. + ## Known Issues ### tuf: invalid key