- Overview
- Roadmap
- Generation of provenance
- Verification of provenance
- Build Your Own Builder
- Technical design
- Contributing
Supply chain Levels for Software Artifacts, or SLSA (salsa), is a security framework, a check-list of standards and controls to prevent tampering, improve integrity, and secure packages and infrastructure in your projects, businesses or enterprises.
SLSA defines an incrementally adoptable set of levels which are defined in terms of increasing compliance and assurance. SLSA levels are like a common language to talk about how secure software, supply chains and their component parts really are.
Provenance is information, or metadata, about how a software artifact was created. 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 of software artifacts that you use.
As part of the framework, SLSA defines a provenance format which can be used to hold this metadata.
slsa-github-generator is a set of tools for generation of SLSA3+ provenance for native GitHub projects. It allows projects to generate SLSA provenance safely and accurately using GitHub Actions.
Specifically, this repository contains:
- tools for generating non-forgeable SLSA provenance on GitHub for your projects. The generated provenance meets the provenance generation and isolation requirements for SLSA Build level 3 and above. See some popular projects generating provenance using this project.
- tools for building a SLSA builder on GitHub using the Build-Your-Own-Builder framework. With this framework, you can "wrap" an existing GitHub Action into a SLSA builder. The SLSA builder will generate non-forgeable provenance meeting the provenance generation and isolation requirements for SLSA Build level 3 and above. See some builders created using the BYOB framework.
While slsa-github-generator can help you achieve SLSA Build level 3, use of the provided GitHub Actions reusable workflows only is not sufficient to meet all of the requirements at SLSA Build level 3. Specifically, these workflows do not address provenance distribution or verification. Those requirements must be handled separately to meet SLSA Build level 3+.
Below is a non-exhaustive list of projects that use the builders in this repository to generate provenance:
Several builders have been built using the "Build Your Own Builder" (BYOB):
- nodejs builder, by @ianlewis
- JReleaser builder, by @aalmiray
- Maven builder, by @AdamKorcz
- Gradle builder, by @AdamKorcz
- Coming soon! Bazel builder, by @enteraga6
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.
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.
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. It also needs to be referred as @vX.Y.Z, because the build will fail if you reference it via a shorter tag like @vX.Y or @vX.
This is contrary to the GitHub best practice for third-party actions 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.
For guidance on how to configure renovate see RENOVATE.md.
Build platforms build and generate provenance. They let you meet the provenance generation and isolation strength requirements for SLSA Build level 3 and above.
This repository hosts the following builders:
- Go Builder. Status: available since v1.0.0. This builder builds and generates provenance for your Go projects.
- Node.js Builder. Status: Beta since v1.6.0. Expected GA release Sept 2023.
- Container-based Builder. Status: Beta release since v1.7.0. This builder builds arbitrary artifacts by executing a user-supplied container image.
- Maven builder. Status: Beta since v1.8.0. This builder builds Maven packages. The package and its attestations can be uploaded to Maven central.
- Gradle builder. Status: Beta since v1.8.0. This builder builds Gradle projects. The Maven package and its attestations can be uploaded to Maven central.
- Bazel builder. Status: WIP. Expected beta-release Sept 2023. This builder builds Bazel projects.
- Container Builder. Status: WIP. This builder builds your container image and generate provenance. The generated provenance is compatible with cosign's attestation format.
There are other available builders using this repository's BYOB framework and not hosted in this repository:
- JReleaser builder. Lets you build and generate provenance using JReleaser.
If you would rather build your project yourself, use the generators instead as explained in the next section.
Provenance-only generators let you build your artifact, and only generate provenance for you. They let you meet the provenance generation requirements for SLSA Build 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: available since v1.4.0. This generator will generate provenance for container images. The generated provenance will be compatible with cosign's attestation format.
To verify the provenance, use the github.com/slsa-framework/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.
A command line example is provided in slsa-framework/slsa-verifier#example.
If you want to build your own builder, use the BYOB framework. The framework lets you create your own SLSA3 builder on GitHub. For example, you can wrap an existing GitHub Action into a SLSA3 builder. For verification, your users can use the slsa-verifier.
The initial technical design was described in the blog post "Improving software supply chain security with tamper-proof builds".
For a more in-depth technical dive, read the SPECIFICATIONS.md.
The format of the provenance is available in PROVENANCE_FORMAT.md.
Please see the Contributor Guide for more info.