Azure Boards
Azure Boards Service integration allows Checkmarx One users to automate the creation, modification, and closure of Azure work items for specific vulnerabilities detected in a scan.
Checkmarx One aggregates matching vulnerabilities during the work items creation process. As a result, the number of work items opened in the Azure service may not align with the number of detected vulnerabilities in Checkmarx One.
Limitations
Limitation | Notes |
---|---|
Container vulnerabilities are not currently supported for Feedback Apps. This may cause a discrepancy between the summary counters shown in Checkmarx One and the ones sent via Feedback App. | Update planned as part of development of the new Container Security scanner |
Creating a New Feedback App
To create a new Azure Feedback App, click on Integrations > Azure
Settings & Trigger Conditions panel is opened in the right screen side.
Alternatively you can create a new Azure Feedback App by performing the following steps:
Click on Integrations > Inventory > Create App.
In the right side panel, select Azure and click Next.
Settings & Trigger Conditions
Azure Settings & Trigger Conditions panel contains basic details for the new Feedback App in addition to its trigger conditions.
Configure the following:
General Settings:
Feedback App Name.
Description.
Associate Tags - Assign tags to a Feedback App. Tags are very useful for filtering purposes.
Trigger Conditions:
Severity - The severity level of a vulnerability that triggers the Feedback App.
Status - To decrease the number of issues created in Azure, specify also the status of a vulnerability that triggers the Feedback App.
In conjunction with the severity, this makes the setting more precise.
Click Next
Credentials
Credentials panel contains all the Azure board connection details.
Configure the following:
URL - Azure URL must contain the organization.
For example:
https://dev.azure.com/<organization>/
https://<organization>/visualstudio.com/
Token - Provide a Personal Access Token (PAT) for authenticating into Azure DevOps.
For Microsoft instructions on creating a PAT, refer to this link.
Important
Minimum required permissions: Graph (Read), User Profile (Read), Project and Team (Read), Work Items (Read & Write)
Click Test Connection
Once the connection to the Azure instance is successful, the Project Key field will be enabled.
Select the project key - All the project keys are automatically fetched and presented in the drop-down list
Click Next
App Configuration
Azure Configuration panel contains all the Azure board details. In this screen users configure the filters for the the Bug Tracking service - in this case Azure.
Configure in the following fields:
Issue Type - The type of an issue that will be created in Azure Board when a Checkmarx scan detects a vulnerability with the severity and, optionally, status that are specified in the Settings Trigger Conditions panel > Trigger Conditions section.
The issue type list is dynamic. All the Jira issue types are automatically fetched from the Jira instance and presented in the drop-down list.
Open-status - The status automatically assigned to an issue that the Feedback App creates in Azure Board.
All the Azure Open statuses are automatically fetched and presented in the drop-down list.
It is possible to configure several statuses.
Close-status - The status automatically assigned when an issue that the Feedback App created in Azure Boards is closed.
All the Azure Close statuses are automatically fetched and presented in the drop-down list.
It is possible to configure several statuses.
Tags (Optional) - The tags are automatically assigned to an issue that the Feedback App creates in Azure Boards.
Open-transition - If a vulnerability that was already attended to reoccurs in a next scan, the corresponding ticket will be automatically reopened with this status.
Note
Only 1 status can be configured.
Free text field - Must be exactly as it exists in Azure.
Any mistake in the Open-transition status characters will cause an error.
Close-transition - If a vulnerability that was already attended to reoccurs in a next scan, the corresponding ticket will be automatically reopened.
When the issue is resolved, the reopened ticket will be closed with this status.
Note
Only 1 status can be configured.
Free text field - Must be exactly as it exists in Azure.
Any mistake in the Close-transition status characters will cause an error.
Click Next
Additional Settings
Azure Additional Settings panel contains supported process type (The official name for custom fields in Azure), of which some/all may be required for opening Azure tickets.
For more information about Azure custom fields see Free Form
Configure the following:
Assigned to (Optional) - Azure user.
To find a user, start typing the user name and click on the magnifying glass.
Area (Optional) - Azure area path.
Iteration (Optional) - Azure Iteration path (also referred to as sprint).
Click Next
Priorities Mapping
Azure Priorities Mapping is used for mapping Checkmarx One vulnerability severity to the corresponding Azure priority.
Configure a suitable Azure priority for each Checkmarx One vulnerability type and click Save
Note
To appear in this screen, the Checkmarx One severities need to be selected in the Settings & Trigger Conditions panel > Trigger Conditions section.
Azure priorities are free text fields, and configured using 1-4 numbers.
For more information about Azure priorities see Azure Priorities
Free Form
Azure free form feature enhances the support for opening Azure tickets.
This is being performed by allowing the user the option to set the relevant values for Azure processes field types, of which some/all may be required for opening Azure tickets.
The feature supports all the default Azure processes in addition to the custom created ones.
The supported processes types are: Epic, Issue, Task, Test Case, Test Plan, Test Suite, Custom processes.
The feature also improves the user experience by allowing additional field types to be configured, mandatory or not.
These field types appear in Azure processes settings, and they are defined per process (Epic, Issue, Task, etc.)
Checkmarx One support the following out of the box Azure custom fields:
Boolean
Date/Time
Decimal
Identity
Integer
Picklist (string)
Picklist (Integer)
Text (single line)
Text (multiple lines)
Fields Override
In large enterprises, different users often have different configurations for the same Azure board where they publish their Azure tickets.
Azure fields override feature adds flexibility to Azure feedback apps configuration.
Users can override any system / custom Azure field value by using tags with a specific naming convention.
Checkmarx One supports mandatory / optional fields.
The classic use-case for using this feature is when 2 users need to publish Azure tickets to the same Azure board, but each user has a different Azure board configuration, containing different fields values.
For example:
User1 and User2 publish Azure tickets to the same Azure board, but each user publish the tickets using his own Assigned to field value.
Prior to the feature, users needed to create 2 Azure apps - one for each user. Now they can use the same Azure feedback app, but to replace the Assigned to field value accordingly.
Tags Naming Convention
Users can override Azure system / custom field value by using the following tags naming convention:
feedback-<key:value>
Important
feedback: Represent feedback app tags.
key: Represent the relevant Azure field.
value: Represent the relevant Azure field value.
Tags Hierarchy
Azure fields override feature is supported using the user interface and the CLI.
It is also is supported in 2 configuration levels:
Project level - For additional information on how to configure project tags see:
General Settings (User interface)
project tags (CLI)
Scan level - For additional information on how to configure scan level tags see:
Running a Scan (User interface)
scan tags (CLI)
Note
Scan level takes priority over project level
Limitations
There are several limitations for the feature:
The following system fields are not supported for override:
Issue-type
Open-status
Close-status
Tags
Open-transition
Close-transition
The following custom fields are not supported for override:
Data/Time
Identity
In order to set a custom tag to override, you must use the prefix "feedback-" which is case sensitive (lower case).
Tags without the "feedback-" prefix won't be taken into account.
Tags need to be in the format of "feedback-<key:value>". key & value are not case sensitive.
The ":" sign should be used as a separator only when configuring <key:value>. No key or value should contain the ":" sign.
Tags with spelling mistakes/Don't exists/not supported will be ignored.
In order to override the Assigned to field:
Azure cloud - Configure the display name (the value is not case sensitive).
For example: feedback-Assigned to:john doe
Multiple select fields are not supported.
For overriding Area and Iteration fields you need to use the ‘\’ sign
Examples:
feedback-Iteration:\Private-Project\Sprint 1
feedback-Iteration:\Private-Project\new-interation
feedback-area:\Private-Project\nimrod-project
Tags Override Verification
All the actions and override attempts can be found in the scan log.
To open the scan log, perform the following:
When the scan is finished, click on the scan line in the Applications and Projects home page.
A panel will be opened on the right screen side.
Click on the relevant scanner ellipses > More Details
Scroll down to see the feedback app tag override