Add rating source tracking for context-aware OWASP scores by fahedouch · Pull Request #1928 · DependencyTrack/hyades-apiserver

fahedouch · 2026-03-24T17:34:48Z

Description

fix DependencyTrack/dependency-track#5796

This PR enables context-aware OWASP Risk Rating scores at the component level, so the same CVE can have different scores depending on the deployment context.

What changed

Added a precedence system to track where analysis ownership comes from:

POLICY (highest) - organizational standards
VEX - authoritative context-aware assessments
MANUAL - analyst notes
NVD (lowest) - default database scores

Higher precedence sources can overwrite lower ones, but not vice versa. This prevents VEX imports from accidentally overwriting your policy ratings or analyst assessments.

OWASP ratings store vector + score, no separate severity column — consistent with how CVSS is handled on Analysis.

Use case

Import contextual OWASP scores from VEX documents (e.g., generated by VENS) that reflect your actual deployment - internet-facing vs internal, production vs dev, sensitive data handling, etc.

Addressed Issue

fixes DependencyTrack/dependency-track#5796

Checklist

I have read and understand the contributing guidelines
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 updated the migration changelog accordingly
This PR introduces new or alters existing behavior, and I have updated the documentation accordingly

Copilot

Pull request overview

This PR introduces tracking of the source of component-level OWASP Risk Rating overrides so that context-aware scores (e.g., from VEX) can be applied with a defined precedence model, aiming to prevent lower-precedence sources from overwriting higher-precedence ratings.

Changes:

Adds a new OWASPSOURCE column to ANALYSIS plus an index, and wires it into the Analysis model.
Introduces a RatingSource enum with precedence + overwrite logic, and adds unit tests for it.
Extends analysis update flows to carry OWASP vector/score/source via MakeAnalysisCommand, and imports OWASP ratings from CycloneDX VEX as RatingSource.VEX.

Reviewed changes

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

Show a summary per file

File	Description
migration/src/main/resources/migration/changelog-v5.8.0.xml	Adds `OWASPSOURCE` column and index in Liquibase.
migration/src/main/resources/migration/changelog-main.xml	Includes the v5.8.0 changelog in the master migration chain.
apiserver/src/test/java/org/dependencytrack/model/RatingSourceTest.java	Adds tests validating precedence and overwrite behavior.
apiserver/src/main/java/org/dependencytrack/persistence/command/MakeAnalysisCommand.java	Adds OWASP vector/score/source fields and a convenience `withOwasp(...)` method.
apiserver/src/main/java/org/dependencytrack/persistence/AnalysisQueryManager.java	Applies precedence when updating OWASP vector/score and persists `owaspSource`.
apiserver/src/main/java/org/dependencytrack/parser/cyclonedx/CycloneDXVexImporter.java	Imports OWASP ratings from CycloneDX VEX and sets source to `VEX`, with basic validation.
apiserver/src/main/java/org/dependencytrack/model/RatingSource.java	Defines precedence order and overwrite logic.
apiserver/src/main/java/org/dependencytrack/model/Analysis.java	Adds the persisted `owaspSource` field mapped to `OWASPSOURCE`.
RATING_SOURCE_TRACKING.md	Documents the precedence model and examples.

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

Copilot · 2026-03-24T17:40:26Z


 import javax.jdo.PersistenceManager;
 import javax.jdo.Query;
+import java.math.BigDecimal;


java.math.BigDecimal is imported but never used in this class. This will fail compilation due to an unused import; please remove it (or use it if intended).

Suggested change

import java.math.BigDecimal;

Copilot · 2026-03-24T17:40:27Z

+     *   <li>MANUAL - User-provided ratings</li>
+     *   <li>VEX - Ratings from VEX documents</li>
+     *   <li>POLICY - Ratings from organizational policies</li>


The precedence order documented here (MANUAL > VEX > POLICY > NVD) contradicts the precedence defined in RatingSource (POLICY > VEX > MANUAL > NVD) and the PR description. Please correct the Javadoc to reflect the actual precedence to avoid future logic being implemented based on the wrong ordering.

