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.