nais/salsa

nais SLSA Provenance Action

About

This is a Github Action for generating signed provenance about a build and its related artifacts. Provenance is an attestation (a "software bill of materials") about a software artifact or collection of artifacts, documenting how an artifact was produced - all in a common format.

Supply chain Levels for Software Artifacts, or SLSA (pronounced: salsa), is a security framework ( standards, guidelines etc.) to prevent tampering, improve integrity, and secure packages and infrastructure in your projects, businesses or enterprises.

The action implements the level 3 requirements of the SLSA Framework (as long as it is run in an ephemeral environment) producing a signed software attestation of your build and dependencies. The attestation is signed and uploaded to your container registry using cosign and can be verified by the salsa cli (also provided in this repo) or using the cosign verify-attestation command.

Disclaimer: This is not an official GitHub Action maintained by the SLSA team. It is created by the nais.io team for the purpose of securing supply chains in NAV. However we encourage other organizations/users to use it and even contribute as it is built with open source in mind.

Built with

• golang
• cosign
• Github Actions

Formats/Standards implemented

• Statement type: in-toto v0.1
• Signing envelope: DSSE
• Predicate type: Provenance v0.2

Materials

This actions creates attestations with materials based on both runtime and transitive dependencies, using a supported build tool.

Supported build tools

• jvm
  • gradle
  • maven
• js
  • yarn
  • npm
• golang
• php (with known limitation: there is no digest over dependencies)

Getting started

• How to use
  • Requirements
  • Key Management
    • Setup
    • Other KMS providers
  • Example
    • Workflows
    • Attestation
• Customizing
  • Inputs
    • Github context
    • Runner context
• Release
  • Checksums
  • Verify signature

How to use

Requirements

• Currently we only support signing keys from a KMS provider - see cosign documentation for more details. Your workflow must set up an explicit authentication step for your KMS provider before the nais salsa action.

  • In the example action we use google-github-actions/auth to authenticate with Google KMS for signing the attestation. See also customizing for other providers

• actions/checkout is required prior to using this action as nais salsa must have access to your build manifest to digest over dependencies.

Key Management

The salsa action use cosign and KMS for signing and verifying the attestation. Cosign supports all the standard key management systems. If your project requires other providers please feel free to submit an issue or pull request.

Setup

KMS with cosign requires some setup at you provider. In short for Google KMS:

1. KMS is enabled in your Google project
   1. create a keyring
      1. create keys: Elliptic Curve P-256 key SHA256 Digest
2. Service accounnt in project has roles:
   1. Cloud KMS CryptoKey signer/verifier
   2. Cloud KMS viewer Role
3. Configure Github actions secret containing the serviceuser
4. Configure with.key with the right URI format for Google: gcpkms://projects/$PROJECT/locations/$LOCATION/keyRings/$KEYRING/cryptoKeys/$KEY/versions/$KEY_VERSION

Other KMS providers

It is possible to use other KMS providers, see the cosign KMS documentation for more information about provider setup and key URI formats.

Example

Workflows

name: ci

on:
  push:
    branches:
      - 'main'

env:
  IMAGE: ttl.sh/nais/salsa-test:1h
  KEY: gcpkms://projects/$PROJECT/locations/$LOCATION/keyRings/$KEYRING/cryptoKeys/$KEY/versions/$KEY_VERSION

jobs:
  provenance:
    runs-on: ubuntu-20.04
    steps:

      - name: Checkout Code
        uses: actions/checkout@v3

      - name: Build and push
        uses: docker/build-push-action@v2
        with:
          push: true
          tags: ${{ env.IMAGE }}

      - name: Authenticate to Google Cloud
        uses: google-github-actions/auth@v0
        with:
          credentials_json: ${{ secrets.GCP_CREDENTIALS }}

      - name: Provenance, upload and sign attestation
        uses: nais/salsa@v0.1
        with:
          key: ${{ env.KEY }}
          docker_pwd: ${{ secrets.GITHUB_TOKEN }}

• Example of a Github action nais-salsa-integration.yml
• An example of a generated slsa provenance with transitive dependencies
• An example of a signed cosign dsse attestation
  • result after an decoded cosign attestation

Customizing

inputs

Github context

The github context contains information about the workflow run and the event that triggered the run. By default, this action uses the Github context.

Runner Context

The runner context contains information about the runner that is executing the current job. By default, this action uses the Runner context.

The Following inputs can be used as step.with keys

Release

Checksums

We generate a checksums.txt file and upload it with the release, so users can validate if the downloaded files are correct. All files are by default digested with algorithm sha256.

Verify signature

The release artifacts are signed with cosign and can be verified by using the public signing key.

cosign verify-blob --key cosign.pub --signature salsa.tar.gz.sig salsa.tar.gz

Verified OK