Skip to main content

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.

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 Managing Checkmarx One Traffic and AWS S3 Access

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

Free Form

Labels system field is mandatory for Checkmarx One to publish Jira tickets

For more information see App Configuration

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 Jira Feedback App, click on Integrations Integrations.png > Jira

JIra_Create_App.png

Settings & Trigger Conditions panel is opened in the right screen side.

Alternatively you can create a new Jira 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 Jira and click Next.

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:

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

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

  4. Click Next

    Jira_Settings_and_Trigger_Conditions2.png

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

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:

    Jira_Unsupported_Fields_Message2.png

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

    Jira_Unsupported_Fields_Message.png

Configure in the following fields:

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

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

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

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

  5. Due-date (Optional) - What is the due date for the Jira tickets that will be opened.

  6. Click Next

    JIra_App_Configuration1.png

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:

JIra_Additional_Settings.png

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.

JIra_Priorities_Mapping1.png

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

Jira_Custom_Fields.png

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

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

  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

    Scan_Log1.png

  3. Scroll down to see the feedback app tag override

    Scan_Log2.png
In this section: