Integrators Tool Reference | DefectDojo Documentation

Integrators Tool Reference (Pro)

Here are specific instructions detailing how to set up a DefectDojo Integration with a third party Issue Tracker.

Azure DevOps Boards

Instance Setup

Authentication with Azure DevOps requires a personal access token with permissions set to “Read, Write and Manage” for “Work Items” for the Azure Project that you wish to work with.

Issue Tracker Mapping

These details dictate how DefectDojo will map Finding or Finding Group attributes to a given Project in Azure DevOps:

Issue Tracker Mapping Details

The Project ID field corresponds to the name or the ID of the Project in Azure.

Severity Mapping Details

The attributes in the form are supplied as defaults, and are as follows:

Status Mapping Details

The attributes in the form are supplied as defaults and are as follows:

Bitbucket

The Bitbucket integration allows you to push issues to the issue tracker of a Bitbucket Cloud repository.

The issue tracker is optional in Bitbucket and must be enabled on the repository before DefectDojo can create Issues in it. To enable it, open the repository in Bitbucket and select Repository settings, then enable the issue tracker under Features.

Instance Setup

Bitbucket app passwords are deprecated by Atlassian and will not work with this integration. To create an API token:

  1. Open Atlassian account settings and choose Security, then Create and manage API tokens.
  2. Choose Create API token with scopes, name the token, and set an expiry date.
  3. Select Bitbucket as the app.
  4. Grant the token permission to read repositories and to read and write issues.

Issue Tracker Mapping

Severity Mapping Details

This maps to the Bitbucket issue Priority field. The attributes in the form are supplied as defaults, and each value must be one of Bitbucket’s priorities: trivial, minor, major, critical, or blocker.

Status Mapping Details

This maps to the Bitbucket issue State field. Each value must be one of Bitbucket’s issue states: new, open, resolved, on hold, invalid, duplicate, wontfix, or closed.

GitHub

The GitHub integration allows you to add issues to a GitHub Project, which also open Issues in an associated Repo. These Repos/Projects can be associated with either a GitHub Organization or a personal GitHub account.

Instance Setup

Personal access tokens for GitHub can be created at https://github.com/settings/tokens. The token must have Repo and Project scopes.

Issue Tracker Mapping

Severity Mapping Details

In order to set up the integration, the Project MUST have a custom field created to represent Issue Priority, otherwise Severity will not be mapped correctly and Issues will not push to GitHub.

Follow this guide to create a custom field. Each Severity will need to have a corresponding single-select option available. For example, out of the box DefectDojo suggests P0, P1, P2, P3, P4 as possible Priority values, and each of those will need to be added to the Priority custom field.

Status Mapping Details

By default, new GitHub Projects will have Statuses for Issues of “In Progress” and “Done”. Additional statuses can be added to the Project to track False Positive or Risk Accepted status if you wish. One of the ways this can be done is by adding a new Status Column to the Project Board.

GitLab

The GitLab integration allows you to add issues to a GitLab Project.

Instance Setup

Issue Tracker Mapping

Severity Mapping Details

This maps to the GitLab Priority field.

Status Mapping Details

By default, GitLab has statuses of ‘opened’ and ‘closed’. Additional status labels can be added if you want to track False Positive or Risk Accepted status. See GitLab Docs for details.

Jira

The Jira integration pushes DefectDojo Findings and Finding Groups to a Jira project as issues, keeps each issue’s status in sync with the Finding, and links the Finding back to the created issue. Both Jira Cloud and Data Center / Server are supported. Jira Service Management is not supported.

Choosing an authentication method

Set Jira Deployment first, then pick an Authentication Method:

Jira Cloud

Jira Data Center / Server

Instance Setup

Issue Tracker Mapping

Severity Mapping Details

Defaults match Jira’s default priority scheme. Edit them to match the priority names in your project:

Status Mapping Details

Statuses vary per project workflow, so these defaults are meant to be edited to your workflow’s status names:

Custom Fields (optional)

You can map additional Jira fields — for example a required resolution on close, or labels — in the mapping’s Custom Fields step. Each custom-field mapping has four parts:

Ticket Templates (optional)

By default Jira issues use DefectDojo’s built-in title and body. To customize them, attach a Ticket Template to the mapping in its Ticket Template step. A template defines four independently-optional pieces — the Finding summary and description, and the Finding Group summary and description. Any piece left blank falls back to the built-in default, so you can override just the title, just the body, or all four. Use Test render in the template editor to preview the rendered output against sample data — catching mistakes such as unknown placeholders or values that exceed a field’s length limit — before saving. If a template is later deleted, the mappings that used it revert to the built-in defaults automatically.

How it works

Linear

The Linear integration allows you to push DefectDojo Findings as Linear Issues. Issues are created in a Team in your Linear workspace.

Instance Setup

Issue Tracker Mapping

curl -H "Authorization: {{API_KEY}}" -H "Content-Type: application/json" 
  -d '{"query":"{ teams { nodes { id name key } } }"}' https://api.linear.app/graphql

Severity Mapping Details

A Linear Issue carries a numeric priority rather than a severity field. Each DefectDojo severity maps to a Linear priority, where 1 is Urgent and 4 is Low:

Status Mapping Details

Each status value must be set to the ID of a Workflow State in your Linear Team. Workflow State IDs are unique to each workspace, so there are no default values. You can list the Workflow States and their IDs by calling the Linear GraphQL API:

curl -H "Authorization: {{API_KEY}}" -H "Content-Type: application/json" 
  -d '{"query":"{ workflowStates { nodes { id name type team { key } } } }"}' https://api.linear.app/graphql

