SLSA level 3 provenance attestations

GitLab can generate SLSA level 3 compatible provenance attestations. The key differences between level 2 and 3 provenance attestation are isolation and “unforgeable” requirements.

For the details of attestations, see the GitLab SLSA provenance specification.

Prerequisites

These conditions need to be met for the attestation of any container or artifact:

• For private and internal projects, the build must use the LOCAL_CA attestation method.
• The build must use the build stage.
• The slsa_provenance_statement feature flag must be enabled for the project.

Attestation methods

GitLab signs each attestation with one of these methods:

SIGSTORE

Signs the attestation with the public Sigstore service and records the signing event in the public Rekor transparency log. To prevent accidental disclosure of project information, GitLab does not generate SIGSTORE attestations for private or internal projects. The public Sigstore service trusts only GitLab.com pipelines, so this method works only on GitLab.com.

LOCAL_CA

Signs the attestation with a certificate from a certificate authority (CA) that GitLab creates for the project. GitLab does not send the attestation to Sigstore or Rekor.

By default, public projects on GitLab.com use SIGSTORE. All other projects use LOCAL_CA, including all projects on GitLab Self-Managed.

Select an attestation method

Select an attestation method to control how GitLab signs the attestations for a pipeline or job.

To select an attestation method:

• In the .gitlab-ci.yml file, use the variables keyword to set ATTEST_METHOD to SIGSTORE or LOCAL_CA.

For example, to use LOCAL_CA for every job in the pipeline:

variables:
  ATTEST_METHOD: LOCAL_CA

The value is not case-sensitive. If the value is not SIGSTORE or LOCAL_CA, GitLab uses the default method. GitLab reads ATTEST_METHOD only from the .gitlab-ci.yml file and ignores values from other places, such as CI/CD variables defined in the UI and pipeline variables.

Generate an attestation for artifacts

To generate an attestation for all artifacts produced by a build:

• Set the ATTEST_BUILD_ARTIFACTS CI/CD variable to true.
• The artifact must not exceed 100 MB.

For example, GitLab generates an attestation for the artifacts in this CI/CD job:

build-job:
  stage: build
  variables:
    ATTEST_BUILD_ARTIFACTS: true
  script:
    - echo "Hello, $GITLAB_USER_LOGIN!"
    - echo "Hello, $GITLAB_USER_LOGIN!" > test.txt
  artifacts:
    paths:
      - test.txt

Generate an attestation for a container

To generate an attestation for a container:

• Set the CI/CD variable ATTEST_CONTAINER_IMAGES to true.

• Set the IMAGE_DIGEST variable to a valid SHA256 reference, with this format:

  sha256:9bf00f5090086aba643d21f8ed663576855add63b7b780b4eaffc5124812c3c9
  org/project-name@sha256:9bf00f5090086aba643d21f8ed663576855add63b7b780b4eaffc5124812c3c9
  9bf00f5090086aba643d21f8ed663576855add63b7b780b4eaffc5124812c3c9

For example, GitLab generates an attestation for the image created in this CI/CD job:

build-dockerhub:
  stage: build
  variables:
    ATTEST_CONTAINER_IMAGES: true
    CI_REGISTRY: docker.io
    DOCKER_IMAGE_NAME: sroqueworcel/test-slsa-sbom:stable
  script:
    - echo $DOCKER_REGISTRY_PASSWORD | docker login $CI_REGISTRY -u $DOCKER_REGISTRY_USER --password-stdin
    - docker build -t $DOCKER_IMAGE_NAME .
    - docker push $DOCKER_IMAGE_NAME
    - IMAGE_DIGEST="$(docker inspect --format='{{index .Id}}' "$DOCKER_IMAGE_NAME")"
    - echo "IMAGE_DIGEST=$IMAGE_DIGEST" >> build.env
  artifacts:
    reports:
      dotenv: build.env

View attestations

Successful attestations are stored in the attestations page. To view the attestations:

1. In the top bar, select Search or go to and find your project.
2. In the left sidebar, select Build > Attestations.

If the attestation is not successful, the CI/CD job log shows an error.

You can also fetch successful attestations with the Attestations API.

Verifying attestations

You can verify both artifacts and containers by using the glab command-line interface. The glab CLI verifies only SIGSTORE attestations, not LOCAL_CA attestations.

For example:

• A successful verification:

  shell

  % glab attestation verify ~/file-or-container -p org/project-name
  Artifact provenance successfully verified. Signatures confirm file.txt was attested by org/project-name

• A failed verification:

  shell

  % glab attestation verify ~/file.txt -p org/project-name
  
     ERROR
  
    Unable to find a provenance statement for 1f9e5808a340916aa5618ee13a893dcf9d4f7e2d42a254be0f7eb06a094ab8ea.