Suggested change

* <li>MANUAL - User-provided ratings</li>

* <li>VEX - Ratings from VEX documents</li>

* <li>POLICY - Ratings from organizational policies</li>

* <li>POLICY - Ratings from organizational policies</li>

* <li>VEX - Ratings from VEX documents</li>

* <li>MANUAL - User-provided ratings</li>

Copilot · 2026-03-24T17:40:27Z

+                        command = command.withOwasp(
+                                rating.getVector(),
+                                rating.getScore(),
+                                RatingSource.VEX);
+                        break; // Only use the first OWASP rating


For OWASP ratings, this logic allows a rating with severity != null but vector == null (and potentially score == null) to be treated as valid, then it calls withOwasp(null, null, VEX) and immediately breaks. That means a later OWASP rating with a usable vector+score in the same VEX document would be ignored, and no OWASP data will be applied. Consider requiring vector+score for OWASP imports (since those are the only fields persisted), or only break once at least one of vector/score is actually applied.

Suggested change

command = command.withOwasp(

rating.getVector(),

rating.getScore(),

RatingSource.VEX);

break; // Only use the first OWASP rating

if (rating.getVector() == null || rating.getScore() == null) {

LOGGER.warn("VEX OWASP rating is missing vector and/or score - skipping");

continue;

}

command = command.withOwasp(

rating.getVector(),

rating.getScore(),

RatingSource.VEX);

break; // Only use the first OWASP rating with usable vector and score

Copilot · 2026-03-24T17:40:28Z

+    @Persistent(defaultFetchGroup = "true")
+    @Column(name = "OWASPSOURCE", jdbcType = "VARCHAR")
+    @JsonProperty(value = "owaspSource")
+    private RatingSource owaspSource;


Adding owaspSource to the JDO model is not sufficient to enforce precedence if OWASP scores/vectors are also written via the JDBI-based policy/analysis upserts: those SQL paths currently don't read/write OWASPSOURCE, so the column will remain NULL or stale while OWASPVECTOR/OWASPSCORE change. This breaks the intended precedence rules (e.g., policy updates won't mark the source as POLICY, and VEX may overwrite rows with NULL source). Please update the relevant JDBI mappers/queries/upserts to include OWASPSOURCE wherever OWASP ratings are set.

Copilot · 2026-03-24T17:40:28Z

+        <addColumn tableName="ANALYSIS">
+            <column name="OWASPSOURCE" type="VARCHAR(50)">
+                <constraints nullable="true"/>
+            </column>
+        </addColumn>


The new OWASPSOURCE column is nullable and there's no data migration/backfill. As a result, any existing analyses that already have OWASPVECTOR/OWASPSCORE populated will have a NULL source and will be treated as overwritable by any new source (since canOverwrite(null) returns true). If the goal is to prevent VEX imports from overwriting existing policy/manual ratings, consider backfilling OWASPSOURCE for existing rows (or introducing an explicit default/UNKNOWN source with appropriate precedence).

Copilot · 2026-03-24T17:40:28Z

+
+import org.junit.jupiter.api.Test;
+
+import static org.junit.jupiter.api.Assertions.*;


Static wildcard import is disallowed by this repo's Checkstyle rules (AvoidStarImport in support/checkstyle/config.xml). Please replace import static org.junit.jupiter.api.Assertions.*; with explicit static imports for the assertions used in this test.

Suggested change

import static org.junit.jupiter.api.Assertions.*;

import static org.junit.jupiter.api.Assertions.assertFalse;

import static org.junit.jupiter.api.Assertions.assertTrue;

fahedouch · 2026-03-30T23:06:10Z

Frontend PR

codacy-production · 2026-04-08T15:14:51Z

Up to standards ✅

🟢 Issues 10 minor

Results:
10 new issues

Category Results

CodeStyle 10 minor

View in Codacy

🟢 Metrics 35 complexity

Metric Results

Complexity 35

View in Codacy

