- Checkmarx Documentation
- Checkmarx One
- Checkmarx One Integrations
- CI/CD Integrations
- Checkmarx One CLI Integrations for CI/CD
- Checkmarx One GitLab Integration
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)
Output scan results in gl-sast and gl-sca format for display in the GitLab Security Dashboard (requires a GitLab license that includes the Security Dashboard)
Prerequisites
You have a Checkmarx One account and you have an OAuth Client for Checkmarx One authentication. To generate the required authentication, see Creating an OAuth Client for Checkmarx One Integrations.
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.
In your GitLab console, in the main navigation click on Settings > CI/CD, then scroll down to the Variables section and click Expand.
Create variables for each of the items shown in the table below, using the following procedure.
Click Add variable.
The Add variable window opens.
For Key, enter a name for the variable.
For Value, enter the value for that variable.
For Type, verify that Variable is selected(default).
For Flags, select Masked for your authentication credentials so that the values are not shown in the open.
Click Add variable.
Key
Value
CX_BASE_URI
US Environment - https://ast.checkmarx.net
US2 Environment - https://us.ast.checkmarx.net
EU Environment - https://eu.ast.checkmarx.net
EU2 Environment - https://eu-2.ast.checkmarx.net
DEU Environment - https://deu.ast.checkmarx.net
Australia & New Zealand – https://anz.ast.checkmarx.net
India - https://ind.ast.checkmarx.net
Singapore - https://sng.ast.checkmarx.net
UAE - https://mea.ast.checkmarx.net
Israel - https://gov-il.ast.checkmarx.net
CX_BASE_AUTH_URI
US Environment - https://iam.checkmarx.net
US2 Environment - https://us.iam.checkmarx.net
EU Environment - https://eu.iam.checkmarx.net
EU2 Environment - https://eu-2.iam.checkmarx.net
DEU Environment - https://deu.iam.checkmarx.net
Australia & New Zealand – https://anz.iam.checkmarx.net
India - https://ind.iam.checkmarx.net
Singapore - https://sng.iam.checkmarx.net
UAE - https://mea.iam.checkmarx.net
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 merge request with the scan results summary.
Running a Checkmarx One Scan in a Pipeline
To add a Checkmarx One scan to a pipeline:
For a standard integration, include template v1 in your pipeline using the following code:
include: 'https://raw.githubusercontent.com/Checkmarx/ci-cd-integrations/main/GitlabCICD/v1/CheckmarxCLI.gitlab-ci.yml'
Alternatively, if you would like to generate merge request decorations and output SAST and SCA results to GitLab Security Dashboard, include template v2 in your pipeline, as follows.
Use the following code to include the v2 template.
include: 'https://raw.githubusercontent.com/Checkmarx/ci-cd-integrations/main/GitlabCICD/v2/CheckmarxCLI.gitlab-ci.yml'
Set the following variable configuration.
variables: SECURITY_DASHBOARD: "true" SECURITY_DASHBOARD_ON_MR: "true"
Notice
SECURITY_DASHBOARD "true" sends results for branch scans triggered in your pipeline to the Security Dashboard. SECURITY_DASHBOARD_ON_MR "true" sends results from scans triggered by merge requests to the Security Dashboard. You can choose to enable one or the other according to your needs.
Go to Security > Settings on the account level and add the relevant project to the list of Monitored projects.
For both templates, you can optionally 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.