Skip to content

checkmarxExecuteScan

Checkmarx is the recommended tool for security scans of JavaScript, iOS, Swift and Ruby code.

Description

Checkmarx is a Static Application Security Testing (SAST) tool to analyze i.e. Java- or TypeScript, Swift, Golang, Ruby code, and many other programming languages for security flaws based on a set of provided rules/queries that can be customized and extended.

This step by default enforces a specific audit baseline for findings and therefore ensures that:

  • No 'To Verify' High and Medium issues exist in your project
  • Total number of High and Medium 'Confirmed' or 'Urgent' issues is zero
  • 10% of all Low issues are 'Confirmed' or 'Not Exploitable'

You can adapt above thresholds specifically using the provided configuration parameters and i.e. check for absolute thresholds instead of percentage whereas we strongly recommend you to stay with the defaults provided.

Usage

We recommend to define values of step parameters via .pipeline/config.yml file.
In this case, calling the step is essentially reduced to defining the step name.
Calling the step can be done either in an orchestrator specific way (e.g. via a Jenkins library step) or on the command line.

library('piper-lib-os')

checkmarxExecuteScan script: this
piper checkmarxExecuteScan

Outputs

Output type Details
influx measurement step_data
  • checkmarx
  • measurement checkmarx_data
    • high_issues
    • high_not_false_positive
    • high_not_exploitable
    • high_confirmed
    • high_urgent
    • high_proposed_not_exploitable
    • high_to_verify
    • medium_issues
    • medium_not_false_positive
    • medium_not_exploitable
    • medium_confirmed
    • medium_urgent
    • medium_proposed_not_exploitable
    • medium_to_verify
    • low_issues
    • low_not_false_positive
    • low_not_exploitable
    • low_confirmed
    • low_urgent
    • low_proposed_not_exploitable
    • low_to_verify
    • information_issues
    • information_not_false_positive
    • information_not_exploitable
    • information_confirmed
    • information_urgent
    • information_proposed_not_exploitable
    • information_to_verify
    • lines_of_code_scanned
    • files_scanned
    • initiator_name
    • owner
    • scan_id
    • project_id
    • projectName
    • team
    • team_full_path_on_report_date
    • scan_start
    • scan_time
    • checkmarx_version
    • scan_type
    • preset
    • deep_link
    • report_creation_time

Parameters

Overview - Step

Name Mandatory Additional information
password (yes) Vault Secret pass via ENV, Vault or Jenkins credentials (checkmarxCredentialsId)
projectName yes
script (yes) Jenkins only reference to Jenkins main pipeline script
serverUrl yes
username (yes) Vault Secret pass via ENV, Vault or Jenkins credentials (checkmarxCredentialsId)
assignees no
avoidDuplicateProjectScans no
convertToSarif no
createResultIssue no
engineConfigurationID no
filterPattern no
fullScanCycle no
fullScansScheduled no
generatePdfReport no
githubApiUrl no
githubToken no Vault Secret pass via ENV, Vault or Jenkins credentials (githubTokenCredentialsId)
incremental no
isOptimizedAndScheduled no
maxRetries no
owner no
preset no
pullRequestName no
repository no
teamId no
teamName no
verbose no activates debug output
verifyOnly no
vulnerabilityThresholdEnabled no
vulnerabilityThresholdHigh no
vulnerabilityThresholdLow no
vulnerabilityThresholdLowPerQuery no
vulnerabilityThresholdLowPerQueryMax no
vulnerabilityThresholdMedium no
vulnerabilityThresholdResult no
vulnerabilityThresholdUnit no

Overview - Execution Environment

Orchestrator-specific only

These parameters are relevant for orchestrator usage and not considered when using the command line option.

Name Mandatory Additional information
stashContent no Jenkins only

Details

assignees

Defines the assignees for the Github Issue created/updated with the results of the scan as a list of login names.

back to overview

Scope Details
Aliases -
Type []string
Mandatory no
Default
Secret no
Configuration scope
  • ☒ parameter
  • ☐ general
  • ☒ steps
  • ☒ stages
Resource references none

avoidDuplicateProjectScans

Tell Checkmarx to skip the scan if no code change is detected

back to overview

Scope Details
Aliases notForceScan
Type bool
Mandatory no
Default true
Possible values - true
- false
Secret no
Configuration scope
  • ☒ parameter
  • ☐ general
  • ☒ steps
  • ☒ stages
Resource references none

convertToSarif

Convert the Checkmarx XML scan results to the open SARIF standard.

back to overview

