Setting Up SLSA Provenance and GitHub Artifact Attestations

#guide #software

Software supply chain attacks infiltrate an application's production and distribution process to inject malicious code. To defend against such attacks, mechanisms like SLSA Provenance and GitHub Artifact Attestations provide a critical layer to verify that software has been reliably produced and remains untampered. In this article, we'll explore what these technologies are and how to enable them in your projects using GitHub Actions, step by step.

Proving where a software artifact comes from, how it was built, and what steps it went through has become a fundamental need in today's complex CI/CD environments. SLSA (Supply-chain Levels for Software Artifacts) offers a framework to standardize this proof, while GitHub Artifact Attestations facilitate generating this proof automatically and cryptographically signed. This approach significantly enhances the ability to verify the integrity and origin of software.

What is SLSA Provenance and Why is it Important?

SLSA Provenance is an immutable and verifiable set of metadata about how a software artifact was created. This metadata includes information such as the source code used in the build process, compiler versions, dependencies, and the build environment. SLSA defines a set of security requirements designed to increase security levels in the software supply chain.

SLSA defines levels that introduce increasingly stringent requirements to enhance software supply chain security. Provenance is a fundamental requirement, especially for SLSA Level 2 and above. With provenance information, we can ensure that software is built from a trusted source, through a trusted process, before using it. This helps mitigate the future impact of large-scale supply chain attacks like SolarWinds.

ℹ️ SLSA Levels

While SLSA Build Level 1 requires basic automation and source control, the highest level, Build Level 3, demands stricter security measures such as fully automated and scripted builds, a trusted build service, and a signed, tamper-resistant provenance record. Each level aims to progressively strengthen your software supply chain security.

The importance of provenance is not limited to authentication; it also plays a critical role in legal compliance and auditability. Transparently presenting a software's build history facilitates compliance with regulations and accelerates root cause analysis in the event of a security breach. This makes it possible to establish trust at every stage of software distribution.

How GitHub Artifact Attestations Work

GitHub Artifact Attestations leverage the Sigstore project to cryptographically sign the provenance information of software artifacts created via GitHub Actions workflows. This system uses OpenID Connect (OIDC) and ephemeral keys to sign attestations without needing any pre-configured credentials, thereby eliminating the complexity of key management.

During a workflow, an action running in the GitHub Actions environment collects metadata about the built artifact and signs this data using Sigstore's Cosign tool. Once the signing process is complete, the signed attestation and its associated certificate are recorded in Rekor, Sigstore's transparency log. Rekor maintains an immutable record of attestations, allowing anyone to independently verify these records.

This architecture takes a significant step towards ensuring trust in the software supply chain. Attestations include not only what the artifact is, but also from which repository, which commit, with which workflow, and by whom it was created. This detailed information makes it possible to quickly and reliably assess the legitimacy of an artifact.

Pre-setup for GitHub Artifact Attestations

Before integrating SLSA Provenance and GitHub Artifact Attestations into your projects, some preliminary preparations are necessary. Without proper configuration and permissions, these systems will not function correctly. These steps form the foundation for a smooth integration.

First, ensure your GitHub repository is properly configured to use GitHub Actions. You need to have Actions enabled in your repository and be a user or organization with sufficient permissions to allow workflows to run. Additionally, it's crucial that the GitHub Actions workflow that will create the attestations has id-token: write permission, as this permission is required to generate the OIDC token.

permissions:
  contents: read # To read repository content
  id-token: write # Critical for generating OIDC token
  packages: write # To upload artifact to GitHub Packages (optional)

⚠️ Permission Management

It's important to remember that the id-token: write permission grants a workflow the ability to request an access token from an external OIDC-supported service. For security, this permission should only be granted to necessary workflows and with the most restricted scope possible. Broad permissions can increase the potential risks of a malicious workflow. Adhering to the principle of least privilege is always the best approach.

Finally, these integrations typically require a specific SLSA builder. GitHub's slsa-github-generator action allows you to easily use this builder. You can include this action in your existing build workflow to automate the attestation creation process. We will cover the details of how to use this action in the next section.

Creating Attestations with SLSA Provenance

To create an SLSA Provenance attestation within a GitHub Actions workflow, we use the slsa-github-generator action. This action automatically collects the provenance information of your build process and signs it with Sigstore. This process is a fundamental step in enhancing the security of your CI/CD pipeline.

As an example, let's create a GitHub Actions workflow that shows how to build a simple Go application and add an SLSA attestation to it. This workflow will build your application, upload the output as a GitHub artifact, and then create an attestation for this artifact. The attestation will contain details of the build process.

name: Build and Attest Go Application

on:
  push:
    branches:
      - main
  workflow_dispatch:

