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#

• Label should be the label that you want to use to identify this integration.
• Location should be set to your Azure URL - for example https://dev.azure.com/{your organization}
• Token should be set to a personal access token from Azure.

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:

• Severity Field Name: /fields/Microsoft.VSTS.Common.Priority
• Info Mapping: 4
• Low Mapping: 4
• Medium Mapping: 3
• High Mapping: 2
• Critical Mapping: 1

Status Mapping Details#

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

• Status Field Name: /fields/System.State
• Active Mapping: To Do
• Closed Mapping: Done
• False Positive Mapping: Done
• Risk Accepted Mapping: Done

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#

• Label should be the label that you want to use to identify this integration.
• Location should be set to https://bitbucket.org.
• Email should be the email address of the Atlassian account that the API token belongs to.
• API Token should be set to a scoped Atlassian API token.

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#

• Workspace should be the slug of the workspace that contains the repository, as it appears in bitbucket.org URLs.
• Repository Slug should be the slug of the repository that you want to create Issues in.

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.

• Severity Field Name: priority
• Info Mapping: trivial
• Low Mapping: minor
• Medium Mapping: major
• High Mapping: critical
• Critical Mapping: 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.

• Status Field Name: state
• Active Mapping: new
• Closed Mapping: resolved
• False Positive Mapping: invalid
• Risk Accepted Mapping: wontfix

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#

• Label should be the label that you want to use to identify this integration.
• Location should be set to your GitHub User or Organization URL, depending on where you wish to create issues. for example https://github.com/{your-organization}
• Token should be set to a personal access token from GitHub.

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#

• Issue Tracker Mapping Label should be set to identify the Project or Repo that you wish to create Issues in.
• Project Number should be the ID of a GitHub project that you want to send items to. You can get this from the URL while looking at a Project, for example https://github.com/orgs/{your-org}/projects/{project number}.
• Repository Name should be the name of a repo associated with your organization (or user) that you want to push Issues to.

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.

• Severity Field Name: Priority
• Info Mapping: P0
• Low Mapping: P1
• Medium Mapping: P2
• High Mapping: P3
• Critical Mapping: P4

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.

• Status Field Name: Status
• Active Mapping: In Progress
• Closed Mapping: Done
• False Positive Mapping: Done
• Risk Accepted Mapping: Done

GitLab#

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

Instance Setup#

• Label should be the label that you want to use to identify this integration.
• Location should be set to the link to your GitLab server, for example https://gitlab.com/.
• Token should be set to a personal access token from GitLab. The token must have API scopes. See GitLab’s guide to creating a personal access token.

Issue Tracker Mapping#

• Project Name: The name of the project in GitLab that you want to send issues to.

Severity Mapping Details#

This maps to the GitLab Priority field.

• Severity Field Name: Priority
• Info Mapping: 1
• Low Mapping: 2
• Medium Mapping: 3
• High Mapping: 4
• Critical Mapping: 5

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.

• Status Field Name: Status
• Active Mapping: opened
• Closed Mapping: closed
• False Positive Mapping: closed
• Risk Accepted Mapping: closed

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

• API Token (email + token) — HTTP Basic auth using an Atlassian account email and an API token. Calls go directly to your site URL.
• OAuth 2.0 (recommended) — a one-time browser consent; DefectDojo obtains and refreshes the tokens for you.
• Service Account Token — a scoped API token created for an Atlassian service account.

Jira Data Center / Server

• Personal Access Token (recommended)
• Username + Password

How Cloud auth reaches Jira: OAuth 2.0 and Service Account both authenticate as a Bearer token against Atlassian’s gateway — https://api.atlassian.com/ex/jira/{cloudId} — which is a different host than your https://your-site.atlassian.net site URL. DefectDojo uses the gateway for every API call but always builds the ticket link shown on a Finding from your site URL, so the link a user clicks is a normal, browsable .../browse/{ISSUE-KEY} link. (API Token and Data Center auth call the site URL directly, so there is no split.)

