Configuration - checkmarx-ltd/cx-flow GitHub Wiki

• Main (Global) Properties
  • Yaml Sample
  • CLI Examples
  • Environment Variable Examples
• Configuration Definitions
  • Server Section
  • Cx-Flow Section
    • E-Mail notifications
    • Filtering
    • Excluding Vulnerability
    • Excluding Files from Zip Archive
    • Break build
  • Checkmarx Section
    • 9.0 Configuration Changes
    • Postback action
    • Override SAST project setting
    • Create Branched Project
    • Scan Queuing and Scan Queuing Timeout
    • Scan Timeout and Scan polling
    • Report Timeout and Report polling
    • Checkmarx E-mail Notifications
• WebHook Configuration
  • WebHook URL Parameters - Code
  • WebHook URL Override Parameters - Details
• Repository configuration blocks
  • GitHub
  • GitLab
  • Azure DevOps
  • Sarif
  • Bitbucket (Cloud and Server)
• JSON Config Override
• BugTrackers
• Encryption
• External Scripting
• SAST Scan ID in Github Action Output variable
• Streaming CxFlow logs to AWS OpenSearch or ElasticSearch
• Issue Labels

CxFlow uses Spring Boot and for Server Mode, it requires an application.yml file to drive the execution. The sections below outlines available properties and when/how they can be used in different execution modes. In addition, all the Spring Boot configuration rules apply. For additional information on Spring Boot, refer to https://docs.spring.io/spring-boot/docs/current/reference/html/boot-features-external-config.html

Command-line arguments and environment variables prevail over values specified in application.yml file. To allow for bootstrapping the launch process with various configurations, especially with containers, CxFlow uses overrides on the command line using the --property.name=Value format as well as PROPERTY_NAME environment variable overrides.

All the relevant configuration is defined by the application.yml file that resides in the same directory as the JAR file, or if an explicit configuration override is provided on the command line as follows:

$ java -jar cx-flow-<version>.jar \
    --spring.config.location=/path/to/application.yml

Please refer to the sample configuration for the entire YAML structure.

server:
  port: ${PORT:8080}

logging:
  file: flow.log

