SLSA Levels

How to generate SLSA provenance and how to add it to your Chainloop workflow.

This feature is only available on Chainloop’s platform paid plans.

With Chainloop, you can continuously evaluate SLSA compliance posture of your projects in three steps:

• Configure your Chainloop Workflow to use the slsa-checks policy group and attach the SLSA framework to your project.
• Configure your CI workflow to generate OIDC tokens so we can do runner verification.
• Automatically verify SLSA compliance using Chainloop platform.

1 - Configure your Chainloop Workflow

We start by configuring Chainloop Workflow (full docs available here). We assume you already have chainloop command line tool available in your local environment (if you don’t have a look at the installation docs:

chainloop workflow create --name "build-and-test" --project "skynet" --team "cyberdyne core"

We created a new workflow, but it is empty for now meaning that it doesn’t have any kind of materials. We should add any binaries, container images, or any kind of Chainloop supported material to our contact. We do this by using the following command (you can see an example contract by looking at the example file available in GitHub):

chainloop workflow contract update --name build-and-test -f https://raw.githubusercontent.com/chainloop-dev/chainloop/main/docs/examples/contracts/slsa/github.yaml

The above example is a generic one, but for a very simple contract that includes a single container image we could go with a following contract definition:

schemaVersion: v1

materials:
  - type: CONTAINER_IMAGE
    name: container

policyGroups:
  - ref: slsa-checks
    with:
      runner: GITHUB_ACTION # or GITLAB_PIPELINE

The above contract file specifies one material - a CONTAINER_IMAGE representing our container image. We can add it during the build. We also included the policyGroups section and referenced the slsa-checks that performs all the required checks for the SLSA framework.

2 - Configure your CI workflow to perform runner verification

The following section assumes you are using GitHub or GitLab as your build platform. More platforms are in the works, if you can’t see yours, please contact us.

To perform the checks you need to modify your workflow file like this

GitHub Action

Add id_token write permission to your GitHub workflow file so Chainloop can verify that you are using a trusted runner.

permissions:
  id-token: write

GitLab Pipeline

If you are already performing keyless attestations, you can skip this step.

For GitLab CI, the chainloop CLI will expect a GitLab OIDC token that’s retrieved either from an environment variable called GITLAB_OIDC or performing keyless attestations.

In either way, the .gitlab-ci.yml file could look like this:

id_tokens:
  GITLAB_OIDC:
    aud: chainloop # make sure the audience is chainloop

Once done, just perform a regular attestation process.

3 - Verifying SLSA level in Chainloop

Now that we are already generating SLSA provenance and including it in the Chainloop attestation, we need to associate the SLSA Framework with the project we want to start monitoring SLSA compliance for.

You can do that by going to the Project and selecting the project of you choice and updating it in the Update Project section of that page.

Once that is done you will be able to see the SLSA compliance in the Frameworks section of the project associated with the SLSA framework.

To learn more about each of the automatic and manual evidence head over to the Frameworks section in the Chainloop Platform UI and check the SLSA 1.1 framework.

4 - Troubleshooting

When working with SLSA attestation you might run into the following errors:

Runner not Authenticated

Chainloop will report that runner is not authenticated or that the workflow file path is missing when the OIDC token can’t be retrieved. The errors that you might see in your SLSA policies execution are:

• Runner is not authenticated
• Runner workflow file path is missing or is empty

The remediation depends on the build platform you are using:

GitHub

When using GitHub Actions, make sure that the id_token permission is set on the workflow level, not job level. For example:

permissions:
  id-token: write

Runner Environment is not Valid

Chainloop will report that runner environment is not valid when the runner environment is not as the one provided in the policy. This means that the build runner platform is not as expected. The expected and actual runner platform are provided in the error message.

The errors that you might see in your SLSA policies execution are:

• Runner environment is not valid

Keyless Signatures not Supported

Chainloop will report that keyless signatures are not supported when the provenance is not signed. Verify that your build platform is using the newest version of Chainloop.

The errors that you might see in your SLSA policies execution are:

• Keyless signing configuration is invalid or not found

5 - Manual Evidence Explained

Chainloop uses a number of manual evidence to verify the SLSA requirements that you need to ensure are fulfilled in order to get SLSA Level 3 compliance. The description of the evidence can be found in Chainloop SLSA reference.