fix(dependency_check): fold related dependency paths into description (#14941)

Dependency-Check's DependencyBundlingAnalyzer merges co-grouped artifacts
into one main dependency and lists the others under <relatedDependencies>.
The vulnerability is attached only to the main dependency in the XML; related
entries are metadata for other files in the same logical component.

Previously the parser emitted one finding per related entry in addition to
the main finding. This multiplied a single CVE into N findings sharing the
same title, CVE, component name, and version — only the file path differed.
Projects with Spring Boot, ActiveMQ, or other libraries whose CPE matches
many sibling artifacts (DC bundling scenario 4) were hit hardest.

Instead, emit one finding per vulnerability per main dependency and surface
related file paths in the description under a "**Related Filepaths:**" block.

The five DependencyBundlingAnalyzer bundling scenarios are documented in the
new build_related_dependencies_block() helper, the parser docs page, and the
2.59.1 upgrade notes.

Closes-style note: findings previously tagged `related` will be closed on the
next reimport as they are no longer emitted. The `related` tag is not applied.

Author: valentijnscholten

docs/content/releases/os_upgrading/2.59.1.md

@@ -0,0 +1,32 @@
+---
+title: 'Upgrading to DefectDojo Version 2.59.1'
+toc_hide: true
+weight: -20260603
+description: Dependency Check parser no longer emits separate findings for related dependencies; related file paths are now listed in the main finding's description.
+---
+
+## Dependency Check parser: related dependencies folded into the main finding
+
+The Dependency Check parser previously created one finding per `<relatedDependency>` in the report, in addition to the finding for the main vulnerable dependency. Because OWASP Dependency-Check attaches the vulnerability only to the main dependency in the XML and the related entries are metadata pointing to other files in the same logical component, this produced N findings sharing the same title, CVE, component name and component version — only the file path differed. For projects with Spring Boot, ActiveMQ, or other libraries whose CPE matches many sibling artifacts this produced significant noise.
+
+Starting in 2.59.1, the parser emits exactly one finding per vulnerability per main dependency. The file paths of any related dependencies are surfaced in the finding description under a `**Related Filepaths:**` block.
+
+### Background: what `<relatedDependencies>` actually contains
+
+OWASP Dependency-Check's `DependencyBundlingAnalyzer` merges co-grouped artifacts into a single main dependency and lists the others under `<relatedDependencies>`. It does this under five scenarios:
+
+1. **Identical content (`hashesMatch`)** — the same jar (matching sha1) found at multiple paths, e.g. the same library packaged into multiple ear/war archives.
+2. **Shaded jar (`isShadedJar`)** — a `.jar` and a `pom.xml` extracted from inside it share the same CPE; the pom.xml is recorded as related.
+3. **WebJar (`isWebJar`)** — a `.js` file extracted from a WebJar matches the jar's CPE (mapped via `pkg:maven/org.webjars/<name>@<version>`); the js file is recorded as related to the jar.
+4. **Same CPE + base path + vulnerabilities + filename match** — sibling artifacts in the same project that share a CPE. Example: `spring-boot`, `spring-boot-actuator`, `spring-boot-starter-jdbc`, etc. all map to the `spring_boot` CPE and are grouped under the main `spring-boot` jar.
+5. **NPM same name + version** — the same npm package discovered via different resolution paths (for example `package-lock.json` plus `node_modules`).
+
+Only scenario 1 represents the same vulnerable artifact at multiple deploy locations. Scenarios 2-5 are different files representing one logical component. Both cases were previously inflated into separate findings; both now collapse to one finding with the related paths listed in the description.
+
+### Required actions
+
+- **Users filtering or grouping by the `related` tag**: that tag is no longer applied because related findings are no longer created. Update any saved filters, dashboards, or rules that depend on it. Equivalent information is now available in the finding description (look for `**Related Filepaths:**`).
+- **Reimport behavior**: on the next reimport of an existing Dependency Check report, the previously-created `related` findings will be closed as no longer present in the report. This is expected and matches the new parsing behavior.
+
+
+For more information, check the [Release Notes](https://github.com/DefectDojo/django-DefectDojo/releases/tag/2.59.1).

docs/content/supported_tools/parsers/file/dependency_check.md

@@ -7,7 +7,21 @@ OWASP Dependency Check output can be imported in Xml format. This parser ingests
 * Suppressed vulnerabilities are tagged with the tag: `suppressed`.
 * Suppressed vulnerabilities are marked as mitigated.
 * If the suppression is missing any `<notes>` tag, it tags them as `no_suppression_document`.
-* Related vulnerable dependencies are tagged with `related` tag.
+
+### Related dependencies
+
+OWASP Dependency-Check's `DependencyBundlingAnalyzer` merges co-grouped artifacts into a single main dependency and lists the others under `<relatedDependencies>` in the report. The vulnerability is attached only to the main dependency; the related entries are metadata pointing to other files in the same logical component.
+
+The parser emits one finding per vulnerability per main dependency and surfaces the related file paths in the finding's description under a `**Related Filepaths:**` block (rather than creating a separate finding per related entry, which produced N findings sharing the same title and CVE differing only in file path).
+
+DC bundles dependencies under five scenarios:
+
+1. **Identical content (`hashesMatch`)** — the same jar (matching sha1) found at multiple paths (e.g. packaged into multiple ear/war archives).
+2. **Shaded jar (`isShadedJar`)** — a `.jar` and a `pom.xml` extracted from inside it share the same CPE.
+3. **WebJar (`isWebJar`)** — a `.js` file extracted from a WebJar maps to the jar's CPE via `pkg:maven/org.webjars/<name>@<version>`.
+4. **Same CPE + base path + vulnerabilities + filename match** — sibling artifacts sharing a CPE (e.g. `spring-boot`, `spring-boot-actuator`, `spring-boot-starter-jdbc` all map to the `spring_boot` CPE).
+5. **NPM same name + version** — the same npm package discovered via different resolution paths (e.g. `package-lock.json` + `node_modules`).
+
 
 ### Sample Scan Data
 Sample Dependency Check scans can be found [here](https://github.com/DefectDojo/django-DefectDojo/tree/master/unittests/scans/dependency_check).

dojo/tools/dependency_check/parser.py

@@ -86,6 +86,57 @@ def add_finding(self, finding, dupes):
         if key not in dupes:
             dupes[key] = finding
 
+    def build_related_dependencies_block(self, dependency, namespace):
+        """
+        Return a markdown block listing related dependencies, or ''.
+
+        Dependency-Check's DependencyBundlingAnalyzer merges co-grouped artifacts
+        into one main dependency and lists the others under <relatedDependencies>.
+        The vulnerability is attached only to the main dependency in the XML; the
+        related entries are metadata pointing to other files in the same logical
+        component. Previously we emitted one finding per related entry, which
+        multiplied a single CVE into N findings sharing the same title and CVE
+        with only the file_path differing — pure noise for the user. Instead we
+        keep one finding for the main dependency and surface the related file
+        paths in its description.
+
+        DC bundles dependencies under five scenarios (see
+        DependencyBundlingAnalyzer.evaluateDependencies):
+
+        1. hashesMatch — identical content (same sha1) found at multiple paths,
+           e.g. the same jar packaged into multiple ear/war archives.
+        2. isShadedJar — a .jar and a pom.xml extracted from inside it share the
+           same CPE; the pom.xml is recorded as related to the jar.
+        3. isWebJar — a .js file extracted from a WebJar matches the jar's CPE
+           (mapped via pkg:maven/org.webjars/<name>@<version>); the js is
+           related to the jar.
+        4. CPE + base path + vulnerabilities + filename match — sibling artifacts
+           in the same project that share a CPE (e.g. spring-boot,
+           spring-boot-actuator, spring-boot-starter all map to the
+           spring_boot CPE).
+        5. NPM same name + version — the same npm package discovered via
+           different resolution paths (e.g. package-lock.json + node_modules).
+
+        Scenario 1 is the only case where the related entries are genuinely
+        separate vulnerable locations; scenarios 2-5 are different files
+        representing one logical component. Listing all related paths in the
+        description preserves the per-location information for scenario 1 while
+        removing the noise from scenarios 2-5.
+        """
+        related = dependency.find(namespace + "relatedDependencies")
+        if related is None:
+            return ""
+        entries = []
+        for rd in related.findall(namespace + "relatedDependency"):
+            file_name = rd.findtext(f"{namespace}fileName")
+            if not file_name:
+                continue
+            file_path = (rd.findtext(f"{namespace}filePath") or "").strip()
+            entries.append(f"- {file_name} ({file_path})" if file_path else f"- {file_name}")
+        if not entries:
+            return ""
+        return "\n**Related Filepaths:**\n" + "\n".join(entries)
+
     def get_filename_and_path_from_dependency(
         self,
         dependency,
@@ -448,6 +499,7 @@ def get_findings(self, filename, test):
                     namespace + "vulnerabilities",
                 )
                 if vulnerabilities is not None:
+                    related_block = self.build_related_dependencies_block(dependency, namespace)
                     for vulnerability in vulnerabilities.findall(
                         namespace + "vulnerability",
                     ):
@@ -459,29 +511,12 @@ def get_findings(self, filename, test):
                                 test,
                                 namespace,
                             )
+                            if related_block:
+                                finding.description += related_block
                             if scan_date:
                                 finding.date = scan_date
                             self.add_finding(finding, dupes)
 
-                            relatedDependencies = dependency.find(
-                                namespace + "relatedDependencies",
-                            )
-                            if relatedDependencies is not None:
-                                for relatedDependency in relatedDependencies.findall(
-                                    namespace + "relatedDependency",
-                                ):
-                                    finding = self.get_finding_from_vulnerability(
-                                        dependency,
-                                        relatedDependency,
-                                        vulnerability,
-                                        test,
-                                        namespace,
-                                    )
-                                    if finding:  # could be None
-                                        if scan_date:
-                                            finding.date = scan_date
-                                        self.add_finding(finding, dupes)
-
                     for suppressedVulnerability in vulnerabilities.findall(
                         namespace + "suppressedVulnerability",
                     ):
@@ -493,6 +528,8 @@ def get_findings(self, filename, test):
                                 test,
                                 namespace,
                             )
+                            if related_block:
+                                finding.description += related_block
                             if scan_date:
                                 finding.date = scan_date
                             self.add_finding(finding, dupes)