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.


General

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 Overview

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:

  1. GitLab’s CI/CD pipeline is triggered (as defined in the .gitlab-ci.yml file)

  2. During the test stage of GitLab’s CI/CD pipeline, Checkmarx’s containerized CxFlow CLI is invoked

  3. CxFlow CLI triggers a security scan via the Checkmarx Scan Manager

  4. Results can be configured to be displayed with GitLab’s ecosystem or a supported bug tracker via CxFlow YAML configuration

    1. Results will be within Checkmarx Scan Results within the Checkmarx Manager Server

    2. Results can be accessed within GitLab’s Merge Request Overview (if the scan was initiated during a Merge Request)

    3. Results can be accessed within GitLab’s Issues if configured (or can be filtered into external bug tracker tools)

    4. 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.

Requirements

  • 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

CI/CD Variables

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 :

Variable

Value

GITLAB_TOKEN

(Type: Variable)

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.

For additional information on creating a Personal Access Token, refer to GitLab: Personal Access Tokens

CX_FLOW_BUG_TRACKER

(Type: Variable)

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

CHECKMARX_PASSWORD

(Type: Variable)

Password for CxSAST

CHECKMARX_BASE_URL

(Type: Variable)

The URL of CxSAST Manager Server (i.e. https://checkmarx.company.com)

CHECKMARX_USERNAME

(Type: Variable)

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)

CX_TEAM

(Type: Variable)

Checkmarx Team Name (i.e. /CxServer/teamname)

SCA_TENANT

(Type: Variable)

The name of the CxSCA Account (i.e. SCA-CompanyName). Only needed if you have a valid license for CxSCA.

SCA_USERNAME

(Type: Variable)

The username of the CxSCA Account. Only needed if you have a valid license for CxSCA.

SCA_PASSWORD

(Type: Variable)

The password of the CxSCA Account. Only needed if you have a valid license for CxSCA.

Pipeline Configuration

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.

note

If you are using TLS certificates, please review the Advanced Options section

If you are using TLS certificates, please review the Advanced Options section

.gitlab-ci.yml

Checkmarx provides a template that you can use that already has jobs defined for the pipeline. All you need to do is add this one line that includes the template file.

include: 'https://raw.githubusercontent.com/checkmarx-ltd/cx-flow/develop/templates/gitlab/v2/Checkmarx.gitlab-ci.yml'

Run Pipeline

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.

Review Results

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

  • GitLab Issues

  • Security Dashboard

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.

GitLab Issues

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.

Security Dashboard

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.

Advanced Options

Adding Certs

If you are using TLS, you will need to add additional options or you will see an error.

Symptoms:

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

Problem:

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. 

Solution:

You have to put the correct certificate into the container’s trusted certificate store:

  1. 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 -------
    <CERT DATA>
    ------- END CERTIFICATE --------
  2. Create a variable of type FILE inside GitLab.  Name it LOCAL_CA_CERT. Paste the contents of the certificate PEM file there.

  3. In the .checkmarx.yml add the following job:

checkmarx-scan:
    before_script: 
      - cat ${LOCAL_CA_CERT} > localcert.cert
      - keytool -import -trustcacerts -alias localca -file localcert.cert –keystore $JAVA_HOME/lib/security/cacerts -storepass changeit –noprompt

Have a question?  Want to report an issue?  Contact Checkmarx support