Xray Jira Integration

JFrog Security Documentation

ft:sourceType
Paligo

Overview

Xray's integration with Atlassian's Jira Software is a powerful feature that enables the manual and automatic creation of Jira tickets based on Xray-identified security threats violations. As DevOps teams are already familiar with the workflow and user experience of Jira, this integration makes it easy to handle Xray detections. Once configured, Policy violations will appear as notifications in Jira, allowing your team to know where the violations are found, how to prioritize them, and take immediate action to resolve them.

How Does it Work?

Prerequisites

As a Jira admin, you must have the following information:

Note

You must have Jira Admin permissions to be able to connect Jira to Xray. For the Jira-related steps, refer to Atlassian Jira Documentation .

  1. The supported authentication type should be one of OAuth1, OAuth2, or Basic Authentication.

  2. User credentials depend on the authentication type.

  3. Jira Project Name.

  4. Issue type (bug, security, escalation, etc).

  5. Jira labels (optional).

  6. Custom Field Mapping (optional).

Step 1 Creating a Jira Connection Profile

Connect Jira to Xray through the Xray interface using one of the supported authentication methods. Navigate to Administration > Xray Security & Compliance > Integrations > Jira Integration and select New Jira Integration.

JFrog Cloud New Interface (Beta)

On the taskbar, click 176260854.png (Platform Configurations), and select Xray Settings > Integrations. To learn more, click here.JFrog : JFrog Platform New UI (Beta) Quick Start Guide

Xray supports three authentication methods:

  • OAuth1

  • OAuth2

  • Basic Auth

Xray Self Hosted

Xray Cloud

Jira On-Prem
  • Basic Auth

  • OAuth1

  • Basic Auth

  • OAuth1

Note: This configuration is not recommended, as it would require allowing inbound connections to your local Jira instance.

Jira Cloud
  • Basic Auth

  • OAuth2

  • Basic Auth

  • OAuth2

Follow the steps depending on the chosen authentication method.

Connecting Jira to Xray Using OAuth1

In Xray:

  1. Define the following fields in the Xray Jira Integration:

    136873539.png

    Field

    Description

    Consumer Key

    The consumer key that is provided in Jira when linking applications.

    Jira server URL

    The URL of your Jira deployment.

  2. Generate a public key that you will define in your Jira.

136872784.png

In Jira:

Paste the generated Public Key you copied from the Xray interface.

136872785.png
Connecting Jira to Xray Using OAuth2

In Atlassian:

Required scope permissions

read:issue-type:jira
read:issue-type.property:jira
read:project:jira
read:project.property:jira
read:user:jira
read:application-role:jira
read:avatar:jira
read:group:jira
read:issue-type-hierarchy:jira
read:project-category:jira
read:project-version:jira
read:project.component:jira
read:field:jira
read:field-configuration:jira
read:issue-meta:jira
write:issue:jira
write:comment:jira
write:comment.property:jira
write:attachment:jira
read:issue:jira
read:label:jira
offline_access
read:issue-security-level:jira
read:issue.vote:jira
read:issue.changelog:jira
read:status:jira
read:comment:jira
read:comment.property:jira
read:project-role:jira
  1. From the Developer Console of Atlassian, create an OAUTH2 Integration. Specify the callback URL as the JFrog server URL, such as:

    https://artifactory:8082/xray/api/v1/ticketing/integrations/callback
  2. In the Authentication details section, copy the Client ID and secret. You will use these in the Xray interface.

    136872786.png

In Xray: Define the following fields in the Xray Jira Integration:

136873540.png

Field

Description

Client ID

The client ID you obtained from the Atlassian OAUTH2 integration.

Client Secret

The client secret you obtained from the Atlassian OAUTH2 integration.

Connecting Jira to Xray Using Basic Authentication

Define the following fields in the Xray Jira Integration:

136872787.png

Field

Description

Username

The username you use for Jira authentication.

Password

The password you use for Jira authentication.

Installation Type

Type of installation of your Jira instance, Cloud or On-Prem

Jira Server URL

URL of the Jira deployment.

Note

Ensure to test connectivity between Xray and Jira by clicking the Test Jira Connectivity button before proceeding to the next step.

Step 2 Creating a Jira Configuration Profile

After successfully completing the connection between Jira and Xray, you need to create a Jira Configuration profile. As there are different Jira projects for different teams, the configuration profile enables you to define specific criteria for the issued Jira ticket per Jira project, such as labels and custom mappings defined in the Jira project.

Notes

Note the following:

  • Tag Labels should be created in Jira before configuring them in the profile.

  • If an issue type has mandatory fields in Jira, these issue types will not appear in the issue type list for selection. The following fields are an exception:

    • summary

    • description

    • project

    • issuetype

    • labels

    • reporter

As each violation creates a new Jira ticket, you might have multiple Jira tickets for the same violation in different versions of the Build, Release Bundle, or package. You can choose to only have one Jira ticket for the violation, by eliminating duplicate Jira tickets. If unchecked, multiple Jira tickets will be created for the same violation in all Builds, Release Bundles, and Packages.

136872812.png

List of Available Custom Fields

Custom Field

Type

Xray_Impacted_Artifact

Text

Xray_Package_Type

Text

Xray_Vulnerability_Id

Text

Xray_Violation_Type

Text

Xray_Severity

Text

Xray_Severity_Source

Text

Xray_JFrog_Research_Severity

Text

Xray_CVEs

Text

Xray_CVSS_V2_Vector

Text

Xray_CVSS_V3_Vector

Text

Xray_CVSS_V2_Score

Text

Xray_CVSS_V3_Score

Text

Xray_Fix_Version

Text

Xray_Watch_Name

Text

Xray_Policy_Name

Text

Xray_Triggered_Rule

Text

Xray_Component_License_Id

Text

Xray_Created_Date

Text

Xray Entities Custom Fields

136877257.png

List of Available Xray Labels

Label

Type

Xray_Impacted_Artifact

Text

Xray_Impacted_Component

Text

Xray_Package_Type

Text

Xray_Vulnerability_Id

Text

Xray_Violation_Type

Text

Xray_Severity

Text

Xray_JFrog_Research_Severity

Text

Xray_CVEs

Text

Xray_CVSS_V2_Score

Text

Xray_CVSS_V3_Score

Text

Xray_Watch_Name

Text

Xray_Policy_Name

Text

Xray_Triggered_Rule

Text

Xray_Component_License_Id

Text

Custom Fields and Labels in the Jira Issue

136877258.png
Step 3 Configuring the Policy Rules

Enable the Jira ticket creation in the Policy rules. In