Instance Setup#

• Label should be the label you want to use to identify this integration.
• Location should be set to your Jira site URL, for example https://your-organization.atlassian.net. This is used for the browsable ticket links, and — for API Token and Data Center auth — as the API base URL.
• The remaining fields depend on the method you chose above (email + API token, OAuth client credentials, service-account token, PAT, or username + password).

OAuth 2.0 setup (Cloud)#

Create a dedicated app in the Atlassian developer console, then connect from DefectDojo.

1. Choose Create → OAuth 2.0 integration. It must be an OAuth 2.0 integration — a Connect or Forge app cannot use the 3LO authorization-code grant (you’d get grant_type is not enabled for client).
2. When prompted for Access type, choose Resource-level. This scopes the token to the single Jira site the user authorizes, which is exactly what one DefectDojo connection targets. (Account-level grants access to every site in the Atlassian account — broader than needed.)
3. Under Permissions, add the Jira platform REST API and grant the scopes listed below. Note: offline_access is not listed here — it is a standard OAuth scope DefectDojo requests in the authorization URL, not something you add on this screen.
4. Under Authorization, next to OAuth 2.0 (3LO) click Configure and set the Callback URL to https://<your-defectdojo-host>/integrators/jira/oauth/callback — it must match your DefectDojo site URL exactly. Enabling this is what turns on the authorization-code grant and refresh tokens; skipping it causes the grant_type is not enabled / Client is not allowed to use offline_access errors.
5. Copy the Client ID and Client Secret into the DefectDojo form and Submit to save the connection.
6. Click Connect with Jira and approve the consent screen. Atlassian redirects back to DefectDojo, which stores the tokens and resolves your cloudId automatically. A “Connected” indicator appears when it succeeds.

The callback host is your DefectDojo SITE_URL. Atlassian must be able to redirect the browser there, and the value must match what DefectDojo sends exactly — so use the real hostname your users reach DefectDojo at, not a value only reachable from inside the network.

Minimum OAuth scopes#

DefectDojo requests these four classic scopes by default, and they are also the absolute minimum required — each one backs a specific behavior:

Atlassian recommends classic scopes over granular ones; the four above keep the app’s footprint minimal and are sufficient for everything the integration does.

Granular scope alternative#

If your organization requires granular scopes instead of classic, the minimum equivalent set is:

Depending on your site’s field configuration, an endpoint may also require companion read scopes to expand fields — most commonly read:status:jira and read:field:jira (and read:issue-meta:jira for create). If a push fails with a 403 “scope does not match” error, add the exact scope named in the error. This companion-scope sprawl is precisely why classic scopes are recommended.

For the Service Account Token method, grant the token read:jira-work and write:jira-work (plus read:jira-user) — or the granular equivalents above without offline_access. offline_access does not apply — a service-account token is long-lived and is not refreshed by DefectDojo.

Issue Tracker Mapping#

• Project Key: the key of the Jira project to create issues in, for example SEC.
• Issue Type: the issue type to create, for example Bug or Task. Defaults to Bug.

Severity Mapping Details#

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

• Severity Field Name: priority
• Info Mapping: Lowest
• Low Mapping: Low
• Medium Mapping: Medium
• High Mapping: High
• Critical Mapping: Highest

Status Mapping Details#

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

• Status Field Name: status
• Active Mapping: To Do
• Closed Mapping: Done
• False Positive Mapping: Done
• Risk Accepted Mapping: Done

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:

• Source — where the value comes from: an attribute of the Finding, Test, Engagement, or Asset being pushed, or a Static value.
• Value — for an object source, the specific attribute to read, chosen from a list of that object’s fields with human-readable labels (for example Severity, CVE, Mitigation). For a Static value source this is a free-text box you type the literal value into.
• Vendor Field — the Jira field to write to. Because DefectDojo can read Jira’s field catalog, this is a searchable picker that lists each field by its display name and resolves it to the internal id for you — so you select DD Close Justification and DefectDojo stores customfield_10255. The picker is populated from the connection, so it works once the connection is saved and validated.
• Application point — when to send the field: on ticket creation, on every update, or as part of a specific status transition (Active / Closed / False Positive / Risk Accepted). A transition-scoped field is sent as part of that transition’s edit — this is how you supply a value Jira only accepts on a transition screen, most commonly a resolution your workflow requires when an issue is resolved.

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#

