/
2022-08-29-slsa-github-workflows-generic-ga.md
87 lines (61 loc) · 7 KB
/
2022-08-29-slsa-github-workflows-generic-ga.md
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
---
title: "General availability of SLSA3 Generic Generator for GitHub Actions"
author: "Ian Lewis, Laurent Simon, Asra Ali"
is_guest_post: false
---
A few months ago Google and GitHub announced [the release of a Go builder](/blog/2022/06/slsa-github-workflows) that would help software developers and consumers more easily verify the origins of software by using verification files known as provenance. Since then, the SLSA community has been working to enable provenance generation for other projects that may use any number of languages or build tools. Today, we’re pleased to announce that we’re adding a new tool to generate similar provenance documents for projects developed in any programming language, while keeping your existing building workflows.
Tools like this are becoming necessary as we see a rise in malicious actors taking advantage of the open source community's trust. Attacks such as version rollback attacks, [hijacked](https://jfrog.com/blog/npm-package-hijacking-through-domain-takeover-how-bad-is-this-new-attack/) or [recycled](https://sockpuppets.medium.com/how-i-hacked-ctx-and-phpass-modules-656638c6ec5e) developer accounts, and [repository recreation](https://sockpuppets.medium.com/how-i-hacked-ctx-and-phpass-modules-656638c6ec5e) are becoming more commonplace. Most recently, [phishing attacks](https://www.bleepingcomputer.com/news/security/pypi-packages-hijacked-after-developers-fall-for-phishing-emails/) have been detected for the Python Package Index (PyPI) and several packages had malicious releases published. Not only are the users of these repositories victims of an attack, but trust in the original OSS maintainers and the ecosystem in general is also damaged.
To counter this, OSS projects can include [SLSA provenance](/provenance/v0.2), which is trustworthy information about what built the artifact, the steps used to create it, and what source code was used. This gives users peace of mind that the code they are running has not been tampered with or even entirely replaced by malicious third parties by establishing a link between release artifacts and their source code.
In order to enable the greatest number of OSS projects to make use of SLSA, we are announcing General Availability of the [generic generator workflow](https://github.com/slsa-framework/slsa-github-generator/tree/main/internal/builders/generic). The generic generator workflow allows OSS projects to build artifacts using their own custom GitHub Actions workflows that support seamless provenance generation. SLSA provenance for those artifacts can be generated by simply adding a new job step. We think this is the easiest way for projects using any language or build tools to add provenance generation to their build pipeline.
Popular projects like [urllib3](https://github.com/urllib3/urllib3), [ko](http://github.com/google/ko), [jib](https://github.com/GoogleContainerTools/jib), [grpc-gateway](https://github.com/grpc-ecosystem/grpc-gateway), and [flatbuffers](https://github.com/google/flatbuffers) have adopted the generic generator workflow. This means you'll be able to download artifacts (zip, binaries, etc.) from these projects and verify that the expected workflow was used to build the source code, without any modifications.
## Generating Provenance
The following is an example of how to generate provenance using the generic generator. You can read more details in the [documentation](https://github.com/slsa-framework/slsa-github-generator/tree/main/internal/builders/generic).
### Step 1: Generate a sha256 checksum for all artifacts
First, in your build job create a sha256 checksum of your artifacts for which you wish to generate provenance.
```yaml
- name: Generate hashes
shell: bash
id: hash
run: |
# sha256sum generates sha256 hash for all artifacts.
# base64 -w0 encodes to base64 and outputs on a single line.
# sha256sum artifact1 artifact2 ... | base64 -w0
echo "::set-output name=hashes::$(sha256sum artifact1 artifact2 | base64 -w0)"
```
### Step 2: Call the generic generator to generate SLSA
Then you can call the generic generator workflow. An example looks like this:
```yaml
provenance:
permissions:
actions: read # Needed for detection of GitHub Actions environment.
id-token: write # Needed for provenance signing and ID.
contents: write # Needed for release uploads.
uses: slsa-framework/slsa-github-generator/.github/workflows/generator_generic_slsa3.yml@v1.2.0
with:
base64-subjects: "{% raw %}${{ needs.build.outputs.hashes }}{% endraw %}"
```
Provenance is then created, signed by the workflow, and attached to your build. The generic generator workflow will also optionally upload the provenance to a GitHub release as a `.intoto.jsonl` file named `provenance.intoto.jsonl` by default. This file will used to verify the release in the next step. You can read more about the available options in the [documentation](https://github.com/slsa-framework/slsa-github-generator/tree/main/internal/builders/generic).
### Step 3: Verification
Users of a project can verify the provenance using [slsa-verifier](https://github.com/slsa-framework/slsa-verifier). This verification tool provides a number of options to verify the metadata in the provenance.
To install the verification CLI tool, run:
```shell
go install github.com/slsa-framework/slsa-verifier/cli/slsa-verifier@v1.3.0
```
Once you have installed the tool and downloaded the provenance from the release you can verify it as follows:
```shell
$ slsa-verifier \
--artifact-path ./artifact1 \
--provenance ./provenance.intoto.jsonl \
# The expected source repository.
--source github.com/ianlewis/actions-test \
# The expected release tag of the artifact
--tag v0.0.39
...
PASSED: Verified SLSA provenance
```
If you are generating a single provenance document for multiple artifacts you can verify each artifact by simply running slsa-verifier on each artifact.
If you are a project maintainer, be sure to include information in your documentation about how to verify provenance for the users of your project.
## There's More To Do
With the generic generator workflow, any project, written in any language, using any build tool, can generate SLSA provenance using GitHub Actions. This should allow a large number of projects to provide this information to their users and improve supply chain security across the Open Source ecosystem.
However, there's lots more to do and we are just getting started. We are exploring future improvements and support for more ecosystems. You can follow along with our project roadmap on our [milestones page](https://github.com/slsa-framework/slsa-github-generator/milestones).
SLSA generation and verification is also only a small part of what we need to do to improve supply chain security. Connect with us via the [SLSA community](/community) on [Slack (#slsa)](https://slack.openssf.org/), discuss ideas with us in the [#slsa-tooling](https://openssf.slack.com/archives/C03PDLFET5W) channel, and join our [SLSA Tooling working group meetings](/notes/tooling) to help us prioritize future work. See you there!