GitLab Runner Integration

GitLab is an open-core company that provides GitLab, a DevOps software package that combines the ability to develop, secure, and operate software in a single application. Its application, GitLab Runner, works with GitLab CI/CD to run jobs in a pipeline.

The following configuration examples show how to install & run the scanner using an API Token stored as a secret named XYGENI_TOKEN. See Generate Xygeni API Token for Scanner or ask your Xygeni administrator to generate it.

See CI/CD variables and using external secrets in CI for details on how to register the Xygeni API token for use in GitLab CI.

Using the CI/CD Component

The CI/CD Component may not be available with an Gitlab On-Premise solution.

Xygeni provides an officially supported GitLab CI/CD Component named xygeni-scanner, available in the GitLab Marketplace: Gitlab Xygeni CI/CD Component

This component runs multiple kinds of scans on the GitLab repository. The scanner is automatically updated and cached for performance. All you need is a Xygeni API token registered as a pipeline secret.

To add this component to your CI/CD pipeline, add the following to your project's .gitlab-ci.yml:

include:
  - component: $CI_SERVER_FQDN/xygeni/gitlab-ci-integration/xygeni-scanner@<tag>
    inputs:
      stage: test
      # any additional input follows

# Create a job that extends the template
xygeni-scanner:
  extends: .xygeni-scanner-job

Where <tag> is the release tag you want to use (releases list). Use ~latest for the latest published component.

Using ~latest is not recommended: it is safer to always pin components to a specific release, to avoid supply chain attacks. In the following examples we use ~latest so you can copy and paste the examples for testing. Set a specific release in production environments.

The component provides a hidden job template .xygeni-scanner-job that you extend with your own job name. This allows you to customize the job name and add additional configuration like artifacts, allow_failure, or other job-level settings.

Multiple Configurations

You can include the component multiple times with different configurations by using the name input parameter. Each unique name creates a separate template that won't collide:

include:
  # Secrets scan configuration
  - component: $CI_SERVER_FQDN/xygeni/gitlab-ci-integration/xygeni-scanner@~latest
    inputs:
      name: secrets
      stage: test
      run: secrets
      to-xygeni: false
      fail-on: high

  # Full security scan configuration
  - component: $CI_SERVER_FQDN/xygeni/gitlab-ci-integration/xygeni-scanner@~latest
    inputs:
      name: full
      stage: security
      run: sast,deps,suspectdeps,misconf
      to-vuln-report: true

# Create jobs extending each template
secrets-scan:
  extends: .xygeni-scanner-secrets

full-security-scan:
  extends: .xygeni-scanner-full
  artifacts:
    reports:
      sast: gl-xygeni-sast-sast.json
      dependency_scanning: gl-xygeni-suspectdeps-dependency_scanning.json

The job in template follows the pattern .xygeni-scanner-<name>, where <name> is the value of the name input (defaults to job). Extend the appropriate job as needed.

For more examples of uses please go to the Gitlab page of the CI/CD component: https://gitlab.com/explore/catalog/xygeni/gitlab-ci-integration

Without using the CI/CD Component

For Cloud Based Gitlab, the CI/CD component is the recommended option. Use this option only if the CI/CD Component is not available.

The CI/CD Component may not be available in some Gitlab On-Premise installations, in this case, the pipeline must be configured manually.

Move to the left panel, Build>Pipeline Editor and Create a new pipeline or modify the existing one. And add the following code and make sure the stage name marches the defined stages in the pipeline:

.xygeni-scan-definition:
  image: maven:3.9-eclipse-temurin-21

  before_script:
    - apt-get update && apt-get install -y unzip curl

  script:
    - curl -L https://get.xygeni.io/latest/scanner/install.sh | /bin/bash -s -- -t "${XYGENI_TOKEN}" -s https://api.xygeni.io
    - |
      $HOME/.xygeni/xygeni scan --never-fail -d $CI_PROJECT_DIR

xygeni_scan:
  stage: test
  extends: .xygeni-scan-definition

Integrate with Gitlab Security Reports

GitLab provides built-in security reporting capabilities that allow you to view security vulnerabilities directly within your GitLab project. When integrated with Xygeni, security findings can be automatically sent to GitLab's security dashboard, providing a centralized view of your project's security posture.

Sending Xygeni Secrets Findings to GitLab

Xygeni can automatically send secrets detection findings to GitLab's security dashboard using the following command:

include:
  - component: $CI_SERVER_FQDN/xygeni/gitlab-ci-integration/xygeni-scanner@~latest
    inputs:
      stage: test
      to-vuln-report: true

xygeni-scanner:
  extends: .xygeni-scanner-job
  # Map the GitLab reports generated to the GL security scan category
  artifacts:
    reports:
      secret_detection: gl-xygeni-secrets-secret-detection.json
      sast: gl-xygeni-sast-sast.json

  allow_failure: true

The allow_failure: true setting ensures that secrets findings don't block pipeline execution while still reporting them to GitLab's security dashboard for review and remediation.

GitLab CI/CD Configuration:

To properly receive Xygeni findings, ensure your GitLab project has the security scanning features enabled. The findings will appear in:

• Security & Compliance > Vulnerability Report

• CI/CD > Pipelines > Security tab for each pipeline run

• Project > Security Dashboard

Benefits of Integration:

• Centralized security reporting in GitLab

• Automated vulnerability tracking

• Historical trend analysis

• Integration with GitLab's issue tracking system

• Compliance reporting capabilities