• Create / Update / Delete: creating pushes a new issue and records the link on the Finding; updating edits the existing issue; deleting a Finding force-closes its issue (nothing is deleted in Jira). Pushes can be manual (“Push to Integrators”) or automatic per the Issue Tracker Assignment.
• Status reconciliation: after creating (and on every update) DefectDojo reads the issue’s current status and, if it differs from the mapped target, finds a single workflow transition that reaches it and applies it. If no such transition exists, the mapping records an error rather than failing silently. Any transition-scoped custom fields are sent with that transition.
• Ticket link: the link surfaced on the Finding is https://your-site.atlassian.net/browse/{ISSUE-KEY} — always your public site URL, never the internal gateway.
• Token lifecycle (OAuth): DefectDojo owns the whole flow — it performs the authorization-code exchange, stores the access and refresh tokens, and refreshes on demand before a push, persisting the new refresh token each time (Atlassian rotates it on every refresh).
• Credential storage: all connection credentials (passwords, tokens, client secrets, OAuth tokens) are encrypted at rest and are never returned through the API — editing a connection shows a “leave blank to keep” placeholder for stored secrets.

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#

• Label should be the label that you want to use to identify this integration.
• Location should be set to https://api.linear.app/graphql.
• API Key should be set to a Linear personal API key. Keys can be generated in Linear under Settings, then Security & access, then API. The key is sent to Linear’s GraphQL API in the Authorization header.

Issue Tracker Mapping#

• Team (Group) ID should be set to the ID of the Linear Team that Issues will be created for. You can list your Teams and their IDs by calling the Linear GraphQL API:

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:

• Severity Field Name: Priority
• Info Mapping: 4
• Low Mapping: 4
• Medium Mapping: 3
• High Mapping: 2
• Critical Mapping: 1

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

• Status Field Name: Workflow State ID
• Active Mapping: the ID of a started or unstarted state, for example Todo or In Progress.
• Closed Mapping: the ID of a completed state, for example Done. When a Finding is deleted in DefectDojo, its Issue is moved to this state.

Opsgenie#

The Opsgenie Integration allows you to push DefectDojo Findings and Finding Groups as Opsgenie Alerts, optionally routed to an Opsgenie Team as a responder.

Instance Setup#

• Label should be the label that you want to use to identify this integration.
• Location should be set to https://api.opsgenie.com. If your Opsgenie account is hosted in the EU service region, use https://api.eu.opsgenie.com instead. If your alerts live in Jira Service Management Operations (Atlassian is folding Opsgenie into JSM), use https://api.atlassian.com/jsm/ops/integration.
• API Key should be set to an Opsgenie API integration key. An account administrator can create one in the Opsgenie web app under Settings > Integrations: add an integration of type API and give it Create and Update Access (and Read Access so DefectDojo can verify the connection). Note that this is an integration key, not a personal API key - DefectDojo authenticates with GenieKey authorization, which only integration keys support.

Issue Tracker Mapping#

• Team Name (optional) should be the name of the Opsgenie Team to add as a responder on created alerts. You can leave it empty: if the API integration key is team-scoped, alerts route to that team automatically, and otherwise your account’s own routing rules decide the responders.

Severity Mapping Details#

Severities map to the Opsgenie alert Priority field, which uses Opsgenie’s fixed P1 (critical) through P5 (informational) scale:

• Severity Field Name: Priority
• Info Mapping: P5
• Low Mapping: P4
• Medium Mapping: P3
• High Mapping: P2
• Critical Mapping: P1

If a severity is mapped to an unrecognized value, the priority is omitted and Opsgenie applies its own default (P3).

