Skip to main content

GitHub Cloud

Overview

Checkmarx One supports GitHub integration, enabling automated scanning of your GitHub projects whenever the code is updated. Checkmarx One’s GitHub integration listens for GitHub commit events and uses a webhook to trigger Checkmarx scans when a push, or a pull request occurs. Once a scan is completed, the results can be viewed in Checkmarx One.

In addition, for pull requests, a comment is created in GitHub, which includes a scan summary, list of vulnerabilities and a link to view the scan results in Checkmarx One.

Notice

This integration supports both public and private git based repos.

The integration is done on a per project basis, with a specific Checkmarx One Project corresponding to a specific GitHub repo.

Notice

You can select several repos to create multiple integrations in a bulk action.

Note

There is an alternative method for integrating GitHub with Checkmarx One which is done by creating a GitHub Action for running Checkmarx One scans, see Quick Start Guide - Checkmarx One GitHub Action. That method is more complex to implement but it enables full customization of the process.

Prerequisites

  • The source code for your project is hosted on a GitHub repo.

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

    Important

    The user must have create-project permission.

  • The GitHub user has admin privileges for this repository, see Code Repository Integrations.

Setting up the Integration and Initiating a Scan

To integrate your GitHub organization with Checkmarx One, perform the following:

  1. In the Applications and Projects home page, click on New > New Project - Code Repository Integration.

    Code_Repo_Integration.png

    The Import From window opens.

    Image_946.png

  2. Select Cloud-hosted >GitHub.

    GitHub_Select.png

  3. Click Authorize.

    6428295198.png

  4. Select the GitHub User/Organization or Group (for the requested repository) and click Select Organization.

    The screen contains the following functionalities:

    • Search bar - Users need to type the full organization name (GitHub limitation). The search is not case sensitive.

    • Infinite scroll - For enterprises with a large amount of organizations.

    Note

    In case you selected GitHub User skip step 5.

    GitHub_Select_Org.png

  5. In the Organization Settings screen you can decide whether to enable the "Monitor new repositories creation" feature.

    For more information about the feature see Monitor New Repositories.

    GitHub_Org_Settings.png

  6. Select the Repository inside the GitHub organization and click Next.

    If the organization contains active repositories, suggested repos will be presented and selected automatically. For additional information see Suggested Repositories.

    Note

    • A separate Checkmarx One Project will be created for each repo that you import.

    • There can’t be more than one Checkmarx One Project per repo. Therefore, once a Project has been created for a repo, that repo is greyed out in the Import dialog.

    GitHub_Select_Repo.png

  7. In the Repositories Settings screen, configure the following and click Next.

    • Permissions:

      • Scan Trigger: Push, Pull request - Automatically trigger a scan when a push event or pull request is done in your SCM. (Default: On)

      • Pull Request Decoration - Automatically send the scan results summary to the SCM. (Default: On)

      • SCA Auto Pull Request - Automatically send PRs to your SCM with recommended changes in the manifest file, in order to replace the vulnerable package versions. (Default: Off)

    • Scanners: Select the scanners for All/Specific repositories. At least 1 scanner must be selected for each repository.

    • Protected Branches: Select which Protected Branches to scan for each repository.

      Note

      For additional information about Protected Branches see About Protected Branches

    • Add SSH key.

    • Assign Groups: Specify the Groups to which you would like to assign the project.

    • Assign Tags: Add Tags to the Project. Tags can be added as a simple strings or as key:value pairs.

    • Set Criticality Level: Manually set the project criticality level.

      GitHub_Repo_Settings.png

    Note

    If multiple repositories are selected, an additional configuration option will appear at the top of the wizard for applying settings to all selected repositories. Configure the necessary parameters, then scroll down on the right-side panel and click Apply to all.

    For example:

    All_Repo_Settings.png

  8. Select which Protected Branches to scan for each Repository and click Next.

    Note

    For additional information about Protected Branches see About Protected Branches

    GitHub_Select_Branches.png

  9. In the Advanced Options screen it is possible to select Scanning the default branch upon the creation of the Project.

    Click Create Project.

    GitHub_Advanced_Options.png

  10. The Project is successfully created in the Applications and Projects home page, and the scan is initiated.

    GitHub_scan_initiated.png

    Note

    In order to update the scanners see Imported Project Settings

Technical Info About GitHub Webhooks

The documentation referenced below relates to GitHub cloud. However, the APIs that are described are relevant for GitHub Enterprise (on prem) as well. 

Webhook listening endpoints

We have one endpoint for listening to webhook events. The endpoint is https://<cxone domain>/ast-flow-listener. This endpoint is registered as a webhook on GitHub with a shared key as per the GitHub spec (each webhook registration has a separate shared key). The Webhook is also registered with an encrypted tenant identifier in the URL query. This is used to validate the requesting tenant. GitHub produces a Hash using the shared key when submitting the event. This is used together with the tenant ID to authenticate the event. Please refer to the following GitHub documentation links:

API Endpoints

Common scenarios include, Commenting on PRs and setting their status (optional), and opening GitHub Issues. Documentation for the relevant APIs:

Notice

Git is used to clone the specific git url of a project being scanned – this would be the URL you see in GitHub for clone/interfacing with the project.

API Methods

Methods are used for CRUD actions, according to GitHub requirements.

Authentication

Authentication is done using an OAuth Application. See GitHub documentaion Creating an OAuth App. Upon authorizing the Checkmarx App, we are receiving a token that is stored, encrypted (with envelop based encryption, AES 256), on our side for driving the integration. This authorization flow is GitHub specific, and is explained in our documentation.

Updating Project Settings

See Imported Project Settings.

In this section: