gitlab

GitLab CI/CD Pipelines

GitLab CI/CD pipelines are a part of GitLab’s integrated continuous integration and deployment features. They allow you to define and automate the different stages and tasks in your software development workflow. This document provides an overview and example job to integrate Endor Labs into your GitLab CI pipeline.

High Level Usage Steps

1. Setup authentication to Endor Labs
2. Install your build toolchain
3. Build your code
4. Scan with Endor Labs

Authentication to Endor Labs

Endor Labs recommends using keyless authentication in continuous integration environments. Keyless Authentication is more secure and reduces the cost of secret rotation. To set up keyless authentication see the keyless authentication documentation. If you choose not to use keyless authentication you can configure an API key and secret in GitLab for authentication using the following steps. See managing API keys for more information.

Configure API key and secret in GitLab

1. In your GitLab environment, select the project you want to scan.
2. Go to Settings > CI/CD.
3. Click Expand in the Variables section.
4. Click the Add variable button at the bottom of the section.
5. In the Key field, enter ENDOR_API_CREDENTIALS_SECRET.
6. In the Value field, enter your Endor Labs API secret.
7. Under Flags, make sure you select Mask variable.
8. Repeat the previous steps to add your API key as the variable ENDOR_API_CREDENTIALS_KEY.

Configure your GitLab CI pipeline

Important: GitLab CI/CD pipelines check out commits in a detached HEAD state, which can lead to fragmented branch tracking in Endor Labs. See Set up branch tracking in GitLab to configure proper branch context.

1. Create a .gitlab-ci.yml file in the root directory of your project if you do not already have one.
2. In your .gitlab-ci.yml file customize the job configuration based on your project’s requirements using the example below.
3. Modify the image field to align with the build tools necessary for building your software packages.
4. Update the before_script section to include any additional steps required before executing the scan, such as installing dependencies or building your project.
5. Save and commit the .gitlab-ci.yml file to your GitLab repository.
6. GitLab will automatically detect the .gitlab-ci.yml file and trigger the defined job whenever there are changes pushed to the repository.
7. Monitor the progress and results of the CI pipeline in the GitLab CI/CD interface.

You can use the following example job to get started. Make sure to customize this job with your specific build environment and build steps.

# You can copy and paste this template into a new `.gitlab-ci.yml` file.
# You should not add this template to an existing `.gitlab-ci.yml` file by using the `include:` keyword.

stages:
  - Scan
Endor Labs Dependency Scan:
  stage: test
  image: node # Modify this image to align with the build tools necessary for building your software packages
  dependencies: []
  variables:
    ENDOR_ENABLED: "true"
    ENDOR_ALLOW_FAILURE: "false"
    ENDOR_NAMESPACE: "example" # Replace with your Endor Labs namespace
    ENDOR_PROJECT_DIR: "."
    ENDOR_ARGS: |
      --path=${ENDOR_PROJECT_DIR}
      --detached-ref-name=$CI_COMMIT_REF_NAME
      --output-type=summary
      --exit-on-policy-warning
      --dependencies --secrets --git-logs
  before_script:
    - npm install yarn # Replace with the build steps for your Endor Labs job.
  script:
    - curl https://api.endorlabs.com/download/latest/endorctl_linux_amd64 -o ./endorctl;
    - echo "$(curl -s https://api.endorlabs.com/sha/latest/endorctl_linux_amd64)  ./endorctl" | sha256sum -c;
    - chmod +x ./endorctl
    - ./endorctl scan ${ENDOR_ARGS}
  rules:
    - if: $ENDOR_ENABLED != "true"
      when: never
    - if: $ENDOR_ALLOW_FAILURE == "true"
      allow_failure: true
    - if: $ENDOR_ALLOW_FAILURE != "true"
      allow_failure: false

If you use Endor Labs with an EU tenant, use https://api.eu.endorlabs.com instead of https://api.endorlabs.com.

SAST scans in GitLab

You can run SAST scans in your GitLab CI pipeline to identify security vulnerabilities and code quality issues in your source code. SAST scanning analyzes your source code for potential security weaknesses based on enabled rules and generates findings based on your configured finding policies.

SAST scan

To run a SAST scan, add --sast to your ENDOR_ARGS variable.

variables:
  ENDOR_ARGS: |
    --path=${ENDOR_PROJECT_DIR}
    --sast
    --dependencies --secrets

script:
  - ./endorctl scan ${ENDOR_ARGS}

AI SAST detection agent scan