Status Mapping Details#

Opsgenie alerts are open or closed, and an open alert can additionally be acknowledged:

• Status Field Name: Status
• Active Mapping: open
• Closed Mapping: closed
• False Positive Mapping: closed
• Risk Accepted Mapping: acknowledged

Note that closed is a final status in Opsgenie - a closed alert cannot be reopened, and its alias is released. Unlike some other tools, Opsgenie does allow content edits after creation, so pushing an updated Finding syncs its message, description, and priority alongside the status.

DefectDojo sets each alert’s alias to a stable key derived from the Finding or Finding Group, and Opsgenie de-duplicates open alerts by alias - so re-pushing the same Finding updates the existing open alert instead of creating a duplicate.

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#

• Label should be the label that you want to use to identify this integration.
• Location should be set to https://api.pagerduty.com. If your PagerDuty account is hosted in the EU service region, use https://api.eu.pagerduty.com instead.
• API Token should be set to a PagerDuty REST API key. An account administrator can create one in the PagerDuty web app under Integrations > API Access Keys > Create New API Key. Leave “Read-only” unchecked - DefectDojo needs to create and update incidents.
• From Email should be the email address of a valid user on your PagerDuty account. PagerDuty requires this address when creating or updating incidents, and it will be shown as the incident requester.

Issue Tracker Mapping#

• Service ID should be the ID of the PagerDuty Service that incidents will be opened on. You can find it at the end of the URL while looking at the Service in PagerDuty, for example https://{your-subdomain}.pagerduty.com/service-directory/{service id}.

Severity Mapping Details#

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

• Severity Field Name: Urgency
• Info Mapping: low
• Low Mapping: low
• Medium Mapping: low
• High Mapping: high
• Critical Mapping: high

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.

• Status Field Name: Status
• Active Mapping: triggered
• Closed Mapping: resolved
• False Positive Mapping: resolved
• Risk Accepted Mapping: acknowledged

Note that resolved is a final status in PagerDuty - a resolved incident cannot be reopened. Also note that PagerDuty does not allow an incident’s title or description to be edited after creation, so pushing an updated Finding will sync its status, urgency, and priority, but not content changes.

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:

• Instance Label should be the label that you want to use to identify this integration.
• Location should be set to the URL for your ServiceNow server, for example https://your-organization.service-now.com/.
• Client ID should be the Client ID from the OAuth registration.
• Client Secret should be the Client Secret from the OAuth registration.

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

Earlier ServiceNow releases (refresh token)#

On releases that still offer the classic registration, obtain a Refresh Token associated with the User or Service account that will push Incidents to ServiceNow:

1. In the left-hand navigation bar, search for “Application Registry” and select it.
2. Click “New”.
3. Choose “Create an OAuth API endpoint for external clients”.
4. Fill in the required fields:
   • Name: Provide a meaningful name for your application (e.g., Vulnerability Integration Client).
   • (Optional) Adjust the Token Lifespan:
   • Access Token Lifespan: Default is 1800 seconds (30 minutes).
   • Refresh Token Lifespan: The default is 8640000 seconds (approximately 100 days).
5. Click Submit to create the application record.
6. After submission, select the application from the list and take note of the Client ID and Client Secret fields.

You will then need to use this registration to obtain a Refresh Token, which can only be obtained through the ServiceNow API. Open a terminal window and paste the following (substituting the variables wrapped in {{}} with your user’s actual information)

curl --request POST \
 --url {{INSTANCE_HOST}}/oauth_token.do \
 --header 'content-type: application/x-www-form-urlencoded' \
 --data grant_type=password \
 --data 'client_id={{CLIENT_ID}}' \
 --data 'client_secret={{CLIENT_SECRET}}' \
 --data 'username={{USERNAME}}' \
 --data 'password={{PASSWORD}}'

If your ServiceNow credentials are correct, and allow for admin level-access to ServiceNow, you should receive a response with a RefreshToken. You’ll need that token to complete integration with DefectDojo.