cx-flow:
  contact: [email protected]
  bug-tracker: Json
  bug-tracker-impl:
    - CxXml
    - Csv
    - Json
    - GitLab
    - GitHub
    - Azure
    - Rally
  branches:
    - develop
    - main
    - release`-\w+ # regular expressions supported. If branch-script is provided, this is ignored. branch-script: D:\\tmp\Branch.groovy #default empty/not used
  filter-severity:
    - High
  filter-category:
    - Stored_XSS
    - SQL_Injection
  filter-cwe:
    - 89
    - 79
  filter-status:
    - New
    - Recurrent
  filter-state:
    - Confirmed
    - Urgent
  mitre-url: https://cwe.mitre.org/data/definitions/%s.html
  deleteForkedProject: true
  wiki-url: https://checkmarx.atlassian.net/wiki/spaces/AS/pages/79462432/Remediation+Guidance
  track-application-only: false
  web-hook-queue: 20
  scan-result-queue: 8
  break-build: false
  scan-resubmit: false
  branch-protection-enabled: false
  preserve-project-name: false
  http-connection-timeout: xxx # milliseconds - default 30000
  http-read-timeout: xxx # milliseconds - default 120000
  mail:
    host: smtp.gmail.com
    port: 587
    username: xxx
    password: xxx
    enabled: true
    notification: true # default is false
    cc: [email protected] # comma-separated list of e-mails
  zip-exclude: \.git/.*, .*\.png
  zip-include: \.git/.*, .*\.png
  comment-script: location/to/commentScript.groovy

checkmarx:
  version: 9.0 # Not required for CxSAST version 8.x
  username: xxx
  password: xxx
  client-secret: xxx
  base-url: https://cx.aws.checkmarx.com
  multi-tenant: true
  scan-preset: Checkmarx Default
  configuration: Default Configuration
  team: /CxServer/SP/Machina # \CxServer\SP\Machina for CxSAST 8.x
  scan-timeout: 120 # Webhook and --scan command line only, number of minutes
  scan-polling: 20000
  report-timeout: 300000
  report-polling: 5000
  preserve-xml: true
  enabled-zip-scan: false
  url: ${checkmarx.base-url}/cxrestapi
  # WSDL Config
  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
  project-script: D:\\tmp\CxProject.groovy # default empty/not used
  team-script: D:\\tmp\CxTeam.groovy # default empty/not used
  custom-state-map:
    "5": "SUSPICIOUS"
  custom-state-false-positive-map:
    "5": "SUSPICIOUS"
  modify-branch-name-by-pattern-map:
    "[[^a-zA-Z0-9-_.]+]": "_" # Key is having regular expression
    # "[/]": "_"   #Use this expression if you want to replace / by underscore 
  post-action-postback-id: 123456
  settings-override: true #default false if not provide
  cx-branch: false
  scan-queuing: true
  scan-queuing-timeout: 720 # Webhook and --scan command line only, number of minutes
  email-notifications:
    after-scan:
      - [email protected]
    before-scan:
      - [email protected]
    failed-scan:
      - [email protected]
  project-branching-check-count: 5
  project-branching-check-interval: 10
  restrict-results-to-branch: true

github:
  webhook-token: XXXXX
  token: XXXXX
  url: https://github.com
  api-url: https://api.github.com/repos/
  false-positive-label: false-positive
  block-merge: true
  cx-summary-header: Checkmarx Scan Summary
  cx-summary: true # default false if not provided
  flow-summary-header: Violation Summary
  flow-summary: true # default true if not provided
  detailed-header: Details
  detailed: true # default true if not provided

gitlab:
  webhook-token: XXXXX
  token: XXXXX
  url: https://gitlab.com
  api-url: https://gitlab.com/api/v4/
  false-positive-label: false-positive
  block-merge: true

bitbucket:
  webhook-token: XXXXX
  token: XXXXX
  url: https://bitbucket.org
  api-url: https://api.bitbucket.org
  api-path: /2.0
  false-positive-label: false-positive

azure:
  webhook-token: xxxx
  token: xxxx
  url: https://dev.azure.com
  issue-type: issue
  api-version: 5.0
  false-positive-label: false-positive

rally:
  token: xxxx
  rally-project-id: xxxx
  rally-workspace-id: xxxx
  url: https://rallydev.com
  api-url: https://rally1.rallydev.com/slm/webservice/v2.0

jira:
  url: https://xxxx.atlassian.net
  username: XXXXX
  token: XXXXX
  project: <JIRA PROJECT KEY>
  issue-type: <JIRA ISSUE TYPE>
  label-prefix: <CUSTOM PREFIX NAME >
  priorities:
    Critical: Highest
    High: High
    Medium: Medium
    Low: Low
    Informational: Lowest
  open-transition: In Review
  close-transition: Done
  open-status:
    - To Do
    - In Progress
    - In Review
  closed-status:
    - Done
  suppress-code-snippets:
    - Hardcoded_Password_in_Connection_String
    - Password_In_Comment
    - Use_Of_Hardcoded_Password
  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
      jira-default-value: XXXXX

json:
  file-name-format: "[NAMESPACE]-[REPO]-[BRANCH]-[TIME].json"
  data-folder: "C:\\tmp"

cx-xml:
  file-name-format: "[NAMESPACE]-[REPO]-[BRANCH]-[TIME].xml"
  data-folder: "C:\\tmp"

csv:
  file-name-format: "[TEAM]-[PROJECT]-[TIME].csv"
  data-folder: "C:\\tmp"
  include-header: true
  fields:
    - header: Customer field (Application)
      name: application
      default-value: unknown
    - header: Primary URL
      name: static
      default-value: ${tmp.url}
    - header: severity
      name: severity
    - header: Vulnerability ID
      name: summary
      prefix: "[APP]:"
    - header: file
      name: filename
    - header: Vulnerability ID
      name: summary
    - header: Vulnerability Name
      name: category
    - header: Category ID
      name: cwe
    - header: Description
      name: summary
      prefix: "*"
      postfix: "*"
    - header: Severity
      name: severity
    - header: recommendation
      name: recommendation

Examples to convert YAML property to CLI property

#YAML
cx-flow:
  bug-tracker:Json
  
#CLI
--cx-flow.bug-tracker=json  

#YAML
cx-flow:
  filter-category:
    - Stored_XSS
    - SQL_Injection
  
#CLI
--cx-flow.filter-category="Stored_XSS,SQL_Injection"  

#YAML
cx-flow:
  thresholds:
    high: 10
    medium: 10
    low: 10
  
#CLI
--cx-flow.thresholds.high=10  
--cx-flow.thresholds.medium=10  
--cx-flow.thresholds.low=10  

Examples to convert YAML property to Environment variables

#YAML
cx-flow:
  bug-tracker:Json
  
#Environment variables
CXFLOW_BUGTRACKER=Json

#YAML
cx-flow:
  filter-category:
    - Stored_XSS
    - SQL_Injection
  
#Environment variables
CXFLOW_FILTERCATEGORY="Stored_XSS,SQL_Injection"  

#YAML
cx-flow:
  thresholds:
    high: 10
    medium: 10
    low: 10
  
#Environment variables
CXFLOW_THRESHOLDS_HIGH=10 
CXFLOW_THRESHOLDS_MEDIUM=10  
CXFLOW_THRESHOLDS_LOW=10  

server:
  port: ${PORT:8080}

cx-flow:
  contact: [email protected]
  bug-tracker: Json
  bug-tracker-impl:
    - CxXml
    - Csv
    - Json
    - GitLab
    - GitHub
    - Azure
    - Rally
  branches:
    - develop
    - main
    - release`-\w+ # regular expressions supported. If branch-script is provided, this is ignored. branch-script: D:\\tmp\Branch.groovy #default empty/not used
  filter-severity:
    - High
  filter-category:
    - Stored_XSS
    - SQL_Injection
  filter-cwe:
    - 89
    - 79
  filter-status:
    - New
    - Recurrent
  filter-state:
    - Confirmed
    - Urgent
  mitre-url: https://cwe.mitre.org/data/definitions/%s.html
  deleteForkedProject: true
  wiki-url: https://checkmarx.atlassian.net/wiki/spaces/AS/pages/79462432/Remediation+Guidance
  track-application-only: false
  web-hook-queue: 20
  scan-result-queue: 8
  branch-protection-enabled: false
  break-build: false
  scan-resubmit: false
  preserve-project-name: false
  http-connection-timeout: xxx # milliseconds - default 30000
  http-read-timeout: xxx # milliseconds - default 120000
  mail:
    host: smtp.gmail.com
    port: 587
    username: xxx
    password: xxx
    enabled: true
    notification: true # default is false
    cc: [email protected] # comma-separated list of e-mails
  zip-exclude: \.git/.*, .*\.png
  zip-include: \.git/.*, .*\.png
  comment-script: location/to/commentScript.groovy
  core-poolsize: 54
  max-poolsize: 302
  queue-capacityarg: 600