To run an AI SAST detection agent scan, add --ai-sast to your ENDOR_ARGS variable. The AI SAST detection agent identifies security vulnerabilities beyond traditional rule-based SAST detection.

variables:
  ENDOR_ARGS: |
    --path=${ENDOR_PROJECT_DIR}
    --ai-sast
    --dependencies --secrets

script:
  - ./endorctl scan ${ENDOR_ARGS}

AI SAST MR scan

To run an AI SAST MR scan, add --ai-sast, --pr, --pr-incremental, and --pr-baseline to your ENDOR_ARGS variable. The scan analyzes only the code changed by the merge request and surfaces the net new findings introduced by the change. A baseline AI SAST scan must exist on the target branch first. See AI SAST PR scans to learn more.

variables:
  ENDOR_ARGS: |
    --path=${ENDOR_PROJECT_DIR}
    --ai-sast
    --pr
    --pr-incremental
    --pr-baseline=main

script:
  - ./endorctl scan ${ENDOR_ARGS}

Set up branch tracking in GitLab

In Git, a detached HEAD state occurs when the repository checks out a specific commit instead of a branch reference. In this state, Git points the HEAD directly to a commit hash, without associating it with a named branch. Proper branch context enables Endor Labs to:

• Associate scans with the correct branch
• Identify scans on the monitored default branch
• Track findings and display metrics accurately across branches

Without proper branch configuration, Endor Labs may create multiple branch entries for the same logical branch, leading to fragmented reporting and inaccurate metrics.

variables:
  ENDOR_ARGS: |
    --path=${ENDOR_PROJECT_DIR}
    --detached-ref-name=$CI_COMMIT_REF_NAME
    --dependencies --secrets

script:
  - ./endorctl scan ${ENDOR_ARGS}

Run MR scans

MR scans are point-in-time scans that run on merge requests to detect new policy violations and security issues introduced by the changes. Unlike default branch scans which create monitored versions, MR scans compare findings against the baseline to surface only new issues. To run scans on merge requests, use the --pr flag. This flag tells endorctl to treat the scan as a merge request scan and compare findings against the target branch baseline.

Endor Labs MR Scan:
  stage: test
  image: node
  variables:
    ENDOR_NAMESPACE: "example" # Replace with your Endor Labs namespace
    ENDOR_PROJECT_DIR: "."
    ENDOR_ARGS: |
      --path=${ENDOR_PROJECT_DIR}
      --detached-ref-name=$CI_COMMIT_REF_NAME
      --pr
      --dependencies --secrets
  before_script:
    - npm install # Replace with your build steps
  script:
    - curl https://api.endorlabs.com/download/latest/endorctl_linux_amd64 -o ./endorctl
    - chmod +x ./endorctl
    - ./endorctl scan ${ENDOR_ARGS}
  rules:
    - if: $CI_MERGE_REQUEST_IID

Enable MR comments

You can enable MR comments in your GitLab CI pipeline to automatically post comments on merge requests when policy violations are detected. MR comments build on top of MR scans by posting the scan results directly on the merge request.

Configure a GitLab token: Configure a GitLab CI/CD variable following the same steps as described in Configure API key and secret in GitLab. Add a variable with the key ENDOR_SCAN_SCM_TOKEN and set its value to your GitLab personal access token with the api scope. Make sure to select Mask variable under Flags.

Configure the pipeline for MR comments

The following example configuration enables MR comments in your GitLab CI pipeline:

Endor Labs MR Scan:
  stage: test
  image: node
  variables:
    ENDOR_NAMESPACE: "example" # Replace with your Endor Labs namespace
    ENDOR_PROJECT_DIR: "."
    ENDOR_ARGS: |
      --path=${ENDOR_PROJECT_DIR}
      --detached-ref-name=$CI_COMMIT_REF_NAME
      --pr
      --enable-pr-comments
      --scm-pr-id=$CI_MERGE_REQUEST_IID
      --scm-token=$ENDOR_SCAN_SCM_TOKEN
      --dependencies --secrets
  before_script:
    - npm install # Replace with your build steps
  script:
    - curl https://api.endorlabs.com/download/latest/endorctl_linux_amd64 -o ./endorctl
    - chmod +x ./endorctl
    - ./endorctl scan ${ENDOR_ARGS}
  rules:
    - if: $CI_MERGE_REQUEST_IID

Configure an action policy

After you enable MR comments, you need to set up an action policy to allow comments to be posted on merge requests. See Configure Action policy for PR comments for more information.