• Instance Label should be the label that you want to use to identify this integration.
• Location should be set to the URL for your ServiceNow server, for example https://your-organization.service-now.com/.
• Refresh Token is where the Refresh Token should be entered.
• Client ID should be the Client ID set in the OAuth App Registration.
• Client Secret should be the Client Secret set in the OAuth App Registration.

Severity Mapping Details#

This maps to the ServiceNow Impact field.

• Info Mapping: 1
• Low Mapping: 1
• Medium Mapping: 2
• High Mapping: 3
• Critical Mapping: 3

Status Mapping Details#

• Status Field Name: State
• Active Mapping: New
• Closed Mapping: Closed
• False Positive Mapping: Resolved
• Risk Accepted Mapping: Resolved

Each mapping accepts a standard state label (New, In Progress, On Hold, Resolved, Closed, Cancelled) or a numeric state value. On instances with customized Incident states — or when targeting a table other than incident — use the numeric state value from your instance’s choice list; a numeric value outside the standard set is sent to ServiceNow exactly as configured. The built-in Resolution-code default only accompanies the standard resolved/closed states, so pair custom state values with the close and resolution field mappings below.

Close and resolution fields#

Some ServiceNow instances enforce a Data Policy that makes fields such as the Resolution code (close_code) mandatory whenever an Incident moves to a resolved or closed state. If DefectDojo closes an Incident without them, ServiceNow rejects the write with an HTTP 403 “Data Policy Exception” and the reason is recorded in the integration’s Errors view.

Attach the required fields to the state change with Custom Field Mappings, setting Apply On to the disposition that should carry them:

• Transition to Closed — sent when a Finding is mitigated / closed.
• Transition to False Positive — sent when a Finding is marked a false positive.
• Transition to Risk Accepted — sent when a Finding is risk accepted.

For example, to satisfy a mandatory Resolution code:

Notes:

• Field Name is the ServiceNow column name — close_code, close_notes, or a custom u_... field.
• Transition mappings fire when the record’s state actually changes: a Finding that is already closed when first pushed, an update that closes or reopens the record, and the forced close when a ticket link is deleted. They are not re-sent on routine updates of an unchanged record, so journal fields such as work_notes receive one entry per transition.
• Reference fields such as assignment_group and assigned_to expect a sys_id, not a display name.
• Values that parse as JSON are sent typed: true, 42, [...], {...} — and null, which clears the field. To send such text as a literal string, wrap it in double quotes (e.g. "null").
• short_description, description, state, impact, urgency, and priority are owned by the description template and the severity/status mappings, so they cannot be set through a custom field mapping.
• On tables other than incident, state values that match the standard Incident set (1, 2, 3, 6, 7, 8) are still interpreted with Incident semantics — including the automatic Resolution code default on 6/7/8. Prefer state values outside that range on custom tables, or supply the close fields explicitly as above.

ServiceNow SecOps#

The ServiceNow SecOps integration (also known as ServiceNow SecOps / Vulnerability Response) pushes DefectDojo Findings and Finding Groups into a ServiceNow security table — a Security Incident (sn_si_incident) or a Vulnerable Item (sn_vul_vulnerable_item) — and keeps it in sync as the Finding changes (create, update, and resolve/close). It is the security-operations counterpart to the ServiceNow issue-tracker integration above; use ServiceNow SecOps when you run the Security Incident Response (SIR) or Vulnerability Response (VR) applications.

Instance Setup#

• Instance Label should be the label that you want to use to identify this integration.
• Location should be set to the URL for your ServiceNow server, for example https://your-organization.service-now.com/.

ServiceNow SecOps supports three authentication methods; provide one:

• OAuth 2.0 — enter a Client ID, Client Secret, and Refresh Token. Obtain them exactly as described in the ServiceNow section above (create an OAuth API endpoint in the Application Registry, then exchange your credentials at /oauth_token.do for a refresh token). Alternatively, provide the Client ID and Client Secret together with a Username and Password to use the OAuth password grant instead of a refresh token.
• API Key — enter an API Key, sent as the x-sn-apikey header. The key authenticates nothing until an Inbound Authentication Profile and a REST API Access Policy are attached to it on the instance.
• HTTP Basic — enter the Username and Password of the service account.

