Checkmarx integrates with GitLab, enabling the identification of new security vulnerabilities with proximity to their creation. GitLab integration triggers Checkmarx scans as defined by the GitLab CI/CD pipeline. Once a scan is completed, both scan summary information and a link to the Checkmarx Scan Results will be provided. Both CxSAST and CxSCA are supported within the GitLab integration.
CxFlow is a Spring Boot application written by Checkmarx that enables initiations of scans and result orchestration. It is the main automation driving the GitLab and Checkmarx integration. Some features of CxFlow include:
Automated project creation
Facilitates feedback channels in a closed loop nature
Channels include GitLab Issues, GitLab Merge Requests, JIRA, Rally, and ServiceNow.
Enables customers to incorporate Checkmarx into their DevOps/Release pipelines as early as possible
Controls the “breaking” of builds
CxFlow is an open source project written and maintained by Checkmarx. For access to CxFlow’s Wiki, please refer to CxFlow Wiki.
GitLab Integration Flow
There are several ways of integrating Checkmarx security scans into GitLab’s ecosystem. This document specifically outlines how to integrate GitLab with Checkmarx’s Containerized CxFlow CLI. For more info on integrating with GitLab’s Webhook feature, please refer to CxFlow Webhook Workflows.
The following steps represent the containerized CxFlow CLI integration flow:
GitLab’s CI/CD pipeline is triggered (as defined in the .gitlab-ci.yml file)
During the test stage of GitLab’s CI/CD pipeline, Checkmarx’s containerized CxFlow CLI is invoked
CxFlow CLI triggers a security scan via the Checkmarx Scan Manager
Results can be configured to be displayed with GitLab’s ecosystem or a supported bug tracker via CxFlow YAML configuration
Results will be within Checkmarx Scan Results within the Checkmarx Manager Server
Results can be accessed within GitLab’s Merge Request Overview (if the scan was initiated during a Merge Request)
Results can be accessed within GitLab’s Issues if configured (or can be filtered into external bug tracker tools)
Results can be accessed within GitLab’s security dashboard, if you have access to it (Gold/Ultimate packages or if your project is public)
Within GitLab, CxFlow CLI will zip the source directory of the repository and send it to the Checkmarx Scan Manager to perform the security scan.
GitLab can access a running Checkmarx CxSAST Server with an up-to-date Checkmarx license
If performing CxSCA scans, you must have a valid CxSCA license and GitLab must be able to access the CxSCA tenant
To review scan results within GitLab’s Security Dashboard, you need the Gold/Ultimate tier or the GitLab project must be public
To review results in the issue management of your choice (i.e. JIRA) configuration is needed in the CxFlow YAML file, please refer to CxFlow Bug Trackers
To allow for easy configuration, it is necessary to create environment variables with GitLab to run the integration. For more information on GitLab CI/CD variables, visit here: GitLab: CI/CD - Environment Variables
Edit the CI/CD variables under Settings → CI / CD → Variables and add the following variables for a CxSAST and/or CxSCA scan :
The key CX_FLOW_CONFIG variable must be of type "File"
API token to create Merge Request Overview entries, should have “api” privileges.
To create a personal token, click your Gitlab profile in the upper right corner >settings
For additional information on creating a Personal Access Token, refer to GitLab: Personal Access Tokens
Type of bug tracking ('GitLabDashboard' or ‘GitLab’). For vulnerabilities to be exported to GitLab’s Dashboard, use ‘GitLabDashboard’ and for vulnerabilities to be added to GitLab’s Issues, use ‘GitLab’. For more details on complete list of Bug Trackers, please refer to CxFlow Configuration
Password for CxSAST
The base URL of CxSAST Manager Server (i.e. https://checkmarx.company.com)
User Name for the CxSAST Manager. User must have ‘SAST Scanner’ privileges. For more information on CxSAST roles, please refer to CxSAST / CxOSA Roles and Permissions (v9.0.0 and up)
enable-vulnerability-scanners: - sca and the sca block are only needed if you have a valid CxSCA license and tenant.
The CxSCA URLs shown in the config file below are for the US environment. For the EU environment, use the following URLs:
Checkmarx Team Name (i.e. /CxServer/teamname)
The name of the CxSCA Account (i.e. SCA-CompanyName). Only needed if you have a valid license for CxSCA.
The username of the CxSCA Account. Only needed if you have a valid license for CxSCA.
The password of the CxSCA Account. Only needed if you have a valid license for CxSCA.
The above CX_FLOW_CONFIG File Variable is just an example and can be configured in many ways. Please refer to CxFlow Configuration for documentation on options to configure CxFlow.
The GitLab CI/CD pipeline is controlled by a file named ‘.gitlab-ci.yml’ located in the root directory of the project. Please refer to GitLab: CI YAML for more info.
It is suggested not to over-pollute your companies already existing '.gitlab-ci.yml' file. Instead, create a new YAML file in the root directory named ‘.checkmarx.yml’ and include it in ‘.gitlab-ci.yml’.
To run a Checkmarx scan, you need to trigger the pipeline. The trigger is based on the .gitlab-ci.yml and in the provided sample above, it will be triggered on Merge Requests and on changes to the master branch.
For information on triggering a pipeline scan, please refer to GitLab: Triggering a pipeline
For information on Merge Requests, please refer to GitLab: Merge Requests
While the scan results will always be available in the Checkmarx UI, users can also access results within the GitLab ecosystem. Currently there are three different ways to review results from the scan:
Merge Request Overview
Merge Request Discussion
When you have configured the .gitlab-ci.yml file to scan on merge_requests issues (please refer to GitLab: Pipelines for Merge Requests), a high level report of the Checkmarx scan will be displayed within GitLab Merge Request Overview.
An example of a Merge Request with a Checkmarx scan report can be found in the below image.
When you have configured the BUG_TRACKER variable to use “GitLab”, CxSAST and CxSCA issues found in Checkmarx will be opened within GitLab Issues. For more information on GitLab issues, please refer to GitLab: Issues
An example of Issues created can be found in the below image.
With the Gold/Ultimate tier for GitLab, or if the project is public, you can review results in GitLab’s Security Dashboard. tFor information on GitLab’s Security Dashboard, please refer to GitLab: Security Dashboard
An example of vulnerabilities displayed in the Security Dashboard can be found in the below image.
If you are using TLS, you will need to add additional options or you will see an error.
When executing the CxFlow container commands from the following error is displayed:
ERROR 11 --- [ main] com.checkmarx.flow.CxFlowRunner : An error occurred while processing request
148 org.springframework.web.client.ResourceAccessException: I/O error on POST request for "https://checkmarx.company.net/cxrestapi/auth/identity/connect/token": sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target; nested exception is javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target
The TLS certificate of the Checkmarx server is not trusted by the CxFlow client. This may be because the Checkmarx server’s TLS certificate is self-signed. Another possibility is that the Checkmarx server’s TLS Certificate was signed by a certificate authority (CA) internal to the company.
You have to put the correct certificate into the container’s trusted certificate store:
Obtain the correct certificate. If the Checkmarx server’s TLS certificate is self-signed, then you need the Checkmarx server’s TLS certificate. If the TLS certificate was signed by a company-internal CA, then you need the certificate of the internal CA. Get it in PEM Format, it’ll have a format of:
Create a variable of type FILE inside GitLab. Name it LOCAL_CA_CERT. Paste the contents of the certificate PEM file there.
In the .checkmarx.yml add the following script: lines prior to the java –jar /app/cx-flow.jar
Have a question? Want to report an issue? Contact Checkmarx support