checkmarxOneExecuteScan

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

Description

checkmarxOne is a Static Application Security Testing (SAST) platform 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.

JenkinsCommand Line

library('piper-lib-os')

checkmarxOneExecuteScan script: this

piper checkmarxOneExecuteScan

Outputs

Output type

Details

influx

measurement step_data checkmarxOne measurement checkmarxOne_data high_issues high_not_false_postive high_not_exploitable high_confirmed high_urgent high_proposed_not_exploitable high_to_verify medium_issues medium_not_false_postive medium_not_exploitable medium_confirmed medium_urgent medium_proposed_not_exploitable medium_to_verify low_issues low_not_false_postive low_not_exploitable low_confirmed low_urgent low_proposed_not_exploitable low_to_verify information_issues information_not_false_postive 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 group group_full_path_on_report_date scan_start scan_time tool_version scan_type preset deep_link report_creation_time

Parameters

Overview - Step

Name	Mandatory	Additional information
APIKey	(yes)	pass via ENV, Vault or Jenkins credentials (checkmarxOneAPIKey)
branch	yes
clientId	(yes)	pass via ENV, Vault or Jenkins credentials (checkmarxOneCredentialsId)
clientSecret	(yes)	pass via ENV, Vault or Jenkins credentials (checkmarxOneCredentialsId)
iamUrl	yes
projectName	yes
script	(yes)	reference to Jenkins main pipeline script
serverUrl	yes
tenant	yes
applicationName	no
assignees	no
avoidDuplicateProjectScans	no
convertToSarif	no
createResultIssue	no
filterPattern	no
fullScanCycle	no
fullScansScheduled	no
generatePdfReport	no
gitBranch	no
githubApiUrl	no
githubToken	no	pass via ENV, Vault or Jenkins credentials (githubTokenCredentialsId)
groupName	no
incremental	no
isOptimizedAndScheduled	no
languageMode	no
owner	no
preset	no
projectCriticality	no
pullRequestName	no
repository	no
sourceEncoding	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

Details

APIKey

The APIKey to authenticate

back to overview

Scope	Details
Aliases	-
Type	string
Mandatory	yes
Default	$PIPER_APIKey (if set)
Secret	yes
Configuration scope	☒ parameter ☐ general ☒ steps ☒ stages
Resource references	Jenkins credential id:   id: checkmarxOneAPIKey   reference to: APIKey Vault paths: $(vaultPath)/checkmarxOne $(vaultBasePath)/$(vaultPipelineName)/checkmarxOne $(vaultBasePath)/GROUP-SECRETS/checkmarxOne

applicationName

The full name of the Checkmarx One application to which the newly created projects will be assigned

back to overview

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

assignees

Defines the assignees for the Github Issue created/updated with the results of the scan as a list of login names. [Not yet supported]

back to overview

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

avoidDuplicateProjectScans

Whether duplicate scans of the same project state shall be avoided or not [Not yet supported]

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

branch

Used to supply the branch scanned in the repository, or a friendly-name set by the user

back to overview

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

clientId

The username to authenticate

back to overview

Scope	Details
Aliases	-
Type	string
Mandatory	yes
Default	$PIPER_clientId (if set)
Secret	yes
Configuration scope	☒ parameter ☐ general ☒ steps ☒ stages
Resource references	Jenkins credential id:   id: checkmarxOneCredentialsId   reference to: clientId Vault paths: $(vaultPath)/checkmarxOne $(vaultBasePath)/$(vaultPipelineName)/checkmarxOne $(vaultBasePath)/GROUP-SECRETS/checkmarxOne

clientSecret

The clientSecret to authenticate using a service account

back to overview

Scope	Details
Aliases	-
Type	string
Mandatory	yes
Default	$PIPER_clientSecret (if set)
Secret	yes
Configuration scope	☒ parameter ☐ general ☒ steps ☒ stages
Resource references	Jenkins credential id:   id: checkmarxOneCredentialsId   reference to: clientSecret Vault paths: $(vaultPath)/checkmarxOne $(vaultBasePath)/$(vaultPipelineName)/checkmarxOne $(vaultBasePath)/GROUP-SECRETS/checkmarxOne

convertToSarif

Convert the checkmarxOne 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

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

gitBranch

Set the GitHub repository branch.

back to overview

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

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 paths: $(vaultPath)/github $(vaultBasePath)/$(vaultPipelineName)/github $(vaultBasePath)/GROUP-SECRETS/github

groupName

The full name of the group to which the newly created projects will be assigned

back to overview

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

iamUrl

The URL pointing to the access control root of the checkmarxOne IAM server to be used

back to overview

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

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

languageMode

Specifies whether the scan should be run for a 'single' language or 'multi' language, default 'multi'

back to overview

Scope	Details
Aliases	-
Type	string
Mandatory	no
Default	multi
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

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 checkmarxOneCredentialsId

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

projectCriticality

The criticality of the checkmarxOne project, used during project creation

back to overview

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

projectName

The name of the checkmarxOne project to scan into

back to overview

Scope	Details
Aliases	-
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. This is supplied by the orchestrator.

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 checkmarxOne server to be used

back to overview

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

sourceEncoding

The source encoding to be used, if not set explicitly the project's default will be used [Not yet supported]

back to overview

Scope	Details
Aliases	-
Type	string
Mandatory	no
Default	1
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	- checkmarxOne
Secret	no
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	none

tenant

The name of the checkmarxOne tenant to be used

back to overview

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

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

checkmarxOneCredentialsId

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

Jenkins 'Username with password' credentials ID containing ClientID and ClientSecret to communicate with the checkmarxOne backend.

back to overview

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

checkmarxOneAPIKey

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

Jenkins 'Secret Text' containing the APIKey to communicate with the checkmarxOne 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