Consider OS distro during vulnerability matching

[nscuro]

Description

Considers OS distro during vulnerability matching.

• Where possible, enriches an affected package's PURL with distro qualifier inferred from the package's ecosystem. e.g. ecosystem=Debian:11 becomes distro=debian-11, ecosystem=Ubuntu:20.04:LTS becomes distro=ubuntu-20.04 etc.
• During vulnerability analysis, if both component and matching criteria have a PURL distro qualifier, ensures they match. Matching can handle codename <-> version comparisons, e.g. for Ubuntu focal would match 20.04 and vice versa.
• Generally improves performance of OSV mirroring by using fewer transactions and disabling ORM features that caused expensive unnecessary queries.

Currently Alpine, Debian, and Ubuntu distribution matching is implemented. These seem to work for SBOMs generated with Trivy and Syft.

The codename <-> version mapping is currently hardcoded for Debian and Ubuntu. There is a fallback mechanism that will handle exact matches, such that when Debian publishes a hypothetical "foo" release, we can still match components with vulnerabilities if both distro qualifiers are exactly "foo".

Debian and Ubuntu provide CSV which we could regularly fetch at runtime, but this involves more work to coordinate.

Addressed Issue

Fixes #1374
Fixes #5776
Fixes #4445
Fixes #4725

Additional Details

A container image for this PR is available at dependencytrack/bundled:feature-distro-matching.

OSV is enabled by default and configured to mirror the Alpine, Debian, and Ubuntu ecosystems.

Checklist

• I have read and understand the contributing guidelines
• This PR fixes a defect, and I have provided tests to verify that the fix is effective
• This PR implements an enhancement, and I have provided tests to verify that it works as intended
• This PR introduces changes to the database model, and I have added corresponding update logic
• This PR introduces new or alters existing behavior, and I have updated the documentation accordingly

[owasp-dt-bot]

✅ Snyk checks have passed. No issues have been found so far.

Status	Scanner	Critical	High	Medium	Low	Total (0)
✅	Open Source Security	0	0	0	0	0 issues

💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse.

[codacy-production]

Coverage summary from Codacy

See diff coverage on Codacy

Coverage variation	Diff coverage
✅ -0.05% (target: -1.00%)	✅ 87.86% (target: 70.00%)

Coverage variation details

	Coverable lines	Covered lines	Coverage
Common ancestor commit (985fbb0)	24556	19987	81.39%
Head commit (15df5bf)	49364 (+24808)	40152 (+20165)	81.34% (-0.05%)

Coverage variation is the difference between the coverage for the head and common ancestor commits of the pull request branch: <coverage of head commit> - <coverage of common ancestor commit>

Diff coverage details

	Coverable lines	Covered lines	Diff coverage
Pull request (#5783)	280	246	87.86%

Diff coverage is the percentage of lines that are covered by tests out of the coverable lines that the pull request added or modified: <covered lines added or modified>/<coverable lines added or modified> * 100%

See your quality gate settings    Change summary preferences

[nscuro]

Testing with cdxgen, scalibr, Syft, and Trivy.

• I can't get cdxgen to generate container image SBOMs that contain OS packages.
• SBOMs with scalibr and Trivy appear to be effectively free from false positives.
• SBOMs generated by Syft still lead to false positives due to them including CPEs, which then get matched against the NVD which does not provide distro qualifiers.

[Copilot]

Pull request overview

This PR improves OSV-based vulnerability matching for OS packages by incorporating the OS distribution (“distro”) into PURL-based matching, and optimizes OSV mirroring/persistence behavior to reduce database overhead.

Changes:

• Add distro-aware PURL matching (including codename ↔ version matching for Debian/Ubuntu, and major.minor handling for Alpine).
• Enrich OSV-affected package PURLs with inferred distro qualifiers derived from OSV ecosystem metadata where missing.
• Refactor version-range comparison to use versatile schemes and adjust OSV mirroring to reduce transaction/ORM overhead; add extensive test coverage.

Reviewed changes

Copilot reviewed 14 out of 14 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
src/main/java/org/dependencytrack/model/ConfigPropertyConstants.java	Changes defaults for vulnerability-source toggles (needs reverting before merge).
src/main/java/org/dependencytrack/model/OsDistribution.java	New distro parsing/matching model for Alpine/Debian/Ubuntu.
src/main/java/org/dependencytrack/tasks/OsvDownloadTask.java	Infers/adds distro qualifiers, refactors mirroring transaction/indexing behavior.
src/main/java/org/dependencytrack/tasks/scanners/AbstractVulnerableSoftwareAnalysisTask.java	Adds distro qualifier gate for PURL matching; refactors version-range checks.
src/main/java/org/dependencytrack/persistence/VulnerableSoftwareQueryManager.java	Extends PURL lookup to include qualifiers in identity matching.
src/main/java/org/dependencytrack/persistence/QueryManager.java	Adds overload to query vulnerable software by PURL including qualifiers.
src/main/java/org/dependencytrack/util/PurlUtil.java	Adds qualifier serialization + distro qualifier extraction helpers.
src/main/java/org/dependencytrack/model/VulnerableSoftware.java	Removes cached Vers building; introduces hasVersionRange() helper.
src/main/java/org/dependencytrack/parser/nvd/ModelConverter.java	Removes PURL→VulnerableSoftware conversion helper (tests now use dedicated util).
src/test/java/org/dependencytrack/model/OsDistributionTest.java	New unit tests for distro parsing and matching behavior.
src/test/java/org/dependencytrack/tasks/scanners/InternalAnalysisTaskDistroMatchingTest.java	New integration tests for distro-aware internal analysis matching.
src/test/java/org/dependencytrack/tasks/scanners/InternalAnalysisTaskPurlMatchingTest.java	Updates PURL matching tests to use new test utility.
src/test/java/org/dependencytrack/tasks/scanners/VulnerableSoftwareTestUtil.java	New test utility for constructing VulnerableSoftware from PURLs.
src/test/java/org/dependencytrack/tasks/OsvDownloadTaskTest.java	Adjusts test setup for vulnerable software PURLs.
dev/docker-compose.postgres.yml	Adds pg_stat_statements + PgHero for local performance analysis.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 14 out of 14 changed files in this pull request and generated 3 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 14 out of 14 changed files in this pull request and generated 6 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 15 out of 15 changed files in this pull request and generated 5 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.