Jira
Jira Service integration allows Checkmarx One users to automate the creation, modification, and closure of Jira issues for specific vulnerabilities detected in a scan.
Checkmarx One aggregates matching vulnerabilities during the issues creation process. As a result, the number of issues opened in the Jira service may not align with the number of detected vulnerabilities in Checkmarx One.
The lowest Jira permission level required to create Jira issues (Bug, Task, Story, etc.) includes Browse projects and Create issues project permissions. For additional information refer to Create Issues and Manage project permissions.
In the right side panel select Jira and click Next
 |
Jira Authentication
Checkmarx One supports both Jira cloud and Jira on-prem integrations.
Notice
For Jira on-prem integration It is possible to add the Checkmarx One external IP addresses to the customer Firewall allowlist - For more information see Checkmarx One External IPs
Jira authentication is performed according to the following table:
Jira Version | Authentication Method |
|---|---|
Jira cloud | Username + API Token |
Jira Core 8.14 and later (on-prem) | Username + Token |
Jira Software 8.14 and later (on-prem) | Personal Access Token |
Jira Service Management 4.15 and later (on-prem) | Username + Token |
Jira on-prem lower than the above versions | Username + Password |
Jira Limitations
The below table presents Jira limitations
Limitation | Notes |
|---|---|
Need to add project id and not name | Update planned |
Can’t add a label-prefix | Update planned |
Can’t change JIRA title in JIRA | |
Can’t customize summary format | Not planned |
Checkmarx One doesn't support all the Jira field types | For the list of supported field see |
Labels system field is mandatory for Checkmarx One to publish Jira tickets | For more information see App Configuration |
Settings & Trigger Conditions
Jira 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 Jira, specify also the status of a vulnerability that triggers the Feedback App.
In conjunction with the severity, this makes the setting more precise.
Scan Engines: Select which scan engine results will be reflected through the Feedback App (By default, all the licensed scanners are enabled).
Direct Path (Optional) - Set up the folder path and/or specify the file name/extension for a specific project. This setup will explicitly define the folder path and/or file name/extension for opening Jira tickets. If you populate this field, Jira tickets will only be created for matching files or files in matching folders.
Note
This functionality might not yet be available in your production environment.
Type the required value and press Enter to store it.
"**" characters are supported for folder paths and files.
Folders/files examples: test/**/, **.java, test.java
Click Next
Credentials
Jira Credentials panel contains all the Jira board connection details.
The details include the following:
Authorization Type - Select how to authenticate to the Jira board.
Credentials - Configure the URL, Username and Token.
Project Key - Jira project key (Automatically fetched and presented in the drop-down list).
API Token flow is mainly used for cloud-hosted Jira instances, although it could be used for several self-hosted Jira versions.
For additional information see See Jira Authentication
Configure the following:
Authorization Type:
Select API Token (By default, this option is selected).
Credentials:
URL - Configure Jira main URL.
For example: https://checkmarx.atlassian.net/
Username - Configure Jira username.
Token - Configure Jira token.
Click Test Connection
Once the connection to the Jira 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
Personal Access Token flow is used for self-hosted Jira instances.
For additional information see See Jira Authentication
Authorization Type:
Select Personal Access Token
Credentials:
URL - Configure Jira self-hosted main URL.
Token / Password - Configure Jira token / password (Depending on the Jira self-hosted version).
Click Test Connection
Once the connection to the Jira 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
App Configuration panel contains all the Jira board details. In this panel users configure the filters for the Bug Tracking service - in this case Jira.
Important
There are cases where a specific issue type (Bug, Task, Story, etc.) contains mandatory fields that are not supported by Checkmarx One. The fields can be either system or custom fields. In such cases a dedicated message will be presented. Hovering over the link will present the relevant field.
For example:
It is also possible that Labels system field is missing from the Jira configuration. In such cases, a dedicated message will be presented as well.
For example:
Configure in the following fields:
Issue Type - The type of an issue that will be created in Jira 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.
Labels (Optional) - Configure which Jira system labels will be assigned to the published Jira tickets.
Warning
Jira system labels are mandatory for Checkmarx One to publish Jira tickets.
In case that labels field will be removed from any Jira issue type configuration, Checkmarx One won't be able to publish Jira tickets of this issue type.
Note
Any label that will be added to Checkmarx One Labels field will be included in the published Jira tickets.
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
For Jira Cloud and Jira on-prem, if the user has the correct permissions, all the Jira open statuses are automatically fetched and presented in the drop-down list. If the user doesn't have the correct permissions, the field changes to free-form text. Any mistake in the status name will lead to an error when opening Jira tickets.
For Jira cloud, see required permissions here
For Jira on-prem, see the required "permission to administer Jira" here
Only 1 status can be configured.
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
For Jira Cloud and Jira on-prem, if the user has the correct permissions, all the Jira close statuses are automatically fetched and presented in the drop-down list. If the user doesn't have the correct permissions, the field changes to free-form text. Any mistake in the status name will lead to an error when opening Jira tickets.
For Jira cloud, see required permissions here
For Jira on-prem, see the required "permission to administer Jira" here
Only 1 status can be configured.
Due-date (Optional) - What is the due date for the Jira tickets that will be opened.
Click Next
Additional Settings
Jira Additional Settings panel contains Jira additional issue fields, of which some/all may be required for opening Jira tickets.
All the fields values are automatically fetched and presented in the drop-down list.
Select the fields values and click Next
For more information about Jira custom fields, see Free Form
For example:
 |
