You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
description: "Supported upgrade procedure for self-hosted DefectDojo Pro deployments using the Helm chart"
4
+
draft: false
5
+
weight: 5
6
+
audience: pro
7
+
---
8
+
9
+
This page describes the supported upgrade procedure for self-hosted DefectDojo Pro deployments that use the DefectDojo Pro Helm chart.
10
+
11
+
## Upgrade everything as one unit
12
+
13
+
Each DefectDojo Pro release consists of a Helm chart version, container image versions, and the Pro settings files. These are built and tested together and must be upgraded together as one unit.
14
+
15
+
Upgrading only the image tags is not supported and will break your deployment.
16
+
17
+
## Settings files and upgrades
18
+
19
+
DefectDojo Pro ships a `pro_settings.py` file with every release, and the file changes with nearly every version. Do not carry a copy of `pro_settings.py` forward across upgrades, and do not patch an older copy by hand. The application must always run the `pro_settings.py` that matches its version.
20
+
21
+
Put your own customizations in `local_settings.py`, never in `pro_settings.py`. Your `local_settings.py` is preserved across upgrades.
22
+
23
+
The Helm chart ships and mounts the matching `pro_settings.py` and your `local_settings.py` automatically. When you upgrade using the chart, there is nothing to copy or migrate by hand.
24
+
25
+
## Supported upgrade procedure
26
+
27
+
1. Review the release notes for every version between your current version and your target version, not just the target itself. See the [DefectDojo Pro Changelog](/releases/pro/changelog/) and the version-specific [upgrade notes](/releases/os_upgrading/upgrading_guide/).
28
+
2. Back up your database.
29
+
3. Upgrade to the Helm chart release that matches your target application version, reusing your existing values files. Do not change image tags independently of the chart version.
30
+
31
+
If you have questions about upgrading your on-premise deployment, contact [support@defectdojo.com](mailto:support@defectdojo.com).
Copy file name to clipboardExpand all lines: docs/content/issue_tracking/jira/PRO__jira_guide.md
+32Lines changed: 32 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -138,6 +138,38 @@ Note that DefectDojo cannot send any Issue\-specific metadata as Custom Fields,
138
138
139
139
Follow **[this guide](#custom-fields-in-jira)** to get started working with Custom Fields.
140
140
141
+
#### Close / Reopen Transition fields
142
+
143
+
Some Jira workflows **require** certain fields to be set as part of a transition — for example, a workflow that refuses to close an Issue unless a Resolution and a Justification field are provided on the close screen. The Custom fields setting above only applies when an Issue is *created*, so it cannot satisfy these workflows.
144
+
145
+
Without these settings, DefectDojo sends close / reopen transitions with no fields. A workflow that requires fields will reject that transition, and the Finding and the Jira Issue fall out of sync: the Finding shows as Mitigated in DefectDojo while the Issue remains open in Jira.
146
+
147
+
The **Close Transition fields** and **Reopen Transition fields** settings accept a JSON object that is sent as the `fields` payload of the close / reopen transition call. For example, to close Issues with a Resolution of *Won't Fix* plus a justification value:
148
+
149
+
```json
150
+
{
151
+
"resolution": {"name": "Won't Fix"},
152
+
"customfield_10200": "Risk accepted by security team #report-false-positive"
153
+
}
154
+
```
155
+
156
+
Leave these settings as 'null' if your Jira workflow does not require fields on transitions.
157
+
158
+
**Which fields do you need?**
159
+
160
+
* Ask your Jira admin which fields are on the close / reopen **transition screens**, and which of them are enforced by a validator. The configured JSON must satisfy **every** required field: if any required field is missing from the payload, Jira rejects the whole transition and sets nothing — supplying only some of the required fields does not help.
161
+
* Conversely, fields must be present **on the transition screen** to be sent at all: Jira rejects transitions that attempt to set fields that are not on the screen for that transition.
162
+
* On workflows built with Jira Cloud's current workflow editor, Jira automatically fills in the site's default Resolution when an Issue moves to a done-category status. So, a required Resolution alone will not block a bare transition there, and the practical use of `"resolution"` in this payload is choosing a *meaningful* value (for example *False Positive*) instead of the site default. Workflows built with the classic editor, or with marketplace validator apps, can still hard-require Resolution.
163
+
* Reopen transitions typically clear the Resolution via the workflow itself, so **Reopen Transition fields** usually only needs the custom fields your workflow requires.
164
+
165
+
**Notes:**
166
+
167
+
* The same JSON is sent for *every* close (or reopen) transition for the Product or Engagement — the values are static and do not vary per Finding. If you need different fields per disposition (for example, a different Resolution for False Positive findings than for remediated findings), use the DefectDojo Pro Jira Integrator, which supports per-status transition field mappings.
168
+
* Values use the same format as Jira's REST API: strings for text fields, `{"name": ...}` for resolutions, `[{"name": ...}]` for multi-select fields, and so on.
169
+
* If transitions were rejected while these settings were missing or incomplete, correcting the settings repairs the drift: the next status push for the Finding retries the transition with the configured fields.
170
+
* Both settings are also available on the `/api/v2/jira_projects/` REST endpoint (`close_transition_fields` / `reopen_transition_fields`), so they can be managed via the API.
171
+
* These fields are also applied when DefectDojo closes an Issue because its Finding was **deleted** — the values are captured at the moment the close is queued.
172
+
141
173
#### Jira labels
142
174
143
175
Select the relevant labels that you want the Issue to be created with in Jira, e.g. **DefectDojo**, **YourProductName..**
Copy file name to clipboardExpand all lines: docs/content/issue_tracking/pro_integration/integrations.md
+16-10Lines changed: 16 additions & 10 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -10,11 +10,14 @@ aliases:
10
10
DefectDojo Pro's Integrations let you push your Findings and Finding Groups to ticket tracking systems to easily integrate security remediation with your teams existing development workflow.
Copy file name to clipboardExpand all lines: docs/content/issue_tracking/pro_integration/integrations_toolreference.md
+132Lines changed: 132 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -48,6 +48,52 @@ The attributes in the form are supplied as defaults and are as follows:
48
48
-**False Positive Mapping**: `Done`
49
49
-**Risk Accepted Mapping**: `Done`
50
50
51
+
## Bitbucket
52
+
53
+
The Bitbucket integration allows you to push issues to the [issue tracker](https://support.atlassian.com/bitbucket-cloud/docs/enable-an-issue-tracker/) of a Bitbucket Cloud repository.
54
+
55
+
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**.
56
+
57
+
### Instance Setup
58
+
59
+
-**Label** should be the label that you want to use to identify this integration.
60
+
-**Location** should be set to `https://bitbucket.org`.
61
+
-**Email** should be the email address of the Atlassian account that the API token belongs to.
62
+
-**API Token** should be set to a scoped Atlassian API token.
63
+
64
+
Bitbucket app passwords are deprecated by Atlassian and will not work with this integration. To create an API token:
65
+
66
+
1. Open [Atlassian account settings](https://id.atlassian.com/manage-profile/security/api-tokens) and choose **Security**, then **Create and manage API tokens**.
67
+
2. Choose **Create API token with scopes**, name the token, and set an expiry date.
68
+
3. Select **Bitbucket** as the app.
69
+
4. Grant the token permission to read repositories and to read and write issues.
70
+
71
+
### Issue Tracker Mapping
72
+
73
+
-**Workspace** should be the slug of the workspace that contains the repository, as it appears in bitbucket.org URLs.
74
+
-**Repository Slug** should be the slug of the repository that you want to create Issues in.
75
+
76
+
### Severity Mapping Details
77
+
78
+
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`.
79
+
80
+
-**Severity Field Name**: `priority`
81
+
-**Info Mapping**: `trivial`
82
+
-**Low Mapping**: `minor`
83
+
-**Medium Mapping**: `major`
84
+
-**High Mapping**: `critical`
85
+
-**Critical Mapping**: `blocker`
86
+
87
+
### Status Mapping Details
88
+
89
+
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`.
90
+
91
+
-**Status Field Name**: `state`
92
+
-**Active Mapping**: `new`
93
+
-**Closed Mapping**: `resolved`
94
+
-**False Positive Mapping**: `invalid`
95
+
-**Risk Accepted Mapping**: `wontfix`
96
+
51
97
## GitHub
52
98
53
99
The GitHub integration allows you to add issues to a [GitHub Project](https://docs.github.com/en/issues/planning-and-tracking-with-projects/learning-about-projects/about-projects), which also open Issues in an associated Repo. These Repos/Projects can be associated with either a GitHub Organization or a personal GitHub account.
@@ -298,3 +344,89 @@ This maps to the ServiceNow Impact field.
298
344
-**Closed Mapping**: `Closed`
299
345
-**False Positive Mapping**: `Resolved`
300
346
-**Risk Accepted Mapping**: `Resolved`
347
+
348
+
## Shortcut
349
+
350
+
The Shortcut integration allows you to push DefectDojo Findings as [Shortcut](https://www.shortcut.com/) Stories. Stories are created with the story type of Bug and assigned to a Team in your Shortcut workspace.
351
+
352
+
### Instance Setup
353
+
354
+
-**Label** should be the label that you want to use to identify this integration.
355
+
-**Location** should be set to `https://api.app.shortcut.com`.
356
+
-**API Token** should be set to a Shortcut API token. Tokens can be generated in Shortcut under Settings, then Your Account, then [API Tokens](https://app.shortcut.com/settings/account/api-tokens).
357
+
358
+
### Issue Tracker Mapping
359
+
360
+
-**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:
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.
369
+
370
+
-**Severity Field Name**: `Label`
371
+
-**Info Mapping**: `sev-info`
372
+
-**Low Mapping**: `sev-low`
373
+
-**Medium Mapping**: `sev-medium`
374
+
-**High Mapping**: `sev-high`
375
+
-**Critical Mapping**: `sev-critical`
376
+
377
+
### Status Mapping Details
378
+
379
+
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:
-**Active Mapping**: the ID of the state for open work, for example a Backlog or To Do state.
387
+
-**Closed Mapping**: the ID of a Done type state. When a Finding is deleted in DefectDojo, its Story is moved to this state.
388
+
-**False Positive Mapping**: the ID of the state to use for False Positive Findings.
389
+
-**Risk Accepted Mapping**: the ID of the state to use for Risk Accepted Findings.
390
+
391
+
## Freshservice
392
+
393
+
The Freshservice Integration allows you to push DefectDojo Findings and Finding Groups as Freshservice tickets, assigned to an agent Group of your choice.
394
+
395
+
### Instance Setup
396
+
397
+
-**Label** should be the label that you want to use to identify this integration.
398
+
-**Location** should be set to your Freshservice URL: `https://yourcompany.freshservice.com`.
399
+
-**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.
400
+
-**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.
401
+
402
+
### Issue Tracker Mapping
403
+
404
+
-**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**.
405
+
-**Workspace ID** (optional) routes tickets to a specific workspace on multi-workspace accounts. Leave it empty to use the primary workspace.
406
+
407
+
### Severity Mapping Details
408
+
409
+
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:
410
+
411
+
-**Severity Field Name**: `Priority`
412
+
-**Info Mapping**: `1`
413
+
-**Low Mapping**: `1`
414
+
-**Medium Mapping**: `2`
415
+
-**High Mapping**: `3`
416
+
-**Critical Mapping**: `4`
417
+
418
+
### Status Mapping Details
419
+
420
+
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:
421
+
422
+
-**Status Field Name**: `Status`
423
+
-**Active Mapping**: `2`
424
+
-**Closed Mapping**: `5`
425
+
-**False Positive Mapping**: `5`
426
+
-**Risk Accepted Mapping**: `3`
427
+
428
+
A few Freshservice-specific behaviors to be aware of:
429
+
430
+
- Updates sync the full ticket content - Freshservice allows the subject and description to be edited after creation.
431
+
- 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.
432
+
- 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.
0 commit comments