Examples: Self‐Hosted Runner - checkmarx-ts/checkmarx-cxflow-plusplus-github-action GitHub Wiki

Using a self-hosted runner with the CxFlow++ GitHub action is possible by simply changing the jobs.<job>.runs-on element of your action to a tag for an appropriate self-hosted runner. This may be ideal for scenarios where the GitHub action workflow needs to access services that are not reachable via the public internet. Since the self-hosted runner is executing commands on a machine behind your firewall, private services are accessible while the SAST and SCA scans are executing.

This document shows examples of deployment scenarios that can be used with self-hosted GitHub runners.

Local CxFlow Configuration

It is possible to define a local CxFlow configuration and pin the CxFlow version without the need for downloading CxFlow on each workflow run. The following example shows the use of a locally installed CxFlow jar file and CxFlow configuration YAML file.

Note that the directory where the CxFlow jar is deployed (not the CxFlow jar or the configuration YAML file) needs to be writable by the process executing the GitHub self-hosted runner.

name: SDLC Workflow with CxFlow++
on:
    push:
        branches: master
    pull_request:
        branches: master
    
jobs:
    checkmarx-scan:
        permissions:
            security-events: write
            pull-requests: write
        runs-on: my-hosted-runner
        steps:
          - name: Fetch Code
            uses: actions/checkout@v4
        
          - name: Execute Scan
            uses: checkmarx-ts/checkmarx-cxflow-plusplus-github-action@v2
            with:
                cxflow-jar-path: /opt/cx-flow/cx-flow-1.7.01.jar
                application-yaml-path: /opt/cx-flow/default.yml
                sast-url: ${{ vars.CX_SAST_URL }}
                sast-username: ${{ secrets.CX_SAST_USERNAME }}
                sast-password: ${{ secrets.CX_SAST_PASSWORD }}
                sca-tenant: ${{ secrets.CX_SCA_TENANT }}
                sca-username: ${{ secrets.CX_SCA_USERNAME }}
                sca-password: ${{ secrets.CX_SCA_PASSWORD }}

The CxFlow YAML configuration for this example has a minimal configuration defined:

logging:
  pattern:
    console: "%clr(%d{yyyy-MM-dd HH:mm:ss.SSS}){faint} %clr(%5p) %clr(${PID:- }){magenta} %clr(---){faint} %clr([%15.15t]){faint} %clr(%-40.40logger{15}){cyan}  [%clr(%X{cx}){blue}] %clr(:){faint} %m%n%wEx"

cx-flow:
  bug-tracker: Sarif
  bug-tracker-impl:
    - Azure
    - CxXml
    - Csv
    - Email
    - Json
    - GITHUBPULL
    - GitHub
    - GitLab
    - Rally
    - ServiceNow
    - Sarif
    - PDF
  scan-resubmit: true
  mitre-url: https://cwe.mitre.org/data/definitions/%s.html
  wiki-url: https://custodela.atlassian.net/wiki/spaces/AS/pages/79462432/Remediation+Guidance
  codebash-url: https://checkmarx-demo.codebashing.com/

codebashing:
 codebashing-api-url: https://api.codebashing.com/
 tenant-base-url: https://checkmarx-demo.codebashing.com

checkmarx:
  version: 9.0
  client-id: resource_owner_client
  scope: access_control_api sast_rest_api
  client-secret: 014DF517-39D1-4453-B7B3-9930C563627C
  url: ${checkmarx.base-url}/cxrestapi
  multi-tenant: false
  incremental: false
  configuration: Default Configuration
  scan-timeout: 600
  report-timeout: 600000
  report-polling: 20000
  portal-url: ${checkmarx.base-url}/cxwebinterface/Portal/CxWebService.asmx
  sdk-url: ${checkmarx.base-url}/cxwebinterface/SDK/CxSDKWebService.asmx
  portal-wsdl: ${checkmarx.base-url}/Portal/CxWebService.asmx?wsdl
  sdk-wsdl: ${checkmarx.base-url}/SDK/CxSDKWebService.asmx?wsdl
  portal-package: checkmarx.wsdl.portal
  cx-branch: true
  settings-override: true

sca:
  appUrl: https://sca.checkmarx.net/
  apiUrl: https://api-sca.checkmarx.net/
  accessControlUrl: https://platform.checkmarx.net/

Note: CxFlow may not execute if these minimal configuration elements are not defined in the YAML file. Many of these are overridden during execution, but CxFlow needs some of these configuration elements defined with a default value at start.

Jira

Configuration with Actions Parameters

This method supplies the CxFlow configuration options during the command-line invocation of CxFlow. The action parameters cxflow-params, pull-request-cxflow-params, or push-cxflow-params can be used to pass all required options for the Jira configuration.

This method of deployment for Jira configuration is likely not going to work for large scale deployments. For complex Jira configurations, maintaining the configuration via command line options is not ideal.

Configuration with Environment Variables