No* = Default is applied

cx-flow:
  mail:
    host: smtp.gmail.com
    port: 587
    username: xxx
    password: xxx
    enabled: true
    notification: true # default is false
    cc: [email protected] # comma-separated list of e-mails

Filtering, as specified above, is available on the following criteria:

cx-flow:
  filter-severity: Medium
  filter-category: Stored_XSS
  filter-cwe: 79
  filter-state: Confirmed

• Severity → Severity from Checkmarx
• Category → Vulnerability name within Checkmarx
• CWE → CWE value from Checkmarx
• State → Urgent | Confirmed

All values are case-sensitive as per the output from Checkmarx (i.e. High severity, Stored_XSS, Confirmed).

We can exclude vulnerabilities according to category, cwe and state.

cx-flow:
 exclude-category: Stored_XSS
 exclude-cwe: 79
 exclude-state: Confirmed

• Category → Vulnerability name within Checkmarx
• CWE → CWE value from Checkmarx
• State → Urgent | Confirmed

All values are case-sensitive as per the output from Checkmarx (Stored_XSS, Confirmed).

The cx-flow.zip-exclude configuration option instructs CxFlow to exclude specific files when it creates a zip archive.

The following option excludes all .png files from the archive, as well as all files inside a root-level .git directory:

cx-flow:
  zip-exclude: \.git/.*, .*\.png

The meaning and syntax of the cx-flow.zip-exclude option are different as opposed to the checkmarx.exclude-folders and checkmarx.exclude-files options.

• If User want to exclude folders or exclude files, settings-override should be true. If user is using CLI they can pass parameter as --checkmarx.settings-override=true
• If user is using Github Action value of exclude files or folders should not be in double or single quotes. Example : If user want to exclude folder name abc he should pass parameter as --checkmarx.exclude-folders=abc or --checkmarx.exclude-folders=*abc or ``--checkmarx.exclude-folders=*abc*

