Skip to main content

Checkmarx One GitLab Integration

You can integrate Checkmarx One into your GitLab CI/CD pipelines using our CLI Tool. You can run Checkmarx One scans as well as perform other Checkmarx One commands using the CLI Tool.

There are two versions of the template used for this integration, template v1 and template v2. Template v2 provides the following extra functionality:

  • Generates a merge request decoration (requires a GitLab Personal Access Token with `API` scope)

    image.png
  • Output scan results in gl-sast format for display in the GitLab Security Dashboard (requires a GitLab license that includes the Security Dashboard)

    image__1_.png

Prerequisites

Initial Setup

Before running Checkmarx One CLI commands in your GitLab pipelines, you need to configure access to Checkmarx One. This is done by specifying the server URLs, tenant account, and authentication credentials for accessing your Checkmarx One environment. Once this is configured, you can create a job to run a Checkmarx One scan or to run other CLI commands.

  1. In your GitLab console, in the main navigation click on Settings > CI/CD, then scroll down to the Variables section and click Expand.

  2. Create variables for each of the items shown in the table below, using the following procedure.

    1. Click Add variable.

      The Add variable window opens.

      6165627651.png
    2. For Key, enter a name for the variable.

    3. For Value, enter the value for that variable.

    4. For Type, verify that Variable is selected(default).

    5. For Flags, select Masked for your authentication credentials so that the values are not shown in the open.

    6. Click Add variable.

    Key

    Value

    CX_BASE_URI

    CX_BASE_AUTH_URI

    CX_TENANT

    The name of your tenant account.

    CX_CLIENT_ID and CX_CLIENT_SECRET

    These values are obtained from the Checkmarx One web application, see Creating an OAuth Client for Checkmarx One Integrations.

    GITLAB_TOKEN

    (for v2)

    Generate a GitLab Personal Access Token with the scope `API`, and submit the value in this variable. This will enable Checkmarx One to decorate the merger request with the scan results summary.

    6143311909.png

Running a Checkmarx One Scan in a Pipeline

To add a Checkmarx One scan to a pipeline:

  1. Include the template in your pipeline using the following code:

    Template v1

    include: 'https://raw.githubusercontent.com/Checkmarx/ci-cd-integrations/main/GitlabCICD/v1/CheckmarxCLI.gitlab-ci.yml'

    Template v2

    include: 'https://raw.githubusercontent.com/Checkmarx/ci-cd-integrations/main/GitlabCICD/v2/CheckmarxCLI.gitlab-ci.yml'
  2. If you are using template v2 and your GitLab license includes "Security Dashboard", you can send results to the Security Dashboard using the following configuration:

    variables:
      SECURITY_DASHBOARD: "true"
  3. Optionally, you can customize the scan by adding additional parameters. For a complete list of additional parameters, see Flags. For example, you can run the scan in debug mode and apply the SAST preset "High and Medium, as follows:

    variables:  CX_ADDITIONAL_PARAMS: "--debug --sast-preset-name 'High and Medium'"

Notice

By default, a pipeline is triggered in GitLab whenever an event occurs in the repo, such as a push, pull request etc. Alternatively, you can schedule pipeline runs, or create external triggers. You can also customize the rules for triggering jobs within a pipeline, using the procedures described in Choose when to run jobs.

Note

See a sample template for running a Checkmarx One scan here.