jensholdgaard · Oct 30, 2026 · Oct 30, 2026 · Oct 30, 2026 · Oct 30, 2026 · Oct 30, 2026
@@ -1,6 +1,6 @@
 {
   "name": "defectdojo",
-  "version": "3.4.304",
+  "version": "3.5.0-dev",
   "license": "BSD-3-Clause",
   "private": true,
   "dependencies": {

@@ -1,25 +1,35 @@
 ---
 title: "Login Settings"
-description: "Control the DefectDojo login page: disable password login, auto-redirect to SSO, session length, and JIT user creation"
+description: "Control the DefectDojo login page: disable password login, auto-redirect to SSO, session length, idle timeout, and JIT user creation"
 weight: 20
 audience: pro
 ---
 
 Once you have an SSO provider working, **Login Settings** controls how the DefectDojo login page itself behaves — whether username/password login is still offered, whether visitors are sent straight to your identity provider, how long a session lasts, and whether SSO can create accounts on the fly. Open-source DefectDojo does not include these controls — see [Authorized Users](/admin/user_management/os__authorized_users/).
 
-Find it under **Connect > Authorization > Login Settings**. Only a **Superuser** can change it.
+Find it under **Connect > Authorization > Login Settings**. Changing it takes the **Tuner Edit** permission, which every Superuser has.
 
 ![Login Settings](images/pro_login_settings.png)
 
 ## Settings
 
-- **Session Age** — how long a session stays valid before the user must log in again. Choices range from 30 minutes to 30 days; the default is **12 hours**.
+- **Session Age**: the longest a login lasts, counted from the moment the user logged in. When it passes, the user is signed out and signs in again, however active they have been. Choices range from 30 minutes to 30 days; the default is **12 hours**.
+- **Idle Timeout**: signs a user out after this long without a request to DefectDojo. Choices are **Off** (the default), 15 minutes, 30 minutes, and 1, 2, 4 or 8 hours. With **Off**, only Session Age ends a session. When both are set, whichever comes first ends it. See [Session expiry](#session-expiry).
 - **Show Username and Password Fields** — when enabled, the username and password fields are shown on the login page.
 - **Allow Login via Username and Password** — when enabled, classic username/password authentication is allowed and its login button is shown. Turn this **off** once SSO is working to make the instance SSO-only. See [Making the instance SSO-only](#making-the-instance-sso-only) for the safe way to do this.
 - **Allow Password Reset** — when enabled, users can start the password-reset flow from the login page. This only applies to local passwords; SSO users reset credentials at their identity provider.
 - **Create User on Successful Login** — when enabled, a user authenticated by SSO who does not yet exist in DefectDojo is created automatically with minimal permissions (just-in-time provisioning). When disabled, only users who already exist in DefectDojo can sign in via SSO. Pair this with a **Default group** (below) so new users are not stranded with no access.
 - **Auto-Redirect to SSO Login Page** — when enabled, visiting DefectDojo redirects straight to the SSO login instead of showing the DefectDojo login form. **This only works when exactly one SSO connection is configured.** Always keep the [login fallback](#login-fallback) in mind before enabling it.
 
+## Session expiry
+
+Session Age and Idle Timeout apply to every login, whether by username and password or by SSO. A user whose session ends, for either reason, is taken to the login page on their next click, and lands back on the page they were on once they sign in again.
+
+- Only requests the user makes count as activity. A page left open in a browser tab still reaches the Idle Timeout, even though it keeps refreshing its notification count in the background.
+- Activity is recorded at most once a minute, so an idle session can end up to a minute before the Idle Timeout, never after it.
+- A change to either setting reaches every running server within a minute, and applies to sessions that are already signed in. Shortening Session Age signs out anyone whose login is older than the new value.
+- API tokens are not sessions: neither setting affects automation that calls the API with a token.
+
 ## Default access for new users
 
 **Create User on Successful Login** decides *whether* an SSO user is provisioned; it does not grant them any access. A newly created user with no group membership sees an empty dashboard. Configure a **Default group** and **Default group role** on the System Settings page so every new user gets a sensible baseline — the mechanism is described in full under [Default access for SSO-provisioned users](/admin/sso/pro__saml/#default-access-for-sso-provisioned-users).

@@ -198,7 +198,7 @@ A user's Configuration Permissions are the union of what their own Global Roles
 
 Global Roles add up, so the role that opens the settings pages sits beside **Reader** or **Maintainer** rather than replacing it. One **Users Manager** role can serve every user who needs that page, whatever else they hold.
 
-Upgrading from a version where Configuration Permissions were set on the User and Group pages creates these roles for you: for every distinct set of Configuration Permissions someone held, one custom role carrying exactly that set, named after the areas it covers, such as **Users Manager** or **Configuration Viewer**, with a description listing them. Every user and every group that held the set gets that role added to their Global Roles; the Global Role they had before (Reader, Maintainer, Owner, or none) is left exactly as it was. The roles are ordinary custom roles: rename them, merge them, or give several holders one role, as you prefer. The old per-user and per-group permission forms no longer change anything and say so.
+Upgrading from a version where Configuration Permissions were set on the User and Group pages creates these roles for you: for every distinct set of Configuration Permissions someone held, one custom role carrying exactly that set, named after the areas it covers, such as **Users Manager** or **Configuration Viewer**, with a description listing them. Every user and every group that held the set gets that role added to their Global Roles, inactive users included, so a user who is reactivated later finds their access in place; the Global Role they had before (Reader, Maintainer, Owner, or none) is left exactly as it was. Superusers are the exception: they already hold every permission, so no role is created from a superuser's own Configuration Permissions, and removing their superuser status later leaves them only the roles they were given. A Group a superuser belongs to is still converted for its other members. The roles are ordinary custom roles: rename them, merge them, or give several holders one role, as you prefer. The old per-user and per-group permission forms no longer change anything and say so.
 
 An instance with its own authentication backend (a subclass of Django's `ModelBackend` named in `AUTHENTICATION_BACKENDS`) must give that class the `RoleAwarePermissionsMixin` from `pro.authorization.backends`, or `manage.py check` refuses to start: without it the backend would keep answering settings-page checks from the old per-user rows.
 

@@ -45,8 +45,8 @@ The five roles below are DefectDojo Pro's **built-in roles**. They are locked pr
 |  | Edit Benchmarks |  | ☑️ | ☑️ | ☑️ |  |
 |  | Delete Benchmarks |  |  | ☑️ | ☑️ |  |
 |  | View Note History | ☑️ | ☑️ | ☑️ | ☑️ |  |
-|  | Add, Edit, Delete Own Notes | ☑️ | ☑️ | ☑️ | ☑️ | ☑️ |
-|  | Edit Other Notes |  | ☑️ | ☑️ | ☑️ | ☑️ |
+|  | Add, Edit, Delete Own Notes | ☑️ | ☑️ | ☑️ | ☑️ |  |
+|  | Edit Other Notes |  | ☑️ | ☑️ | ☑️ |  |
 |  | Delete Other Notes |  |  | ☑️ | ☑️ |  |
 
 1. A user who is assigned permissions at the Asset level only cannot view the Organization it is contained in.

@@ -0,0 +1,101 @@
+---
+title: "Archive"
+description: "Archive Organizations, Assets, Engagements, Tests and Findings instead of deleting them, restore them during the retention period, and remove old Findings automatically with Triage Engine rules"
+audience: pro
+weight: 8
+---
+
+**Archive** removes an Organization, Asset, Engagement, Test or Finding from view without deleting it. Archived data stays in the database for a fixed retention period, and you can restore it at any point during that period. When the period ends, DefectDojo deletes the archived data permanently, together with its audit history.
+
+Archive is turned on from the **Archive** row on the **Settings > Feature Flags** page. Turning the flag off stops new archives but does not bring archived data back, and archived data is still deleted on its scheduled date.
+
+## What archiving does
+
+When you archive an object, DefectDojo archives it and everything under it:
+
+- Archiving an Organization archives its Assets, their Engagements, Tests and Findings.
+- Archiving an Asset archives its Engagements, Tests and Findings.
+- Archiving an Engagement archives its Tests and Findings.
+- Archiving a Test archives its Findings.
+
+The records attached to those objects are archived with them, for example endpoint and location statuses, vulnerability IDs, Jira links, deduplication signatures, and memberships.
+
+Archived data does not appear in:
+
+- list and detail pages, search, dashboards, metrics and reports
+- the API (`/api/v2/` returns 404 for an archived object)
+- deduplication and reimport: a new scan never matches an archived Finding, and you cannot import into an archived Engagement or Test
+- Triage Engine rules: archived Findings never enter a rule run
+
+The only place archived data appears is the **Archived** page.
+
+If a Finding you archive is the original of a duplicate cluster, DefectDojo promotes one of the remaining duplicates to be the new original, the same way it does when you delete a Finding. Restoring the archived Finding does not relink the cluster.
+
+## The retention period
+
+Archived data is kept for 2 months by default. Self-hosted installs can change this with the `DD_ARCHIVE_RETENTION_MONTHS` environment variable (minimum 1). The period cannot be shortened for data that is already archived.
+
+Every archive has a purge date. A daily task permanently deletes archives whose purge date has passed. This removes the archived objects, everything under them, and their audit history. Nothing remains that refers to them, and they cannot be recovered.
+
+Because of this, DefectDojo asks you to confirm the retention period every time you archive.
+
+## Archived data and your license
+
+Archived data does not count toward your license. Archived Findings, Endpoints and Assets leave license usage when they are archived and count again if you restore them. Archived rows still take up database storage until they are purged, so a database size limit still includes them. While your license is over its limit and blocking changes, archiving still works, so it is a way back under the limit. Restoring an archive adds its objects back to your usage, so it is blocked until you are under the limit again.
+
+## Archiving an object
+
+You need permission to delete an object to archive it.
+
+1. Open the gear menu on the object, either in a list or on its detail page, and choose **Archive**.
+2. The dialog shows how many objects will be archived and the date they will be permanently deleted.
+3. Enter a reason. It is recorded with the archive and shown on the **Archived** page and in the audit log.
+4. Tick the box to confirm you understand the data is deleted after the retention period, then choose **Archive**.
+
+The object disappears straight away. Everything under it is archived in the background, so a large Asset or Organization can take a few minutes to finish. Until it does, its archive shows **Archiving** on the **Archived** page, and the Engagements, Tests and Findings not yet reached are still visible in lists, metrics and the API, and can still be changed. They are hidden as the background work reaches them.
+
+To archive several Findings at once, select them in a Findings list and choose **Archive** from the bulk actions. The selected Findings form one archive and are restored together.
+
+## Restoring archived data
+
+The **Archived** page lists every archive you have permission to restore. For each one it shows what was archived, who archived it and why, when, how it was archived (user interface, API or Triage Engine rule) and its purge date.
+
+Expand an archive to browse the objects it holds. Choose **Unarchive** from its menu to restore it. Restoring brings back the whole tree that was archived together. It runs in the background: the archive shows **Restoring** until everything is back, then leaves the list. An archive that is still archiving or restoring cannot be restored until that finishes.
+
+An object archived on its own before its parent was archived keeps its own archive. Restoring the parent does not restore it, so restore it separately from the **Archived** page.
+
+The reverse is refused: an archive cannot be restored while something above it is still archived, because its objects would come back under a parent that stays hidden. Restore the parent's archive first. The API refuses it with `400` and `"code": "parent_archived"`.
+
+## Removing old Findings with Triage Engine rules
+
+Triage Engine has two actions for retention, available while Archive is turned on:
+
+- **Archive Findings** archives the Findings that reach it, with the reason you set. Each rule run makes one archive holding every Finding it archived, and restoring that archive brings them all back.
+- **Delete Findings Permanently** deletes each Finding that reaches it. This cannot be undone.
+
+Both actions require you to tick a confirmation in the node before the rule can be saved.
+
+A typical retention rule runs on a schedule and archives Findings older than a set age:
+
+1. **On a Schedule** trigger, for example daily.
+2. **If / Filter**: `Date` **is more than N days ago**, with N set to `365`.
+3. **Archive Findings**, with a reason such as "Retention: older than 365 days".
+
+## Excess duplicates are archived, not deleted
+
+When **Delete Duplicate Findings** is turned on in System Settings, DefectDojo removes the oldest duplicates of a Finding once it has more than **Maximum Duplicates**. While Archive is turned on, those duplicates are archived instead of deleted, so a deduplication run that marked the wrong Findings as duplicates can be undone. With Archive turned off they are deleted, as before.
+
+The duplicates removed on one day share one archive, listed on the **Archived** page with the source **Deduplication**. It is kept for the same retention period as any other archive, counted from the last duplicate added to it.
+
+Before you restore one of these archives, turn off **Delete Duplicate Findings** or raise **Maximum Duplicates**. Otherwise the restored duplicates are still over the maximum, and the next run, within a minute, archives them again. The same applies to any archive that holds duplicates of a Finding that is still live: restoring it can put that Finding over its maximum.
+
+## API
+
+Each of `/api/v2/product_types/`, `/api/v2/products/`, `/api/v2/engagements/`, `/api/v2/tests/` and `/api/v2/findings/` has two actions for a single object:
+
+- `GET {id}/archive_preview/` returns what an archive would hide and the purge date.
+- `POST {id}/archive/` archives the object. The body is `{"reason": "...", "acknowledge_retention": true}`. Without `acknowledge_retention: true` the request is refused with `400` and `"code": "acknowledge_required"`. It returns `202` with the archive record: the object is hidden already, and the record's `state` is `archiving` until everything under it is archived, then `archived`.
+
+Archives are listed at `/api/v2/archive/records/`. `GET /api/v2/archive/records/{id}/tree/?model=finding` browses an archive's contents, and `POST /api/v2/archive/records/{id}/unarchive/` starts restoring it and returns `202` with the record in state `restoring`. The record is deleted once everything is back. Restoring an archive that is still archiving or restoring is refused with `400` and `"code": "archive_busy"`.
+
+A new Asset or Organization cannot reuse the name of an archived one. Restore the archived one or choose another name.
@@ -28,6 +28,8 @@ Overall, Findings are designed to work with the Asset Hierarchy to standardize y
 
 Findings are accessible via the sidebar. The submenu provides access to Open and Closed Findings, All Findings (regardless of Open or Closed status), [Risk Accepted Findings](/triage_findings/findings_workflows/os__risk_acceptance/), as well as Findings Templates. Individual Findings are also accessible from within the Test that contains them. 
 
+Through the API, `/api/v2/findings/?engagement=<id>` lists the Findings of one Engagement, `?product=<id>` those of one Asset and `?prod_type=<id>` those of one Organization. Each takes a comma-separated list of ids and combines with every other filter. The longer `test__engagement`, `test__engagement__product` and `test__engagement__product__prod_type` names do the same.
+
 ![image](images/osfindings_ss1.png)
 
 ### Permissions

@@ -100,7 +100,8 @@ Asset views contain a variety of tables and charts to interpret an Asset’s sta
 - **Finding Severity Breakdown**
     - A graph of the Findings within the Asset, organized by severity. 
 - **Finding Distribution**
-    - A breakdown of the Findings within the Asset, organized by status (e.g., Active, Mitigated, Static, and Dynamic)
+    - A ring of the Asset's Findings by status: Active, Mitigated, and Other (Findings that are neither active nor mitigated, such as false positives and accepted risks). The three add up to the total, which the panel header shows, and each status in the legend links to the Asset's Findings with that status.
+    - Beside the ring, the share of Findings reported by static and by dynamic tools. Each is measured against the total on its own, because a Finding can be both static and dynamic, or neither.
 - **All Engagements**
     - A list of Engagements contained within the Asset. 
 

@@ -26,6 +26,8 @@ Overall, Findings are designed to work with the Asset Hierarchy to standardize y
 ## Accessing Findings 
 Findings are accessible from the sidebar under **Act > Explore > Findings**. The submenu provides access to **Active** and **Mitigated** Findings, **All** Findings (regardless of Open or Closed status), Finding **Groups**, **Risk Accepted** Findings and Finding **Templates**; new Findings are created with the **New Finding** button at the top of a Findings list. Individual Findings are also accessible from within the Test that contains them. 
 
+Through the API, `/api/v2/findings/?engagement=<id>` lists the Findings of one Engagement, `?product=<id>` those of one Asset and `?prod_type=<id>` those of one Organization. Each takes a comma-separated list of ids and combines with every other filter. The longer `test__engagement`, `test__engagement__product` and `test__engagement__product__prod_type` names do the same.
+
 [Risk Accepted Findings](/triage_findings/findings_workflows/os__risk_acceptance/) are listed under **Act > Explore > Findings > Risk Accepted**; the Risk Acceptance records themselves are managed from **Act > Risk Acceptances** in the sidebar. 
 
 ![image](images/profindings_ss1.png)