cx-flow.zip-exclude is a comma-separated list. Each of the list items is a regex (not a wildcard). Spaces before and after a comma are ignored.

During zipping, CxFlow checks each file in the target directory against each of the regexes in cx-flow.zip-exclude. If there is a match, CxFlow excludes the file from the archive. In this case, when log level is debug, CxFlow writes a message to the log having the following format:

match: <regex>|<relative_file_path>

CxFlow uses relative file path to test the regex match. E.g. if the following file exists:

c:\cxdev\projectsToScan\myproj\bin\internal-dir\exclude-me.txt

and we specify this CLI option: --f="c:\cxdev\projectsToScan\myproj,

then CxFlow will check the following relative file path against the regexes:

bin/internal-dir/exclude-me.txt

CxFlow normalizes slashes in the relative path into a forward slash (/).

For a file to be excluded, a regex must match the whole relative file path. Thus, the .* regex expression should be used where necessary.

The cx-flow.zip-include configuration option instructs CxFlow to include specific files when it creates a zip archive.

cx-flow:
  zip-include: \.git/.*, .*\.png

Note: Process of zip-exclude and zip-include are same, the only difference is zip-exclude excludes the files from zip and zip-include includes only mentioned files to zip.

The configuration can be set or overridden at execution time using the command line (--cx-flow.break-build=true) to exit the command line execution flow for a single project result or scan for results that meet the filter criteria.

For more details on break build, please refer to Thresholds and policies chapter.

Note: This does not apply to WebHooks or for batch cli execution (instance and team). It only works, if one project result is processed.

checkmarx:
  version: 9.0 # Required for version 9.x
  username: xxxxx
  password: xxxxx
  client-id: resource_owner_client
  client-secret: 014DF517-39D1-4453-B7B3-9930C563627C
  scope: access_control_api sast_rest_api # Required for version 9.x
  base-url: http://cx.local
  multi-tenant: true
  configuration: Default Configuration
  scan-preset: Checkmarx Default
  team: /CxServer/Checkmarx/CxFlow
  url: ${checkmarx.base-url}/cxrestapi
  preserve-xml: true
  incremental: true
  trustcerts: true
  portal-url: ${checkmarx.base-url}/cxwebinterface/Portal/CxWebService.asmx
  exclude-files: "*.tst,*.json"
  exclude-folders: ".git,test"
  cx-branch: false
  scan-queuing: true
  scan-timeout: 120
  scan-polling: 20000
  report-timeout: 300000
  report-polling: 5000
  scan-queuing-timeout: 720 # Webhook and --scan command line only, number of minutes  

Note:

• Make sure to include version: 9.0 (or higher) and scope: access_control_api sast_rest_api
• The Team path must include the unix path separator /, the path is for example defined as follows: /CxServer/Checkmarx/CxFlow

On using post back mode, Checkmarx post back action will be added to the Checkmarx project and that action will trigger the /postbackAction endpoint on CxFlow.

checkmarx
  ...
post-action-postback-id: 123456

For more details on postback mode, Please refer to CxSAST Version 9.0 chapter

The configuration can be set to override project settings with Cxflow configuration when triggering new scan for SAST project, or to avoid project setting update if property set to 'false'.

Defaults value is false, if set to true the projects settings like "scan-preset","post-action-postback-id" are re-written/overridden when each SAST scan is invoked from CxFlow.

checkmarx
  ...
settings-override: true #default false if not provide

A branched project is a child of a base project in CxSAST. Upon initiating a scan from the default branch of a repository, CxSAST creates a base project in the server with name RepoName-defaultBranchName and any subsequent scans from the branches of that repository will create child projects off of it with name RepoName-currentBranchName. The project count in CxSAST does not increase when a branched project is added. Branching of projects can be enabled by setting the cx-branch property to true.

• When you initiate a scan from the default branch of a repository, CxSAST automatically creates a base project on the server.
• The naming convention used is RepoName-defaultBranchName (e.g., MyRepo-main if main is your default branch).

• For scans initiated from other branches (not the default), CxSAST creates branched projects or child projects.
• These child projects are named using the convention RepoName-currentBranchName (e.g., MyRepo-feature1).
• Importantly, the total project count in CxSAST does not increase when these branched projects are added. They are treated as extensions of the base project.