Priorities Mapping
Jira Priorities Mapping is used for mapping Checkmarx One vulnerabilities severities to the corresponding Jira priorities.
Configure a suitable Jira 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.
 |
Free Form
Jira free form feature enhances the support for opening Jira tickets.
This is being performed by allowing the user the option to set the relevant values for Jira custom fields, of which some/all may be required for opening Jira tickets.
The feature also improves the user experience by allowing additional field types to be configured, mandatory or not.
These field types appear in Jira project settings on the right side, and they are defined per issue type (Bug, Task, Story, etc.)
 |
Checkmarx One support the following out of the box Jira custom fields:
Short text
Paragraph
Date
Number
Time stamp
Labels
Dropdown
Checkbox
Cascading select
Checkmarx One also supports the following Jira advanced custom fields:
Version Picker (single version)
Limitations
Only a Jira user with Create issues project permission user role will be able to see the custom fields.
For additional information about Jira permissions see Create issues in Jira and Jira operation permissions
Predefined fields that are created using Jira plugins are not supported. This means that it might be that some required Jira fields won't appear in the additional issue fields options.
Fields Override
In large enterprises, different users often have different configurations for the same Jira board where they publish their Jira tickets.
Jira fields override feature adds flexibility to Jira feedback apps configuration.
Users can override any system / custom Jira 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 Jira tickets to the same Jira board, but each user has a different Jira board configuration, containing different fields values.
For example:
User1 and User2 publish Jira tickets to the same Jira board, but each user publish the tickets using his own Assignee field value.
Prior to the feature, users needed to create 2 Jira apps - one for each user. Now they can use the same Jira feedback app, but to replace the Assignee field value accordingly.
Tags Naming Convention
Users can override Jira system / custom field value by using the following tags naming convention:
feedback-<key:value>
Important
feedback: Represent feedback app tags.
key: Represent the relevant Jira field.
value: Represent the relevant Jira field value.
Tags Hierarchy
Jira 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
Labels
Open-transition
Close-transition
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 Assignee field:
Jira cloud - Configure the display name (the value is not case sensitive).
For example: feedback-Assignee:john doe
Jira On-Prem - Configure the username (not email)
For example: feedback-Assignee:john.doe
Multiple select fields are not supported.
date picker (without timeline) is supported in the format of 'yyyy-MM-dd'
For example: '2023-02-20'
It is not possible to override a field if a Jira issue-type has another field with the same name (Jira allows it).
In case that the same field is configured in several places, the below should be the override hierarchy:
scan_tags - First priority.
project_tags - Second priority.
feedback-app tags - Third priority.
It is possible to override fields even if they are not set & saved in the Jira application in Checkmarx One, as long as they are Jira valid fields.
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
