Generation of SLSA3+ provenance for native GitHub projects
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.
- Generation of provenance
- Verification of provenance
- Technical design
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 or if you reference it by a tag of a different form (e.g.,
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.
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.
To install the verifier, see slsa-framework/slsa-verifier#installation.
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.
Find our blog post series here.
For a more in-depth technical dive, read the SPECIFICATIONS.md.
The format of the provenance is available in PROVENANCE_FORMAT.md.
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
You can run unit tests locally using
make. This requires that the Go runtime be installed.
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.
- 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
These linters will also run as GitHub checks for pull requests.