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:
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):
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:
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.
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:
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:
When using GitHub Actions, make sure that the id_token
permission is set on the workflow level, not job level. For example:
When using GitHub Actions, make sure that the id_token
permission is set on the workflow level, not job level. For example:
When using GitLab make sure that the GITLAB_OIDC
environment variable is set. For example:
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: