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_data |
Parameters¶
Overview - Step¶
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¶
assignees¶
Defines the assignees for the Github Issue created/updated with the results of the scan as a list of login names.
Scope | Details |
---|---|
Aliases | - |
Type | []string |
Mandatory | no |
Default | |
Secret | no |
Configuration scope |
|
Resource references | none |
avoidDuplicateProjectScans¶
Tell Checkmarx to skip the scan if no code change is detected
Scope | Details |
---|---|
Aliases | notForceScan |
Type | bool |
Mandatory | no |
Default | true |
Possible values | - true - false |
Secret | no |
Configuration scope |
|
Resource references | none |
convertToSarif¶
Convert the Checkmarx XML scan results to the open SARIF standard.
Scope | Details |
---|---|
Aliases | - |
Type | bool |
Mandatory | no |
Default | true |
Possible values | - true - false |
Secret | no |
Configuration scope |
|
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.
Scope | Details |
---|---|
Aliases | - |
Type | bool |
Mandatory | no |
Default | false |
Possible values | - true - false |
Secret | no |
Configuration scope |
|
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
Scope | Details |
---|---|
Aliases | sourceEncoding |
Type | string |
Mandatory | no |
Default | $PIPER_engineConfigurationID (if set) |
Secret | no |
Configuration scope |
|
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
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 |
|
Resource references | none |
fullScanCycle¶
Indicates how often a full scan should happen between the incremental scans when activated
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | no |
Default | 5 |
Secret | no |
Configuration scope |
|
Resource references | none |
fullScansScheduled¶
Whether full scans are to be scheduled or not. Should be used in relation with incremental
and fullScanCycle
Scope | Details |
---|---|
Aliases | - |
Type | bool |
Mandatory | no |
Default | true |
Possible values | - true - false |
Secret | no |
Configuration scope |
|
Resource references | none |
generatePdfReport¶
Whether to generate a PDF report of the analysis results or not
Scope | Details |
---|---|
Aliases | - |
Type | bool |
Mandatory | no |
Default | true |
Possible values | - true - false |
Secret | no |
Configuration scope |
|
Resource references | none |
githubApiUrl¶
Set the GitHub API URL.
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | no |
Default | https://api.github.com |
Secret | no |
Configuration scope |
|
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
Scope | Details |
---|---|
Aliases | access_token |
Type | string |
Mandatory | no |
Default | $PIPER_githubToken (if set) |
Secret | yes |
Configuration scope |
|
Resource references | Jenkins credential id: id: githubTokenCredentialsId Vault resource: name: githubVaultSecretName default value: github Vault paths:
|
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
Scope | Details |
---|---|
Aliases | - |
Type | bool |
Mandatory | no |
Default | true |
Possible values | - true - false |
Secret | no |
Configuration scope |
|
Resource references | none |
isOptimizedAndScheduled¶
Whether the pipeline runs in optimized mode and the current execution is a scheduled one
Scope | Details |
---|---|
Aliases | - |
Type | bool |
Mandatory | no |
Default | false |
Possible values | - true - false |
Secret | no |
Configuration scope |
|
Resource references | commonPipelineEnvironment: reference to: custom/isOptimizedAndScheduled |
maxRetries¶
Maximum number of HTTP request retries upon intermittend connetion interrupts
Scope | Details |
---|---|
Aliases | - |
Type | int |
Mandatory | no |
Default | 3 |
Secret | no |
Configuration scope |
|
Resource references | none |
owner¶
Set the GitHub organization.
Scope | Details |
---|---|
Aliases | githubOrg |
Type | string |
Mandatory | no |
Default | $PIPER_owner (if set) |
Secret | no |
Configuration scope |
|
Resource references | commonPipelineEnvironment: reference to: github/owner |
password¶
The password to authenticate
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | yes |
Default | $PIPER_password (if set) |
Secret | yes |
Configuration scope |
|
Resource references | Jenkins credential id: id: checkmarxCredentialsId reference to: password Vault resource: name: checkmarxVaultSecretName default value: checkmarx Vault paths:
|
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
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | no |
Default | $PIPER_preset (if set) |
Secret | no |
Configuration scope |
|
Resource references | none |
projectName¶
The name of the Checkmarx project to scan into
Scope | Details |
---|---|
Aliases | - checkmarxProject - checkMarxProjectName (deprecated) |
Type | string |
Mandatory | yes |
Default | $PIPER_projectName (if set) |
Secret | no |
Configuration scope |
|
Resource references | none |
pullRequestName¶
Used to supply the name for the newly created PR project branch when being used in pull request scenarios
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | no |
Default | $PIPER_pullRequestName (if set) |
Secret | no |
Configuration scope |
|
Resource references | none |
repository¶
Set the GitHub repository.
Scope | Details |
---|---|
Aliases | githubRepo |
Type | string |
Mandatory | no |
Default | $PIPER_repository (if set) |
Secret | no |
Configuration scope |
|
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.
Scope | Details |
---|---|
Aliases | - |
Type | Jenkins Script |
Mandatory | yes |
Default | |
Secret | no |
Configuration scope |
|
Resource references | none |
serverUrl¶
The URL pointing to the root of the Checkmarx server to be used
Scope | Details |
---|---|
Aliases | checkmarxServerUrl |
Type | string |
Mandatory | yes |
Default | $PIPER_serverUrl (if set) |
Secret | no |
Configuration scope |
|
Resource references | none |
stashContent¶
Jenkins-specific: Used for proper environment setup.
Specific stashes that should be considered for the step execution.
Scope | Details |
---|---|
Aliases | - |
Type | []string |
Mandatory | no |
Default | - checkmarx |
Secret | no |
Configuration scope |
|
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
Scope | Details |
---|---|
Aliases | - checkmarxGroupId - groupId (deprecated) |
Type | string |
Mandatory | no |
Default | $PIPER_teamId (if set) |
Secret | no |
Configuration scope |
|
Resource references | none |
teamName¶
The full name of the team to assign newly created projects to which is preferred to teamId
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | no |
Default | $PIPER_teamName (if set) |
Secret | no |
Configuration scope |
|
Resource references | none |
username¶
The username to authenticate
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | yes |
Default | $PIPER_username (if set) |
Secret | yes |
Configuration scope |
|
Resource references | Jenkins credential id: id: checkmarxCredentialsId reference to: username Vault resource: name: checkmarxVaultSecretName default value: checkmarx Vault paths:
|
verbose¶
verbose output
Scope | Details |
---|---|
Aliases | - |
Type | bool |
Mandatory | no |
Default | false |
Possible values | - true - false |
Secret | no |
Configuration scope |
|
Resource references | none |
verifyOnly¶
Whether the step shall only apply verification checks or whether it does a full scan and check cycle
Scope | Details |
---|---|
Aliases | - |
Type | bool |
Mandatory | no |
Default | false |
Possible values | - true - false |
Secret | no |
Configuration scope |
|
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
Scope | Details |
---|---|
Aliases | - |
Type | bool |
Mandatory | no |
Default | true |
Possible values | - true - false |
Secret | no |
Configuration scope |
|
Resource references | none |
vulnerabilityThresholdHigh¶
The specific threshold for high severity findings
Scope | Details |
---|---|
Aliases | - |
Type | int |
Mandatory | no |
Default | 100 |
Secret | no |
Configuration scope |
|
Resource references | none |
vulnerabilityThresholdLow¶
The specific threshold for low severity findings
Scope | Details |
---|---|
Aliases | - |
Type | int |
Mandatory | no |
Default | 10 |
Secret | no |
Configuration scope |
|
Resource references | none |
vulnerabilityThresholdLowPerQuery¶
Flag to activate/deactivate the threshold of low severity findings per query
Scope | Details |
---|---|
Aliases | - |
Type | bool |
Mandatory | no |
Default | false |
Possible values | - true - false |
Secret | no |
Configuration scope |
|
Resource references | none |
vulnerabilityThresholdLowPerQueryMax¶
Upper threshold of low severity findings per query (in absolute number)
Scope | Details |
---|---|
Aliases | - |
Type | int |
Mandatory | no |
Default | 10 |
Secret | no |
Configuration scope |
|
Resource references | none |
vulnerabilityThresholdMedium¶
The specific threshold for medium severity findings
Scope | Details |
---|---|
Aliases | - |
Type | int |
Mandatory | no |
Default | 100 |
Secret | no |
Configuration scope |
|
Resource references | none |
vulnerabilityThresholdResult¶
The result of the build in case thresholds are enabled and exceeded
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | no |
Default | FAILURE |
Possible values | - FAILURE |
Secret | no |
Configuration scope |
|
Resource references | none |
vulnerabilityThresholdUnit¶
The unit for the threshold to apply.
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | no |
Default | percentage |
Secret | no |
Configuration scope |
|
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.
Scope | Details |
---|---|
Aliases | - |
Type | string |
Configuration scope |
|
githubTokenCredentialsId¶
Jenkins-specific: Used for proper environment setup. See using credentials for details.
Jenkins 'Secret text' credentials ID containing token to authenticate to GitHub.
Scope | Details |
---|---|
Aliases | - |
Type | string |
Configuration scope |
|