slsa-framework · ianlewis · May 12, 2023 · May 12, 2023 · May 12, 2023 · May 12, 2023
@@ -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