Skip to main content

CxFlow Configuration (GitHub Webhooks)

CxFlow, which comes preinstalled on your Agent, enables you to integrate Checkmarx SCA with your GitHub repository. You can create a “webhook” which will automatically trigger a Checkmarx SCA scan of the source code in your repository whenever the specified type of action occurs (e.g., push event, create branch, merge branch etc.) on that repository. You can use CxFlow to integrate multiple repositories, as long as they are all accessible from a single user account and use the identical “Secret”.

Prerequisites

  • Checkmarx SCA Agent (v0.3.1+) installed and running

  • You have Checkmarx SCA credentials with scanning permission (You will need to provide: Tenant Account, User Name, Password)

  • Your source code is in a GitHub repository for which you have an admin role

Configuring CxFlow

To configure CxFlow integration with GitHub:

  1. Open your Agent’s .env file.

  2. In the CxFlow section, you will need to configure the following parameters.

    ################################ CxFlow ###############################################
    SCA_TENANT=tenant
    SCA-TENANT-USERNAME=sca_username
    SCA_TENANT_PASSWORD=sca_password
    WEBHOOK_TOKEN=token
    WEBHOOK_SECRET=secret
  3. For Tenant Account, User Name, Password enter your SCA account and credentials.

  4. For the WEBHOOK_TOKEN you need enter the token which you generate in your GitHub account, using the following procedure. (Detailed info about generating GitHub access tokens is available here.)

    1. In GitHub, on the User Settings page, select Developer settings > Personal access tokens.

    2. On the personal access tokens page, click Generate new token.

      Notice

      You may need to confirm your password.

    3. In the New personal access token form, in the Note field, enter a note explaining that the token will be used for CxFlow.

    4. In theSelect Scopessection, select therepocheckbox (including all sub-elements).

      6435045381.png
    5. Click on the Generate Token button.

      The new token is displayed.

    6. If the repo is in an organization you will need to authorize access by clicking on the Enable SSO button and following the prompts.

      6434848793.png
    7. Copy the token to your clipboard and paste it in the WEBHOOK_TOKEN in CxFlow.

      Notice

      Once you navigate away from the page, you will no longer be able to view this token.

  5. For the WEBHOOK_SECRET you need to create a webhook in your repository and enter the Secret that you specify for that webhook. Use the following procedure. (Detailed info about creating webhooks is available here.)

    1. In GitHub, open the desired repository.

    2. Go to Settings > Webhooks.

    3. Click on the Add webhook button.

      A new webhook form opens.

    4. In the Payload URL field, enter the URL of the Checkmarx SCA Agent, using the following format: https://<Agent_Localhost>:<Agent_External_Port>/webhook

      Notice

      The Agent port is set by default as 80. You can check in your .env file to see which port was designated as the “EXTERNAL_PORT”. For example, if you are using https the port may be set as 443.

    5. In the Secret field, specify a string that you would like to assign as the Secret.

    6. In the the CxFlow section of the .env file, for the WEB_HOOK_SECRET, enter the identical string that you set as the Secret in GitHub.

    7. In GitHub, in the section “What events would you like to trigger this webhook?”, select the desired settings.

    8. Click on the Add webhook button.

      Notice

      If you would like to integrate multiple repositories in the same GitHub account, you can do so by creating additional webhooks using the above procedure. Make sure to use the identical “Secret” for each webhook.

  6. Webhooks will only trigger scans in CxFlow for branches that are configured in the Agent’s “application.yml” file. The default configuration includes the following branch names: develop, master, security and main. If your repository has branches with other names, then navigate to volumes\cx-flow\application.yml in your Agent. Under cx-flow > branches, add the desired branches.

    6434848799.png

Notice

You can include a series of names using regular expressions, i.e., “release-\w+” will enable any branches starting with “release-”. Additional info about CxFlow configuration is available here.

The webhook is created. Whenever the specified events occur on your repository it will trigger a Checkmarx SCA scan on your source code. You can view the results in the Checkmarx SCA web platform. The scan will be visible to the user whose credentials are specified in the .env file as well as to admin users. To learn more about viewing scan results, see Viewing Scan Results.