📋 Jira Integration Guide (Pro)

DefectDojo’s Jira integration can be used to push Finding data to one or more Jira Spaces. By doing so, you can integrate DefectDojo into your standard development workflow. Here are some examples of how this can work:

• The AppSec team can selectively push Findings to a Jira Space used by developers, so that issue remediation can be appropriately prioritized alongside regular development. Developers on this board don’t need to access DefectDojo - they can keep all their work in one place.
• DefectDojo can push ALL Findings to a bidirectional Jira Space which the AppSec team uses, which allows them to split up issue validation. This board keeps in sync with DefectDojo and allows for complex remediation workflows.
• DefectDojo can selectively push Findings from separate Products &/or Engagements to separate Jira Spaces, to keep things in their proper context.

Setting Up Jira

Setting Up Jira requires the following steps:

1. Connect a Jira Instance, either with a username / password or an API token. Multiple instances can be linked.
2. Add that Jira Instance to one or more Products or Engagements within DefectDojo.
3. If you wish to use bidirectional sync, create a Jira Webhook which will send updates to DefectDojo.

Step 1: Connect a Jira Instance

Connecting a Jira Instance is the first step to take when setting up DefectDojo’s Jira integration. Please note Jira Service Management is currently not supported.

Required information from Jira

Atlassian uses different ways of authentication between Jira Cloud and Jira Data Center.

for Jira Cloud, you will need:

• a Jira URL, i.e. https://yourcompany.atlassian.net/
• an account with permissions to create and update issues in your Jira instance. This can be:
  • A standard username / password combination
  • A username / API Token combination

for Jira Data Center (or Server), you will need:

• a Jira URL, i.e. https://jira.yourcompany.com
• an account with permissions to create and update issues in your Jira instance. This can be:
  • A standard username / password combination
  • A emailaddress / Personal Access Token combination

Optionally, you can map:

• Jira Transitions to trigger Re-Opening and Closing Findings
• Jira Resolutions which can apply Risk Acceptance and False Positive statuses to Findings (optional)

Add a Jira Instance

1. If you have not already done so, navigate to the System Settings page and check the box on Enable Jira Integration.

2. Navigate to the Enterprise Settings > Jira Instances > + New Jira Instance page from the DefectDojo sidebar.

3. Select a Configuration Name for this Jira Instance to use in DefectDojo. This name is simply a label for the Instance connection in DefectDojo, and does not need to be related to any Jira data.

4. Select the URL for your company’s Jira instance - likely similar to https://**yourcompany**.atlassian.net if you’re using a Jira Cloud installation.

5. Enter an appropriate authentication method in the Username / Password fields for Jira:

   • For standard username / password Jira authentication, enter a Jira Username and corresponding Password in these fields.
   • For authentication with a user’s API token (Jira Cloud) enter the Username with the corresponding API token in the password field.
   • For authentication with a Jira Personal Access Token (aka PAT, used in Jira Data Center and Jira Server only), enter the PAT in the password field. Username is not used for authentication with a Jira PAT, but the field is still required in this form, so you can use a placeholder value here to identify your PAT.

Note that the user associated with this connection must have permission to create Issues and access data in your Jira instance.

6. You will need to provide values for an Epic Name ID, Re-open Transition ID and Close Transition ID. These values can be changed later.

7. Select the Default issue type which you want to create Issues as in Jira. The options for this are Bug, Task, Story and Epic (which are standard Jira issue types) as well as Spike and Security, which are custom issue types.

8. Select your Issue Template, which will determine the Issue Description when Issues are created in Jira.

Step 2: Connect a Product or Engagement to Jira

Each Product or Engagement in DefectDojo has its own settings which govern how Findings are converted to JIRA Issues. From here, you can decide the associated Jira Space and set the default behaviour for creating Issues, Epics, Labels and other JIRA metadata.

Add Jira to a Product

You can find this page by clicking the Gear menu on a Product ⚙️ and opening the Jira Project Settings page.

Jira Instance