• To enable project branching, you need to set the cx-branch property to true.
• Additionally, you must provide both the default branch name and the current branch name.

• The overall project count in CxSAST does not increase when branched projects are added. Branched projects are managed under the umbrella of the base project, which keeps the total project count static.

• When configuring the scan (e.g., via a CxSAST API or build pipeline), you might set these properties like this:

checkmarx:
  ...
  cx-branch: true #default false if not provided

• CLI parameter to provide default branch name is default-branch = main and current branch can be passed branch = feature1.
• In case of webhook it will be passed automatically in payloads.

If the number of concurrent scans which can run on CxSAST server is all utilized, then enabling scan-queuing will allow CxFlow to keep the event of the scan within itself and let the existing scans finish before sending the new scan event to CxSAST. Cx-flow keeps events with itself for a number of minutes, specified by the scan-queuing-timeout parameter, with a default value of 120 minutes.

checkmarx:
  ...
  scan-queuing: true
  scan-queuing-timeout: 720 #Amount of time in minutes

The amount of time (in minutes) for which cx-flow will wait for CxSAST scan to finish.If scan is not completed within 120(in minutes) then it will gives Timeout exceeded during scan as error messase.The default value of scanTimeout 120 minutes. The amount of time (in milliseconds) in which cx-flow pings CxSAST server to get the status of the scan (i.e Queued, Finished or Failed).The default value of scanPolling 20000 miliseconds.

checkmarx:
  ...
  scan-timeout: 120 #Amount of time in minutes
  scan-polling: 20000 #Amount of time in miliseconds

The amount of time (in milliseconds) for which cx-flow will wait for CxSAST to generate scan report.If report is not generated within 300000(in miliseconds)it will through Timeout exceeded during report generation as error message.The default value of reportTimeout 30000 miliseconds. The amount of time (in milliseconds) in which cx-flow pings CxSAST server to get the status of the report.The default value of reportPolling 5000 miliseconds.

checkmarx:
  ...
  report-timeout: 300000 #Amount of time in miliseconds
  report-polling: 5000 #Amount of time in miliseconds

If present, this property specifies the email notifications to be sent when a SAST scan is run. Notifications can be sent before a scan starts, after a scan finishes, and when a scan fails. The content of the email-notifications property is a map from the following keys to lists of email receipients: after-scan, before-scan, failed-scan.

checkmarx:
  ...
  email-notifications:
    after-scan:
      - [email protected]
      - [email protected]
    before-scan:
      - [email protected]
      - [email protected]
    failed-scan:
      - [email protected]
      - [email protected]

Email notifications can also be configured via conf-as-code.

Each repository type requires its own specific configuration block as defined below. Each of these have available overrides that can be provided in the form of URL parameters or as a JSON configuration blob that is base64 encoded and provided as an url parameter (override=).

WebHook scans are triggered based on the protected branches list. This configuration is under the config block.

The protected branches list can be provided in the application.yml file under the cx-flow section, or it can be provided in the config-as-code file. If branches are provided in application.yml as well as config-as-code file then the branches in config-as-code file will override the branches in application.yml. If protected branches is not provided in either of the files then CxFlow triggers a scan for Push/Pull/Merge event for all the branches.

For Pull/Merge, if a request is made to pull/merge code into one of the listed protected branches, CxFlow triggers the scan. The pull/merge is commented with the filtered findings from Checkmarx.

For Push, the findings are published according to the specified bug-tracker in the main or overridden configuration - i.e. JSON/CSV/XML output or Jira defect.

For additional information, refer to the workflow for WebHooks.

@RequestParam(value = "application", required = false) String application,
@RequestParam(value = "branch", required = false) List<String> branch,
@RequestParam(value = "severity", required = false) List<String> severity,
@RequestParam(value = "cwe", required = false) List<String> cwe,
@RequestParam(value = "category", required = false) List<String> category,
@RequestParam(value = "project", required = false) String project,
@RequestParam(value = "team", required = false) String team,
@RequestParam(value = "status", required = false) List<String> status,
@RequestParam(value = "assignee", required = false) String assignee,
@RequestParam(value = "preset", required = false) String preset,
@RequestParam(value = "incremental", required = false) Boolean incremental,
@RequestParam(value = "exclude-files", required = false) List<String> excludeFiles,
@RequestParam(value = "exclude-folders", required = false) List<String> excludeFolders,
@RequestParam(value = "override", required = false) String override,
@RequestParam(value = "bug", required = false) String bug,
@RequestParam(value = "app-only", required = false) Boolean appOnlyTracking,
@RequestParam(value = "state", required = false) List<String> state,
@RequestParam(value = "threshold-high", required =false) Integer thresholdHigh,
@RequestParam(value = "threshold-medium", required =false) Integer thresholdMedium,
@RequestParam(value = "threshold-low", required = false) Integer thresholdLow,
@RequestParam(value = "threshold-info", required = false) Integer thresholdInfo

