Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs: npm provenance verification from GitHub runner #595

Merged
merged 8 commits into from
May 12, 2023
Merged

docs: npm provenance verification from GitHub runner #595

Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
3e941af
update
laurentsimon May 12, 2023
0d20feb
update
laurentsimon May 12, 2023
8f184ff
update readme
ianlewis May 12, 2023
7dd7fd6
fix header
ianlewis May 12, 2023
b44d63a
fix toc
ianlewis May 12, 2023
fd10518
fix version
ianlewis May 12, 2023
c5e5a36
fix c&p
ianlewis May 12, 2023
0a10125
fix version
ianlewis May 12, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
155 changes: 96 additions & 59 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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
Expand All @@ -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
```

Expand All @@ -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
Expand Down