_{NEW Get contextual insights on your PRs based on Codacy's metrics, along with PR and Jira context, without leaving GitHub. Enable AI reviewer}
_{TIP This summary will be updated as you push new changes.}

nscuro · 2026-04-13T12:49:20Z

+    @Persistent(defaultFetchGroup = "true")
+    @Column(name = "OWASPSEVERITY")
+    @Extensions(value = {
+            @Extension(vendorName = "datanucleus", key = "insert-function", value = "CAST(? AS severity)"),
+            @Extension(vendorName = "datanucleus", key = "update-function", value = "CAST(? AS severity)")
+    })
+    @JsonProperty(value = "owaspSeverity")
+    private Severity owaspSeverity;


What is the use case for tracking the severity for OWASP ratings separately? Adding more severity fields adds complexity to all queries that operate on severities, including metrics calculation.

Analogue to a previous comment, if we do this for OWASP ratings, why not also for CVSS?

Makes sense, dropped owaspSeverity — no separate severity column for CVSS either, no reason to add one for OWASP.

fahedouch · 2026-04-17T14:30:08Z

@nscuro thank you for the review. I’ve addressed your latest comments.

Two questions before I go further:

1. OWASP rating validation in VEX imports
Right now the importer skips OWASP ratings if vector or score is missing. CVSS fields elsewhere in the codebase are independent though (you can have a score without a vector, or vice versa). Should I relax this to match, or keep both required for OWASP?

2. Scope of the precedence guard
The source-based precedence currently only protects OWASP vector/score — state, justification, response, suppression are still updatable regardless of source. I kept it scoped to ratings intentionally. Worth extending to the full analysis, or fine as-is for now?

nscuro · 2026-04-23T14:27:47Z

@fahedouch

OWASP rating validation in VEX imports
Right now the importer skips OWASP ratings if vector or score is missing. CVSS fields elsewhere in the codebase are independent though (you can have a score without a vector, or vice versa). Should I relax this to match, or keep both required for OWASP?

I'd say relax it. If we enforce invariants it should be consistent.

Scope of the precedence guard
The source-based precedence currently only protects OWASP vector/score — state, justification, response, suppression are still updatable regardless of source. I kept it scoped to ratings intentionally. Worth extending to the full analysis, or fine as-is for now?

It should be scoped to the entire analysis, otherwise ownership becomes messy or even impossible to track.

fahedouch · 2026-04-24T13:13:16Z

Thanks @nscuro, both addressed:

Relaxed VEX OWASP validation — vector or score alone is now accepted, consistent with CVSS handling.
Extended precedence guard to the full analysis (state, justification, response, details, suppression) — not just OWASP fields anymore.

fahedouch · 2026-05-20T15:14:28Z

@nscuro squashed into one commit, should be easier to review now.

Quick reading order if you're short on time:

RatingSource.java (46 lines) — the enum with precedence
AnalysisQueryManager — the canUpdate guard, wraps all field updates now
Analysis.java — just a SOURCE column + getter/setter
CycloneDXVexImporter — handles OWASP ratings from VEX, sets source = VEX
AnalysisResource — REST path sets source = MANUAL

JDBI is wired too — AnalysisDao writes SOURCE = POLICY on upsert, VulnerabilityPolicyDao clears it on unassign, AnalysisRowMapper reads it.

Migration is one Flyway file: column + index + backfill.

Your previous feedback is all in — per-analysis ownership, no owaspSeverity, precedence on full analysis, relaxed VEX validation.

Signed-off-by: Fahed Dorgaa <fahed.dorgaa@gmail.com>

nscuro · 2026-05-29T16:02:24Z

Hi @fahedouch, in preparation of the v5 GA release we have migrated the code to the canonical dependency-track repository. Please kindly re-target your PR as per https://github.com/DependencyTrack/dependency-track/blob/main/V5_MIGRATION.md#contributors-and-pr-authors.

fahedouch · 2026-05-29T17:24:38Z

Thanks @nscuro. Re-opened it on dependency-track: DependencyTrack/dependency-track

Just to make sure I understand: hyades-apiserver will be archived and everything v5 lives under dependency-track from now on, so "hyades" as a name is basically going away?

Copilot AI review requested due to automatic review settings March 24, 2026 17:34

Copilot started reviewing on behalf of fahedouch March 24, 2026 17:35 View session

fahedouch force-pushed the feature/rating-source-tracking branch from faf1f2a to 1b90695 Compare March 24, 2026 17:36

Copilot AI reviewed Mar 24, 2026

View reviewed changes

nscuro reviewed Mar 27, 2026

View reviewed changes

Comment thread apiserver/src/main/java/org/dependencytrack/model/Analysis.java Outdated

fahedouch mentioned this pull request Mar 27, 2026

feat: add UNKNOWN enum value to Vulnerability sources #1948

Closed

5 tasks

fahedouch commented Mar 30, 2026

View reviewed changes

Comment thread apiserver/src/main/java/org/dependencytrack/model/Vulnerability.java

fahedouch force-pushed the feature/rating-source-tracking branch from aabffe2 to e62e0c7 Compare March 30, 2026 23:00

fahedouch mentioned this pull request Mar 30, 2026

feat: add OWASP analysis fields to FindingAudit component DependencyTrack/hyades-frontend#465

Open

2 tasks

fahedouch requested a review from nscuro March 31, 2026 09:24

fahedouch mentioned this pull request Apr 7, 2026

Vulnerability prioritization DependencyTrack/dependency-track#2671

Open

2 tasks

fahedouch force-pushed the feature/rating-source-tracking branch 3 times, most recently from e791dc0 to ad2c4a5 Compare April 8, 2026 15:12

nscuro reviewed Apr 13, 2026

View reviewed changes

fahedouch force-pushed the feature/rating-source-tracking branch 6 times, most recently from 425ff0a to 964150c Compare April 17, 2026 13:44

fahedouch requested a review from nscuro April 17, 2026 14:22

fahedouch force-pushed the feature/rating-source-tracking branch from ae67a02 to abb31ba Compare April 17, 2026 16:49

fahedouch force-pushed the feature/rating-source-tracking branch from f1a9da8 to 15bcba3 Compare April 24, 2026 14:04

fahedouch force-pushed the feature/rating-source-tracking branch from 15bcba3 to 1eb3c24 Compare May 12, 2026 10:29

fahedouch force-pushed the feature/rating-source-tracking branch from 1eb3c24 to 70e187d Compare May 20, 2026 15:14

feat: add rating source tracking for context-aware OWASP scores

67db5ce

Signed-off-by: Fahed Dorgaa <fahed.dorgaa@gmail.com>

fahedouch force-pushed the feature/rating-source-tracking branch from 70e187d to 67db5ce Compare May 20, 2026 15:26

fahedouch mentioned this pull request May 29, 2026

feat: add rating source tracking for context-aware OWASP scores DependencyTrack/dependency-track#6210

Open

6 tasks


		import org.junit.jupiter.api.Test;

		import static org.junit.jupiter.api.Assertions.*;

Uh oh!

Conversation

fahedouch commented Mar 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

What changed

Use case

Addressed Issue

Checklist

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Mar 24, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 24, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 24, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 24, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 24, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 24, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

fahedouch commented Mar 30, 2026

Uh oh!

codacy-production Bot commented Apr 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Up to standards ✅

Uh oh!

nscuro Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

fahedouch Apr 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

fahedouch commented Apr 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

nscuro commented Apr 23, 2026

Uh oh!

fahedouch commented Apr 24, 2026

Uh oh!

fahedouch commented May 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

nscuro commented May 29, 2026

Uh oh!

fahedouch commented May 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

fahedouch commented Mar 24, 2026 •

edited

Loading

codacy-production Bot commented Apr 8, 2026 •

edited

Loading

fahedouch Apr 17, 2026 •

edited

Loading

fahedouch commented Apr 17, 2026 •

edited

Loading

fahedouch commented May 20, 2026 •

edited

Loading

fahedouch commented May 29, 2026 •

edited

Loading