permissions:
  contents: read
  id-token: write # Required for signing attestation

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v6 # Latest stable version recommended

      - name: Setup Go
        uses: actions/setup-go@v7 # Latest stable version recommended
        with:
          go-version: '1.22' # Specify the Go version you want to use

      - name: Build Go application
        run: go build -o myapp .

      - name: Upload artifact
        uses: actions/upload-artifact@v4 # v4 is the recommended version for GitHub.com
        with:
          name: myapp
          path: myapp

      # Step to generate SLSA Provenance attestation
      - name: Generate SLSA attestation
        uses: slsa-framework/slsa-github-generator/.github/actions/generator@v2.0.0 # Use a specific version of slsa-github-generator
        with:
          generator-uses: slsa-framework/slsa-github-generator/.github/workflows/generator_generic_go.yml@v2.0.0 # Use a specific version of the generator workflow for Go
          artifact-path: myapp # Path to the artifact for which attestation will be created

In the example above, the slsa-github-generator action monitors our Go application's build process to create a provenance attestation. The generator-uses parameter points to a generator workflow specific to the language and build environment used. This ensures the attestation is accurate and complete. artifact-path specifies which artifact's attestation will be created. With these steps, you will automatically have signed provenance information for each of your builds.

Verifying Generated Attestations

Once SLSA Provenance attestations are created, their verification is a critical part of software supply chain security. Verification proves that a software artifact has indeed gone through the specified sources and processes. This is vital for detecting potential manipulations or unauthorized builds.

For the verification process, the gh CLI (GitHub CLI) or Sigstore's cosign tool is typically used. These tools retrieve the attestation from the Rekor transparency log, verify its signature, and inspect its content. If verification is successful, we can trust the integrity and origin of the artifact.

First, you need to download the artifact you want to verify and its associated attestation. You can easily do this with the gh CLI:

# List the last successful workflow run with GitHub CLI
gh run list --workflow "Build and Attest Go Application" --json databaseId,status,conclusion --jq '.[0].databaseId'

# Download the attestation using the relevant workflow run ID
# In this example, replace {RUN_ID} with the ID you got from the command above
gh run download {RUN_ID} -n attestation # This command downloads the attestation file

Once the attestation file is downloaded, you can verify its signature and content using the cosign tool. Verification with cosign checks if the attestation matches the record in Rekor and if the signature is valid.

# Verify attestation with Cosign
# Replace {ARTEFACT_NAME} with 'myapp' as in our Go application
cosign verify-attestation --type slsaprovenance --key https://github.com/slsa-framework/slsa-github-generator/releases/download/v2.0.0/slsa-github-generator.pub --predicate-type "https://slsa.dev/provenance/v1" {ARTEFACT_NAME}

Warning: In the command above, the --key parameter uses a static public key published by a specific version of slsa-github-generator. To fully leverage Sigstore's keyless signing feature, verifying via OIDC identity using the --certificate-identity and --certificate-oidc-issuer parameters is a more common and recommended approach.

This command verifies that the attestation is a valid SLSA provenance and was signed with the public key published by slsa-github-generator. In the output, you will see the content of the attestation (predicate). This content includes detailed information about the build process (source repository, commit, build steps, etc.). This information can be used to check if the artifact has gone through the expected processes.

SLSA Provenance and Security Strategies

Setting up SLSA Provenance and GitHub Artifact Attestations is only the beginning of a software supply chain security strategy. The true value of these tools emerges from how they are integrated into your overall security posture. It's important not only to create attestations but also to use them to enforce your security policies.

For example, by using an admission controller in Kubernetes environments, you can allow only signed and verified container images with a specific SLSA level of provenance to be deployed. This is an approach consistent with Zero Trust Architecture (ZTNA) principles. No artifact should enter a production environment without its origin and integrity being verified.

💡 Automated Policy Enforcement

Using attestations for automated policy enforcement minimizes human error and ensures that your security standards are always applied. Policy-as-Code tools (e.g., OPA Gatekeeper or Kyverno) are ideal for this integration.

However, implementing these strategies involves some trade-offs. Attestation creation and verification processes can add extra steps and thus extra time to your CI/CD pipeline. Additionally, configuring and managing these systems correctly may require additional expertise. As complexity increases, so do the risks of misconfiguration. Therefore, a careful balance must be struck between security levels and operational overhead.

In advanced scenarios, it may also be necessary to create attestations for multi-stage builds or custom builders. The flexibility of GitHub Actions allows you to define custom builder workflows for such complex scenarios. Having provenance for each build stage makes every step in the supply chain traceable and verifiable. This comprehensive approach provides maximum security assurance throughout the software's lifecycle.

Conclusion

Software supply chain security is a topic that cannot be overlooked in today's digital landscape. SLSA Provenance and GitHub Artifact Attestations offer a robust defense mechanism against these security challenges. Cryptographically signed and verifiable proof of a software artifact's origin and build process provides significant assurance against malicious interference.

The setup and verification steps covered in this article provide a fundamental framework for making your projects more secure. By integrating these capabilities into your CI/CD pipelines, you can enhance the integrity and trustworthiness of your software, thereby minimizing potential security risks. Remember, security is a continuous journey, and tools like these are solid steps to take on that journey.