SLSA Provenance Blog Series, Part 2: Deeper Dive Into SLSA Provenance

In Part 2 of this blog series, we uncover the details of SLSA provenance from end to end. Previously in Part 1, we started by reviewing in-toto attestations, which are the underlying technology of SLSA provenance. Now, we dive into the internals of SLSA provenance, understand its content, and how you can leverage SLSA provenance to improve the security of your software supply chain and gain more visibility into it. In the next post, we will go further into the requirements of SLSA level 3, including how to implement it and why it is useful.

Recap: SLSA and in-toto Attestations

We highly recommend reading Part 1 of this series to understand attestations before you continue. Here’s a quick summary to provide some context:

The SLSA Framework

SLSA is focused on protecting software from its origination source through deployment by allowing users to make automated decisions about the integrity of the artifacts they use. This can help prevent many possible attacks throughout the software supply chain. SLSA defines different levels of security, covering your source code, build system, and provenance generation.

In-toto Attestations

In-toto is a framework for software attestations and includes a signed document that associates metadata with an artifact. Encapsulating provenance information in an in-toto attestation provides the provenance with integrity and authenticity. Using a standard format designed for artifacts metadata association enables us to focus on the essential part that we want to generate: the metadata.

What is SLSA Provenance

SLSA provenance is the verifiable information about software artifacts describing where, when, and how the artifacts were produced. For example, when you install 3rd-party software, you want to verify that it comes from that vendor's repository, that the software's version matches the source code version, and that no one tampered with it after the build.

Provenance must be there from the beginning to trace software back to the source and define the moving parts in a complex supply chain.

In practical terms, provenance associates source code and build steps with the resulting artifacts. It essentially acts as a receipt generated for the build process by documenting how resulting artifacts were created in relation to the build. 

What SLSA Provenance Is Used For

Artifacts Integrity is about the ability to trust the authenticity of artifacts, meaning verifying that the artifact you get is really the original artifact uploaded by its author.

For example, when you install 3rd-party software, you want to verify that is the authentic version created by the vendor that you trust, and that no one modified it after its creation. When you don’t verify the authenticity of the software you consume, you can easily install untrusted software that hackers crafted to look like the software you were looking for, but actually steals your information or encrypts your disks for ransomware.

Check out this blog post to learn more about it and gain technical background about hashes and signatures. This post also shows how signing containers for integrity might be more tricky than expected.

What is Software Attestation, and what can you use it for?

Authenticity and Integrity via Artifacts Signing

SLSA provenance verifies the authenticity and integrity of the software artifact. The in-toto format of the provenance contains a signature of the artifact that can be validated by the user. Since SLSA provenance uses in-toto attestations as the delivery medium, artifact signing is built into the provenance.

Attack Prevention via Policy Enforcement

SLSA provenance describes the build process: how some materials (namely, code) are brought together (namely, built) to produce the software artifact. We can use this information to enforce different policies. For example, we can allow the deployment of artifacts only if they are:

• Generated from a specific repository or a set of repositories.

• Generated from the main branch, a tag, etc.

• Generated by a specific build job, such as a specific version of a GitHub Action triggered by a pull request.

• Generated since/up-to a certain date and time.

• Contain commits that are created/approved by a specific set of authors.

• Generated using specific arguments, such as a --mode=release flag.

Policy enforcement ensures the application was built from a known and trusted source. It can prevent attacks that tamper with the build process, poison the artifacts, and more.

Observability Into the Software Supply Chain

In addition to these security capabilities, generating provenance provides us with observability into the software supply chain. We now have a trusted set of metadata about the artifact, and we can use it to map the pipeline and understand what components are going where. As organizations grow bigger, with a lot of developers and repositories, understanding (let alone managing) how these relationships work becomes impossible without this level of visibility.

Forensics

• What source code was modified by the user while it was compromised?

• What artifacts were generated by the user while it was compromised?

With provenance, you can detect all the artifacts that were built during that period and analyze it to detect all these occurrences. You can then use that knowledge to remove the malicious source code and delete the malicious artifacts - and prevent them from ever reaching production. Moreover, if any of the artifacts was already deployed, you can use that knowledge to investigate into your production environment and analyze its impact.

Platform for more attestations

SLSA provenance creates a trusted link between the source, build and artifact. We can then use it as a platform for more metadata that’ll be associated with it. For example, we can run SAST and secret scanning tools on the source code, and use the link between the source code and the artifact to also bind these checks to the artifact.

What SLSA Provenance Is NOT Used For

As we’ve demonstrated, SLSA Provenance enables us to enforce policies on a CI/CD pipeline. And as described above, it is also a platform for many more attestations. But it isn’t meant to solve everything out of the box.

Provenance alone will not:

• Detect malicious code inserted into the source code of the artifact. Provenance would include the commits containing the code but does not try to detect malicious code.
• Detect a user compromise. Provenance would include the user that triggered the artifact generation but does not try to detect that it was compromised.
• Detect misconfigurations in your SDLC assets that allow for branch protection bypass. Provenance would include the source branch of the artifact but does not try to detect misconfigurations that allowed code to be inserted into it.
• List dependencies of your software artifact or vulnerabilities that it contains (PROVENANCE IS NOT SBOM!).

