Skip to main content

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 Integrations.png > Azure

Azure_Create_App.png

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:

  1. Click on Integrations Integrations.png > Inventory > Create App.

    JIra_Create_App2.png

  2. 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:

  1. General Settings:

    • Feedback App Name.

    • Description.

    • Associate Tags - Assign tags to a Feedback App. Tags are very useful for filtering purposes.

  2. 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.

  3. Click Next

    Azure_Settings_and_Trigger_Conditions.png

Credentials

Credentials panel contains all the Azure board connection details.

Configure the following:

  1. URL - Azure URL must contain the organization.

    For example:

    https://dev.azure.com/<organization>/

    https://<organization>/visualstudio.com/

  2. 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)

  3. Click Test Connection

    Azure_Test_Connection.png

  4. 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

  5. Click Next

    Azure_Click_Next.png

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:

  1. 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.

  2. Open-status - The Azure statuses that are treated as "Open." These can be "To Do," "In Progress," etc.

  3. Close-status - The Azure statuses that are treated as "Closed." These can be "Done," "Resolved," etc.

  4. Tags (Optional) - The tags are automatically assigned to an issue that the Feedback App creates in Azure Boards.

  5. 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.

  6. 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.

  7. Click Next

    Azure_App_Configuration1.png

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:

  1. Assigned to (Optional) - Azure user.

    To find a user, start typing the user name and click on the magnifying glass.

  2. Area (Optional) - Azure area path.

  3. Iteration (Optional) - Azure Iteration path (also referred to as sprint).

  4. Click Next

    Azure_Additional_Fields.png

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

Azure_Priorities_Mapping1.png

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.

Processes_Types.png

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.)

Field_Types.png

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

      Azure_Unsupported_Fields1.png

  • The following custom fields are not supported for override:

    • Data/Time

    • Identity

      Azure_Unsupported_Custom_Fields.png

  • 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:

  1. 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.

  2. Click on the relevant scanner ellipses More_Options.png > More Details

    Azure_Scan_Log1.png

  3. Scroll down to see the feedback app tag override

    Azure_Scan_Log2.png
In this section: