Generation of SLSA3+ provenance for native GitHub projects
This repository contains tools for generating non-forgeable SLSA provenance on GitHub that meets the build and provenance requirements for SLSA level 3 and above.
Use of the provided GitHub Actions reusable workflows only is not sufficient to meet all of the requirements at SLSA level 3. Specifically, the source requirements are not covered by these workflows and must be handled explicitly to meet all requirements at SLSA level 3+.
This repository contains the code, examples and technical design for system described in the blog post on Non forgeable SLSA provenance using GitHub workflows.
Roadmap
The project roadmap is tracked via milestones. You can track progress and open issues via the milestones page. Each milestone includes a description of what is being worked on and a rough timeline for completion.
Generation of provenance
Below we describe the various builders and generators in this repository. They let you build and / or generate non-forgeable provenance using a trusted / isolated re-usable workflow. You can read up on the design in our technical design document.
Note: At present the GitHub Actions provided in this repository as builders and generators MUST be referenced by a tag that correpsonds to a semantic version of the form @vX.Y.Z
. The build will fail if you reference it via a shorter tag like @vX.Y
or @vX
or if you reference it by a tag of a different form (e.g., @main
).
Builders
Builders build and generate provenance. They let you meet the build and provenance requirements for SLSA Level 3 and above.
Builders are able to report the commands used to generate your artifact in the provenance.
This repository hosts the following builders:
- Go Builder SLSA Level 3. Status: available since v1.0.0. This builder builds and generates provenance for your Go projects. To use it, follow the Go builder's README.md.
- Container Builder SLSA Level 3. Status: WIP, expected release in Sept 2022. This builder will build your container image and generate provenance. The generated provenance will be compatible with cosign's attestation format.
- Dockerfile-based Builder SLSA Level 3. Status: WIP, see #23. This builder will build arbitrary artifacts using building steps defined in a Dockerfile.
If you would rather build your project yourself, use the generators instead as explained in the next section.
Provenance-only generators
Provenance-only generators let you build your artifact, and only generate provenance for you. They let you meet the provenance requirements for SLSA Level 3.
Generators create an attestation to a software artifact coming from your repository.
Generators are not able to report the commands used to generate your artifact in the provenance.
This repository hosts the following generators:
- Generic generator SLSA Level 3. Status: available since v1.2.0. This generator generates provenance for arbitrary artifacts of your choice. To use it, follow the Generic generator's README.md.
- Container generator SLSA Level 3. Status: WIP, expected release Aug-Sept 2022, see #409. This generator will generate provenance for container images. The generated provenance will be compatible with cosign's attestation format.
Verification of provenance
To verify the provenance, use the github.com/slsa-framework/slsa-verifier project.
Note: At present the GitHub Actions provided in this repository as builders and generators MUST be referenced by tag in order for the slsa-verifier
to be able to verify the ref of the trusted builder/generator's reusable workflow.
This is contrary to the best practice which recommends referencing by digest, but intentional due to limits in GitHub Actions. The desire to be able to verify reusable workflows pinned by hash, and the reasons for the current status, are tracked as Issue #12 in the slsa-verifier project.
Installation
To install the verifier, see slsa-framework/slsa-verifier#installation.
Inputs
The inputs of the verifier are described in slsa-framework/slsa-verifier#available-options.
Command line examples
A command line example is provided in slsa-framework/slsa-verifier#example.
Technical design
Blog post
Find our blog post series here.
Specifications
For a more in-depth technical dive, read the SPECIFICATIONS.md.
Provenance format
The format of the provenance is available in PROVENANCE_FORMAT.md.
Development
Since this project includes reusable workflows for use on GitHub Actions local development is limited to building and testing the binaries used by the reusable workflows. The workflows themselves must be tested in your own fork.
Local commands that can be used for development are defined in the Makefile. You can list the available targets by running make
.
make
Unit Tests
You can run unit tests locally using make
. This requires that the Go runtime be installed.
make unit-test
Linters
This project uses several linters in order to maintain code quality. If you wish to run these linters locally, follow the instructions for each of these to install them on your development machine.
- yamllint
- golangci-lint
- shellcheck
- eslint (NOTE: eslint is installed automatically so you don't need to install it)
Once each of these are installed you can run the linters using make
.
make lint
These linters will also run as GitHub checks for pull requests.
[e2e]: generic tag main annotated slsa3
Repo: https://github.com/slsa-framework/example-package/tree/v13.0.101 Run: https://github.com/slsa-framework/example-package/actions/runs/3148082895 Workflow file: https://github.com/slsa-framework/example-package/tree/main/.github/workflows/e2e.generic.tag.main.annotated.slsa3.yml Workflow runs: https://github.com/slsa-framework/example-package/actions/workflows/e2e.generic.tag.main.annotated.slsa3.yml Trigger: push Branch: v13.0.101 Date: Thu Sep 29 01:51:39 UTC 2022
[e2e]: go tag main adversarial-asset-binary slsa3
Repo: https://github.com/slsa-framework/example-package/tree/v12.0.64 Run: https://github.com/slsa-framework/example-package/actions/runs/2661149407 Workflow file: https://github.com/slsa-framework/example-package/tree/main/.github/workflows/e2e.go.tag.main.adversarial-asset-binary.slsa3.yml Workflow runs: https://github.com/slsa-framework/example-package/actions/workflows/e2e.go.tag.main.adversarial-asset-binary.slsa3.yml Trigger: push Branch: v12.0.64 Date: Wed Jul 13 05:17:07 UTC 2022
[e2e]: go tag main adversarial-asset-provenance slsa3
Repo: https://github.com/slsa-framework/example-package/tree/v11.0.62 Run: https://github.com/slsa-framework/example-package/actions/runs/2660889601 Workflow file: https://github.com/slsa-framework/example-package/tree/main/.github/workflows/e2e.go.tag.main.adversarial-asset-provenance.slsa3.yml Workflow runs: https://github.com/slsa-framework/example-package/actions/workflows/e2e.go.tag.main.adversarial-asset-provenance.slsa3.yml Trigger: push Branch: v11.0.62 Date: Wed Jul 13 04:01:37 UTC 2022
[e2e]: go workflow_dispatch main workflow_inputs slsa3
Repo: https://github.com/slsa-framework/example-package/tree/main Run: https://github.com/slsa-framework/example-package/actions/runs/2976473622 Workflow file: https://github.com/slsa-framework/example-package/tree/main/.github/workflows/e2e.go.workflow_dispatch.main.workflow_inputs.slsa3.yml Workflow runs: https://github.com/slsa-framework/example-package/actions/workflows/e2e.go.workflow_dispatch.main.workflow_inputs.slsa3.yml Trigger: workflow_dispatch Branch: main Date: Fri Sep 2 03:44:56 UTC 2022
E2E: go tag main config-ldflags-noassets slsa3
Repo: https://github.com/slsa-framework/example-package/tree/v14.0.44 Run: https://github.com/slsa-framework/example-package/actions/runs/2540306790 Workflow file: https://github.com/slsa-framework/example-package/tree/main/.github/workflows/e2e.go.tag.main.config-ldflags-noassets.slsa3.yml Workflow runs: https://github.com/slsa-framework/example-package/actions/workflows/e2e.go.tag.main.config-ldflags-noassets.slsa3.yml Trigger: push Branch: v14.0.44 Date: Wed Jun 22 06:33:04 UTC 2022
[bug] Creating and signing provenance fails because retrieving signed certificate fails.
Describe the bug
Creating signed provenance fails with
To Reproduce
This happens in a private repository, based on the this job:
Expected behavior
Finish successfully.
Screenshots
Additional context
I’m going to be honest: I’m trying to convince people in my org to integrate SLSA into the CI and build processes, but it’s getting harder when the actions break with different issues every other week.
I just updated to v1.2.1 and hope that’ll work.
Examples on using generic provenance for containers
[e2e]: generic schedule main multi-subjects slsa3
Repo: https://github.com/slsa-framework/example-package/tree/main Run: https://github.com/slsa-framework/example-package/actions/runs/3087641521 Workflow file: https://github.com/slsa-framework/example-package/tree/main/.github/workflows/e2e.generic.schedule.main.multi-subjects.slsa3.yml Workflow runs: https://github.com/slsa-framework/example-package/actions/workflows/e2e.generic.schedule.main.multi-subjects.slsa3.yml Trigger: schedule Branch: main Date: Tue Sep 20 05:36:34 UTC 2022
[e2e]: go schedule main config-ldflags-main slsa3
Repo: https://github.com/slsa-framework/example-package/tree/main Run: https://github.com/slsa-framework/example-package/actions/runs/2575503422 Workflow file: https://github.com/slsa-framework/example-package/tree/main/.github/workflows/e2e.go.schedule.main.config-ldflags-main.slsa3.yml Workflow runs: https://github.com/slsa-framework/example-package/actions/workflows/e2e.go.schedule.main.config-ldflags-main.slsa3.yml Trigger: schedule Branch: main Date: Tue Jun 28 10:31:48 UTC 2022
[bug] ”Generate Builder“ step fails
Describe the bug
It looks like the Generate Builder step fails:
when invoked as a job similar to this public example but in a private repo:
To Reproduce
Restarting the failed job continues to fail. Alas, private repo.
Expected behavior
This has worked before and during today’s run failed.
Screenshots
See above.
Additional context
Github Job only producing one intoto.jsonl file
I have Github build running which is building three docker images, for each docker image I want attestation.intoto.jsonl file but I am only getting one file in Artifacts. Is it due to static name and overriding happening? if so, how can I change the file name since I am not seeing the attestaion-name var in input
How can I produce three intoto.jsonl for three docker images in one build?
[cleanup] [byo] Can the slsa-token be a slsa predicate?
Is your feature request related to a problem? Please describe. This is something I was trying to think about as I was updating https://github.com/slsa-framework/slsa-github-generator/pull/1477
The SLSA token should contain all the inputs needed to execute the tool, and this information should be the information in the signed predicate as well.
I was wondering if this could in effect just be a SLSA predicate. Note that the caller workflow would be signing the predicate in the
setup-token
action, and after the SRW verifies it, the SRW would then use this, augment with the additional context (from the reusable workflow) to sign in the output provenance.Right now, the predicate I have in https://github.com/slsa-framework/slsa-github-generator/pull/1477 doesn't include the build action path or the builder info (private_repository, runner, audience) though. But that is trivial to add in buildconfig.
The reason for this is just simplifying the format for the SLSA token.
@laurentsimon
Use custom WrappableError types in the docker builder
See the
WrappableError
type https://github.com/slsa-framework/slsa-github-generator/blob/1ed3657976aadcbd9fe3aaf2117d315e0a934e97/internal/errors/wrappable.gosome examples where it's used https://github.com/slsa-framework/slsa-github-generator/blob/1ed3657976aadcbd9fe3aaf2117d315e0a934e97/internal/builders/generic/generic.go#L59-L82
and some tests where it's checked https://github.com/slsa-framework/slsa-github-generator/blob/1ed3657976aadcbd9fe3aaf2117d315e0a934e97/internal/builders/generic/attest_test.go#L26
Originally posted by @ianlewis in https://github.com/slsa-framework/slsa-github-generator/pull/1388#discussion_r1063417838
feat: output slsa predicate based on verifier token [DO NOT REVIEW YET]
Signed-off-by: Asra Ali [email protected]
As a test, I've run in slsa-delegator and produced the following provenance
[feature] support creating a draft release
The Go builder and generic generator use
softprops/action-gh-release
to create releases. We should support setting thedraft
flag so that users can create draft releases.