/slsa-github-generator

Language-agnostic SLSA provenance generation for Github Actions

Primary LanguageGoApache License 2.0Apache-2.0

SLSA GitHub Generator

OpenSSF Scorecard CII Best Practices Go Report Card Slack SLSA 3

Overview

This repository contains free tools to generate and verify SLSA Build Level 3 provenance for native GitHub projects using GitHub Actions. Developers can build their software using a secure process that protects against many supply chain attacks and tampering. Users of their software can verify a tamper-proof statement of the process to know how the software was created.

What is SLSA?

Supply-chain Levels for Software Artifacts, or SLSA (salsa), is a security framework, a checklist 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.

What is provenance?

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.

What is slsa-github-generator?

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:

While slsa-github-generator can help you achieve SLSA Build level 3, use of the provided GitHub Actions reusable workflows alone is not sufficient to meet all of the requirements at SLSA Build level 3. Specifically, these workflows do not address provenance distribution or verification. You can use the slsa-verifier to verify the provenance.

Hall of Fame

Generation of Provenance

Below is a non-exhaustive list of projects that use the builders in this repository to generate provenance:

flask stars flatbuffers stars grpc-gateway stars argo-cd stars click stars SOPS stars jib stars jinja stars docker-bench-security stars sentencepiece stars werkzeug stars ko stars micronaut-core stars kubeedge stars osv-scanner stars flux2 stars kyverno stars flask-sqlalchemy stars scorecard stars urllib3 stars pdns stars powertools-lambda-python stars hishtory stars PrivateBin stars

Edit this file to add your repository!

Builder Creation

Several builders have been built using the "Build Your Own Builder" (BYOB) framework:

  1. nodejs builder, by @ianlewis
  2. JReleaser builder, by @aalmiray
  3. Maven builder, by @AdamKorcz
  4. Gradle builder, by @AdamKorcz
  5. Coming soon! Bazel builder, by @enteraga6

Generate provenance

Below we describe the various builders and generators in this repository. They 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.

To select the right option to generate provenance for your use case, take into account the programming language and build toolchain you already use, e.g. go, mvn, bazel, etc. Select a builder for your ecosystem. For example, if you use Go, use the Go builder. If you use Java and build Maven packages, use the Maven builder, and so on. If your release scripts are more complex than what the builder supports; or if there is no builder for your ecosystem, use a provenance generator instead.

Referencing SLSA builders and generators

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.

Builders

Builders 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:

Ecosystem Builder Description Status
Go projects Go Builder Builds and generates provenance for Go projects available since v1.0.0
Node.js projects Node.js Builder Builds and generates provenance for npm packages Beta since v1.6.0. Expected GA release Sept 2023
Maven projects Maven builder Build Maven packages and generates provenance. Can be uploaded to Maven central Beta since v1.9.0
Gradle projects Gradle builder Build Gradle projects and generates provenance. Can be uploaded to Maven central Beta since v1.9.0
Bazel projects Bazel builder Builds Bazel projects and generates provenance WIP
docker images Container Builder Builds docker containers and generates provenance. The generated provenance is compatible with cosign's attestation format WIP
Any Container-based Builder Builds projects whose build pipeline is defined with a Dockerfile Beta since v1.7.0

There are other available builders using this repository's BYOB framework and not hosted in this repository:

Ecosystem Builder Description Status
JReleaser projects JReleaser builder Builds and generates provenance using JReleaser since v1.0.0-java

If none of these options fit your needs, use a generator as described below:

Generators

Generators only generate provenance for you. They let you meet the provenance generation and isolation strength requirements for SLSA Build level 3 and above.

Generators create an attestation to a software artifact coming from your repository.

This repository hosts the following generators:

Artifact type Generator Description Status
file (binary, package tarball etc.) Generic generator Generates provenance for arbitrary file-based artifacts, for any ecosystem and programming language available since v1.2.0
container Container generator Generate provenance for container images. The generated provenance is compatible with cosign's attestation format. available since v1.4.0

Verify provenance

To verify provenance created by any of the builders in this repository, use the github.com/slsa-framework/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.

Known Issues

error updating to TUF remote mirror: invalid

This will occur when generating provenance with all builders and generators.

Affected versions: all versions up and including v1.9.0

error updating to TUF remote mirror: invalid

This issue is tracked by issue #3350. You must update to v1.10.0 to fix this issue.

Build Your Own Builder

Use the BYOB framework to create your own SLSA builder on GitHub. If you have an existing GitHub Action, you can use the BYOB framework to wrap it into a SLSA builder. This will harden the build process by running the Action in an isolated environment. Generated artifacts will meet Build Level 3 expectations and produce Build Level 3 provenance. To verify the provenance, your users can use the slsa-verifier.

Project 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.

Technical design

The initial technical design was described in the blog post "Improving software supply chain security with tamper-proof builds".

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.

Contributing

Please see the Contributor Guide for more info.