github.com/yogeshkumararora/slsa-github-generator@v1.10.1-0.20240520161934-11278bd5afb4/README.md (about) 1 # SLSA GitHub Generator 2 3 [![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/yogeshkumararora/slsa-github-generator/badge)](https://api.securityscorecards.dev/projects/github.com/yogeshkumararora/slsa-github-generator) 4 [![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/6503/badge)](https://bestpractices.coreinfrastructure.org/projects/6503) 5 [![Go Report Card](https://goreportcard.com/badge/github.com/yogeshkumararora/slsa-github-generator)](https://goreportcard.com/report/github.com/yogeshkumararora/slsa-github-generator) 6 [![Slack](https://img.shields.io/static/v1?label=openssf.slack.com&message=%23slsa-tooling&color=4A154B&logo=slack)](https://slack.openssf.org/) 7 [![SLSA 3](https://slsa.dev/images/gh-badge-level3.svg)](https://slsa.dev) 8 9 <img align="right" src="https://slsa.dev/images/logo-mono.svg" width="140" height="140"> 10 11 <!-- markdown-toc --bullets="-" -i README.md --> 12 13 <!-- toc --> 14 15 - [Overview](#overview) 16 - [What is SLSA?](#what-is-slsa) 17 - [What is provenance?](#what-is-provenance) 18 - [What is slsa-github-generator?](#what-is-slsa-github-generator) 19 - [Hall of Fame](#hall-of-fame) 20 - [Generation of Provenance](#generation-of-provenance) 21 - [Builder Creation](#builder-creation) 22 - [Generate provenance](#generate-provenance) 23 - [Referencing SLSA builders and generators](#referencing-slsa-builders-and-generators) 24 - [Builders](#builders) 25 - [Generators](#generators) 26 - [Verify provenance](#verify-provenance) 27 - [Installation](#installation) 28 - [Inputs](#inputs) 29 - [Command line examples](#command-line-examples) 30 - [Known Issues](#known-issues) 31 - [error updating to TUF remote mirror: invalid](#error-updating-to-tuf-remote-mirror-invalid) 32 - [Build Your Own Builder](#build-your-own-builder) 33 - [Project Roadmap](#project-roadmap) 34 - [Technical design](#technical-design) 35 - [Specifications](#specifications) 36 - [Provenance format](#provenance-format) 37 - [Contributing](#contributing) 38 39 <!-- tocstop --> 40 41 ## Overview 42 43 This repository contains free tools to generate and verify SLSA Build Level 3 provenance for native GitHub projects using GitHub Actions. 44 Developers can build their software using a secure process that protects against many supply chain attacks and tampering. 45 Users of their software can verify a tamper-proof statement of the process to know how the software was created. 46 47 ### What is SLSA? 48 49 [Supply-chain Levels for Software Artifacts](https://slsa.dev), or SLSA (salsa), 50 is a security framework, a checklist of standards and controls to prevent 51 tampering, improve integrity, and secure packages and infrastructure in your 52 projects, businesses or enterprises. 53 54 SLSA defines an incrementally adoptable set of levels which are defined in 55 terms of increasing compliance and assurance. SLSA levels are like a common 56 language to talk about how secure software, supply chains and their component 57 parts really are. 58 59 ### What is provenance? 60 61 Provenance is information, or metadata, about how a software artifact was 62 created. This could include information about what source code, build system, 63 and build steps were used, as well as who and why the build was initiated. 64 Provenance can be used to determine the authenticity and trustworthiness of 65 software artifacts that you use. 66 67 As part of the framework, SLSA defines a 68 [provenance format](https://slsa.dev/provenance/) which can be used to hold this 69 metadata. 70 71 ### What is slsa-github-generator? 72 73 slsa-github-generator is a set of tools for generation of SLSA3+ provenance for 74 native GitHub projects. It allows projects to generate 75 [SLSA provenance](https://slsa.dev/provenance/) safely and accurately using 76 [GitHub Actions](https://github.com/features/actions). 77 78 Specifically, this repository contains: 79 80 - tools for generating non-forgeable SLSA provenance on GitHub for your 81 projects. The generated provenance meets the 82 [provenance generation](https://slsa.dev/spec/v1.0/requirements#provenance-generation) and 83 [isolation](https://slsa.dev/spec/v1.0/requirements#isolation-strength) 84 requirements for 85 [SLSA Build level 3 and above](https://slsa.dev/spec/v1.0/levels). See some 86 [popular projects](#hall-of-fame) generating provenance using this project. 87 - tools for building a SLSA builder on GitHub using the 88 [Build-Your-Own-Builder](#build-your-own-builder) framework. With this 89 framework, you can "wrap" an existing GitHub Action into a SLSA builder. The 90 SLSA builder will generate non-forgeable provenance meeting the 91 [provenance generation](https://slsa.dev/spec/v1.0/requirements#provenance-generation) and 92 [isolation](https://slsa.dev/spec/v1.0/requirements#isolation-strength) 93 requirements for 94 [SLSA Build level 3 and above](https://slsa.dev/spec/v1.0/levels). See some 95 [builders](#builder-creation) created using the BYOB framework. 96 97 While slsa-github-generator can help you achieve SLSA Build level 3, use of the provided 98 [GitHub Actions reusable workflows](https://docs.github.com/en/actions/using-workflows/reusing-workflows) 99 alone is not sufficient to meet all of the requirements at SLSA Build level 3. 100 Specifically, these workflows do not address provenance 101 [distribution](https://slsa.dev/spec/v1.0/distributing-provenance) or 102 [verification](https://slsa.dev/spec/v1.0/verifying-artifacts). 103 You can use the [slsa-verifier](#verify-provenance) to verify the provenance. 104 105 ### Hall of Fame 106 107 #### Generation of Provenance 108 109 Below is a non-exhaustive list of projects that use the builders in this repository to generate provenance: 110 111 [![flask stars](https://img.shields.io/github/stars/pallets/flask?logo=github&label=pallets/flask)](https://github.com/pallets/flask) 112 [![flatbuffers stars](https://img.shields.io/github/stars/google/flatbuffers?logo=github&label=google/flatbuffers)](https://github.com/google/flatbuffers) 113 [![grpc-gateway stars](https://img.shields.io/github/stars/grpc-ecosystem/grpc-gateway?logo=github&label=grpc-ecosystem/grpc-gateway)](https://github.com/grpc-ecosystem/grpc-gateway) [![argo-cd stars](https://img.shields.io/github/stars/argoproj/argo-cd?logo=github&label=argoproj/argo-cd)](https://github.com/argoproj/argo-cd) 114 [![click stars](https://img.shields.io/github/stars/pallets/click?logo=github&label=pallets/click)](https://github.com/pallets/click) 115 [![SOPS stars](https://img.shields.io/github/stars/getsops/sops?logo=github&label=getsops/sops)](https://github.com/getsops/sops) 116 [![jib stars](https://img.shields.io/github/stars/GoogleContainerTools/jib?logo=github&label=GoogleContainerTools/jib)](https://github.com/GoogleContainerTools/jib) 117 [![jinja stars](https://img.shields.io/github/stars/pallets/jinja?logo=github&label=pallets/jinja)](https://github.com/pallets/jinja) 118 [![docker-bench-security stars](https://img.shields.io/github/stars/docker/docker-bench-security?logo=github&label=docker/docker-bench-security)](https://github.com/docker/docker-bench-security) 119 [![sentencepiece stars](https://img.shields.io/github/stars/google/sentencepiece?logo=github&label=google/sentencepiece)](https://github.com/google/sentencepiece) 120 [![werkzeug stars](https://img.shields.io/github/stars/pallets/werkzeug?logo=github&label=pallets/werkzeug)](https://github.com/pallets/werkzeug) 121 [![ko stars](https://img.shields.io/github/stars/ko-build/ko?logo=github&label=ko-build/ko)](https://github.com/ko-build/ko) 122 [![micronaut-core stars](https://img.shields.io/github/stars/micronaut-projects/micronaut-core?logo=github&label=micronaut-projects/micronaut-core)](https://github.com/micronaut-projects/micronaut-core) 123 [![kubeedge stars](https://img.shields.io/github/stars/kubeedge/kubeedge?logo=github&label=kubeedge/kubeedge)](https://github.com/kubeedge/kubeedge) 124 [![osv-scanner stars](https://img.shields.io/github/stars/google/osv-scanner?logo=github&label=google/osv-scanner)](https://github.com/google/osv-scanner) 125 [![flux2 stars](https://img.shields.io/github/stars/fluxcd/flux2?logo=github&label=fluxcd/flux2)](https://github.com/fluxcd/flux2) 126 [![kyverno stars](https://img.shields.io/github/stars/kyverno/kyverno?logo=github&label=kyverno/kyverno)](https://github.com/kyverno/kyverno) 127 [![flask-sqlalchemy stars](https://img.shields.io/github/stars/pallets-eco/flask-sqlalchemy?logo=github&label=pallets-eco/flask-sqlalchemy)](https://github.com/pallets-eco/flask-sqlalchemy) 128 [![scorecard stars](https://img.shields.io/github/stars/ossf/scorecard?logo=github&label=ossf/scorecard)](https://github.com/ossf/scorecard) 129 [![urllib3 stars](https://img.shields.io/github/stars/urllib3/urllib3?logo=github&label=urllib3/urllib3)](https://github.com/urllib3/urllib3) 130 [![pdns stars](https://img.shields.io/github/stars/PowerDNS/pdns?logo=github&label=PowerDNS/pdns)](https://github.com/PowerDNS/pdns) 131 [![powertools-lambda-python stars](https://img.shields.io/github/stars/aws-powertools/powertools-lambda-python?logo=github&label=aws-powertools/powertools-lambda-python)](https://github.com/aws-powertools/powertools-lambda-python) 132 [![hishtory stars](https://img.shields.io/github/stars/ddworken/hishtory?logo=github&label=ddworken/hishtory)](https://github.com/ddworken/hishtory) 133 [![PrivateBin stars](https://img.shields.io/github/stars/PrivateBin/PrivateBin?logo=github&label=PrivateBin/PrivateBin)](https://github.com/PrivateBin/PrivateBin) 134 [![NoPorts stars](https://img.shields.io/github/stars/atsign-foundation/noports?logo=github&label=Atsign-Foundation/NoPorts)](https://github.com/atsign-foundation/noports) 135 [![openfga stars](https://img.shields.io/github/stars/openfga/openfga?logo=github&label=openfga/openfga)](https://github.com/openfga/openfga) 136 137 [Edit this file](https://github.com/yogeshkumararora/slsa-github-generator/edit/main/README.md) to add your repository! 138 139 #### Builder Creation 140 141 Several builders have been built using the ["Build Your Own Builder" (BYOB) framework](#build-your-own-builder): 142 143 1. [nodejs builder](https://github.com/yogeshkumararora/slsa-github-generator/tree/main/internal/builders/nodejs#readme), by [@ianlewis](https://github.com/ianlewis) 144 2. [JReleaser builder](https://github.com/jreleaser/release-action/tree/java#slsa-builder), by [@aalmiray](https://github.com/aalmiray) 145 3. [Maven builder](https://github.com/yogeshkumararora/slsa-github-generator/blob/main/internal/builders/maven/README.md), by [@AdamKorcz](https://github.com/AdamKorcz) 146 4. [Gradle builder](https://github.com/yogeshkumararora/slsa-github-generator/tree/main/internal/builders/gradle/README.md), by [@AdamKorcz](https://github.com/AdamKorcz) 147 5. **Coming soon!** [Bazel builder](https://github.com/yogeshkumararora/slsa-github-generator/tree/main/internal/builders/bazel/README.md), by [@enteraga6](https://github.com/enteraga6) 148 149 ## Generate provenance 150 151 Below we describe the various [builders](#builders) and [generators](#generators) in this repository. They build and / or generate non-forgeable provenance 152 using a trusted / isolated re-usable workflow. You can read up on the design in our [technical design document](#technical-design). 153 154 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](#builders) for your ecosystem. 155 For example, if you use Go, use the [Go builder](internal/builders/go/README.md). If you use Java and build Maven packages, use the [Maven builder](internal/builders/maven/README.md), and so on. 156 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](#generators) instead. 157 158 ### Referencing SLSA builders and generators 159 160 At present, the GitHub Actions provided in this repository as builders and generators **MUST** be referenced 161 by tag in order for the `slsa-verifier` to be able to verify the ref of the trusted builder/generator's 162 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`. 163 164 This is contrary to the [GitHub best practice for third-party actions](https://docs.github.com/en/actions/security-guides/security-hardening-for-github-actions#using-third-party-actions) which recommends referencing by digest, but intentional due to limits in GitHub Actions. 165 The desire to be able to verify reusable workflows pinned by hash, and the reasons for the current status, are tracked as [Issue #12](https://github.com/slsa-framework/slsa-verifier/issues/12) in the slsa-verifier project. 166 167 For guidance on how to configure renovate see [RENOVATE.md](RENOVATE.md). 168 169 ### Builders 170 171 Builders build and generate provenance. They let you meet the 172 [provenance generation](https://slsa.dev/spec/v1.0/requirements#provenance-generation) and 173 [isolation strength](https://slsa.dev/spec/v1.0/requirements#isolation-strength) 174 requirements for [SLSA Build level 3 and above](https://slsa.dev/spec/v1.0/levels). 175 176 This repository hosts the following builders: 177 178 | Ecosystem | Builder | Description | Status | 179 | :------------------------------------------ | :------------------------------------------------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | 180 | [Go](https://go.dev/) projects | [Go Builder](internal/builders/go/README.md) | Builds and generates provenance for Go projects | [available since v1.0.0](https://github.com/yogeshkumararora/slsa-github-generator/milestone/1) | 181 | [Node.js](https://nodejs.org) projects | [Node.js Builder](internal/builders/nodejs/README.md) | Builds and generates provenance for npm packages | [Beta since v1.6.0](https://github.com/yogeshkumararora/slsa-github-generator/milestone/8). [Expected GA release Sept 2023](https://github.com/yogeshkumararora/slsa-github-generator/milestone/17) | 182 | [Maven](https://maven.apache.org/) projects | [Maven builder](internal/builders/maven/README.md) | Build Maven packages and generates provenance. Can be uploaded to [Maven central](https://search.maven.org) | [Beta since v1.9.0](https://github.com/yogeshkumararora/slsa-github-generator/milestone/14) | 183 | [Gradle](https://gradle.org/) projects | [Gradle builder](internal/builders/gradle/README.md) | Build Gradle projects and generates provenance. Can be uploaded to [Maven central](https://search.maven.org) | [Beta since v1.9.0](https://github.com/yogeshkumararora/slsa-github-generator/milestone/15) | 184 | [Bazel](https://bazel.build/) projects | [Bazel builder](internal/builders/bazel/README.md) | Builds [Bazel](https://bazel.build/) projects and generates provenance | [WIP](https://github.com/yogeshkumararora/slsa-github-generator/milestone/16) | 185 | [docker](https://www.docker.com/) images | Container Builder | Builds docker containers and generates provenance. The generated provenance is compatible with [cosign](https://github.com/sigstore/cosign)'s attestation format | [WIP](https://github.com/yogeshkumararora/slsa-github-generator/milestone/5) | 186 | Any | [Container-based Builder](internal/builders/docker/README.md) | Builds projects whose build pipeline is defined with a Dockerfile | [Beta since v1.7.0](https://github.com/yogeshkumararora/slsa-github-generator/milestone/16) | 187 188 There are other available builders using this repository's [BYOB framework](#build-your-own-builder) and not hosted in this repository: 189 190 | Ecosystem | Builder | Description | Status | 191 | :------------------------------------------- | :-------------------------------------------------------------------------------------- | :------------------------------------------------------------------------ | :-------------------------------------------------------------------------------- | 192 | [JReleaser](https://jreleaser.org/) projects | [JReleaser builder](https://github.com/jreleaser/release-action/tree/java#slsa-builder) | Builds and generates provenance using [JReleaser](https://jreleaser.org/) | [since v1.0.0-java](https://github.com/jreleaser/release-action/tree/v1.0.0-java) | 193 194 If none of these options fit your needs, use a [generator](#generators) as described below: 195 196 ### Generators 197 198 Generators only generate provenance for you. They let you meet the 199 [provenance generation](https://slsa.dev/spec/v1.0/requirements#provenance-generation) and 200 [isolation strength](https://slsa.dev/spec/v1.0/requirements#isolation-strength) 201 requirements for [SLSA Build level 3 and above](https://slsa.dev/spec/v1.0/levels). 202 203 Generators create an attestation to a software artifact coming from your repository. 204 205 This repository hosts the following generators: 206 207 | Artifact type | Generator | Description | Status | 208 | :---------------------------------- | :----------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------- | 209 | file (binary, package tarball etc.) | [Generic generator](internal/builders/generic/README.md) | Generates provenance for arbitrary file-based artifacts, for any ecosystem and programming language | [available since v1.2.0](https://github.com/yogeshkumararora/slsa-github-generator/milestone/2) | 210 | container | [Container generator](internal/builders/container/README.md) | Generate provenance for container images. The generated provenance is compatible with [cosign](https://github.com/sigstore/cosign)'s attestation format. | [available since v1.4.0](https://github.com/yogeshkumararora/slsa-github-generator/milestone/3) | 211 212 ## Verify provenance 213 214 To verify provenance created by any of the builders in this repository, use the [github.com/slsa-framework/slsa-verifier](https://github.com/slsa-framework/slsa-verifier) project. 215 216 ### Installation 217 218 To install the verifier, see [slsa-framework/slsa-verifier#installation](https://github.com/slsa-framework/slsa-verifier#installation). 219 220 ### Inputs 221 222 The inputs of the verifier are described in [slsa-framework/slsa-verifier#available-options](https://github.com/slsa-framework/slsa-verifier#available-options). 223 224 ### Command line examples 225 226 A command line example is provided in [slsa-framework/slsa-verifier#example](https://github.com/slsa-framework/slsa-verifier#example). 227 228 ## Known Issues 229 230 ### error updating to TUF remote mirror: invalid 231 232 This will occur when generating provenance with all builders and generators. 233 234 **Affected versions:** all versions up and including v1.9.0 235 236 ```shell 237 error updating to TUF remote mirror: invalid 238 ``` 239 240 This issue is tracked by [issue #3350](https://github.com/yogeshkumararora/slsa-github-generator/issues/3350). You _must_ update to v1.10.0 to fix this issue. 241 242 ## Build Your Own Builder 243 244 Use the [BYOB framework](BYOB.md) 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. 245 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. 246 To verify the provenance, your users can use the [slsa-verifier](#verification-of-provenance). 247 248 ## Project Roadmap 249 250 The project roadmap is tracked via milestones. You can track progress and open 251 issues via the [milestones page](https://github.com/yogeshkumararora/slsa-github-generator/milestones?direction=asc&sort=due_date&state=open). 252 Each milestone includes a description of what is being worked on and a rough 253 timeline for completion. 254 255 ## Technical design 256 257 The initial technical design was described in the blog post 258 "[Improving software supply chain security with tamper-proof builds](https://security.googleblog.com/2022/04/improving-software-supply-chain.html)". 259 260 ### Specifications 261 262 For a more in-depth technical dive, read the [SPECIFICATIONS.md](./SPECIFICATIONS.md). 263 264 ### Provenance format 265 266 The format of the provenance is available in [PROVENANCE_FORMAT.md](./PROVENANCE_FORMAT.md). 267 268 ## Contributing 269 270 Please see the [Contributor Guide](CONTRIBUTING.md) for more info.