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:

CxFlow is an open source project written and maintained by Checkmarx. For access to CxFlow’s Wiki, please refer to CxFlow Wiki.

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:

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/v3/Checkmarx.gitlab-ci.yml'

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:

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

variables:
    CHECKMARX_SCAN_PRESET: "OWASP Top 10 - 2017"
    CX_FLOW_ENABLED_VULNERABILITY_SCANNERS: "sast, sca"
    SCA_TEAM: "/CxServer/team"
    SCA_FILTER_SEVERITY: "High"

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

variables:
    CHECKMARX_SETTINGS_OVERRIDE: "true"
    CHECKMARX_EXCLUDE_FILES: "node_js/"

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.

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.

variables:
    GITLAB_URL: http://mygitlab.mycompany.com

For Proxy support, you need to override the CX_FLOW_EXE command in your .gitlab-ci.yml file. Enter the appropriate host, port, user, and password as show here:

variables:
    CX_FLOW_EXE: "java -Dhttp.proxyHost=myproxyserver.com -Dhttp.proxyPort=9595 -Dhttp.proxyUser=<proxy user> -Dhttp.proxyPassword=<proxy password> -jar /app/cx-flow.jar"

For detailed info, please refer to CxFlow Proxy & HTTPS Configuration.

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:

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:

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