These parameters are related to the WebHook URL parameters above.

Notes: All the repository configurations have common elements such as:

• token → api token for the repo, to gain access (typically personal access token for a service account)
• web-token → CxFlow shared secret to be used when registering the webhook on the repo
• url → base url for the repo
• api-url → base url for the api endpoints for the repo
• block-merge → boolean, determine if merge should be blocked while scan is completing in Checkmarx
• cx-summary-header → Pull/Merge Markdown comment header for the Checkmarx Summary, if used
• cx-summary → boolean, determine if the base Checkmarx Summary is displayed (unfiltered)
• flow-summary-header → Pull/Merge Markdown comment header for the CxFlow Violation Summary, if used
• flow-summary → boolean, determine if the base CxFlow Violation Summary is displayed (filtered)
• detailed-header → Pull/Merge Markdown comment header for the CxFlow details, if used
• detailed → boolean, determine if the detailed CxFlow results (vulnerability lines/files are displayed

github:
  webhook-token: xxxx
  token: xxxx
  url: https://github.com
  api-url: https://api.github.com/repos/
  false-positive-label: false-positive
  block-merge: true
  detailed: false
  scan-submitted-comment: false
  max-description-length : <should be greater than 4 and less than 50000>
  max-delay : <minimum value should be 3>
  comment-update: false
  zero-vulnerability-summary: true
  fields:
    - type: result
      name: application
    - type: result
      name: project

gitlab:
  webhook-token: xxxx
  token: xxxx
  url: https://gitlab.com
  api-url: https://gitlab.com/api/v4/
  false-positive-label: false-positive
  block-merge: true
  comment-update: false
  zero-vulnerability-summary: true
  fields:
    - type: result
      name: application
    - type: result
      name: project

Note: A service account is required with access to the repositories that are going to be scanned, pull requests that are commented on, and GitLab issues that are created/updated.

azure:
  webhook-token: cxflow:1234
  token: xxxx
  url: https://dev.azure.com/XXXXXX
  issue-type: issue
  api-version: 5.0
  false-positive-label: false-positive
  block-merge: true
  closed-status: Closed
  open-status: Active
  zero-vulnerability-summary: true

sarif:
 hassnippet: true

Note: Command line parameter for snippet is --sarif.hassnippet=true

bitbucket:
  webhook-token: xxx
  token: <user>:xxx
  url: http://bitbucket.org
  api-url: http://api.bitbucket.org
  api-path: /2.0
  zero-vulnerability-summary: true

The sample below illustrates an override configuration in JSON format. It has similarities with the YAML config blocks. Its main use is to override cx-flow and Jira Yaml configuration.

for more details, please refer to Config as Code

{
  "version": 1.0,
  "project": "XYZ-${repo}-${branch}",
  "team": "/a/b/c",
  "sast": {
    "preset": "",
    "engineConfiguration": "",
    "incremental": "false", // values: "true" or "false"
    "forceScan": "true", // values: "true" or "false"
    "fileExcludes": "*.pyc, *.test, *.class",
    "folderExcludes": "*test, out/, *bin"
  },
  "additionalProperties": {
    "cxFlow": {
      "application": "test app",
      "branches": ["develop", "main", "master"],
      "emails": ["[email protected]"],
      "bugTracker": "JIRA", // other possible values: "GitLab", "GitHub", "Azure"
      "scanResubmit": "true", // values: "true" or "false"
      "sshKeyIdentifier": "Key of the ssh-key-list parameter present in application.yml file."
      "jira": {
        "project": "APPSEC",
        "issue_type": "Bug",
        "assignee": "admin",
        "opened_status": ["Open","Reopen"],
        "closed_status": ["Closed","Done"],
        "open_transition": "Reopen Issue",
        "close_transition": "Close Issue",
        "close_transition_field": "resolution",
        "close_transition_value": "Done",
        "priorities": {
          "High": "High",
          "Medium": "High",
          "Low": "High"
        },
        "fields": [
          {
            "type": "cx", // cx, static, result
            "name": "xxx",
            "jira_field_name": "xxxx",
            "jira_field_type": "text", // security text | label | single-select | multi-select
            "jira_default_value": "xxx"
          },
          {
            "type": "result",
            "name": "xxx",
            "jira_field_name": "xxxx",
            "jira_field_type": "label"
          },
          {
            "type": "static",
            "name": "xxx",
            "jira_field_name": "xxxx",
            "jira_field_type": "label",
            "jira_default_value": "xxx"
          }
        ]
      },
      "filters": {
        "severity": ["High", "Medium"],
        "cwe": ["79", "89"],
        "category": ["XSS_Reflected", "SQL_Injection"],
        "status": ["New", "Recurring"],
        "state": ["Confirmed", "To Verify"]
      }
    }
  },
  "customFields": {
    "field1": "value1",
    "field2": "value2"
  },
  "scanCustomFields": {
    "field3": "value3",
    "field4": "value4"
  }
}

Refer to the Bug Tracker documentation for a list of all our Bug Trackers and Feedback Channels.

CxFlow is bundled with support for Jasypt for encrypting property files: http://www.jasypt.org/

Sample: https://www.ricston.com/blog/encrypting-properties-in-spring-boot-with-jasypt-spring-boot/

To avoid storing the decryption password in the YAML configuration, invoke CxFlow with the password and the encryption algorithm specified on the command line:

$ java -jar cx-flow-<version>.jar \
    --jasypt.encryptor.password=passphrase \
    --jasypt.encryptor.algorithm=PBEWITHHMACSHA512ANDAES_256

If desired, the password can also be specified in the YAML configuration file:

jasypt:
  encryptor:
    password: passphrase
    algorithm: PBEWITHHMACSHA512ANDAES_256

NOTE: Choose the appropriate algorithm for your deployment. This is a sample.

Environment variables can be leveraged for injecting the required jasypt cli values specified above:

JASYPT_ENCRYPTOR.PASSWORD=passphrase
JASYPT_ENCRYPTOR.ALGORITHM=PBEWITHHMACSHA512ANDAES_256

To create encrypted text, use the following command line to produce a base-64 encoded string:

$ java -cp cx-flow-<version>.jar \
    -Dloader.main=org.jasypt.intf.cli.JasyptPBEStringEncryptionCLI \
    org.springframework.boot.loader.PropertiesLauncher \
    ivGeneratorClassName=org.jasypt.iv.RandomIvGenerator \
    input="stuff to encrypt goes here" \
    password=passphrase \
    algorithm=PBEWITHHMACSHA512ANDAES_256
    

Encrypted values can be assigned to fields in the YAML configuration file using the format ENC(<base-64 encoded ciphertext>). Example:

jira:
   token: ENC(r2Q0H31voNvp4NWHQ3bSkNzxmguHnHe/fuA+JiJ6DeOt8Fbzcslm6Hlly78dm6RONSaL8lGywG5atPC0xzyCsA==)

There are places where a custom groovy script can be used while executing CxFlow. These include:

• Deciding which branch is applicable for scanning.
• The project name to be used.
• The team to be used.

For additional information, refer to the External Scripting chapter.

If user want to use SAST Scan ID for further usage cx-flow stores SCAN ID in githuab output variable name : cxflowscanid

- name: Checkmarx CxFlow Action
      id: step1
      uses: cx-flow/[email protected]
        project: ${{ github.event.repository.name }}
        team: ${{ secrets.CHECKMARX_TEAMS }}
        checkmarx_url: ${{ secrets.CHECKMARX_URL }}
        checkmarx_username: ${{ secrets.CHECKMARX_USERNAME }}
        checkmarx_password: ${{ secrets.CHECKMARX_PASSWORD }}
        checkmarx_client_secret: ${{ secrets.CHECKMARX_CLIENT_SECRET }}
        scanners: sast
        params: --github --checkmarx.incremental=false --checkmarx.settings-override=true --namespace=${{ github.repository_owner }} --repo-name=${{ github.event.repository.name }} --branch=${{ github.ref_name }} --cx-flow.filter-severity --cx-flow.filter-category --checkmarx.disable-clubbing=true --repo-url=${{ github.event.repository.url }}
   

Steps to retrieve SCAN ID**** in output variable -

• Since Scan ID we are getting only after run of cx-flow, So we will use ID of Checkmarx CxFlow Action steps in output variable to fetch SCAN ID

outputs:
      output1: ${{ steps.step1.outputs.cxflowscanid }}

• Now SCAN ID is stored in output1 variable which can be used in any jobs as per user convince.

NOTE: If SAST scan is taking time to scan files and other jobs are stuck due to this so user can run cx-flow in Async mode and with the help of SCAN ID from output variable, User can fetch results. In This way there is no jobs will be blocked due to processing of cx-flow.

Create an XML file named logback-spring.xml with a Logback configuration similar to the XML below:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>

  <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
    <layout class="ch.qos.logback.classic.PatternLayout">
      <pattern>%d{dd-MM-yyyy HH:mm:ss.SSS} %magenta([%thread]) %highlight(%-5level) %logger{36}.%M - %msg%n</pattern>
    </layout>
  </appender>

  <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
    <encoder>
      <pattern>%d{dd-MM-yyyy HH:mm:ss.SSS} [%thread] %-5level %logger{36}.%M - %msg%n</pattern>
    </encoder>

    <rollingPolicy class="ch.qos.logback.core.rolling.SizeAndTimeBasedRollingPolicy">
      <fileNamePattern>/logs/cxflow.%d{yyyy-MM-dd}.%i.log.gz</fileNamePattern>
      <maxFileSize>10MB</maxFileSize>
      <totalSizeCap>20GB</totalSizeCap>
      <maxHistory>7</maxHistory>
    </rollingPolicy>
  </appender>

  <logger name="com.checkmarx" level="INFO" />
  <logger name="org.apache.http.wire" level="ERROR" />
  <logger name="org.springframework.ws" level="ERROR" />

  <root level="INFO">
    <appender-ref ref="FILE" />
    <appender-ref ref="CONSOLE" />
  </root>
</configuration>

Place this file in a location where CxFlow can access it during execution.

Remove all logging configuration from the CxFlow configuration YAML file and replace it with this line:

logging.config: logback-spring.xml

Provide the full path of the logback-spring.xml file.

This example is showing the pipeline configured for the AWS OpenSearch version of Logstash. The ElasticSearch version of Logstash is configured similarly. Please consult the appropriate Logstash documentation for a configuration that best fits your needs.

The pipeline configuration should look similar to the following example:

input {

    file {
        check_archive_validity => true
        path => "/cxflow-logs/*.log"
    }
}


output {

    opensearch {
        hosts => ["https://<your host url here>:443/"] 
        index => "cxflow-logs"
        user => "<username>"
        password => "<password>"
        ecs_compatibility => "disabled"
        ssl_certificate_verification => false
    }
}

Adjust the path configuration element as appropriate to tail logs where you set the CxFlow logs to be stored in the XML file created in Step 1. The OpenSearch configuration elements will need to be adjusted to fit your appropriate storage requirements for OpenSearch/ElasticSearch.

If Logstash has been configured correctly, the CxFlow logs will now be tailed and sent to OpenSearch/ElasticSearch.

• We can label SAST issue in GITHUB and GITLAB.If user want to create issue he can pass labels in following way-

github:
  webhook-token: 12345
  url: https://github.com
  api-url: https://api.github.com/repos/
  false-positive-label: false-positive
  block-merge: true
  error-merge: true
  max-description-length : 400
  cx-summary: true
  issueslabel:
    high: high,must fix
    medium: Medium,Not critical
    low: ignore
  #max-delay : 3

gitlab:
  webhook-token: 12345
  url: https://gitlab.com
  api-url: https://gitlab.com/api/v4/
  false-positive-label: false-positive
  block-merge: true
  issueslabel:
    high: high,must fix
    medium: Medium,Not critical
    low: ignore

• User can also pass this as command line parameter.

--gitlab.issueslabel.medium="Medium,Not critical" --gitlab.issueslabel.low="ignore" --gitlab.issueslabel.high="high,must fix" #assigns 2 labels, high and must fix" --gitlab.issueslabel.info="very low"
--github.issueslabel.medium="Medium,Not critical" --github.issueslabel.low="ignore" --github.issueslabel.high="high,must fix" #assigns 2 labels, high and must fix" --github.issueslabel.info="very low"