- Notifications
You must be signed in to change notification settings - Fork56
Verify provenance from SLSA compliant builders
License
slsa-framework/slsa-verifier
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
- Overview
- Installation
- Available options
- Option list
- Verification for GitHub builders
- Verification for GitHub
attest-build-provenanceAttestations - Verification for Google Cloud Build
- Verification Summary Attestations (VSA)
- Known Issues
- Technical design
Supply chain Levels for Software Artifacts, or SLSA (salsa),is a security framework, a check-list of standards and controls to preventtampering, improve integrity, and secure packages and infrastructure in yourprojects, businesses or enterprises.
SLSA defines an incrementially adoptable set of levels which are defined interms of increasing compliance and assurance. SLSA levels are like a commonlanguage to talk about how secure software, supply chains and their componentparts really are.
Provenance is information, or metadata, about how a software artifact wascreated. This could include information about what source code, build system,and build steps were used, as well as who and why the build was initiated.Provenance can be used to determine the authenticity and trustworthiness ofsoftware artifacts that you use.
As part of the framework, SLSA defines aprovenance format which can be used hold thismetadata.
slsa-verifier is a tool for verifyingSLSA provenance that was generated by CI/CDbuilders. slsa-verifier verifies the provenance by verifying the cryptographicsignatures on provenance to make sure it was created by the expected builder.It then verifies that various values such as the builder id, source coderepository, ref (branch or tag) matches the expected values.
It currently supports verifying provenance generated by:
You have two options to install the verifier.
If you want to install the verifier, you can run the following command:
$ go install github.com/slsa-framework/slsa-verifier/v2/cli/slsa-verifier@v2.7.1$ slsa-verifier<options>
Tools likedependabot orrenovate use your project's go.mod to identify the version of your Go dependencies.If you install the verifier binary in CI, we strongly recommend you create a placeholdergo.mod containing slsa-verifier as a dependency to receive updates and keep the binary up-to-date. Use the following the steps:
- Create a tooling/tooling_test.go file containing the following:
//go:build tools// +build toolspackage mainimport (_"github.com/slsa-framework/slsa-verifier/v2/cli/slsa-verifier")
- Run the following commands in the tooling directory. (It will create a go.sum file.)
$ go mod init<your-project-name>-tooling$ go mod tidy
- Commit the tooling folder (containing the 3 files tooling_test.go, go.mod and go.sum) to the repository.
- To install the verifier in your CI, run the following commands:
$cd tooling$ grep _ tooling_test.go| cut -f2 -d'"'| xargs -n1 -t go install
Alternatively, if your project does not rely on additional tools and only uses slsa-verifier, you can instead run the following commands:
$cd tooling$ go install github.com/slsa-framework/slsa-verifier/v2/cli/slsa-verifier$ git clone git@github.com:slsa-framework/slsa-verifier.git$cd slsa-verifier&& git checkout v2.7.1$ go run ./cli/slsa-verifier<options>
If you need to install the verifier to run in a GitHub workflow, use the installer Action as described inactions/installer/README.md.
Download the binary from the latest release athttps://github.com/slsa-framework/slsa-verifier/releases/tag/v2.7.1
Download theSHA256SUM.md.
Verify the checksum:
$ sha256sum -c --strict SHA256SUM.md slsa-verifier-linux-amd64: OK
If you are using macOS and Homebrew, then you can install the verifier using this community-maintainedformula.
We currently support artifact verification (for binary blobs) and container images.
Below is a list of options currently supported for binary blobs and container images. Note that signature verification is handled seamlessly without the need for developers to manipulate public keys. SeeAvailable options for details on the options exposed to validate the provenance.
$ git clone git@github.com:slsa-framework/slsa-verifier.git$ go run ./cli/slsa-verifier/ verify-artifact --helpVerifies SLSA provenance on artifact blobs given as arguments (assuming same provenance)Usage: slsa-verifier verify-artifact [flags] artifact [artifact..]Flags: --build-workflow-input map[] [optional] a workflow input provided by a user at triggertimein the format'key=value'. (Onlyfor'workflow_dispatch' events on GitHub Actions). (default map[]) --builder-id string [optional] the unique builder ID who created the provenance -h, --helphelpfor verify-artifact --print-provenance [optional] print the verified provenance to stdout --provenance-path string path to a provenance file --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 expectedsource 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
Multiple artifacts can be passed toverify-artifact. As long as they are all covered by the same provenance file, the verification will succeed.
The following options are available:
| Option | Description | Support |
|---|---|---|
source-uri | Expects a source, for e.g.github.com/org/repo. | All builders |
source-branch | Expects abranch likemain ordev. Not supported for all GitHub Workflow triggers. | GitHub builders |
source-tag | Expects atag likev0.0.1. Verifies exact tag used to create the binary. Supported for newtag andrelease triggers. | GitHub builders |
source-versioned-tag | Liketag, but verifies using semantic versioning. | GitHub builders |
build-workflow-input | Expects key-value pairs likekey=value to match againstinputs for GitHub Actionsworkflow_dispatch triggers. | GitHub builders |
To verify an artifact, run the following command:
$ slsa-verifier verify-artifact slsa-test-linux-amd64 \ --provenance-path slsa-test-linux-amd64.intoto.jsonl \ --source-uri github.com/slsa-framework/slsa-test \ --source-tag v1.0.3Verified signature against tlog entry index 3189970 at URL: https://rekor.sigstore.dev/api/v1/log/entries/206071d5ca7a2346e4db4dcb19a648c7f13b4957e655f4382b735894059bd199Verified build using builder https://github.com/slsa-framework/slsa-github-generator/.github/workflows/builder_go_slsa3.yml@refs/tags/v1.2.0 at commit 5bb13ef508b2b8ded49f9264d7712f1316830d10PASSED: Verified SLSA provenance
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 notbe specified, even if the provenance was built at some tag. If you intend to dosource versioning validation, you can use--source-tag to validate therelease tag. For commit SHA validation, use--print-provenance and inspectthe commit SHA of the config source or materials.
Multiple artifacts built from the same GitHub builder can be verified in thesame command, by passing them in the same command line as arguments:
$ slsa-verifier verify-artifact \ --provenance-path /tmp/demo/multiple.intoto.jsonl \ --source-uri github.com/mihaimaruseac/example \ /tmp/demo/fib /tmp/demo/helloVerified signature against tlog entry index 9712459 at URL: https://rekor.sigstore.dev/api/v1/log/entries/24296fb24b8ad77a1544828b67bb5a2335f7e0d01c504a32ceb6f3a8814ed12c8f1b222d308bd9e8Verified build using builder https://github.com/slsa-framework/slsa-github-generator/.github/workflows/generator_generic_slsa3.yml@refs/tags/v1.4.0 at commit 11fab87c5ee6f46c6f5e68f6c5378c62ce1ca77cVerifying artifact /tmp/demo/fib: PASSEDVerified signature against tlog entry index 9712459 at URL: https://rekor.sigstore.dev/api/v1/log/entries/24296fb24b8ad77a1544828b67bb5a2335f7e0d01c504a32ceb6f3a8814ed12c8f1b222d308bd9e8Verified build using builder https://github.com/slsa-framework/slsa-github-generator/.github/workflows/generator_generic_slsa3.yml@refs/tags/v1.4.0 at commit 11fab87c5ee6f46c6f5e68f6c5378c62ce1ca77cVerifying artifact /tmp/demo/hello: PASSEDPASSED: Verified SLSA provenance
The only requirement is that the provenance file covers all artifacts passed as arguments in the command line (that is, they are a subset ofsubject field in the provenance file).
To verify a container image, you need to pass a container image name that isimmutable by providing its digest, in order to avoidTOCTOU attacks.
$ slsa-verifier verify-image --helpVerifies SLSA provenancefor an imageUsage: slsa-verifier verify-image [flags] tarballFlags: --build-workflow-input map[] [optional] a workflow input provided by a user at triggertimein the format'key=value'. (Onlyfor'workflow_dispatch' events on GitHub Actions). (default map[]) --builder-id string [optional] the unique builder ID who created the provenance -h, --helphelpfor verify-npm-package --print-provenance [optional] print the verified provenance to stdout --provenance-path string path to a provenance file --provenance-repository string [optional] provenance repository when stored different from image repository. When set, overrides COSIGN_REPOSITORY environment variable --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 expectedsource 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
First set the image name:
IMAGE=ghcr.io/ianlewis/actions-test:v0.0.86
Get the digest for your containerwithout pulling it using thecrane command:
IMAGE="${IMAGE}@"$(crane digest"${IMAGE}")
To verify a container image, run the following command. Note that to useghcr.io you need to set theGH_TOKEN environment variable as well.
slsa-verifier verify-image"$IMAGE" \ --source-uri github.com/ianlewis/actions-test \ --source-tag v0.0.86You should see that the verification passed in the output.
Verified build using builder https://github.com/slsa-framework/slsa-github-generator/.github/workflows/generator_container_slsa3.yml@refs/tags/v1.4.0 at commit d9be953dd17e7f20c7a234ada668f9c8c4aaafc3PASSED: Verified SLSA provenanceVerification of npm packages is currently an experimental feature.
More details about npm attestations are indocs/npm.md
$ slsa-verifier verify-npm-package --helpVerifies SLSA provenancefor an npm package tarball [experimental]Usage: slsa-verifier verify-npm-package [flags] tarballFlags: --attestations-path string path to a file containing the attestations --build-workflow-input map[] [optional] a workflow input provided by a user at triggertimein the format'key=value'. (Onlyfor'workflow_dispatch' events on GitHub Actions). (default map[]) --builder-id string [optional] the unique builder ID who created the provenance -h, --helphelpfor 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 expectedsource 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
This section describes how to verify packages built using the SLSA Build L3Node.js builder.
To verify an npm package, first download the package tarball and attestations.
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:
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 notbe specified, even if the provenance was built at some tag. If you intend to dosource versioning validation, you can use--source-tag to validate therelease tag and--package-version to validate the package version. For commitSHA validation, use--print-provenance and inspect the commit SHA of theconfig source or materials.
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.
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:
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 notbe specified, even if the provenance was built at some tag. If you intend to dosource versioning validation, you can use--source-tag to validate therelease tag and--package-version to validate the package version. For commitSHA validation, use--print-provenance and inspect the commit SHA of theconfig source or materials.
To verify an artifact produced by theContainer-based builder, you will first need to run the following command to verify the provenance like the section above for generalArtifacts:
$ slsa-verifier verify-artifact slsa-test-linux-amd64 \ --provenance-path slsa-test-linux-amd64.sigstore \ --source-uri github.com/slsa-framework/slsa-test \ --source-tag v1.0.3Verified signature against tlog entry index 3189970 at URL: https://rekor.sigstore.dev/api/v1/log/entries/206071d5ca7a2346e4db4dcb19a648c7f13b4957e655f4382b735894059bd199Verified build using builder https://github.com/slsa-framework/slsa-github-generator/.github/workflows/builder_container-based_slsa3.yml@refs/tags/v1.7.0 at commit 5bb13ef508b2b8ded49f9264d7712f1316830d10PASSED: Verified SLSA provenance
The input provenance is a.sigstore file, which is aSigstore bundle that contains the in-toto statement containing the SLSA provenance along with verification material. The verified in-toto statement contained in the bundle may be written to stdout with the--print-provenance flag to pipe into policy engines.
To verify the user-specified builder image that was used to produce the artifact, extract the builder image with the following command and validate in a policy engine:
$ cat verifier-statement.intoto| jq -r'.predicate.buildDefinition.externalParameters.builderImage'
The builder image is described using anin-toto Resource Descriptor.
In case the builds are reproducible, you may also use the internaldocker CLI tool to verify the artifact by rebuilding the artifact with the provided provenance.
Attestations produced by builders that leverage theattest-build-provenance action.
Currently limited to artifacts built with the following builder-ids:
github.com/bazel-contrib/.github/blob/master/.github/workflows/release_ruleset.yamlgithub.com/bazel-contrib/publish-to-bcr/.github/workflows/publish.yaml
$ slsa-verifier verify-github-attestation --helpVerifies SLSA provenancefor a GitHub attestationUsage: slsa-verifier verify-github-attestation [flags] module-fileFlags: --attestation-path string path to an attestation file --builder-id string the unique builder ID who created the provenance -h, --helphelpfor verify-github-attestation --print-attestation [optional] print the verified attestation to stdout --source-uri string expectedsource repository that should have produced the binary, e.g. github.com/some/repo
First download the artifact and attestation (from bazel central registry in this example)
$ curl -sSO https://bcr.bazel.build/modules/aspect_rules_lint/1.3.4/MODULE.bazel$ curl -sSO https://bcr.bazel.build/modules/aspect_rules_lint/1.3.4/MODULE.bazel.intoto.jsonl
Verify the attestation
$ slsa-verifier verify-github-attestation --source-uri github.com/aspect-build/rules_lint --builder-id https://github.com/bazel-contrib/publish-to-bcr/.github/workflows/publish.yaml --attestation-path MODULE.bazel.intoto.jsonl MODULE.bazelVerified build using builder"https://github.com/bazel-contrib/publish-to-bcr/.github/workflows/publish.yaml@refs/tags/v0.0.1" at commit 1e1a949147d641428dac19e77f044b782f5941fdVerifying artifact MODULE.bazel: PASSEDPASSED: SLSA verification passedThis is WIP and currently not supported.
To verify a container image, you need to pass a container image name that isimmutable by providing its digest, in order to avoidTOCTOU attacks.
First set the image name:
IMAGE=laurentsimon/slsa-gcb-v0.3:test
Download the provenance:
gcloud artifacts docker images describe$IMAGE --format json --show-provenance> provenance.json
Get the digest for your containerwithout pulling it using thecrane command:
IMAGE="${IMAGE}@"$(crane digest"${IMAGE}")
Verify the image:
slsa-verifier verify-image"$IMAGE" \ --provenance-path provenance.json \ --source-uri github.com/laurentsimon/gcb-tests \ --builder-id=https://cloudbuild.googleapis.com/GoogleHostedWorkerYou should see that the verification passed in the output.
PASSED: Verified SLSA provenanceThe 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 likegithub.com/$OWNER/$REPO when the build was enabled with a Cloud BuildGitHub trigger. Otherwise, the build provenance will contain the name of the Cloud Storage bucket used to host the source files, usually of the formgs://[PROJECT_ID]_cloudbuild/source (seeRunning build). We recommend using GitHub triggers in order to preserve the source provenance and valiate that the source came from an expected, version-controlled repository. Youmay match on the fully-qualified tar likegs://[PROJECT_ID]_cloudbuild/source/1665165360.279777-955d1904741e4bbeb3461080299e929a.tgz.
We have support forverifying VSAs.Rather than passing in filepaths as arguments, we allow passing in mulitple--subject-digest cli options, toaccomodate subjects that are not simple-files.
The verify-vsa command
$ slsa-verifier verify-vsa --helpVerifies SLSA VSAsfor the given subject-digestsUsage: slsa-verifier verify-vsa [flags] subject-digest [subject-digest...]Flags: --attestation-path string path to a file containing the attestation -h, --helphelpfor verify-vsa --print-attestation [optional] print the contents of attestation to stdout --public-key-id string [optional] the ID of the public key, defaults to the SHA256 digest of the base64-encoded public key --public-key-path string path to a public key file --resource-uri string the resource URI to be verified --subject-digest stringArray the digests to be verified. Pass multiple digests by repeating the flag. e.g. --subject-digest<digest type>:<digest value> --subject-digest<digest type>:<digest value> --verified-level stringArray [optional] the levels of verification to be performed. Pass multiple digests by repeating the flag, e.g., --verified-level SLSA_BUILD_LEVEL_2 --verified-level FEDRAMP_LOW' --verifier-id string the unique verifier ID who created the attestation
To verify VSAs, invoke like this
$ slsa-verifier verify-vsa \--subject-digest gce_image_id:8970095005306000053 \--attestation-path ./cli/slsa-verifier/testdata/vsa/gce/v1/gke-gce-pre.bcid-vsa.jsonl \--verifier-id https://bcid.corp.google.com/verifier/bcid_package_enforcer/v0.1 \--resource-uri gce_image://gke-node-images:gke-12615-gke1418000-cos-101-17162-463-29-c-cgpv1-pre \--verified-level BCID_L1 \--verified-level SLSA_BUILD_LEVEL_2 \--public-key-path ./cli/slsa-verifier/testdata/vsa/gce/v1/vsa_signing_public_key.pem \--public-key-id keystore://76574:prod:vsa_signing_public_key \--print-attestation
For multiple subjects, use:
--subject-digest sha256:abc123--subject-digest sha256:xyz456This support does not work yet with VSAs wrapped in Sigstore bundles, only with simple DSSE envelopes.With that, we allow the user to pass in the public key.Note that if the DSSE Envelopesignatures specifies akeyid that is not a unpadded base64 encoded sha256 hash the key, likesha256:abc123... (not a well-known identifier, e.g,my-kms:prod-vsa-key), then you must supply the--public-key-id cli option.
According to slsa.dev'sVSA schema, we only support the Subject'sName andDigest, not the full in_totoStatement'sResourceDescriptor.
This will occur only when verifying provenance generated with GitHub Actions.
Affected versions: v1.3.0-v1.3.1, v1.2.0-v1.2.1, v1.1.0-v1.1.2, v1.0.0-v1.0.4
slsa-verifier will fail with the following error:
FAILED: SLSA verification failed: could not find a matching valid signature entry: got unexpected errors unable to initialize client, local cache may be corrupt: tuf: invalid key: unable to fetch Rekor public keys from TUF repositoryThis issue is tracked byissue #325. Youmust update to the newest patch versions of each minor release to fix this issue.
This will occur only when verifying provenance against workflow inputs.
Affected versions: v2.0.0
slsa-verifier will fail with the following error:
panic: assignment to entry in nil mapThis is fixed byPR #379. Youmust update to the newest patch versions of each minor release to fix this issue.
Find our blog post serieshere.
For a more in-depth technical dive, read theSPECIFICATIONS.md.
As explained onWikipedia, a "time-of-check to time-of-use (TOCTOU) is a class of software bugs caused by a race condition involving the checking of the state of a part of a system and the use of the results of that check".
In the context of provenance verification, imagine you verify a container refered to via amutable imageimage:tag. The verification succeeds and verifies the corresponding hash issha256:abcdef.... After verification, you pull and run the image usingdocker run image:tag. An attacker could have altered the image between the verification step and the run step. To mitigate this attack, we ask users to always pass animmutable reference to the artifact they verify.
About
Verify provenance from SLSA compliant builders
Resources
License
Security policy
Uh oh!
There was an error while loading.Please reload this page.
Stars
Watchers
Forks
Packages0
Uh oh!
There was an error while loading.Please reload this page.