Configuring & Running the Checkmarx-Maven Plugin (v8.7.0 to v8.9.0)

The Checkmarx CxSAST/CxOSA plugin for Maven is simple to configure and run.

  1. First, ensure you have Apache Maven installed on the build machine (or go to the Apache Maven site for downloading and installing).

       2. Configure the Checkmarx-Maven plugin as needed.

       3. Create a new Maven project and compile it.  

You can also visit our Frequently Asked Questions page for the Checkmarx-Maven plugin.

Configuring the Checkmarx-Maven Plugin (CxSAST & CxOSA)

To include CxSAST & CxOSA for your project, add the following code (below) inside the <plugin> section.

The following is a typical example of a pom.xml file snippet - relevant for both CxSAST & CxOSA scans, that contains the available parameters with sample values. Note that url, username and password are mandatory parameters.

Configuring the Plugin with CxOSA

  • You can easily run CxOSA with the CxSAST scan by including the <osaEnabled> tag in the pom.xml file.
  • Note that you cannot run CxOSA without running the CxSAST scan.
<build>
		<plugins>
        	<plugin>
            	<groupId>com.checkmarx.maven</groupId>
                <artifactId>checkmarx-maven-plugin</artifactId>
                <version>x.xx.x</version>				
				<configuration>
                    <url>http://localhost</url>
                    <username>user@org</username>
                    <password>Org123456</password>
                    <fullTeamPath>CxServer\SP</fullTeamPath>
                    <preset>all</preset>
                    <isIncrementalScan>false</isIncrementalScan>
                    <highSeveritiesThreshold>1</highSeveritiesThreshold>
                    <mediumSeveritiesThreshold>20</mediumSeveritiesThreshold>
                    <lowSeveritiesThreshold>30</lowSeveritiesThreshold>                
                    <fileExclusions>file1, file2</fileExclusions>
                    <folderExclusions></folderExclusions>                                       
                    <generatePDFReport>true</generatePDFReport>
                    <isSynchronous>true</isSynchronous>
                    <outputDirectory>c:\users\tmp</outputDirectory>
                    <projectName>Project 22 (Maven)</projectName>
                    <scanTimeoutInMinutes>10</scanTimeoutInMinutes>                      
                    <disableCertificateVerification>false</disableCertificateVerification>
                    <osaEnabled>false</osaEnabled>
                    <osaHighSeveritiesThreshold>1</osaHighSeveritiesThreshold>
                    <osaMediumSeveritiesThreshold>0</osaMediumSeveritiesThreshold>
                    <osaLowSeveritiesThreshold>0</osaLowSeveritiesThreshold>
                    <osaExclusions>file1, file2</osaExclusion>
                    <osaIgnoreScopes>1</osaIgnoreScopes>
                    <osaGenerateJsonReport>0</osaGenerateJsonReport>
			     </configuration>
			</plugin>        
         </plugins>
</build>  

CheckmarxMaven Plugin Parameters for CxSAST & CxOSA

You can change the following parameter values (for example, to the default values as listed in the table)

ParameterTypeScan TypeDefault ValueDescription

url

 

URL


http://localhost

Host name of the Checkmarx application.

NOTE: CxSAST Maven plugin also supports https://

username

string


 

The username of the user running the scan.

password

string


 

The password of the user running the scan.

fullTeamPath





string
CxServerThe full path describing the team the scan belongs to.

outputDirectory





file


{project.build.directory}\checkmarxDefine an output directory for scan reports.

projectName





string


${project.name}The name of the project being scanned. It will be taken from the Maven pom.xml project name if not provided.

isSynchronous





Boolean

CxSAST

CxOSA

trueIf true, the build will wait for the scan to end and display the results. If false, the build will trigger the scan without waiting for the scan to end and the results will not be displayed.

disableCertificateVerification





Boolean

CxSAST

CxOSA

falseDisables the SSL/TLS Certificate Validation.

highSeveritiesThreshold

integer

CxSAST

 

Configure a threshold for the High Severity Vulnerabilities. The build will fail if the sum of High Severity Vulnerabilities is larger than the threshold. Leave empty to ignore threshold.

mediumSeveritiesThreshold

integer

CxSAST

 

Configure a threshold for the Medium Severity Vulnerabilities. The build will fail if the sum of Medium Severity Vulnerabilities is larger than the threshold. Leave empty to ignore threshold.

lowSeveritiesThreshold

 

 

 

integer

CxSAST

 

Configure a threshold for the Low Severity Vulnerabilities. The build will fail if the sum of Low Severity Vulnerabilities is larger than the threshold. Leave empty to ignore threshold.

isIncrementalScan

Boolean

CxSAST

true

If true, an incremental scan will be performed, meaning - only modified files will be scanned.

preset

string

CxSAST

Checkmarx default

Configure this field to scan the project with one of the predefined scan presets, or one of your custom presets.

fileExclusions

string

CxSAST

 

List of files and\or file patterns which the scan will ignore.

folderExclusions

string

CxSAST

 

List of folders and\or folder patterns which the scan will ignore.

generatePDFReport

Boolean

CxSAST

true

If true, a PDF report will be generated in the output directory.

scanTimeoutInMinutes

integer

CxSAST


0

Defines a timeout (in minutes) for the scan. If the specified time has passed, the build fails. Set to 0 to run the scan with no time limit. This value is ignored if not provided.

osaEnabledBooleanCxOSAfalseIf true, CxOSA will be enabled.
osaHighSeveritiesThresholdintegerCxOSA
Configure a threshold for the CxOSA High Severity Vulnerabilities. The build will fail if the sum of High Severity Vulnerabilities is larger than the threshold. Leave empty to ignore threshold.
osaMediumSeveritiesThresholdintegerCxOSA
Configure a threshold for the CxOSA Medium Severity Vulnerabilities. The build will fail if the sum of Medium Severity Vulnerabilities is larger than the threshold. Leave empty to ignore threshold
osaLowSeveritiesThresholdintegerCxOSA
Configure a threshold for the CxOSA Low Severity Vulnerabilities. The build will fail if the sum of Low Severity Vulnerabilities is larger than the threshold. Leave empty to ignore threshold.
osaIgnoreScopesstringCxOSA
List of Maven scopes to be ignored in a CxOSA scan. Provided scopes are ignored by default unless configured otherwise
osaExclusionsstringCxOSA

List of Maven dependencies that will not be included in CxOSA. An exclusion should be of the form: groupId.artifactId.

NOTE: osaExclusions has been deprecated and is no longer supported. If applied, the following log message is written; ${param} is not supported in this Maven version.

osaGenerateJsonReportBooleanCxOSAtrueIf true, a CxOSA PDF report will be generated in the output directory.


Running the Checkmarx-Maven Plugin 

After you have added the code (above) inside the <plugin> section, now run the following command: mvn checkmarx:scan "–D<parameter>=<value>"

For example:  mvn checkmarx:scan "–Dcx.password=[your password]"

Running your build process will now automatically initiate the CxSAST scan that includes the Open Source Analysis (CxOSA) scan.


How to Pass External Variables to the Checkmarx–Maven Plugin

If, for example, you want to avoid storing your personal password inside the pom.xml file, you can pass it externally (therefore overwriting the password parameter in the pom.xml).

  • Run: mvn checkmarx:scan "–D<parameter>=<value>"

For example:  mvn checkmarx:scan "–Dcx.password=[your password]"

Note that when passing special characters, the entire –D parameter should be in quotes.

You can pass all other parameters per the example above using the –Dcx. prefix. For example: cx.<parameter> (e.g. cx.fullTeamPath="")