CxFlow allows all configuration parameters to be defined as environment variables. This may be utilized as:

Setting environment variables at startup of a self-hosted runner.
Using GitHub to define environment variables that are injected into the environment during the action execution.

Configuration with Local YAML File

A local configuration YAML for basic Jira configuration with a few selected override parameters may be a more ideal approach for configuring Jira. This approach sets most of the Jira configuration as static and utilizes environment variables to provide the Jira login and project key appropriate for the repository.

name: SDLC Workflow with CxFlow++
on:
    push:
        branches: master
    pull_request:
        branches: master
    
jobs:
    checkmarx-scan:
        env:
            # Defined at Org-Level
            JIRA_USERNAME: ${{ secrets.CX_JIRA_USER }}
            JIRA_TOKEN: ${{ secrets.CX_JIRA_PASSWORD }}

            # Defined at Repo-Level
            JIRA_PROJECT: ${{ vars.CX_JIRA_PROJECT_KEY }}
        permissions:
            pull-requests: write
        runs-on: my-self-hosted-runner
        steps:
          - name: Fetch Code
            uses: actions/checkout@v4
        
          - name: Execute Scan
            uses: checkmarx-ts/checkmarx-cxflow-plusplus-github-action@v2
            with:
                cxflow-jar-path: /opt/cx-flow/cx-flow-1.7.01.jar
                application-yaml-path: /opt/cx-flow/default.yml
                push-feedback-channel: Jira
                sast-url: ${{ vars.CX_SAST_URL }}
                sast-username: ${{ secrets.CX_SAST_USERNAME }}
                sast-password: ${{ secrets.CX_SAST_PASSWORD }}
                sca-tenant: ${{ secrets.CX_SCA_TENANT }}
                sca-username: ${{ secrets.CX_SCA_USERNAME }}
                sca-password: ${{ secrets.CX_SCA_PASSWORD }}

This is the CxFlow configuration YAML that defines the static Jira parameters along with other common CxFlow parameters:

logging:
  pattern:
    console: "%clr(%d{yyyy-MM-dd HH:mm:ss.SSS}){faint} %clr(%5p) %clr(${PID:- }){magenta} %clr(---){faint} %clr([%15.15t]){faint} %clr(%-40.40logger{15}){cyan}  [%clr(%X{cx}){blue}] %clr(:){faint} %m%n%wEx"

cx-flow:
  bug-tracker: Sarif
  bug-tracker-impl:
    - Azure
    - CxXml
    - Csv
    - Email
    - Json
    - GITHUBPULL
    - GitHub
    - GitLab
    - Rally
    - ServiceNow
    - Sarif
    - PDF
  scan-resubmit: true
  mitre-url: https://cwe.mitre.org/data/definitions/%s.html
  wiki-url: https://custodela.atlassian.net/wiki/spaces/AS/pages/79462432/Remediation+Guidance
  codebash-url: https://checkmarx-demo.codebashing.com/

codebashing:
 codebashing-api-url: https://api.codebashing.com/
 tenant-base-url: https://checkmarx-demo.codebashing.com

checkmarx:
  version: 9.0
  client-id: resource_owner_client
  scope: access_control_api sast_rest_api
  client-secret: 014DF517-39D1-4453-B7B3-9930C563627C
  url: ${checkmarx.base-url}/cxrestapi
  multi-tenant: false
  incremental: false
  configuration: Default Configuration
  scan-timeout: 600
  report-timeout: 600000
  report-polling: 20000
  portal-url: ${checkmarx.base-url}/cxwebinterface/Portal/CxWebService.asmx
  sdk-url: ${checkmarx.base-url}/cxwebinterface/SDK/CxSDKWebService.asmx
  portal-wsdl: ${checkmarx.base-url}/Portal/CxWebService.asmx?wsdl
  sdk-wsdl: ${checkmarx.base-url}/SDK/CxSDKWebService.asmx?wsdl
  portal-package: checkmarx.wsdl.portal
  cx-branch: true
  settings-override: true

sca:
  appUrl: https://sca.checkmarx.net/
  apiUrl: https://api-sca.checkmarx.net/
  accessControlUrl: https://platform.checkmarx.net/

jira:
  token-type: PASSWORD
  url: http://localhost:8000
  issue-type: Bug
  priorities:
    High: High
    Medium: Medium
    Low: Low
    Informational: Lowest
  open-transition: To Do
  close-transition: Done
  open-status:
    - To Do
    - In Progress
    - In Review
  closed-status:
    - Done
  fields:
    - type: result
      name: application
      jira-field-name: Application
      jira-field-type: label
    - type: result
      name: cve
      jira-field-name: CVEs
      jira-field-type: label
    - type: result
      name: cwe
      jira-field-name: CWEs
      jira-field-type: label
    - type: result
      name: category
      jira-field-name: Category
      jira-field-type: label
    - type: result
      name: loc
      jira-field-name: LOC
      jira-field-type: label