The service account (or OAuth client) needs write access to the target table.

Issue Tracker Mapping#

• Target Table selects the ServiceNow table records are written to: Security Incident (sn_si_incident, the default) or Vulnerable Item (sn_vul_vulnerable_item).

Severity Mapping Details#

For a Security Incident this maps to the Impact field; ServiceNow derives the incident Priority from Impact and Urgency, so Urgency mirrors the mapped Impact unless you map it yourself. For a Vulnerable Item, map severity to the risk field your instance uses. The defaults below match the standard SIR Impact scale (1 High, 2 Medium, 3 Low) and are editable.

• Severity Field Name: impact
• Info Mapping: 3
• Low Mapping: 3
• Medium Mapping: 2
• High Mapping: 1
• Critical Mapping: 1

Status Mapping Details#

This maps to the record’s State field. State values are numeric codes that differ between the Security Incident and Vulnerable Item tables and can be customized per instance, so review these against your own configuration. The defaults below use the standard SIR state codes (16 Analysis, 3 Closed).

• Status Field Name: state
• Active Mapping: 16
• Closed Mapping: 3
• False Positive Mapping: 3
• Risk Accepted Mapping: 3

When a record is closed, DefectDojo also sets the ServiceNow Close Code and Close Notes (Resolved for closed Findings, False positive and Risk accepted for the corresponding states).

ServiceNow SecOps-specific behaviors#

• Deduplication — each record is tagged with the Finding or Finding Group’s DefectDojo identifier in its correlation_id. Before creating a record DefectDojo looks one up by correlation_id; a match is adopted and updated rather than duplicated, so re-syncs are idempotent.
• Updates are posted to the record’s Work notes journal (internal), never to customer-visible Comments.
• Resolve on delete — deleting a Finding in DefectDojo resolves/closes the ServiceNow record (State + Close Code) rather than deleting it; records are never hard-deleted.
• Reference fields — optional cmdb_ci, assignment_group, and assigned_to values may be supplied as display names; DefectDojo resolves each to its sys_id. A name that does not resolve is dropped with a warning rather than failing the push.

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#

• Label should be the label that you want to use to identify this integration.
• Location should be set to https://api.app.shortcut.com.
• API Token should be set to a Shortcut API token. Tokens can be generated in Shortcut under Settings, then Your Account, then API Tokens.

Issue Tracker Mapping#

• Team (Group) ID should be set to the UUID of the Shortcut Team that Stories will be created for. You can find this UUID by opening the Team page in Shortcut and copying the identifier from the URL, or by calling the Shortcut API:

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.

• Severity Field Name: Label
• Info Mapping: sev-info
• Low Mapping: sev-low
• Medium Mapping: sev-medium
• High Mapping: sev-high
• Critical Mapping: sev-critical

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

• Status Field Name: Workflow State ID
• Active Mapping: the ID of the state for open work, for example a Backlog or To Do state.
• Closed Mapping: the ID of a Done type state. When a Finding is deleted in DefectDojo, its Story is moved to this state.
• False Positive Mapping: the ID of the state to use for False Positive Findings.
• Risk Accepted Mapping: the ID of the state to use for Risk Accepted Findings.

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#

• Label should be the label that you want to use to identify this integration.
• Location should be set to your Freshservice URL: https://yourcompany.freshservice.com.
• API Key should be a Freshservice API key. Find it by clicking your profile picture (top right) > Profile settings - the key appears on the right below the Delegate Approvals section, after you complete the captcha. If no key is shown there, API access may be disabled at the account level and an administrator has to enable it first.
• Requester Email should be the email address tickets are requested on behalf of. Freshservice requires a requester on every ticket, so DefectDojo creates tickets with this address as the requester.

Issue Tracker Mapping#

