SLSA Levels

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

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

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:

permissions:
  id-token: write

permissions:
  id-token: write

id_tokens:
  GITLAB_OIDC:
    aud: chainloop

​

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. Let’s look into some them and how to verify them when using certain build platforms.

​

Forcing Multi-factor Authentication

The requirement for forcing multi-factor authentication is one of the SLSA requirements for SLSA Level 3. Chainloop enforces this by requiring you to verify your builld platform configuration and marking this as fullfiled.

​

GitHub

For GitHub, you can verify that your build platform is forcing multi-factor authentication by checking your organization security settings that can be accessed via https://github.com/organizations/[YOUR_ORGANIZATION]/settings/security and checking if the Require two-factor authentication for everyone in the YOUR_ORGANIZATION organization option is enabled.

​

GitLab

For GitLab, you can verify and configure your organization to for multi-factor authentication by going to the Admin section, selecting Settings -> General, expanding the Sign-in restrictions and enabling the Enforce two-factor authentication option.

​

Build Environment Isolation

SLSA Level 3 requires that the build environment is isolated from the rest of the system. Chainloop enforces this by requiring you to verify that your build platform is using an isolated environment, not interfering with other runs.

​

GitHub

You need to ensure that you are using the hosted runners or that your self-hosted runners used in GitHub are isolated. You can learn about your runners and their types in your GitHub organization settings, in the Actions -> Runners section.

​

GitLab

You need to ensure that you are using the hosted runners or that your self-hosted runners used in GitLab are isolated. You can learn about your GitLab runners and their types in your Project section, by going to Settings -> CI/CD -> Runners.

​

Limited Build Platform Human Access

The number of users with the access to the build plartform should be limited and kept to a minimum.

​

GitHub

You can check the user permissions of your GitHub in the Settings -> Access section of your GitHub organization and you can manage repository level access by visiting the Settings -> Collaborators and teams section of the repository of interest.

​

GitLab

You can manage repository level access by visiting the Project -> Manage -> Members section of the GitLab project of interest.

​

Build Platform Strong Controls

SLSA Level 3 requires that the build platform has strong controls in place and that your organization follows good practices.

There is not a single setting that we can verify and Chainloop suggest undergoing an annual security audit targeted at your build platform and the pracitices around it.

Some reference about the good practices for your build platform hardening:

• GitHub
• GitLab