Merge pull request #14880 from paulOsinski/may-docs

May docs maintenance

Author: rossops

docs/content/admin/sso/PRO__saml.md

@@ -41,6 +41,19 @@ DefectDojo can use the SAML assertion to automatically assign users to [User Gro
 
 The **Group Name Attribute** field specifies which attribute in the SAML assertion contains the user's group memberships. When a user logs in, DefectDojo reads this attribute and assigns the user to any matching groups. To limit which groups from the assertion are considered, use the **Group Limiter Regex Expression** field.
 
+The value must match the attribute name your Identity Provider emits in the assertion exactly, including any namespace prefix. A short, friendly name like `groups` will only work if your IdP is configured to emit that literal attribute name — many IdPs use a fully qualified claim URI instead.
+
+### Group Name Attribute by Identity Provider
+
+| Identity Provider | Default attribute name to use |
+|---|---|
+| **Entra ID / Azure AD** | `http://schemas.microsoft.com/ws/2008/06/identity/claims/groups` |
+| **Okta** | `groups` (the attribute name you configured on the SAML app's Group Attribute Statement) |
+| **Keycloak** | `groups` (or whatever you set as the "SAML Attribute Name" on the Group List mapper) |
+| **PingFederate / generic** | Whatever value you configured on the IdP side — check your IdP's assertion before assuming `groups` |
+
+If group mapping appears to do nothing — users log in successfully but no groups are created or assigned — the most common cause is a mismatch between this field and the attribute name your IdP is actually sending. Enable **Enable SAML Debugging** (see [Additional Options](#additional-options)) to see the raw attributes coming back from the IdP.
+
 If no group with a matching name exists, DefectDojo will automatically create one. Note that a newly created group will not have any permissions configured — those can be set later by a Superuser.
 
 To activate group mapping, check the **Enable Group Mapping** checkbox at the bottom of the form.

docs/content/admin/user_management/OS__creating_new_users.md

@@ -0,0 +1,41 @@
+---
+title: "Creating a new user"
+description: "How to onboard a new user onto your DefectDojo instance"
+audience: opensource
+weight: 1
+---
+
+This page describes the recommended onboarding workflow for adding new users to a DefectDojo instance.  DefectDojo users can be used as both standard, human-operated accounts and as service accounts.
+
+The admin who creates the account is responsible for delivering the initial credentials (username and password) to the new user.
+
+## Recommended workflow
+
+1. **Create the user account** in DefectDojo (Superuser only):
+   * Navigate to **👤 Users → Users** to open the All Users table.
+   * Click the 🛠️ (crossed wrench and screwdriver) icon.
+   * Enter the new user's name and email address.
+   * Set a temporary password.
+   * Submit the form.
+
+2. **Assign permissions** as appropriate — Product/Product Type membership, Configuration Permissions, Global Role, or Superuser status. See [Set a User's permissions](../set_user_permissions/) for details. A new user with no assignments will not be able to see any Products or Findings.
+
+3. **Send the credentials to the new user out-of-band** (over email, your team's chat tool, or however you normally share secrets). Include:
+   * The DefectDojo instance URL.
+   * The username (typically their email address).
+   * The temporary password you just set.
+   * A note that they should change the password and enable MFA (if your instance uses MFA) on first login.
+
+4. **The new user logs in and rotates the credential.** They can either:
+   * Log in with the temporary password and then change it from their profile menu, or
+   * Use the **I forgot my password** link on the login page to set a password directly without using the temporary one. The temporary password is still required for the initial account record to exist, but the user does not need to remember it if they use the password-reset flow.
+
+5. **The new user configures MFA** from their profile menu. We strongly recommend requiring MFA for all users on instances that aren't behind SSO.
+
+## SSO Users
+
+If your instance is configured with [SSO](../configure_sso/), the workflow is different — users are typically created on first login from the Identity Provider, and you only need to grant them group membership or roles afterwards.
+
+## Recovering from a lost MFA token
+
+If a user loses access to their MFA device, see the [MFA recovery section](/get_started/pro/cloud/connectivity-troubleshooting/#ive-lost-access-to-my-mfa-codes) of the connectivity troubleshooting guide. There is currently no way to remove MFA from an account without an MFA code — the workaround is to create a new account for the user and re-grant the same permissions.

docs/content/admin/user_management/PRO__creating_new_users.md

@@ -0,0 +1,40 @@
+---
+title: "Creating a new user"
+description: "How to onboard a new user onto your DefectDojo instance"
+audience: pro
+weight: 1
+---
+
+This page describes the recommended onboarding workflow for adding new users to a DefectDojo instance.  DefectDojo users can be used as both standard, human-operated accounts and as service accounts.
+
+The admin who creates the account is responsible for delivering the initial credentials (username and password) to the new user.
+
+## Recommended workflow
+
+1. **Create the user account** in DefectDojo (Superuser only):
+   * Navigate to **👤 Users → ➕ New User**.
+   * Enter the new user's name and email address.
+   * Set a temporary password.
+   * Submit the form.
+
+2. **Assign permissions** as appropriate — Product/Product Type membership, Configuration Permissions, Global Role, or Superuser status. See [Set a User's permissions](../set_user_permissions/) for details. A new user with no assignments will not be able to see any Products or Findings.
+
+3. **Send the credentials to the new user out-of-band** (over email, your team's chat tool, or however you normally share secrets). Include:
+   * The DefectDojo instance URL.
+   * The username (typically their email address).
+   * The temporary password you just set.
+   * A note that they should change the password and enable MFA (if your instance uses MFA) on first login.
+
+4. **The new user logs in and rotates the credential.** They can either:
+   * Log in with the temporary password and then change it from their profile menu, or
+   * Use the **I forgot my password** link on the login page to set a password directly without using the temporary one. The temporary password is still required for the initial account record to exist, but the user does not need to remember it if they use the password-reset flow.
+
+5. **The new user configures MFA** from their profile menu. We strongly recommend requiring MFA for all users on instances that aren't behind SSO.
+
+## SSO Users
+
+If your instance is configured with [SSO](../configure_sso/), the workflow is different — users are typically created on first login from the Identity Provider, and you only need to grant them group membership or roles afterwards.
+
+## Recovering from a lost MFA token
+
+If a user loses access to their MFA device, see the [MFA recovery section](/get_started/pro/cloud/connectivity-troubleshooting/#ive-lost-access-to-my-mfa-codes) of the connectivity troubleshooting guide. There is currently no way to remove MFA from an account without an MFA code — the workaround is to create a new account for the user and re-grant the same permissions.

docs/content/import_data/import_intro/reimport.md

@@ -59,6 +59,22 @@ If you’re using a triage\-less scanner, or you don’t otherwise want Closed F
 * Set **do\_not\_reactivate** to **True** if using the API
 * Check the **Do Not Reactivate** checkbox if using the UI
 
+### Force Active and Force Verified behavior
+
+Setting `active=true` (UI: **Force Active**) or `verified=true` (UI: **Force Verified**) on a Reimport will set the corresponding status on every matched Finding, **including findings that would otherwise be Inactive because they were Mitigated**. This is the same reactivation behavior described above, just made explicit on every incoming Finding.
+
+Force Active and Force Verified do **not** override statuses that represent an explicit user or system decision about why a Finding should not be Active:
+
+| Status | Does Force Active reactivate it? | Why |
+|---|---|---|
+| Mitigated / Closed | Yes | Same as the default reactivation behavior |
+| Risk Accepted | No | The Finding is Inactive because a user explicitly accepted the risk; reimport must not silently revoke that decision |
+| Duplicate | No | The Finding is Inactive because deduplication marked it as a duplicate of another Finding; the original Finding (not the duplicate) is what should be active |
+| False Positive | No | Same reasoning as Risk Accepted — an explicit triage decision |
+| Out of Scope | No | Same reasoning as Risk Accepted — an explicit triage decision |
+
+If you want a Risk Accepted or Duplicate Finding to become Active again, you need to remove the Risk Acceptance or the Duplicate marker first. Force Active alone will not do it.
+
 ## Opening the Reimport form
 
 The **Re\-Import Findings** form can be accessed on any Test page, under the **⚙️Gear** drop\-down menu.

docs/content/supported_tools/parsers/universal_parser.md

@@ -161,3 +161,14 @@ You can edit the Test_Type associated with your Universal Parser to change:
 * Whether it is "active" or not. If not, it will not appear as an option in the "Scan Type" drop-down on the "Add Findings" page
 * Whether its findings should be marked "static" or "dynamic"
 * You can tweak the same-tool and cross-tool deduplication hash codes, as well as the reimport hash codes, for your Universal Parser under "Enterprise Settings". By default, only same-tool deduplication and reimport hash codes are populated, with the required values Title, Severity, and Description.
+
+### Current limitations: editing and deleting a Universal Parser
+
+The field-mapping configuration of an existing Universal Parser cannot be modified after it is created — only the associated Test_Type (above) is editable. There is also no in-UI option to delete a Universal Parser.
+
+The current workaround for both cases is:
+
+* **To change a parser's field mappings:** create a new Universal Parser with the desired mappings (using a representative sample file as in Step 1), and switch new imports to use the new parser. Existing Tests already imported under the old parser are unaffected.
+* **To "retire" a parser you no longer want to use:** mark its associated Test_Type as inactive (uncheck "active" on the Test_Type). It will stop appearing in the "Scan Type" drop-down on the Add Findings page. The parser configuration itself will remain in the database.
+
+If you need a parser configuration permanently removed (for example, because it contains sensitive field names), contact [DefectDojo Support](mailto:support@defectdojo.com).

docs/content/triage_findings/finding_deduplication/PRO_enabling_product_deduplication.md

@@ -1,55 +1,55 @@
 ---
 title: "Enabling Deduplication"
-description: "How to enable Deduplication at the Product level"
+description: "How to enable Deduplication at the Product or Engagement level"
 weight: 2
 audience: pro
 aliases:
   - /en/working_with_findings/finding_deduplication/enabling_product_deduplication
 ---
-Deduplication can be implemented at either a Product level or at a more narrow Engagement level.
+Deduplication can be applied at a Product\-wide level, or scoped more narrowly to a single Engagement.
 
 ## Deduplication for Products
 
-1. Start by navigating to the System Settings page. This is nested under **Settings \> Pro Settings \> ⚙️ System Settings** on the sidebar.
+1. Navigate to the System Settings page: **Settings \> Pro Settings \> ⚙️ System Settings** on the sidebar.
 
 ![image](images/enabling_product-level_deduplication.png)
 
-2. **Deduplication and Finding Settings** are at the top of the **System Settings** menu.  
-​
+2. The **Deduplication and Finding Settings** card is at the top of the **System Settings** page.
+
 ![image](images/enabling_product-level_deduplication_2.png)
 
 ### Enable Finding Deduplication
 
-**Enable Finding Deduplication** will turn on the Deduplication Algorithm for all Findings. Deduplication will be triggered on all subsequent imports \- when this happens, DefectDojo will look at any Findings contained in the destination Product, and deduplicate as per your settings. 
-
-### Delete Deduplicate Findings
+**Enable Finding Deduplication** turns on the Deduplication Algorithm for all Findings. Once enabled, Deduplication runs on every subsequent import — DefectDojo compares imported Findings against existing Findings in the destination Product and marks duplicates according to your configuration.
 
-**Delete Deduplicate Findings**, combined with the **Maximum Duplicates** field allows DefectDojo to limit the amount of Duplicate Findings stored. When this field is enabled, DefectDojo will only keep a certain number of Duplicate Findings.
+### Delete Duplicate Findings
 
-Applying **Delete Deduplicate Findings** will begin a deletion process immediately. DefectDojo will look at each Finding with Duplicates recorded, and will delete old duplicate Findings until the Maximum Duplicate number has been reached.
+**Delete Duplicate Findings**, combined with the **Maximum Duplicates** field, limits how many duplicate Findings DefectDojo retains. When enabled, a background job periodically prunes excess duplicates so that each original Finding keeps no more than the configured **Maximum Duplicates** count. Oldest duplicates are removed first.
 
 ## Deduplication for Engagements
 
-Rather than Deduplicating across an entire Product, you can set a deduplication scope to be within a single Engagement exclusively.
+Rather than Deduplicating across an entire Product, you can scope Deduplication to a single Engagement.
+
+### Open the Engagement form
 
-### Edit Engagement page
+* **For a new Engagement:** open the **📥 Engagements** sub‑menu on the sidebar and click **\+ New Engagement**.
 
-* To enable Deduplication within a New Engagement, start with the **\+ New Engagement** option from the sidebar, which you can find by opening the **📥Engagements** sub\-menu.  
-​
 ![image](images/enabling_deduplication_within_an_engagement.png)
 
-* To enable Deduplication within an existing Engagement: from the **All Engagements** page, select the **Edit Engagement** option from the **⋮** menu.   
-​
+* **For an existing Engagement (from the All Engagements page):** open the **⋮** menu for the Engagement and select **Edit Engagement**.
+
 ![image](images/enabling_deduplication_within_an_engagement_2.png)
 
-* You can also open this menu from a specific **Engagement Page** by clicking the ⚙️Gear icon in the top\-right hand corner.  
-​
+* **For an existing Engagement (from the Engagement page):** open the **⚙️ Gear** menu in the top‑right corner of the page and select **Edit Engagement**.
+
 ![image](images/enabling_deduplication_within_an_engagement_3.png)
 
-### Completing the Edit Engagement form
+### Completing the Engagement form
 
-1. Start by opening the **Optional Fields \+** menu at the bottom of the **Edit Engagement** form.
-2. Click the ☐ **Deduplication Within This Engagement** box.
+1. On the Engagement form, locate the ☐ **Isolate Deduplication from Other Engagements** checkbox. It appears above the **Optional Fields \+** panel.
+2. Check the box to scope Deduplication to this Engagement.
 3. Submit the form.
 
-![image](images/enabling_deduplication_within_an_engagement_4.png)
+When this option is enabled, Findings in this Engagement will only be deduplicated against other Findings within the same Engagement. Findings in other Engagements on the same Product are ignored by the Deduplication Algorithm.
+
+![image](images/enabling_deduplication_within_an_engagement_4.png)