From 1ac77fa5dc4b1998bb6ea242670157027d14bd58 Mon Sep 17 00:00:00 2001 From: laurentsimon <64505099+laurentsimon@users.noreply.github.com> Date: Thu, 11 May 2023 20:13:22 -0700 Subject: [PATCH] docs: npm provenance verification from GitHub runner (#595) Signed-off-by: laurentsimon Signed-off-by: Ian Lewis Co-authored-by: Ian Lewis --- README.md | 163 +++++++++++++++++++++++++++++++++--------------------- 1 file changed, 100 insertions(+), 63 deletions(-) diff --git a/README.md b/README.md index 666e224..fb613c8 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,6 +283,102 @@ Verified build using builder https://github.com/slsa-framework/slsa-github-gener PASSED: Verified SLSA provenance ``` +### npm packages + +Verification of npm packages is currently an experimental feature. + +#### The verify-npm-package command + +```bash +$ slsa-verifier verify-npm-package --help +Verifies SLSA provenance for an npm package tarball [experimental] + +Usage: + slsa-verifier verify-npm-package [flags] tarball + +Flags: + --attestations-path string path to a file containing the attestations + --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 on GitHub Actions). (default map[]) + --builder-id string [optional] the unique builder ID who created the provenance + -h, --help help for verify-npm-package + --package-name string the package name + --package-version string the package version + --print-provenance [optional] print the verified provenance to stdout + --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 +``` + +#### 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 an npm package, first download the package tarball and attestations. + +```shell +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 \ + --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.127 \ + --source-uri github.com/ianlewis/actions-test +``` + +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. + +#### 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 @@ -330,66 +427,6 @@ The verified in-toto statement may be written to stdout with the 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 - -Verification of npm packages is currently an experimental feature. - -### The verify-npm-package command - -```bash -$ slsa-verifier verify-npm-package --help -Verifies SLSA provenance for an npm package tarball [experimental] - -Usage: - slsa-verifier verify-npm-package [flags] tarball - -Flags: - --attestations-path string path to a file containing the attestations - --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 on GitHub Actions). (default map[]) - --builder-id string [optional] the unique builder ID who created the provenance - -h, --help help for verify-npm-package - --package-name string the package name - --package-version string the package version - --print-provenance [optional] print the verified provenance to stdout - --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 -``` - -### Verify 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. - -```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')" -``` - -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/slsa-framework/slsa-github-generator/.github/workflows/builder_nodejs_slsa3.yml" \ - --package-name "@ianlewis/actions-test" \ - --package-version 0.1.126 \ - --source-uri github.com/ianlewis/actions-test -``` - -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. - ## Known Issues ### tuf: invalid key