forked from slsa-framework/slsa-verifier
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
✨ Transfer docs from go repo (slsa-framework#111)
* Add specs/readme from original repo * updates * updates * updates * updates * updates * updates
- Loading branch information
1 parent
b18a9ec
commit 76ce8e1
Showing
4 changed files
with
721 additions
and
149 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,163 +1,32 @@ | ||
| # slsa-github-generator | ||
| # Generation of SLSA3+ provenance for native GitHub projects | ||
|
|
||
| This repository contains a reference implementation for generating non-forgeable | ||
| [SLSA provenance](https://slsa.dev/) that meets the requirements for the [SLSA | ||
| level 2 and above](https://slsa.dev/spec/v0.1/levels) using a [Github Actions | ||
| reusable | ||
| workflow](https://docs.github.com/en/actions/using-workflows/reusing-workflows). | ||
| This repository contains the implementation for generating non-forgeable [SLSA provenance](https://slsa.dev/) that meets the requirement for the [SLSA level 3 and above](https://slsa.dev/spec/v0.1/levels). The SLSA generation makes use of a [Github Actions reusable workflow](https://docs.github.com/en/actions/using-workflows/reusing-workflows). | ||
|
|
||
| --- | ||
|
|
||
| - [Project Status](#project-status) | ||
| - [Generating Provenance](#generating-provenance) | ||
| - [Getting Started](#getting-started) | ||
| - [Workflow Inputs](#workflow-inputs) | ||
| - [Workflow Outputs](#workflow-outputs) | ||
| - [Provenance Format](#provenance-format) | ||
| - [Provenance Example](#provenance-example) | ||
| This repository contains the code, examples and technical design for the blog post on [Non forgeable SLSA provenance using GitHub workflows](https://security.googleblog.com/2022/04/improving-software-supply-chain.html). | ||
|
|
||
| --- | ||
|
|
||
| ## Project Status | ||
|
|
||
| This project is currently under active development. The API could change while | ||
| approaching an initial release. | ||
|
|
||
| ## Generating Provenance | ||
|
|
||
| `slsa-github-generator` uses a Github Actions reusable workflow to generate the | ||
| provenance. | ||
|
|
||
| ### Getting Started | ||
|
|
||
| To get started, you will need to add some steps to your current workflow. We | ||
| will assume you have an existing Github Actions workflow to build your project. | ||
|
|
||
| Add a step to your workflow after you have built your project to generate a | ||
| sha256 hash of your artifacts. The following assumes you have a binary called | ||
| `binary-linux-amd64`. | ||
|
|
||
| After that, add a new job to call the `slsa-github-generator` reusable workflow. | ||
|
|
||
| ```yaml | ||
| jobs: | ||
| build: | ||
| outputs: | ||
| digest: ${{ steps.hash.outputs.digest }} | ||
| runs-on: ubuntu-latest | ||
| steps: | ||
| # Your build steps are here. | ||
| - name: "generate hash" | ||
| shell: bash | ||
| id: hash | ||
| run: | | ||
| set -euo pipefail | ||
| DIGEST=$(sha256sum binary-linux-amd64) | ||
| DIGEST="${DIGEST//'%'/'%25'}" | ||
| DIGEST="${DIGEST//$'\n'/'%0A'}" | ||
| DIGEST="${DIGEST//$'\r'/'%0D'}" | ||
| echo "::set-output name=digest::$DIGEST" | ||
| provenance: | ||
| needs: [build] | ||
| permissions: | ||
| id-token: write | ||
| contents: read | ||
| uses: slsa-framework/slsa-github-generator/.github/workflows/slsa2_provenance.yml@main | ||
| with: | ||
| subjects: "${{ needs.build.outputs.digest }}" | ||
| ``` | ||
| ### Workflow Inputs | ||
| The builder workflow | ||
| [.github/workflows/slsa2_provenance.yml](.github/workflows/slsa2_provenance.yml) accepts | ||
| the following inputs: | ||
| | Name | Required | Description | | ||
| | ---------- | -------- | -------------------------------------------------------------------------------------------------------------- | | ||
| | `subjects` | yes | Artifacts for which to generate provenance, formatted the same as the output of sha256sum (SHA256 NAME\n[...]) | | ||
| - [Golang projects](#golang-projects) | ||
| - [Other projects](#other-projects) | ||
| - [Technical design](#technical-design) | ||
| - [Blog post](#blog-post) | ||
| - [Specifications](#specifications) | ||
| --- | ||
|
|
||
| ### Workflow Outputs | ||
| ## Golang projects | ||
|
|
||
| The builder workflow | ||
| [.github/workflows/slsa2_provenance.yml](.github/workflows/slsa2_provenance.yml) | ||
| produces the following outputs: | ||
| To generate SLSA provenance for your Golang project, follow [builders/go/README.md](builders/go/README.md) | ||
|
|
||
| | Name | Description | | ||
| | ------------------ | ------------------------------------------ | | ||
| | `attestation-name` | The artifact name of the signed provenance | | ||
| ## Other projects | ||
|
|
||
| ### Provenance Format | ||
| To generate SLSA provenance for other programming languages, follow [builders/generic/README.md](builders/generic/README.md) | ||
|
|
||
| The project generates SLSA provenance with the following values. | ||
| ## Technical design | ||
|
|
||
| | Name | Value | Description | | ||
| | ---------------------------- | -------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ||
| | `buildType` | `"https://github.com/slsa-framework/slsa-github-generator@v1"` | Identifies a generic GitHub Actions build. | | ||
| | `metadata.buildInvocationID` | `"[run_id]-[run_attempt]"` | The GitHub Actions [`run_id`](https://docs.github.com/en/actions/learn-github-actions/contexts#github-context) does not update when a workflow is re-run. Run attempt is added to make the build invocation ID unique. | | ||
| ### Blog post | ||
|
|
||
| ### Provenance Example | ||
| Find our blog post series [here](https://security.googleblog.com/2022/04/improving-software-supply-chain.html). | ||
|
|
||
| The following is an example of the generated proveanance. Provenance is | ||
| generated as an [in-toto](https://in-toto.io/) statement with a SLSA predecate. | ||
| ### Specifications | ||
|
|
||
| ```json | ||
| { | ||
| "_type": "https://in-toto.io/Statement/v0.1", | ||
| "predicateType": "https://slsa.dev/provenance/v0.2", | ||
| "subject": [ | ||
| { | ||
| "name": "binary-linux-amd64", | ||
| "digest": { | ||
| "sha256": "2e0390eb024a52963db7b95e84a9c2b12c004054a7bad9a97ec0c7c89d4681d2" | ||
| } | ||
| }, | ||
| ], | ||
| "predicate": { | ||
| "builder": { | ||
| "id": "https://github.com/slsa-framework/slsa-github-generator/.github/workflows/slsa2_provenance.yml@refs/heads/main" | ||
| }, | ||
| "buildType": "https://github.com/slsa-framework/slsa-github-generator@v1", | ||
| "invocation": { | ||
| "configSource": { | ||
| "uri": "git+https://github.com/ianlewis/actions-test@refs/heads/main.git", | ||
| "digest": { | ||
| "sha1": "3b5dc7cf5c0fd71c5a74c6b16cae78d49e03857c" | ||
| }, | ||
| "entryPoint": "SLSA provenance" | ||
| }, | ||
| "parameters": {}, | ||
| "environment": { | ||
| "github_actor": "ianlewis", | ||
| "github_base_ref": "", | ||
| "github_event_name": "workflow_dispatch", | ||
| "github_event_payload": ..., | ||
| "github_head_ref": "", | ||
| "github_ref": "refs/heads/main", | ||
| "github_ref_type": "branch", | ||
| "github_run_attempt": "1", | ||
| "github_run_id": "2093917134", | ||
| "github_run_number": "19", | ||
| "github_sha1": "3b5dc7cf5c0fd71c5a74c6b16cae78d49e03857c" | ||
| } | ||
| }, | ||
| "metadata": { | ||
| "buildInvocationID": "2182400786-1", | ||
| "completeness": { | ||
| "parameters": true, | ||
| "environment": false, | ||
| "materials": false | ||
| }, | ||
| "reproducible": false | ||
| }, | ||
| "materials": [ | ||
| { | ||
| "uri": "git+https://github.com/ianlewis/actions-test@refs/heads/main.git", | ||
| "digest": { | ||
| "sha1": "3b5dc7cf5c0fd71c5a74c6b16cae78d49e03857c" | ||
| } | ||
| } | ||
| ] | ||
| } | ||
| } | ||
| ``` | ||
| For a more in-depth technical dive, read the [SPECIFICATIONS.md](./SPECIFICATIONS.md). |
Oops, something went wrong.