SLSA Provenance Content

The following schema (from SLSA v0.2 spec) describes the content of the provenance document, using the example of a GitHub Actions workflow:

This is a shortened version of the document. In practice, it would contain even more info!

How to Generate SLSA Provenance

As the SLSA framework matures, we see more and more support for SLSA generation and consumption. SLSA provenance generation can be implemented in different ways depending on the CI/CD system, the SCM, etc. In the following section, we will describe SLSA provenance generation for both GitHub and GitLab.

GitHub Actions

What

The SLSA project provides an off-the-shelf solution for SLSA provenance generation in GitHub Actions. It leverages “Reusable Workflows” to generate SLSA provenance documents that meet the SLSA level 3 requirements for provenance. Reusable workflows are workflows that can be triggered from a different workflow - streamlining the process to something as simple as a function call.

SLSA’s workflow uses SigStore’s cosign project to sign the provenance with the GitHub Action Invocation ID as its identity. The invocation ID is a unique ID associated with the specific invocation of the workflow.

You can use this workflow to generate provenance for any kind of software artifact: Docker containers, packages, executable and config files, and generally any type of files.

For more information about that solution, see the slsa-github-generator repository.

How

The provenance generation is comprised of 3 steps:

1. Output the names and digests of the subject artifacts.

2. Format them like a sha256sum output.

3. Invoke SLSA’s reusable workflow to generate the provenance.

Example

GitLab CI

What

GitLab has built-in support for SLSA provenance generation in GitLab CI. The provenance documents meet SLSA level 1 requirement for provenance, i.e., the metadata, without signatures (not using in-toto attestations).

The provenance document is generated for all the artifacts that are uploaded as a Job Artifact. As a result, you cannot use it to generate provenance for Docker containers.

How

The provenance document is generated for any job with the environment variable RUNNER_GENERATE_ARTIFACTS_METADATA set to true.

You can turn this flag on any level:

• Server: if you are running a private GitLab Server instance, you can set this flag for the entire instance.

• Group: set the flag for all repositories in the group.

• Environment: set the flag for all repositories within a GitLab environment.

• Project: set the flag for the pipelines of the project (repository).

For example, to turn it on for a repository:

1. Go to the Repository.

2. Go to Settings → CI/CD → Variables

3. Click the ‘Add a variable’ button.

4. Set RUNNER_GENERATE_ARTIFACTS_METADATA as the key and true as the value.

5. Click the “Add variable” button.

How to Verify SLSA Provenance

SLSA provides instructions on how to properly verify provenance documents.

As described above, GitLab CI only provides the metadata without the encapsulating attestation, so there is no proper way to verify it. Provenance attestations generated with GitHub Actions on the other hand, can be verified—and there’s already tooling in place to make it easy for you.

We expect that tooling will improve to support more complicated use cases and policies as the project matures.

The slsa-verifier CLI

To complement the GitHub Action that generates a signed provenance document, SLSA also provides a CLI to verify the provenance. You can download it from the slsa-verifier repository.

The following example demonstrates how to use the slsa-verifier CLI to verify the provenance document generated for the Legitify project:

VERSION=0.2.8 # the relevant legitify version

ARCH=darwin_arm64 # the relevant OS and architecture of the legitify archive

./slsa-verifier verify-artifact \

   --source-branch main \

   --builder-id 'https://github.com/slsa-framework/slsa-github-generator/.github/workflows/generator_generic_slsa3.yml@refs/tags/v1.6.0' \

   --source-uri "git+https://github.com/Legit-Labs/legitify" \

   --provenance-path multiple.intoto.jsonl \

./legitify_${VERSION}_${ARCH}.tar.gz

Keyverno

Keyverno is a policy engine designed for Kubernetes.

Using a YAML configuration file, you can enforce SLSA provenance verification in the deployment of your Kubernetes cluster.

For more information and an example, see Keyverno’s Verify Image SLSA policy.

Looking for help with Software Attestations or SLSA Provenance?

Although it’s important to learn about these technologies, adopting them requires some expertise. Today, the SigStore project is a popular way to start integrating attestations and provenance into your CI/CD pipelines. Unfortunately, SigStore operates in an open-source minded approach, uploading your private information to public logs. 

Legit Security provides a seamless solution for SLSA provenance generation that meets SLSA level 3 requirements: simply integrate your organization to generate provenance documents for your SCM (GitHub / GitLab / Bitbucket / Azure DevOps) without any extra action.

Contact Legit Security if you’re looking for an alternative that fits enterprise needs (complete data privacy, independency of your production environment on 3rd-party service, and more).

Up Next

Thank you for reading the SLSA Provenance Blog Series, Part 2: Deeper Dive Into SLSA Provenance. Read the next installment, SLSA Provenance Blog Series, Part 3: The Challenges of Adopting SLSA Provenance.