Skip to main content

Quick Start Guide - Checkmarx One GitHub Action

Overview

The Checkmarx One GitHub Action enables you to trigger SAST, SCA, and KICS scans directly from the GitHub workflow. It provides a wrapper around the Checkmarx One CLI Tool which creates a zip archive from your source code repository and uploads it to Checkmarx One for scanning. The Github Action provides easy integration with GitHub while enabling scan customization using the full functionality and flexibility of the CLI tool.

The GitHub Action can be customized to trigger scans when particular actions (e.g., push, or pull request) occur on specific branches of your repo. You can also add pre and post scan steps to your workflow. For example, you can add a step to screen commits to verify if the changes made warrant running a new scan.

Note

The plugin code can be found here. Comprehensive documentation for using the Checkmarx One GitHub Action is available here.

Notice

There is an alternative method for integrating GitHub with Checkmarx One which is done directly from Checkmarx One, see GitHub Cloud. That method is easier to implement but doesn’t enable full customization of the process.

Prerequisites

  • The source code for your project is hosted on a GitHub repo (public or private)

  • You have a Checkmarx One account and have credentials to log in to your account

Getting Started Using the GitHub Action

This tutorial will guide you through the initial setup and basic workflow for using the Checkmarx One GitHub Action. We will use an OAuth2 Client to authenticate with Checkmarx One and we will configure an Action to trigger a scan whenever a push commit is done on your GitHub repo.

Step 1 – Create an OAuth2 Client in Checkmarx One

For this tutorial we will create an OAuth2 Client in Checkmarx One to be used for authentication in the GitHub Action. To create an OAuth2 client, see Creating an OAuth2 Client for Checkmarx One Integrations.

Notice

An alternative method is to generate an API Key and use that for authentication.

Step 2 – Configure Secrets in Your GitHub Repository

In order to avoid passing authentication data in the open, we will create GitHub Secrets for the Client ID and Secret.

  1. In the GitHub console, open the repository for which you are setting up the Checkmarx One integration and click on the Settings tab.

  2. In the left side navigation panel, click Secrets and then click on New repository secret.

    5894539961.png
  3. Enter a Name for the Client ID Secret in GitHub and then in the Value field enter the name that you designated for the Client_ID in Checkmarx One.

    5894506850.png
  4. Repeat the above step to create a GitHub Secret for the Checkmarx One Client Secret, using the Value that you copied from Checkmarx One.

    The two Secrets are shown in the Secrets tab.

    5893884240.png

Step 3 – Set Up a GitHub Action

For this tutorial we will create a simple GitHub Action that triggers a scan using SAST, SCA and KICS scanners whenever a push commit is done on any one of the three specified branches.

  1. Navigate to your GitHub repository Actions tab and click New Workflow and then click on set up a workflow yourself.

    5908398103.bmp
  2. In the Edit new file section, enter the following code, which defines a standard action for triggering a scan when a push is made on the main, master or dev branch.

    name: Checkmarx One Scan
    on:
      push:
        branches:
          - main
          - master
          - dev
    jobs:
      build:
        runs-on: ubuntu-latest
        steps:
          - name: Checkout
            uses: actions/[email protected]
          - name: Checkmarx One CLI Action
            uses: checkmarx/[email protected] #Github Action version
            with:
              project_name: <Name of Checkmarx One Project>
              cx_tenant: <Checkmarx One Tenant Account>
              base_uri: <Checkmarx One Base uri> 
              cx_client_id: ${{ secrets.CLIENT_ID }}
              cx_client_secret: ${{ secrets.SECRET }}
  3. For project_name, enter the name of an existing Project in Checkmarx One or enter a new name to create a new Project.

    Notice

    The project_name parameter must not be left blank. You can omit the project_name parameter completely, in which case it will default to ${{ github.repository }}.

  4. For cx_tenant, enter the name of your Tenant Account.

  5. For base_uri, enter the base URL of your Checkmarx One Environment.

  6. For branch, enter the name of an existing branch of your Project or enter a new name to create a new branch.

    Notice

    The branch parameter must not be left blank. You can omit the branch parameter completely, in which case it will default to ${{ github.ref }}.

  7. You can customize the Action by adding additional arguments, see Checkmarx One GitHub Action Configuration Variables.

  8. Click Start Commit.

  9. In the dialog that opens, click Commit new file.

The Checkmarx One Action is added to the repo and an initial scan is run on the source code. Subsequent scans will be triggered each time a push commit is done.

Step 4 – Monitor the Build

  1. Navigate back to your GitHub repository Actions tab and click on your workflow run to see the build.

    5894637935.png
  2. Click on build to see details of the run.

    5903876114.png

    The build details are shown.

    5903876124.png

Step 5 – View Scan Results

  1. Go to the Checkmarx One Home page > Projects tab (default) and identify your Project in the list of Projects.

    5903876132.png
  2. You can click on the Project to drill-down to show more detailed results. For more information about viewing scan results, see Viewing the Project Page.