• Group ID should be the numeric ID of the Freshservice agent group tickets will be assigned to. Find it in the URL while viewing the group under Admin > Agent Groups.
• Workspace ID (optional) routes tickets to a specific workspace on multi-workspace accounts. Leave it empty to use the primary workspace.

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:

• Severity Field Name: Priority
• Info Mapping: 1
• Low Mapping: 1
• Medium Mapping: 2
• High Mapping: 3
• Critical Mapping: 4

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:

• Status Field Name: Status
• Active Mapping: 2
• Closed Mapping: 5
• False Positive Mapping: 5
• Risk Accepted Mapping: 3

A few Freshservice-specific behaviors to be aware of:

• Updates sync the full ticket content - Freshservice allows the subject and description to be edited after creation.
• Tickets are closed rather than deleted when a Finding is removed; tickets already Resolved or Closed are left untouched. A resolution note is attached automatically on closure, so accounts that require one (a common business rule) accept the close.
• Some accounts compute a ticket’s priority from an Impact/Urgency matrix or a business rule and ignore the priority sent at creation. DefectDojo detects this and re-applies the mapped priority with a follow-up update, so the mapping still takes effect.

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#

• Label should be the label that you want to use to identify this integration.
• Location should be set to your ServiceDesk Plus URL: https://sdpondemand.manageengine.com for the cloud edition (or your regional equivalent), or your server’s address for on-premises installs.

Then provide one of the two credential sets:

On-premises: Technician Key#

• Technician Key should be an API key generated for a technician on your server, under Admin > General Settings > API. Leave the Zoho OAuth fields empty.

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}}'

5. 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#

• Group Name should be the name of the ServiceDesk Plus support group requests will be assigned to, exactly as it appears under Admin > Users > Support Groups.

Severity Mapping Details#

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

• Severity Field Name: Priority
• Info Mapping: Low
• Low Mapping: Normal
• Medium Mapping: Medium
• High Mapping: High
• Critical Mapping: High

Status Mapping Details#

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

• Status Field Name: Status
• Active Mapping: Open
• Closed Mapping: Closed
• False Positive Mapping: Closed
• Risk Accepted Mapping: On Hold

A few ServiceDesk Plus-specific behaviors to be aware of:

• Updates sync the full request content - unlike most trackers, ServiceDesk Plus allows the subject and description to be edited after creation.
• Requests are closed rather than deleted when a Finding is removed; requests already Closed or Resolved are left untouched.
• If your account makes fields mandatory on closure (for example a resolution), a close pushed from DefectDojo may be rejected by those rules and will appear in the Integration errors table.

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#

• Label should be the label that you want to use to identify this integration.
• Location should be set to your Zendesk account URL, for example https://your-subdomain.zendesk.com.
• Email should be the email address of the Zendesk agent the API token belongs to.
• API Token should be set to a Zendesk API token. An administrator can create one in the Zendesk Admin Center under Apps and integrations > APIs > Zendesk API (token access must be enabled).

Issue Tracker Mapping#

• Group ID should be the numeric ID of the Zendesk Group that tickets will be assigned to. You can find it in the Admin Center under People > Team > Groups, or in the URL while viewing the group.

Severity Mapping Details#

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

• Severity Field Name: Priority
• Info Mapping: low
• Low Mapping: low
• Medium Mapping: normal
• High Mapping: high
• Critical Mapping: 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.

• Status Field Name: Status
• Active Mapping: new
• Closed Mapping: solved
• False Positive Mapping: solved
• Risk Accepted Mapping: pending

A few Zendesk-specific behaviors to be aware of:

• The ticket description is the first comment in Zendesk and cannot be edited after creation, so pushing an updated Finding will sync the ticket’s subject, priority, and status, but not description changes.
• Tickets are marked solved rather than deleted when a Finding is removed; Zendesk closes solved tickets automatically after a period of time.
• closed is a final status - closed tickets cannot be updated at all, and pushing a Finding whose ticket has closed will report an error.