GitLab CI/CD

Use the following instructions to integrate your GitLab pipelines with Scribe.

1. Obtain a Scribe Hub API Token

1. Sign in to Scribe Hub. If you don't have an account you can sign up for free here.

2. Create a API token in Scribe Hub > Settings > Tokens. Copy it to a safe temporary notepad until you complete the integration.

Important

The token is a secret and will not be accessible from the UI after you finalize the token generation.

2. Add the API token to GitLab secrets

Set your Scribe Hub API token in GitLab with a key named SCRIBE_TOKEN as instructed in GitLab project variables

3. Install Scribe CLI

Valint (Scribe CLI) is required to generate evidence in such as SBOMs and SLSA provenance. Install Valint on your build runner with the following command:

sh 'curl -sSfL https://get.scribesecurity.com/install.sh | sh -s -- -b ./temp/bin'

Alternatively, add an instalation stage at the beginning of your relevant builds as follows:

before_script:
  - apt update
  - apt install git curl -y
  - curl -sSfL https://get.scribesecurity.com/install.sh | sh -s -- -b /usr/local/bin

4. Instrument your build scripts

Usage

image: ubuntu:latest
before_script:
  - apt update
  - apt install git curl -y
  - curl -sSfL https://get.scribesecurity.com/install.sh | sh -s -- -b /usr/local/bin

stages:
    - scribe-gitlab-stage

scribe-gitlab-job:
    stage: scribe-gitlab-stage
    script:
      - valint [bom,slsa,evidence] [target]
          -o [attest, statement]
          --context-type gitlab
          --output-directory ./scribe/valint
          -P $SCRIBE_TOKEN

      - valint verify [target]
          -i [attest, statement, attest-slsa, statement-slsa, attest-generic, statement-generic]
          --context-type gitlab
          --output-directory ./scribe/valint
          -P $SCRIBE_TOKEN

Basic example

before_script:
  - apt update
  - apt install git curl -y
  - curl -sSfL https://get.scribesecurity.com/install.sh | sh -s -- -b /usr/local/bin

stages:
    - scribe-gitlab-job

scribe-gitlab-job:
    stage: scribe-gitlab-job
    script:
      - valint bom busybox:latest
          --context-type gitlab
          --output-directory ./scribe/valint
          -P $SCRIBE_TOKEN

Additional examples

Generate an SBOM for an image in a public registry

- valint bom busybox
      --context-type gitlab
      --output-directory ./scribe/valint

Add NTIA metadata to SBOM

image: docker:latest

services:
  - docker:dind

stages:
    - custom-ntia-metadata-stage

custom-ntia-metadata:
    stage: custom-ntia-metadata-stage
    script:
      - valint bom busybox
            --context-type gitlab
            --output-directory ./scribe/valint

Generate SLSA provenance for an image in a public registry

- valint slsa busybox
      --context-type gitlab
      --output-directory ./scribe/valint

Generate an SBOM for for an image built with local docker

- valint bom image_name:latest
      --context-type gitlab
      --output-directory ./scribe/valint

Generate SLSA provenance for for an image built with local docker

- valint slsa image_name:latest
      --context-type gitlab
      --output-directory ./scribe/valint

Generate an SBOM for an image in a private registry

Before the following task add a docker login task

- valint bom scribesecurity.jfrog.io/scribe-docker-local/example:latest \
      --context-type gitlab \
      --output-directory ./scribe/valint \

Generate SLSA provenance for an image in a private registry

Before the following task add a docker login task

- valint slsa scribesecurity.jfrog.io/scribe-docker-local/example:latest \
      --context-type gitlab \
      --output-directory ./scribe/valint \

Add custom metadata to SBOM

valint_image_job:
  variables:
    test_env: "test_env_value"
  script:
    - valint bom busybox:latest
      --context-type gitlab
      --output-directory ./scribe/valint
      --env test_env
      --label test_label

Add custom metadata to SLSA provenance

valint_image_job:
  variables:
    test_env: "test_env_value"
  script:
    - valint slsa busybox:latest
      --context-type gitlab
      --output-directory ./scribe/valint
      --env test_env
      --label test_label

Export SBOM as an artifact

Use format input argumnet to set the format.

save-artifact-job:
  script:
    - valint bom busybox:latest
      --context-type gitlab
      --output-directory ./scribe/valint
      --output-file ./my_sbom.json
  artifacts:
      paths:
        - ./scribe/valint
        - ./my_sbom.json

Export SLSA provenance as an artifact

Using command output-directory or output-file to export evidence as an artifact.

Use --format, -o to select between the format.

save-artifact-job:
  script:
    - valint slsa busybox:latest
      --context-type gitlab
      --output-directory ./scribe/valint
      --output-file ./my_slsa.json

  artifacts:
      paths:
        - ./scribe/valint
        - ./my_slsa.json

