# 📋 Jira Integration Guide (Open Source) 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 methods 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 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) Multiple Jira Spaces can be handled by a single Jira Instance connection, as long as the Jira account / token used by DefectDojo has permission to create Issues in the associated Jira Space. ### 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**. You will need to do this before the ⚙️ **Configuration > JIRA** option shows up on the sidebar. 2. Navigate to the ⚙️ **Configuration > JIRA** page from the DefectDojo sidebar. 3. You will see a list of all currently configured Jira Spaces which are linked to DefectDojo. To add a new Project Configuration, click the wrench icon and choose either the **Add Jira Configuration (Express)** or **Add Jira Configuration** options. #### Add Jira Configuration (Express) The Express method allows for a quicker method of linking a Space. Use the Express method if you simply want to connect a Jira Space quickly, and you aren’t dealing with a complex Jira workflow. 1. Select a name for this Jira Configuration 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. 2. Select the URL for your company’s Jira instance - likely similar to `https://**yourcompany**.atlassian.net` if you’re using a Jira Cloud installation. 3. 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. 4. 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. If you have a different Issue Type which you want to use, please contact [support@defectdojo.com](mailto:support@defectdojo.com) for assistance. 5. Select your Issue Template, which will determine the Issue Description when Issues are created in Jira. The two types are: - **Jira_full**, which will include all Finding information in Jira Issues - **Jira_limited**, which will include a smaller amount of Finding information and metadata. If you leave this field blank, it will default to **Jira_full.** 6. Select one or more Jira Resolution types which will change the status of a Finding to Accepted (when the Resolution is triggered on the Issue). If you don’t wish to use this automation, you can leave the field blank. 7. Select one or more Jira Resolution types which will change the status of a Finding to False Positive (when the Resolution is triggered on the Issue). If you don’t wish to use this automation, you can leave the field blank. 8. Decide whether you wish to send SLA Notifications as a comment on a Jira issue. 9. Decide whether you wish to automatically sync Findings with Jira. If this is enabled, Jira Issues will automatically be kept in sync with the related Findings. If this is not enabled, you will need to manually push any changes made to a Finding after the Issue has been created in Jira. 10. Select your Issue key. In Jira, this is the string associated with an Issue (e.g. the word **‘EXAMPLE’** in an issue called **EXAMPLE-123**). If you don’t know your issue key, create a new Issue in the Jira Space. In the screenshot below, we can see that the issue key on our Jira Space is **DEF**. 11. Click **Submit.** DefectDojo will automatically look for appropriate mappings in Jira and add them to the configuration. You are now ready to link this configuration to one or more Products in DefectDojo. ## 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 or Engagement In the Classic UI, you can find Jira settings by opening the Edit Product or Edit Engagement form. “ **📝 Edit**” button under **Settings** on the page: #### List of Jira settings Jira settings are located near the bottom of the Product 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 Project from the drop-down menu. If this menu doesn’t list any Jira instances, confirm that those Projects are connected in your global Jira Configuration for DefectDojo - yourcompany.defectdojo.com/jira. #### Project key This is the key of the Space that you want to use with DefectDojo. The Space Key for a given project can be found in the URL, or under “Space key” listed in Space Settings. #### 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. Useful if you need complete Finding context in Jira (for example, if someone is working on this Issue who doesn’t have access to DefectDojo). Here is an example of a **jira_full** Issue: - **Jira_limited:** Issues will only track the DefectDojo link, the Product/Engagement/Test links, the Reporter and Environment fields. All other fields are tracked in DefectDojo only. Useful if you don’t require full Finding context in Jira (for example, if someone is working on this Issue who mainly works in DefectDojo, and doesn’t need the full picture in JIRA as well.) #### 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 (for example, `Security, DevSecOps`); each value is sent to Jira as a separate component. **Custom fields** If you don’t need to use Custom Fields with DefectDojo issues, you can leave this field as ’null’. However, if your Jira Space Settings **require you** to use Custom Fields on new Issues, you will need to hard-code these mappings. ### Step 3: Configure Bidirectional Sync: Jira Webhook The Jira integration allows for bidirectional sync via webhook. DefectDojo receives Jira notifications at a unique address, which can allow for Jira comments to be received on Findings, or for Findings to be resolved via Jira depending on your configuration. ### Locating your Jira Webhook URL Your Jira Webhook is located on the System Settings form under **Jira Integration Settings**: **Enterprise Settings > System Settings** from the sidebar. ### Creating the Jira Webhook 1. Visit `**https:// /plugins/servlet/webhooks**` 2. Click ‘Create a Webhook’. 3. For the field labeled ‘URL’ enter: `https:// <**YOUR DOJO DOMAIN**> /jira/webhook/ <**YOUR GENERATED WEBHOOK SECRET**>`. 4. Under ‘Comments’ enable ‘Created’. Under Issue enable ‘Updated’. 5. Make sure your JIRA instance trusts the SSL certificate used by your DefectDojo instance. ## Testing the Jira integration #### Test 1: Do Findings successfully push to Jira? To test the Jira integration, you can add a new blank Finding to the Product associated with Jira in DefectDojo. **Product > Findings > Add New Finding.** #### Test 2: Jira Webhooks send to DefectDojo Add a Note to a Finding which also exists in JIRA as an Issue. ## Disconnecting from Jira Jira integrations can be removed from your instance only if no related Issues have been created. However, you can disable your Jira integration by disabling it at the Product level.