GitHub Actions Integration

GitHub Actions makes it easy to automate all your software workflows with the CI/CD feature built into GitHub. Users can build, test, and deploy their code right from GitHub by using GitHub Actions. By triggering events within GitHub Actions, code reviews, branch management, issue triaging and security testing work the way you want.

General

Checkmarx integrates with GitHub Actions, enabling the identification of new security vulnerabilities with proximity to their creation. GitHub Action integration triggers Checkmarx scans as defined by the triggering event in GitHub Actions. Once a Checkmarx 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 GitHub Actions integration.

Checkmarx’s GitHub Action can also publish Security Alerts to GitHub’s Code Alerting feature with Checkmarx’s supported SARIF output.

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 GitHub Actions and Checkmarx integration. Some features of CxFlow include:

Automated project creation
Facilitates feedback channels in a closed loop nature
- Channels include GitHub Issues, GitHub Pull 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.

GitHub Actions Integration Flow

These directions specifically outlines how to integrate GitHub Actions with Checkmarx’s Containerized CxFlow CLI. For more info on integrating with GitHub’s Webhook feature, please refer to CxFlow Webhook Workflows.

The following steps represent the containerized CxFlow CLI integration flow:

GitHub’s Actions pipeline is triggered - usually by either a Pull Request or a Commit (as defined by the Workflow created)
As part of the trigger, Checkmarx’s containerized CxFlow CLI is invoked
CxFlow CLI triggers a security scan via the Checkmarx Scan Manager
Results will be displayed within GitHub’s Pull Request or a supported bug tracker via additional parameter configuration
1. Results will be within Checkmarx Scan Results within the Checkmarx Manager Server
2. Results can be accessed within GitHub’s Pull Request Overview (if the scan was initiated during a Pull Request)
3. Results can be accessed within GitHub’s Issues if configured (or can be filtered into external bug tracker tools)
4. Results can be accessed within GitHub’s code alerting, if you have access to it (GitHub Enterprise - Advance Security)

Notice

Within GitHub, CxFlow CLI will zip the source directory of the repository and send it to the Checkmarx Scan Manager to perform the security scan.

Requirements

GitHub 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 GitHub must be able to access the CxSCA tenant
To review scan results within GitHub’s Code Alerting you need the GitHub Enterprise - Advance Security tier or the GitHub project must be public
- To review results in the issue management of your choice (i.e., JIRA) configuration is needed in the additional parameters, please refer to CxFlow Bug Trackers

Secret Variables

To allow for easy configuration, it is necessary to create environment variables with GitHub to run the integration. Secrets should be set at the organization level so you don’t have to create them per project. For more information on GitHub Secret variables, visit here: GitHub: CI/CD - Secrets. The following secrets are need. Note, the secret names below can be named whatever you choose, the just have to match up to the secret names referenced in your workflow yaml file.

Variable	Value
GH_TOKEN	API token to create Pull Request Overview entries, should have privileges to update the Pull Request. To create a personal token, click your GitHub profile in the upper right corner ->Settings Click on Developer settings Click Personal access Tokens and add a personal access token. Generate new token Select the correct permissions to update the Pull Request For additional information on creating a Personal Access Token, refer to GitHub: Personal Access Tokens
CHECKMARX_PASSWORD	Password for CxSAST Manager
CHECKMARX_SERVER	The base URL of CxSAST Manager Server (i.e., https://checkmarx.company.com)
CHECKMARX_USERNAME	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)
SCA_USERNAME	The username of the CxSCA Account. Only needed if you have a valid license for CxSCA.
SCA_PASSWORD	The password of the CxSCA Account. Only needed if you have a valid license for CxSCA.

GitHub Actions Configuration

The GitHub Actions workflow is controlled by yaml files located in the root directory of the project. These yaml files are triggered by different events in GitHub such as a Pull Request or Commit. Please refer to GitHub Action: YAML for more info.

Pull Request

For an example on adding a GitHub Action that is triggered by a Pull Request, please refer to Sample Workflow Pull Request YAML.

Commit

For an example on adding a GitHub Action that is triggered by a Commit, please refer to Sample Workflow Commit YAML.

Run Pipeline

To run a Checkmarx scan, you need to trigger the GitHub Action. The trigger is automatically performed based on the GitHub Action trigger event that was created in the provided sample above; it will be triggered on Pull Requests and Commits to the main branch. You can also trigger it manually.

For information on manually running a GitHub Action, please refer to GitHub Actions: Manual Run

Review Results

While the scan results will always be available in the Checkmarx CxSAST Manager, users can also access results within the GitHub ecosystem.

Pull Request Discussion

When you have configured the GitHub Action file to scan on Pull Requests issues (please refer to GitHub: Pull Requests), a report of the Checkmarx scan will be displayed within GitHub Pull Request Overview.

An example of a Pull Request with a Checkmarx scan report can be found in the below image.

GitHub Issues

When you have configured the --bug-tracker option to use “GITHUBPULL” in the ‘params’ field of the GitHub Action yaml file, CxSAST and CxSCA issues found in Checkmarx will be opened within GitHub Issues. For more information on GitHub Issues, please refer to GitHub: Issues.

Code Alerting

With Code Alerting enabled, you can review results in GitHub’s Security Tab. For information on GitHub's Code Alerting, please refer to GitHub: Code Alerting.

This is done by uploading the SARIF file Checkmarx creates when a GitHub Action is triggered. You need to add another step in your yaml file that uploads the file ‘cx.sarif’. For more information, please refer to: GitHub: Upload SARIF and refer to the yaml code snippet below:

    - name: Upload SARIF file
      uses: github/codeql-action/upload-sarif@v1
      with:
        sarif_file: cx.sarif

In this section: