GitLab is a web-based DevOps life cycle tool that provides a Git-repository manager providing wiki, issue-tracking and continuous integration/continuous deployment pipeline features. GitLab offers the ability to automate the entire DevOps life cycle from planning to creation, build, verify, security testing, deploying, and monitoring offering high availability and replication, and scalability and available for using on-prem or cloud storage.
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) extra configuration is needed, 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 :
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
Click Access Tokens and add a personal access token.
Give the token api, read_user, write_repository, read_registry scopes.
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
If you need to override any parameters or variables of the scan, all you need to do is define the variables in the .gitlab-ci.yml file. For example, let’s say you want to use a different preset and also enable CxSCA scans with filtering on High. Your .gitlab-ci.yml file would look like this:
With GitLab, the order of precedence when it comes to variables is:
Variables defined in .gitlab-ci.yml file
Variables defined in Checkmarx template file
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.
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. For 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.
On Premise GitLab
For On Premise GitLab Instances, you need to override the GITLAB_URL command in your .gitlab-ci.yml file. By default, it points to the cloud version of GitLab so you need to input the location of your GitLab instance. Below is an example, replace ‘http://mygitlab.mycompany.com’ with the location of your on premise GitLab instance.
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:
------- BEGIN CERTIFICATE -------
------- END CERTIFICATE --------
Create a variable of type FILE inside GitLab. Name it LOCAL_CA_CERT. Paste the contents of the certificate PEM file there.