PagerDuty

The PagerDuty Integration allows you to push DefectDojo Findings and Finding Groups as PagerDuty Incidents, opened on a PagerDuty Service of your choice.

Instance Setup

Issue Tracker Mapping

Severity Mapping Details

By default this maps to the PagerDuty incident Urgency field, which only accepts high or low:

Alternatively, if your PagerDuty account has Priorities enabled, you can map severities to Priority names instead. Set the Severity Field Name to Priority and use your account’s Priority names (for example P1 through P5) as the mapping values. When mapping to Priority, the incident’s Urgency is left to your Service’s own urgency rules.

Status Mapping Details

PagerDuty incidents have three statuses: triggered, acknowledged, and resolved.

ServiceNow

The ServiceNow Integration allows you to push DefectDojo Findings as ServiceNow Incidents.

Instance Setup

DefectDojo authenticates to ServiceNow over OAuth 2.0. How you create the OAuth credentials depends on your ServiceNow release — newer releases (Zurich and later) use a Client Credentials grant, while earlier releases use a refresh token.

ServiceNow Zurich and later (client credentials)

Recent ServiceNow releases deprecated the classic “Create an OAuth API endpoint for external clients” option in favor of the New Inbound Integration Experience, which issues an OAuth Client Credentials grant bound to a service account:

  1. In the left-hand navigation bar, search for “Application Registry” and select it.
  2. Click New, then choose New Inbound Integration Experience.
  3. Select New Integration → OAuth - Client credentials grant.
  4. Set the OAuth Application User to the service account that will create Incidents. That account’s roles determine what DefectDojo is allowed to write.
  5. Save the registration. ServiceNow auto-generates the Client ID and Client Secret (leave those fields blank when creating the registration).

Then, in DefectDojo:

Leave the Refresh Token, Username, and Password fields empty — DefectDojo requests a fresh client-credentials token for each sync.

Severity Mapping Details

This maps to the ServiceNow Impact field.

Status Mapping Details

Shortcut

The Shortcut integration allows you to push DefectDojo Findings as Shortcut Stories. Stories are created with the story type of Bug and assigned to a Team in your Shortcut workspace.

Instance Setup

Issue Tracker Mapping

curl -H "Shortcut-Token: {{API_TOKEN}}" https://api.app.shortcut.com/api/v3/groups

Severity Mapping Details

Each severity value is applied to the Story as a label. Labels are created automatically in Shortcut if they do not already exist, so the default values below can be used as they are, or replaced with label names of your choosing. When a Finding’s severity changes, the old severity label is removed from the Story and the new one is added.

Status Mapping Details

Each status value must be set to the numeric ID of a Workflow State in your Shortcut workspace. Workflow State IDs are unique to each workspace, so there are no default values. You can list the Workflow States and their IDs by calling the Shortcut API:

curl -H "Shortcut-Token: {{API_TOKEN}}" https://api.app.shortcut.com/api/v3/workflows

Freshservice

The Freshservice Integration allows you to push DefectDojo Findings and Finding Groups as Freshservice tickets, assigned to an agent Group of your choice.

Instance Setup

Issue Tracker Mapping

Severity Mapping Details

This maps to the Freshservice ticket Priority field, which uses numeric codes (1 Low, 2 Medium, 3 High, 4 Urgent). The priority names are also accepted:

Status Mapping Details

This maps to the ticket Status field, which uses numeric codes (2 Open, 3 Pending, 4 Resolved, 5 Closed). The status names are also accepted:

ServiceDesk Plus

The ManageEngine ServiceDesk Plus Integration allows you to push DefectDojo Findings and Finding Groups as ServiceDesk Plus requests, assigned to a support Group of your choice. Both the cloud (ServiceDesk Plus OnDemand) and on-premises editions are supported by the same integration - the credentials you provide determine which mode is used.

Instance Setup

Then provide one of the two credential sets:

On-premises: Technician Key

Cloud: Zoho OAuth

The cloud edition authenticates through Zoho Accounts OAuth:

  1. Open the Zoho API Console and create a Self Client.
  2. Note the Client ID and Client Secret.
  3. In the Self Client’s “Generate Code” tab, enter the scope SDPOnDemand.requests.ALL, choose a duration, and generate the code.
  4. Exchange the code for a refresh token:
curl --request POST \
 --url 'https://accounts.zoho.com/oauth/v2/token' \
 --data 'grant_type=authorization_code' \
 --data 'client_id={{CLIENT_ID}}' \
 --data 'client_secret={{CLIENT_SECRET}}' \
 --data 'code={{GENERATED_CODE}}'
  1. Enter the Client ID, Client Secret, and the returned Refresh Token in the instance form. If your account is hosted outside the US data center, set Token URL to your regional Zoho Accounts endpoint (for example https://accounts.zoho.eu/oauth/v2/token).

Issue Tracker Mapping

Severity Mapping Details

This maps to the ServiceDesk Plus request Priority field by name, using your account’s priority names:

Status Mapping Details

This maps to the request Status field by name. The defaults use the built-in statuses:

Zendesk

The Zendesk Integration allows you to push DefectDojo Findings and Finding Groups as Zendesk tickets, assigned to a Zendesk Group of your choice.

Instance Setup

Issue Tracker Mapping

Severity Mapping Details

This maps to the Zendesk ticket Priority field, which accepts low, normal, high, and urgent:

Status Mapping Details

Zendesk tickets support the statuses new, open, pending, hold, solved, and closed. Note that hold must be enabled on your account before it can be used.