If you have multiple instances of Jira set up, for separate products or teams within your organization, you can indicate which Jira Space you want DefectDojo to create Issues in. Select a Space from the drop-down menu.

Project key

This is the key of the Space that you want to use with DefectDojo. The Space Key for a given Space can be found in the URL.

Epic Issue Type Name

The name of the Epic issue type in Jira. This defaults to “Epic” but can be changed if your Jira instance uses a different name.

Issue template

Here you can determine how much DefectDojo metadata you want to send to Jira. Select one of two options:

• jira_full: Issues will track all of the parameters from DefectDojo - a full Description, CVE, Severity, etc.
• jira_limited: Issues will only track the DefectDojo link, the Product/Engagement/Test links, the Reporter and Environment fields.

Component

If you manage your Jira Space using Components, you can assign the appropriate Component for DefectDojo here. To assign more than one Component, enter a comma-separated list.

Custom fields

If you don’t need to use Custom Fields with DefectDojo issues, you can leave this field as ’null'.

Close / Reopen Transition fields

Some Jira workflows require certain fields to be set as part of a transition.

Jira labels

Select the relevant labels that you want the Issue to be created with in Jira.

Default assignee

The name of the default assignee in Jira. If left blank, DefectDojo will follow the default behaviour in your Jira Space when creating Issues.

Jira Project Settings

This toggle controls whether DefectDojo pushes Findings to Jira for this Product. Disabling this will not delete or change any existing Jira tickets created by DefectDojo, but will prevent any further updates or new Issue creation.

Pushing Findings To Jira

A Product with a JIRA mapping can push Findings to Jira as Issues using several methods. You can push Findings individually, in bulk, as Finding Groups, or automatically.

Push a Single Finding

1. Open the Finding you want to push.
2. Click the ☰ Finding Menu and select Push to Jira.
3. Confirm the push when prompted.

Once the Issue is created, DefectDojo will display a link to the Jira Issue on the Finding page.

Updating a Linked Jira Issue

If a Finding already has a linked Jira Issue, selecting Push to Jira again will update the existing Jira Issue with any changes made in DefectDojo.

Unlinking a Finding from Jira

To remove the association between a Finding and its Jira Issue, click the ☰ Finding Menu and select Unlink From Jira. This removes the link in DefectDojo but does not delete the Jira Issue itself.

Bulk Push Findings

You can push multiple Findings to Jira at once using the Bulk Update form:

1. From a Findings list, select the Findings you want to push using the checkboxes.
2. Open the Bulk Update form.
3. Check the Push to Jira checkbox.
4. Click Submit.

Automatically Create and Push Finding Groups

With Push All Issues enabled on the Product, and a Group By option selected on import:

Automatic Push Behaviour

DefectDojo can automatically push Findings and updates to Jira in several scenarios:

Push All Issues

When the Push All Issues setting is enabled on a Product’s Jira Project Settings, DefectDojo will automatically create Jira Issues for all Active and Verified Findings.

Auto-Sync on Status Changes

When Push All Issues or the system-level Finding Jira Sync setting is enabled, DefectDojo will automatically update linked Jira Issues when certain actions are taken on Findings:

• Request Review - A comment is added to the linked Jira Issue.
• Clear Review - A comment is added to the linked Jira Issue.
• Close Finding - The linked Jira Issue is updated to reflect the closure.

Jira Comments and Notes

When Push Notes is enabled in the Jira Project Settings:

• If a comment is added to a Jira Issue, the same comment will be added to the Finding, under the Notes section.
• Likewise, if a Note is added to a Finding, the Note will be added to the Jira issue as a comment.

Disconnecting from Jira

Jira integrations can be removed from your instance only if no related Issues have been created. If Issues have been created, there is no way to completely remove a Jira Instance from DefectDojo.

However, you can disable your Jira integration by disabling it at the Product level. From the Jira Project Settings page, uncheck the Enabled toggle. This will not delete or change any existing Jira tickets created by DefectDojo, but will disable any further updates.