docs: global component deduplication (#14717)

* docs: global component deduplication

* cleanup

Author: paulOsinski

docs/content/triage_findings/finding_deduplication/PRO__deduplication_tuning.md

@@ -34,7 +34,7 @@ To adjust Same Tool Deduplication:
 
 ### Available Deduplication Algorithms
 
-DefectDojo Pro offers three deduplication methods for same-tool deduplication:
+DefectDojo Pro offers the following deduplication methods for same-tool deduplication:
 
 #### Hash Code
 Uses a combination of selected fields to generate a unique hash. When selected, a third dropdown will appear showing the fields being used to calculate the hash.
@@ -47,6 +47,9 @@ This algorithm can be useful when working with SAST scanners, or situations wher
 #### Unique ID From Tool or Hash Code
 Attempts to use the tool's unique ID first, then falls back to the hash code if no unique ID is available. This provides the most flexible deduplication option.
 
+#### Global Component
+Matches findings by component name and version across **all Products** in the instance, rather than within a single Product or Engagement. Intended for SCA tools where the same vulnerable dependency appears in many Products. This algorithm is off by default and must be enabled by DefectDojo Support. See [Global Component Deduplication](/triage_findings/finding_deduplication/pro__global_component_deduplication/) for details.
+
 ## Cross Tool Deduplication
 
 Cross Tool Deduplication is disabled by default, as deduplication between different security tools requires careful configuration due to variations in how tools report the same vulnerabilities.
@@ -59,7 +62,7 @@ To enable Cross Tool Deduplication:
 2. Change the **Deduplication Algorithm** from "Disabled" to "Hash Code"
 3. Select which fields should be used for generating the hash in the **Hash Code Fields** dropdown
 
-Unlike Same Tool Deduplication, Cross Tool Deduplication only supports the Hash Code algorithm, as different tools rarely share compatible unique identifiers.
+Cross Tool Deduplication supports the Hash Code algorithm, which is suitable for most workflows, as different tools rarely share compatible unique identifiers. For SCA tools reporting the same dependencies, [Global Component Deduplication](/triage_findings/finding_deduplication/pro__global_component_deduplication/) is also available as a cross-tool option (off by default).
 
 ## Reimport Deduplication
 
@@ -76,7 +79,7 @@ When configuring Reimport Deduplication:
 1. Select the **Security Tool** (Universal or Generic Parser)
 2. Choose the appropriate **Deduplication Algorithm**
 
-The same three algorithm options are available for Reimport Deduplication as for Same Tool Deduplication:
+The following algorithm options are available for Reimport Deduplication:
 - Hash Code
 - Unique ID From Tool
 - Unique ID From Tool or Hash Code

docs/content/triage_findings/finding_deduplication/PRO__global_component_deduplication.md

@@ -0,0 +1,87 @@
+---
+title: "Global Component Deduplication (Pro)"
+description: "Deduplicate Software Composition Analysis Findings by component name and version across all Products"
+weight: 5
+audience: pro
+---
+
+Global Component Deduplication is a DefectDojo Pro algorithm that identifies duplicate Findings across **all Products** based on the component name and version they reference. It is intended for Software Composition Analysis (SCA) tools, where the same vulnerable dependency (for example, `timespan@2.3.0`) may appear in many Products, and you want DefectDojo to treat those occurrences as duplicates of a single original Finding.
+
+Unlike the other deduplication algorithms, Global Component matching is **not scoped to a single Product or Engagement**. A Finding imported into Product B can be marked as a duplicate of an older Finding in Product A, even if the two Products are unrelated.
+
+## Enabling the Global Component Algorithm
+
+Global Component Deduplication is gated behind a feature flag and is **off by default**. To request that it be enabled on your instance, contact [DefectDojo Support](mailto:support@defectdojo.com).
+
+Once the feature is enabled, **Global Component** will become available as an option in the **Deduplication Algorithm** dropdown for both Same Tool and Cross Tool Deduplication settings in the Tuner.
+
+## Configuring Global Component Deduplication
+
+Global Component can be applied to Same-Tool Deduplication, Cross-Tool Deduplication, or both, and is configured per security tool from **Settings > Pro Settings > Deduplication Settings**.
+
+### Same-Tool
+
+Use Same-Tool Deduplication with the Global Component algorithm when you want to deduplicate findings from a single SCA tool across multiple Products.
+
+1. Open the **Same Tool Deduplication** tab.
+2. Select the SCA tool from the **Security Tool** dropdown (for example, `Dependency Track Finding Packaging Format (FPF) Export`).
+3. Set the **Deduplication Algorithm** to **Global Component**.
+4. Submit the form.
+
+Hash Code Fields are not used by this algorithm and are hidden when it is selected.
+
+### Cross-Tool
+
+Use Cross-Tool Deduplication with the Global Component algorithm when you want to deduplicate findings of the same component across different SCA tools and Products.
+
+Cross-tool matching requires Global Component to be configured on **each** tool that should participate.
+
+1. Open the **Cross Tool Deduplication** tab.
+2. For each tool to include: select it from the **Security Tool** dropdown, set the algorithm to **Global Component**, and submit.
+
+## How Matching Works
+
+A new Finding is marked as a duplicate of an existing Finding when:
+
+- The component name and component version match exactly, **and**
+- An older Finding with the same component name and version exists anywhere in the DefectDojo instance — in any Product or Engagement.
+
+Component version matching is exact. A Finding for `timespan@2.3.0` will **not** deduplicate against one for `timespan@2.3.1`.
+
+The Engagement-scoped deduplication setting is ignored for this algorithm; matching is always global.
+
+## Example
+
+Assume Global Component is enabled on `Dependency Track Finding Packaging Format (FPF) Export` (Same Tool) and on a Generic Findings Import tool (Cross Tool):
+
+| Step | Import | Into Product | Result |
+| --- | --- | --- | --- |
+| 1 | Dependency Track scan for `timespan@2.3.0` | Application 0 | 1 active Finding created |
+| 2 | Same Dependency Track scan | Application 1 | 1 Finding created, marked as duplicate of the Application 0 Finding |
+| 3 | Generic Findings Import for `timespan@2.3.0` | Application 2 | 1 Finding created, marked as duplicate of the Application 0 Finding (cross-tool match) |
+| 4 | Dependency Track scan for `timespan@2.3.1` | Application 3 | 1 active Finding created — different version, no match |
+
+Each duplicate Finding shows its original at the bottom of the Finding page in the duplicate chain.
+
+## Cross-Product Visibility
+
+Because Global Component matching crosses Product boundaries, the original Finding in a duplicate chain may live in a Product that the user viewing the duplicate does not have permission to access.
+
+In that case, the Finding is visible and labelled as a duplicate, but the user will not be able to open or navigate to the original. Consider this before enabling Global Component on tools whose Findings are sensitive to Product-level access controls.
+
+## Reverting
+
+To stop using Global Component for a given tool, open its Deduplication Settings and switch the algorithm back to one of the scoped options.
+
+For **Same Tool** Deduplication:
+
+- Hash Code
+- Unique ID From Tool
+- Unique ID From Tool or Hash Code
+
+For **Cross Tool** Deduplication:
+
+- Hash Code
+- Disabled
+
+Changing the algorithm triggers a background recalculation of deduplication hashes for the tool's existing Findings.

docs/content/triage_findings/finding_deduplication/about_deduplication.md

@@ -145,4 +145,5 @@ Sometimes, Deduplication does not work as expected.  Here are some examples of w
 | Reimport closes an old Finding and creates a new one when only the line number changed | Reimport matching uses unstable fields (for example, line number) | <strong>Reimport Deduplication</strong> (prefer stable IDs or stable hash fields) |
 | Multiple Findings are created in the same Test that you believe should be duplicates | Deduplication matching is not configured for that tool or scope | <strong>Same Tool Deduplication</strong> (and consider “Delete Deduplicate Findings” behavior) |
 | Duplicates are created across different tools | Cross-tool matching is disabled or too strict | <strong>Cross Tool Deduplication (Pro only)</strong> (hash-based matching) |
+| The same SCA dependency imported into multiple Products creates separate Findings instead of duplicates | Deduplication is scoped per Product by default | <strong>Global Component Deduplication (Pro only)</strong> ([enable for your SCA tools](/triage_findings/finding_deduplication/pro__global_component_deduplication/)) |
 | Excess duplicates of the same Finding are being created, across Tests | Asset Hierarchy is not set up correctly | [Consider Reimport for continual testing](/triage_findings/finding_deduplication/avoid_excess_duplicates/) |