Scope Details
Aliases -
Type bool
Mandatory no
Default true
Possible values - true
- false
Secret no
Configuration scope
  • ☒ parameter
  • ☐ general
  • ☒ steps
  • ☒ stages
Resource references none

createResultIssue

Whether the step creates a GitHub issue containing the scan results in the originating repo. Since optimized pipelines are headless the creation is implicitly activated for scheduled runs.

back to overview

Scope Details
Aliases -
Type bool
Mandatory no
Default false
Possible values - true
- false
Secret no
Configuration scope
  • ☒ parameter
  • ☒ general
  • ☒ steps
  • ☒ stages
Resource references commonPipelineEnvironment:
  reference to: custom/isOptimizedAndScheduled

engineConfigurationID

The engine configuration ID to be used, if not set explicitly the project's default will be used

back to overview

Scope Details
Aliases sourceEncoding
Type string
Mandatory no
Default $PIPER_engineConfigurationID (if set)
Secret no
Configuration scope
  • ☒ parameter
  • ☐ general
  • ☒ steps
  • ☒ stages
Resource references none

filterPattern

The filter pattern used to zip the files relevant for scanning, patterns can be negated by setting an exclamation mark in front i.e. !test/*.js would avoid adding any javascript files located in the test directory

back to overview

Scope Details
Aliases -
Type string
Mandatory no
Default !**/node_modules/**, !**/.xmake/**, !**/*_test.go, !**/vendor/**/*.go, **/*.html, **/*.xml, **/*.go, **/*.py, **/*.js, **/*.scala, **/*.ts
Secret no
Configuration scope
  • ☒ parameter
  • ☐ general
  • ☒ steps
  • ☒ stages
Resource references none

fullScanCycle

Indicates how often a full scan should happen between the incremental scans when activated

back to overview

Scope Details
Aliases -
Type string
Mandatory no
Default 5
Secret no
Configuration scope
  • ☒ parameter
  • ☐ general
  • ☒ steps
  • ☒ stages
Resource references none

fullScansScheduled

Whether full scans are to be scheduled or not. Should be used in relation with incremental and fullScanCycle

back to overview

Scope Details
Aliases -
Type bool
Mandatory no
Default true
Possible values - true
- false
Secret no
Configuration scope
  • ☒ parameter
  • ☐ general
  • ☒ steps
  • ☒ stages
Resource references none

generatePdfReport

Whether to generate a PDF report of the analysis results or not

back to overview

Scope Details
Aliases -
Type bool
Mandatory no
Default true
Possible values - true
- false
Secret no
Configuration scope
  • ☒ parameter
  • ☐ general
  • ☒ steps
  • ☒ stages
Resource references none

githubApiUrl

Set the GitHub API URL.

back to overview

Scope Details
Aliases -
Type string
Mandatory no
Default https://api.github.com
Secret no
Configuration scope
  • ☒ parameter
  • ☒ general
  • ☒ steps
  • ☒ stages
Resource references none

githubToken

GitHub personal access token as per https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line

back to overview

Scope Details
Aliases access_token
Type string
Mandatory no
Default $PIPER_githubToken (if set)
Secret yes
Configuration scope
  • ☒ parameter
  • ☒ general
  • ☒ steps
  • ☒ stages
Resource references Jenkins credential id:
  id: githubTokenCredentialsId

Vault resource:
  name: githubVaultSecretName
  default value: github

Vault paths:
  • $(vaultPath)/github
  • $(vaultBasePath)/$(vaultPipelineName)/github
  • $(vaultBasePath)/GROUP-SECRETS/github

incremental

Whether incremental scans are to be applied which optimizes the scan time but might reduce detection capabilities. Therefore full scans are still required from time to time and should be scheduled via fullScansScheduled and fullScanCycle

back to overview

Scope Details
Aliases -
Type bool
Mandatory no
Default true
Possible values - true
- false
Secret no
Configuration scope
  • ☒ parameter
  • ☐ general
  • ☒ steps
  • ☒ stages
Resource references none

isOptimizedAndScheduled

Whether the pipeline runs in optimized mode and the current execution is a scheduled one

back to overview

Scope Details
Aliases -
Type bool
Mandatory no
Default false
Possible values - true
- false
Secret no
Configuration scope
  • ☒ parameter
  • ☐ general
  • ☐ steps
  • ☐ stages
Resource references commonPipelineEnvironment:
  reference to: custom/isOptimizedAndScheduled

maxRetries

Maximum number of HTTP request retries upon intermittend connetion interrupts

back to overview

Scope Details
Aliases -
Type int
Mandatory no
Default 3
Secret no
Configuration scope
  • ☒ parameter
  • ☐ general
  • ☒ steps
  • ☒ stages
Resource references none

owner

Set the GitHub organization.

back to overview

Scope Details
Aliases githubOrg
Type string
Mandatory no
Default $PIPER_owner (if set)
Secret no
Configuration scope
  • ☒ parameter
  • ☒ general
  • ☒ steps
  • ☒ stages
Resource references commonPipelineEnvironment:
  reference to: github/owner

password

The password to authenticate

back to overview

Scope Details
Aliases -
Type string
Mandatory yes
Default $PIPER_password (if set)
Secret yes
Configuration scope
  • ☒ parameter
  • ☐ general
  • ☒ steps
  • ☒ stages
Resource references Jenkins credential id:
  id: checkmarxCredentialsId
  reference to: password

Vault resource:
  name: checkmarxVaultSecretName
  default value: checkmarx

Vault paths:
  • $(vaultPath)/checkmarx
  • $(vaultBasePath)/$(vaultPipelineName)/checkmarx
  • $(vaultBasePath)/GROUP-SECRETS/checkmarx

preset

The preset to use for scanning, if not set explicitly the step will attempt to look up the project's setting based on the availability of checkmarxCredentialsId

back to overview

Scope Details
Aliases -
Type string
Mandatory no
Default $PIPER_preset (if set)
Secret no
Configuration scope
  • ☒ parameter
  • ☐ general
  • ☒ steps
  • ☒ stages
Resource references none

projectName

The name of the Checkmarx project to scan into

back to overview

Scope Details
Aliases - checkmarxProject
- checkMarxProjectName (deprecated)
Type string
Mandatory yes
Default $PIPER_projectName (if set)
Secret no
Configuration scope
  • ☒ parameter
  • ☐ general
  • ☒ steps
  • ☒ stages
Resource references none

pullRequestName

Used to supply the name for the newly created PR project branch when being used in pull request scenarios

back to overview

Scope Details
Aliases -
Type string
Mandatory no
Default $PIPER_pullRequestName (if set)
Secret no
Configuration scope
  • ☒ parameter
  • ☐ general
  • ☒ steps
  • ☒ stages
Resource references none

repository

Set the GitHub repository.

back to overview

Scope Details
Aliases githubRepo
Type string
Mandatory no
Default $PIPER_repository (if set)
Secret no
Configuration scope
  • ☒ parameter
  • ☒ general
  • ☒ steps
  • ☒ stages
Resource references commonPipelineEnvironment:
  reference to: github/repository

script

Jenkins-specific: Used for proper environment setup.

The common script environment of the Jenkinsfile running. Typically the reference to the script calling the pipeline step is provided with the this parameter, as in script: this. This allows the function to access the commonPipelineEnvironment for retrieving, e.g. configuration parameters.

back to overview

Scope Details
Aliases -
Type Jenkins Script
Mandatory yes
Default
Secret no
Configuration scope
  • ☐ parameter
  • ☐ general
  • ☐ steps
  • ☐ stages
Resource references none

serverUrl

The URL pointing to the root of the Checkmarx server to be used

back to overview

Scope Details
Aliases checkmarxServerUrl
Type string
Mandatory yes
Default $PIPER_serverUrl (if set)
Secret no
Configuration scope
  • ☒ parameter
  • ☒ general
  • ☒ steps
  • ☒ stages
Resource references none

stashContent

Jenkins-specific: Used for proper environment setup.

Specific stashes that should be considered for the step execution.

back to overview

Scope Details
Aliases -
Type []string
Mandatory no
Default - checkmarx
Secret no
Configuration scope
  • ☒ parameter
  • ☒ general
  • ☒ steps
  • ☒ stages
Resource references none

teamId

The group ID related to your team which can be obtained via the Pipeline Syntax plugin as described in the Details section

back to overview

Scope Details
Aliases - checkmarxGroupId
- groupId (deprecated)
Type string
Mandatory no
Default $PIPER_teamId (if set)
Secret no
Configuration scope
  • ☒ parameter
  • ☐ general
  • ☒ steps
  • ☒ stages
Resource references none

teamName

The full name of the team to assign newly created projects to which is preferred to teamId

back to overview

Scope Details
Aliases -
Type string
Mandatory no
Default $PIPER_teamName (if set)
Secret no
Configuration scope
  • ☒ parameter
  • ☐ general
  • ☒ steps
  • ☒ stages
Resource references none

username

The username to authenticate

back to overview

Scope Details
Aliases -
Type string
Mandatory yes
Default $PIPER_username (if set)
Secret yes
Configuration scope
  • ☒ parameter
  • ☐ general
  • ☒ steps
  • ☒ stages
Resource references Jenkins credential id:
  id: checkmarxCredentialsId
  reference to: username

Vault resource:
  name: checkmarxVaultSecretName
  default value: checkmarx

Vault paths:
  • $(vaultPath)/checkmarx
  • $(vaultBasePath)/$(vaultPipelineName)/checkmarx
  • $(vaultBasePath)/GROUP-SECRETS/checkmarx

verbose

verbose output

back to overview

Scope Details
Aliases -
Type bool
Mandatory no
Default false
Possible values - true
- false
Secret no
Configuration scope
  • ☒ parameter
  • ☒ general
  • ☒ steps
  • ☒ stages
Resource references none

verifyOnly

Whether the step shall only apply verification checks or whether it does a full scan and check cycle

back to overview

Scope Details
Aliases -
Type bool
Mandatory no
Default false
Possible values - true
- false
Secret no
Configuration scope
  • ☒ parameter
  • ☐ general
  • ☒ steps
  • ☒ stages
Resource references none

vulnerabilityThresholdEnabled

Whether the thresholds are enabled or not. If enabled the build will be set to vulnerabilityThresholdResult in case a specific threshold value is exceeded

back to overview

Scope Details
Aliases -
Type bool
Mandatory no
Default true
Possible values - true
- false
Secret no
Configuration scope
  • ☒ parameter
  • ☐ general
  • ☒ steps
  • ☒ stages
Resource references none

vulnerabilityThresholdHigh

The specific threshold for high severity findings

back to overview

Scope Details
Aliases -
Type int
Mandatory no
Default 100
Secret no
Configuration scope
  • ☒ parameter
  • ☐ general
  • ☒ steps
  • ☒ stages
Resource references none

vulnerabilityThresholdLow

The specific threshold for low severity findings

back to overview

Scope Details
Aliases -
Type int
Mandatory no
Default 10
Secret no
Configuration scope
  • ☒ parameter
  • ☐ general
  • ☒ steps
  • ☒ stages
Resource references none

vulnerabilityThresholdLowPerQuery

Flag to activate/deactivate the threshold of low severity findings per query

back to overview

Scope Details
Aliases -
Type bool
Mandatory no
Default false
Possible values - true
- false
Secret no
Configuration scope
  • ☒ parameter
  • ☐ general
  • ☒ steps
  • ☒ stages
Resource references none

vulnerabilityThresholdLowPerQueryMax

Upper threshold of low severity findings per query (in absolute number)

back to overview

Scope Details
Aliases -
Type int
Mandatory no
Default 10
Secret no
Configuration scope
  • ☒ parameter
  • ☐ general
  • ☒ steps
  • ☒ stages
Resource references none

vulnerabilityThresholdMedium

The specific threshold for medium severity findings

back to overview

Scope Details
Aliases -
Type int
Mandatory no
Default 100
Secret no
Configuration scope
  • ☒ parameter
  • ☐ general
  • ☒ steps
  • ☒ stages
Resource references none

vulnerabilityThresholdResult

The result of the build in case thresholds are enabled and exceeded

back to overview

Scope Details
Aliases -
Type string
Mandatory no
Default FAILURE
Possible values - FAILURE
Secret no
Configuration scope
  • ☒ parameter
  • ☐ general
  • ☒ steps
  • ☒ stages
Resource references none

vulnerabilityThresholdUnit

The unit for the threshold to apply.

back to overview

Scope Details
Aliases -
Type string
Mandatory no
Default percentage
Secret no
Configuration scope
  • ☒ parameter
  • ☐ general
  • ☒ steps
  • ☒ stages
Resource references none

checkmarxCredentialsId

Jenkins-specific: Used for proper environment setup. See using credentials for details.

Jenkins 'Username with password' credentials ID containing username and password to communicate with the Checkmarx backend.

back to overview

Scope Details
Aliases -
Type string
Configuration scope
  • ☒ parameter
  • ☒ general
  • ☒ steps
  • ☒ stages

githubTokenCredentialsId

Jenkins-specific: Used for proper environment setup. See using credentials for details.

Jenkins 'Secret text' credentials ID containing token to authenticate to GitHub.

back to overview

Scope Details
Aliases -
Type string
Configuration scope
  • ☒ parameter
  • ☒ general
  • ☒ steps
  • ☒ stages