A few months ago Google and GitHub announced the release of a Go builder 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 or recycled developer accounts, and repository recreation are becoming more commonplace. Most recently, phishing attacks 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, 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. 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, ko, jib, grpc-gateway, and 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.
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.
- 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:
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: "${{ needs.build.outputs.hashes }}"
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.
Step 3: Verification
Users of a project can verify the provenance using slsa-verifier. This verification tool provides a number of options to verify the metadata in the provenance.
To install the verification CLI tool, run:
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:
$ 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.
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 on Slack (#slsa), discuss ideas with us in the #slsa-tooling channel, and join our SLSA Tooling working group meetings to help us prioritize future work. See you there!