Installing and Configuring the Azure DevOps (MS-VSTS) Plugin (v8.8.0)
The Checkmarx CxSAST plug-in for Azure DevOps is simple to install and configure.
Prerequisites
The following components are required before installing and using the Azure DevOps pluging (MS-VSTS).
- Registered Microsoft Visual Studio Team Services Cloud version user.
- Access to the Checkmarx plugin, available from the Visual Studio Market Place for download and installation.
On the CxServer site, the following is required:
- Existing User - CxServer installed on Cloud (Checkmarx Cloud Account)
- New User - Checkmarx for Microsoft Visual Studio Team Services Registration required
- Firewall admin must open Firewall ports to allow Azure DevOps servers to communicate with the on-premise Checkmarx IIS installation, usually ports 80 or 443.
Installing the Checkmarx plug-in for Azure DevOps
To install the Checkmarx CxSAST plug-in for Azure DevOps:
If the plugin has been released to the Azure DevOps Marketplace (post beta) perform Search and Install the Checkmarx CxSAST plugin.
Open Azure DevOps and go to Browse Marketplace
> Manage Extensions > Extensions. The Checkmarx CxSAST plugin should be displayed as installed.
Adding CxSAST as a Build Task
To add CxSAST as a build task:
Open Azure DevOps and select your project.
Click Pipelines and select Builds. The Build Definition screen is displayed.
Select the project that you would like to perform a build and click Edit. The Build Tasks screen is displayed.
Click 
Add Task. The Add Tasks list is displayed.
Click Add for the Checkmarx CxSAST task. The Checkmarx CxSAST task is displayed in the Build Task list.
Select the Checkmarx CxSAST task. The Checkmarx CxSAST Task definitions are displayed.
Define the following Checkmarx Server definitions:
| Definition | Description |
|---|---|
| Version | The plugin supports multiple server versions. Select the plugin version corresponding with your server version (select 86.* for any version lower than v8.8.0 or select 88.* for v8.8.0.) |
| Display Name | Enter the display name for the Checkmarx task (e.g. Checkmarx CxSAST Scan) |
| Checkmarx Endpoint | Select an existing endpoint (entry point to the service) from the drop-down list, or setup a new endpoint by clicking Manage (see Setting up a New Service Endpoint). NOTE: Select the Checkmarx Endpoint that corresponds with the selected plugin version. |
| Project Name | Enter a Project Name by either selecting an existing project from the list, or by typing in a name to create a new scan project. |
| Preset | Select a predefined set of queries (preset) from the list. Predefined presets are provided by Checkmarx or you can configure your own. |
| Custom Preset | Select a custom set of queries (custom preset) from the list. Custom presets are provided in cases where the desired preset is not available from the Checkmarx presets. |
| Team | Select a team (group) for which the project is associated. |
Define the following Checkmarx Scan (CxSAST) definitions:
| Definition | Description |
|---|---|
| Incremental Scan | Enable the Incremental Scan checkbox if you want to reduce the scan time. Scans only the recently updated changes. |
| CxSAST Folder Exclusion | Define a comma delineated list of the folders to exclude from the scan (e.g. dto,target,WEB-INF). |
| CxSAST Include/Exclude File Extension | Define a comma separated list of include or exclude wildcard patterns. Exclude patterns start with exclamation mark "!" (Exclusion Example: !.tmp, !.html. Inclusion Example: *.java ). |
Scan Timeout In Minutes | Define a timeout period for which if exceeded, the scan will then fail. |
Deny New Checkmarx Projects Creation | Define that new projects cannot be created via VSTS, therefore allowing Azure DevOps only to run existing projects. |
Comment | Write a scan comment |
| Synchronous Mode | Enabling this option will cause the build step to wait for scan results. You can see the scan results inside the Checkmarx plug-in results window. If disabled, the results are only displayed inside the Checkmarx web-application. |
| Enable CxSAST Vulnerability Threshold Level | Enable the vulnerability threshold option (only available if synchronous mode is enabled). Set the maximum number of vulnerabilities of a given severity before the scan fails. |
CxSAST High: Define a threshold for the high severity vulnerabilities. The build will be marked as failed if the number of the high severity vulnerabilities is larger than the threshold. | |
CxSAST Medium: Define a threshold for the medium severity vulnerabilities. The build will be marked as failed if the number of the medium severity vulnerabilities is larger than the threshold. Threshold must be 0 or greater to set a threshold, or leave blank for no thresholds. | |
CxSAST Low: Define a threshold for the low severity vulnerabilities. The build will be marked as failed if the number of the low severity vulnerabilities is larger than the threshold. Threshold must be 0 or greater to set a threshold, or leave blank for no thresholds. | |
Enable CxOSA Scan | Enable the CxOSA option to initiate Open Source Analysis for this scan/job. Disabled by default. |
CxOSA Folder Exclusions | Define a comma separated list of the folders to exclude from OSA scan (e.g. **/*.jar) |
CxOSA Include/Exclude wildcard patterns | Define a comma separated list of include or exclude wildcard patterns. Exclude patterns start with exclamation mark "!", Include with "*". |
CxOSA Archive Extract Extensions | Comma separated list of archive wildcard patterns to include their extracted content for the scan (e.g. *.zip, *.jar, *.ear). Supported archive types are: jar, war, ear, sca, gem, whl, egg, tar, tar.gz, tgz, zip, rar. Leave blank to extract all archives. |
Execute NPM and Bower install packages command before Scan | Enable the execution of NPM and Bower install packages command before initiating CxOSA scan. NOTE: NPM and Bower must be installed in order to use this option. |
| Enable CxOSA Vulnerability Thresholds | Enable the vulnerability threshold option (only available if synchronous mode is enabled). Set the maximum number of vulnerabilities of a given severity before the scan fails. |
CxOSA High: Define a threshold for the high severity vulnerabilities. The build will be marked as failed if the number of the high severity vulnerabilities is larger than the threshold. Threshold must be 0 or greater to set a threshold, or leave blank for no thresholds | |
CxOSA Medium: Define a threshold for the medium severity vulnerabilities. The build will be marked as failed if the number of the medium severity vulnerabilities is larger than the threshold. Threshold must be 0 or greater to set a threshold, or leave blank for no thresholds. | |
CxOSA Low: Define a threshold for the low severity vulnerabilities. The build will be marked as failed if the number of the low severity vulnerabilities is larger than the threshold. Threshold must be 0 or greater to set a threshold, or leave blank for no thresholds. |
Define the following Checkmarx Control Option definitions:
| Definition | Description |
|---|---|
| Enabled | Clear the Enabled check box if you want to disable a step. This is a handy option if a step is not working correctly or if you need to focus on other parts of the process. |
| Continue On Error | Enable the Continue On Error checkbox to define that if an error occurs in a step, the build will be partially successful at best, and the next step will be run. If disabled, the build fails and no subsequent steps are run. |
| Timeout | Specify the maximum time, in minutes, that a task is allowed to execute before being cancelled by server. A zero value indicates an infinite timeout. |
| Run this Task | Specify when this task should run. Choose "Custom conditions" to specify more complex conditions. |
Setting up a New Service Endpoint
You can select an existing service endpoint from the drop-down list when you are configuring the Checkmarx endpoint definitions (which must correspond to the selected plugin version – see Adding CxSAST as a Build Task), or you can setup a new service endpoint.
To setup a new service endpoint:
From the Checkmarx Task definitions screen, go to the Checkmarx Endpoint field and click Manage. The Service Connection screen is displayed.
Click the New Service Connection drop-down and select Checkmarx. The Service Endpoint screen is displayed.
Define the following CxServer authentication definitions:
| Definition | Description |
|---|---|
| Connection Name | Enter the Connection Name (e.g. CxEndPoint) |
| Server URL | Enter your server URL (URL must start with the http(s)://<serverurl>) |
| User Name | Enter your Checkmarx username |
| Password | Enter your Checkmarx password |
Click OK to complete.