Generate an SBOM for 'docker save'

Use oci-archive target type when creating a OCI archive (podman save).

before_script:
  - apk update
  - apk add curl
  - curl -sSfL https://get.scribesecurity.com/install.sh | sh -s -- -b /usr/local/bin

valint-docker-job:
    tags: [ saas-linux-large-amd64 ]
    stage: valint-docker-job
    image: docker:latest
    variables:
      DOCKER_DRIVER: overlay2
      DOCKER_TLS_CERTDIR: "/certs"
    services:
      - docker:dind
    script:
      - docker pull busybox:latest
      - docker save -o busybox.tar busybox:latest
      - valint bom docker-archive:busybox.tar
          --context-type gitlab
          --output-directory ./scribe/valint
          --output-file ./busybox.json

Generate SLSA provenance for 'docker save'

Use oci-archive target type when creating a OCI archive (podman save).

before_script:
  - apk update
  - apk add curl
  - curl -sSfL https://get.scribesecurity.com/install.sh | sh -s -- -b /usr/local/bin

valint-docker-job:
    tags: [ saas-linux-large-amd64 ]
    stage: valint-docker-job
    image: docker:latest
    variables:
      DOCKER_DRIVER: overlay2
      DOCKER_TLS_CERTDIR: "/certs"
    services:
      - docker:dind
    script:
      - docker pull busybox:latest
      - docker save -o busybox.tar busybox:latest
      - valint slsa docker-archive:busybox.tar
          --context-type gitlab
          --output-directory ./scribe/valint
          --output-file ./busybox.json

Generate an SBOM for a local directory

dir-sbom-job:
  script:
    - mkdir testdir
    - echo "test" > testdir/test.txt
    - valint bom dir:testdir
          --context-type gitlab
          --output-directory ./scribe/valint

Generate SLSA provenance for a local directory

dir-sbom-job:
  script:
    - mkdir testdir
    - echo "test" > testdir/test.txt
    - valint slsa dir:testdir
          --context-type gitlab
          --output-directory ./scribe/valint

Generate an SBOM for a remote git repository

git-remote-job:
  script:
    - valint bom git:https://github.com/mongo-express/mongo-express.git
          --context-type gitlab
          --output-directory ./scribe/valint

Note If you use implicit checkout, git-strategy affects the commits collected into the SBOM.

git-remote-job:
  script:
    - valint bom .
          --context-type gitlab
          --output-directory ./scribe/valint

Generate SLSA provenance for a git repo

For a remote git repo:

git-remote-job:
  script:
    - valint slsa git:https://github.com/mongo-express/mongo-express.git
          --context-type gitlab
          --output-directory ./scribe/valint

For a local git repo:

git-remote-job:
  script:
    - valint slsa .
          --context-type gitlab
          --output-directory ./scribe/valint

Alternative evidence stores

You can learn more about alternative stores here.

Details

OCI Evidence store

Valint supports both storage and verification flows for attestations and statement objects utilizing OCI registry as an evidence store.

Using OCI registry as an evidence store allows you to upload, download and verify evidence across your supply chain in a seamless manner.

Related flags:

• --oci Enable OCI store.
• --oci-repo - Evidence store location.

Before you begin

Evidence can be stored in any accusable registry.

• Write access is required for upload (generate).
• Read access is required for download (verify).

You must first login with the required access privileges to your registry before calling Valint. For example, using docker login command or DOCKER_AUTH_CONFIG field.

Usage

image: docker:latest
variables:
  DOCKER_DRIVER: overlay2
  DOCKER_TLS_CERTDIR: "/certs"

services:
  - docker:dind

before_script:
  - apt update
  - apt install git curl -y
  - curl -sSfL https://get.scribesecurity.com/install.sh | sh -s -- -b /usr/local/bin
  - echo "$DOCKER_PASSWORD" | docker login -u "$DOCKER_USERNAME" --password-stdin [my_registry]

stages:
    - scribe-gitlab-oci-stage

scribe-gitlab-job:
    stage: scribe-gitlab-oci-stage
    script:
      - echo $CI_REGISTRY_PASSWORD | docker login -u $CI_REGISTRY_USER $CI_REGISTRY --password-stdin

      - valint [bom,slsa,evidence] [target]
          -o [attest, statement]
          --context-type gitlab
          --output-directory ./scribe/valint
          --oci --oci-repo=[my_repo]

      - valint verify [target]
          -i [attest, statement, attest-slsa, statement-slsa, attest-generic, statement-generic]
          --context-type gitlab
          --output-directory ./scribe/valint
          --oci --oci-repo=[my_repo]

Use gitlab as context-type.