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

docs: npm provenance verification from GitHub runner (#595)

Browse Source 
Signed-off-by: laurentsimon <laurentsimon@google.com>
Signed-off-by: Ian Lewis <ianlewis@google.com>
Co-authored-by: Ian Lewis <ianlewis@google.com>
This commit is contained in:
laurentsimon
2023-05-12 03:13:22 +00:00
committed by GitHub
co-authored by Ian Lewis
parent 18ee30fca6
commit 1ac77fa5dc
1 changed files with 100 additions and 63 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+100 -63
View File
@@ -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