Add EPSS score support for GitHub Advisory (GHSA) vulnerabilities

valentijnscholten · valentijnscholten · commit 51efce88464b · 2026-02-19T19:22:36.000+01:00
Resolves #4330 - Map `percentage` (exploitation probability) and `percentile` (relative rank) from the GitHub EPSS API response to the `epssScore` and `epssPercentile` fields on GHSA Vulnerability records. - Extend `VulnerabilityQueryManager.hasChanges()` to also trigger an update when an advisory has EPSS data but the stored record does not, enabling backfill without relying on a changed `updatedAt` timestamp. - Add upgrade item `v4140Updater` that resets the GHSA mirror timestamp on first boot, causing the next mirror run to re-fetch all advisories and populate EPSS fields on existing records. - Add `ModelConverterTest` (unit) and extend `GitHubAdvisoryMirrorTaskTest` (integration) with EPSS test cases using real values from the GitHub API. - Add AGENTS.md with guidance on running tests via `tee`.
diff --git a/AGENTS.md b/AGENTS.md
@@ -0,0 +1,15 @@
+# Agent Guidance
+
+## Running Tests
+
+Always tee test output to a file rather than piping directly into `tail`. This keeps the full output accessible for inspection without truncation.
+
+```bash
+# ✅ GOOD — full output preserved, can be grepped/tailed afterwards
+mvn test -Dtest="MyTest" 2>&1 | tee /tmp/test-output.txt
+grep -E "Tests run|FAIL|ERROR" /tmp/test-output.txt
+tail -50 /tmp/test-output.txt
+
+# ❌ BAD — output is lost if the tail window is too small
+mvn test -Dtest="MyTest" 2>&1 | tail -60
+```
diff --git a/docs/_posts/2026-02-19-v4.14.0.md b/docs/_posts/2026-02-19-v4.14.0.md
@@ -0,0 +1,45 @@
+---
+title: v4.14.0
+type: feature
+---
+
+**Features:**
+
+* Add EPSS score support for GitHub Advisory (GHSA) vulnerabilities - [apiserver/#4330]
+
+**Fixes:**
+
+For a complete list of changes, refer to the respective GitHub milestones:
+
+* [API server milestone 4.14.0](https://github.com/DependencyTrack/dependency-track/milestone/?closed=1)
+* [Frontend milestone 4.14.0](https://github.com/DependencyTrack/frontend/milestone/?closed=1)
+
+We thank all organizations and individuals who contributed to this release, from logging issues to taking part in discussions on GitHub & Slack to testing of fixes.
+
+###### dependency-track-apiserver.jar
+
+| Algorithm | Checksum |
+|:----------|:---------|
+| SHA-1     |          |
+| SHA-256   |          |
+
+###### dependency-track-bundled.jar
+
+| Algorithm | Checksum |
+|:----------|:---------|
+| SHA-1     |          |
+| SHA-256   |          |
+
+###### frontend-dist.zip
+
+| Algorithm | Checksum                                                         |
+|:----------|:-----------------------------------------------------------------|
+| SHA-1     |                                                                  |
+| SHA-256   |                                                                  |
+
+###### Software Bill of Materials (SBOM)
+
+* API Server: [bom.json](https://github.com/DependencyTrack/dependency-track/releases/download/4.14.0/bom.json)
+* Frontend: [bom.json](https://github.com/DependencyTrack/frontend/releases/download/4.14.0/bom.json)
+
+[apiserver/#4330]: https://github.com/DependencyTrack/dependency-track/issues/4330
diff --git a/src/main/java/org/dependencytrack/parser/github/ModelConverter.java b/src/main/java/org/dependencytrack/parser/github/ModelConverter.java
@@ -24,6 +24,7 @@
 import com.github.packageurl.PackageURLBuilder;
 import io.github.jeremylong.openvulnerability.client.ghsa.CWE;
 import io.github.jeremylong.openvulnerability.client.ghsa.CWEs;
+import io.github.jeremylong.openvulnerability.client.ghsa.Epss;
 import io.github.jeremylong.openvulnerability.client.ghsa.Package;
 import io.github.jeremylong.openvulnerability.client.ghsa.Reference;
 import io.github.jeremylong.openvulnerability.client.ghsa.SecurityAdvisory;
@@ -37,6 +38,7 @@
 import org.dependencytrack.util.CvssUtil;
 import org.dependencytrack.util.VulnerabilityUtil;
 
+import java.math.BigDecimal;
 import java.time.ZonedDateTime;
 import java.util.ArrayList;
 import java.util.Arrays;
@@ -101,6 +103,25 @@ public Vulnerability convert(final SecurityAdvisory advisory) {
                     vuln.getOwaspRRBusinessImpactScore()));
         }
 
+        if (advisory.getEpss() != null) {
+            final Epss epss = advisory.getEpss();
+            // GitHub's GraphQL API (https://docs.github.com/en/graphql/reference/objects#securityadvisoryepss):
+            //   "percentage" = exploitation probability (EPSS score, 0.0-1.0)
+            //   "percentile" = relative rank compared to other CVEs (0.0-1.0)
+            //
+            // NOTE: the open-vulnerability-clients library Javadoc has these two fields documented
+            // with swapped semantics — trust the live API values, not the Javadoc.
+            // Verified against real API responses, e.g. GHSA-57j2-w4cx-62h2 (CVE-2020-36518):
+            //   percentage=0.00514 (0.514% exploitation probability)
+            //   percentile=0.66009 (ranked above 66% of all CVEs)
+            if (epss.getPercentage() != null) {
+                vuln.setEpssScore(new BigDecimal(epss.getPercentage().toString()));
+            }
+            if (epss.getPercentile() != null) {
+                vuln.setEpssPercentile(new BigDecimal(epss.getPercentile().toString()));
+            }
+        }
+
         if (advisory.getIdentifiers() != null && !advisory.getIdentifiers().isEmpty()) {
             vuln.setAliases(advisory.getIdentifiers().stream()
                     .filter(identifier -> "cve".equalsIgnoreCase(identifier.getType()))
diff --git a/src/main/java/org/dependencytrack/persistence/VulnerabilityQueryManager.java b/src/main/java/org/dependencytrack/persistence/VulnerabilityQueryManager.java
@@ -85,8 +85,16 @@ public Vulnerability createVulnerability(Vulnerability vulnerability, boolean co
         return result;
     }
 
-    private boolean hasChanges(Vulnerability vulnerability, Vulnerability transientVulnerability) {
-        return vulnerability.getUpdated() == null || transientVulnerability.getUpdated() == null || !vulnerability.getUpdated().equals(transientVulnerability.getUpdated());
+    private boolean hasChanges(Vulnerability existing, Vulnerability incoming) {
+        if (existing.getUpdated() == null || incoming.getUpdated() == null
+                || !existing.getUpdated().equals(incoming.getUpdated())) {
+            return true;
+        }
+        // Also trigger an update when EPSS data is newly available for a vulnerability
+        // that was previously mirrored without it (e.g. GHSA entries backfilled after
+        // EPSS support was added). This condition is self-limiting: once epssScore is
+        // populated it will not match again, so normal updatedAt-based detection resumes.
+        return existing.getEpssScore() == null && incoming.getEpssScore() != null;
     }
 
     private Vulnerability getExistingVulnerability(Vulnerability transientVulnerability){
@@ -140,6 +148,8 @@ public Vulnerability updateVulnerability(Vulnerability transientVulnerability, b
                 differ.applyIfChanged("owaspRRVector", Vulnerability::getOwaspRRVector, existingVulnerability::setOwaspRRVector);
                 differ.applyIfChanged("cwes", Vulnerability::getCwes, existingVulnerability::setCwes);
                 differ.applyIfNonNullAndChanged("vulnerableSoftware", Vulnerability::getVulnerableSoftware, existingVulnerability::setVulnerableSoftware);
+                differ.applyIfNonNullAndChanged("epssScore", Vulnerability::getEpssScore, existingVulnerability::setEpssScore);
+                differ.applyIfNonNullAndChanged("epssPercentile", Vulnerability::getEpssPercentile, existingVulnerability::setEpssPercentile);
             }
             else {
                 // Handle cases where no existing vulnerability is found if needed (e.g., log an error)
diff --git a/src/main/java/org/dependencytrack/upgrade/UpgradeItems.java b/src/main/java/org/dependencytrack/upgrade/UpgradeItems.java
@@ -46,6 +46,7 @@ class UpgradeItems {
         UPGRADE_ITEMS.add(org.dependencytrack.upgrade.v4130.v4130_1Updater.class);
         UPGRADE_ITEMS.add(org.dependencytrack.upgrade.v4131.v4131Updater.class);
         UPGRADE_ITEMS.add(org.dependencytrack.upgrade.v4135.v4135Updater.class);
+        UPGRADE_ITEMS.add(org.dependencytrack.upgrade.v4140.v4140Updater.class);
     }
 
     static List<Class<? extends UpgradeItem>> getUpgradeItems() {
diff --git a/src/main/java/org/dependencytrack/upgrade/v4140/v4140Updater.java b/src/main/java/org/dependencytrack/upgrade/v4140/v4140Updater.java
@@ -0,0 +1,62 @@
+/*
+ * This file is part of Dependency-Track.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ * Copyright (c) OWASP Foundation. All Rights Reserved.
+ */
+package org.dependencytrack.upgrade.v4140;
+
+import alpine.common.logging.Logger;
+import alpine.persistence.AlpineQueryManager;
+import alpine.server.upgrade.AbstractUpgradeItem;
+
+import java.sql.Connection;
+import java.sql.PreparedStatement;
+import java.sql.SQLException;
+
+public class v4140Updater extends AbstractUpgradeItem {
+
+    private static final Logger LOGGER = Logger.getLogger(v4140Updater.class);
+
+    @Override
+    public String getSchemaVersion() {
+        return "4.14.0";
+    }
+
+    @Override
+    public void executeUpgrade(final AlpineQueryManager qm, final Connection connection) throws Exception {
+        resetGhsaLastModifiedTimestamp(connection);
+    }
+
+    /**
+     * Resets the GitHub Advisories last-modified epoch timestamp to force a full re-mirror on next run.
+     * <p>
+     * This is necessary to backfill EPSS scores on existing GHSA vulnerability entries. The normal
+     * mirror update path is skipped when an advisory's {@code updatedAt} has not changed, but EPSS
+     * data is now available for advisories that were previously mirrored without it.
+     */
+    private void resetGhsaLastModifiedTimestamp(final Connection connection) throws SQLException {
+        LOGGER.info("Resetting GitHub Advisories last-modified timestamp to trigger full re-mirror for EPSS backfill");
+        try (final PreparedStatement ps = connection.prepareStatement("""
+                UPDATE "CONFIGPROPERTY"
+                   SET "PROPERTYVALUE" = NULL
+                 WHERE "GROUPNAME" = 'vuln-source'
+                   AND "PROPERTYNAME" = 'github.advisories.last.modified.epoch.seconds'
+                """)) {
+            final int rows = ps.executeUpdate();
+            LOGGER.info("Reset last-modified timestamp (%d row(s) affected)".formatted(rows));
+        }
+    }
+}
diff --git a/src/test/java/org/dependencytrack/parser/github/ModelConverterTest.java b/src/test/java/org/dependencytrack/parser/github/ModelConverterTest.java
@@ -0,0 +1,163 @@
+/*
+ * This file is part of Dependency-Track.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ * Copyright (c) OWASP Foundation. All Rights Reserved.
+ */
+package org.dependencytrack.parser.github;
+
+import alpine.common.logging.Logger;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.databind.json.JsonMapper;
+import com.fasterxml.jackson.datatype.jsr310.JavaTimeModule;
+import io.github.jeremylong.openvulnerability.client.ghsa.SecurityAdvisory;
+import org.dependencytrack.model.Severity;
+import org.dependencytrack.model.Vulnerability;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.data.Offset.offset;
+
+class ModelConverterTest {
+
+    private final ObjectMapper jsonMapper = new JsonMapper()
+            .registerModule(new JavaTimeModule());
+
+    private ModelConverter converter;
+
+    @BeforeEach
+    void setUp() {
+        converter = new ModelConverter(Logger.getLogger(ModelConverterTest.class));
+    }
+
+    @Test
+    void testConvertEpssScore() throws Exception {
+        // Real values from the GitHub GraphQL API for GHSA-57j2-w4cx-62h2 (CVE-2020-36518):
+        //   "percentage": 0.00514  →  exploitation probability (EPSS score, 0.0-1.0)
+        //   "percentile": 0.66009  →  relative rank (0.0-1.0, i.e. above 66% of all CVEs)
+        //
+        // A 0.514% exploitation probability at the 66th percentile is realistic because EPSS
+        // scores are heavily skewed toward zero; even a small absolute probability can rank high.
+        // If the two fields were accidentally swapped the assertions below would fail with values
+        // that are semantically impossible (e.g. 66% exploitation probability).
+        final var advisory = jsonMapper.readValue(/* language=JSON */ """
+                {
+                  "ghsaId": "GHSA-57j2-w4cx-62h2",
+                  "severity": "HIGH",
+                  "publishedAt": "2022-03-12T00:00:36Z",
+                  "updatedAt": "2024-03-15T00:24:56Z",
+                  "epss": {
+                    "percentage": 0.00514,
+                    "percentile": 0.66009
+                  }
+                }
+                """, SecurityAdvisory.class);
+
+        final Vulnerability vuln = converter.convert(advisory);
+
+        assertThat(vuln).isNotNull();
+        assertThat(vuln.getEpssScore())
+                .as("epssScore must hold the exploitation probability from the 'percentage' JSON field")
+                .isNotNull();
+        assertThat(vuln.getEpssScore().doubleValue()).isCloseTo(0.00514, offset(0.00001));
+        assertThat(vuln.getEpssPercentile())
+                .as("epssPercentile must hold the relative rank from the 'percentile' JSON field")
+                .isNotNull();
+        assertThat(vuln.getEpssPercentile().doubleValue()).isCloseTo(0.66009, offset(0.00001));
+    }
+
+    @Test
+    void testConvertEpssAbsent() throws Exception {
+        final var advisory = jsonMapper.readValue(/* language=JSON */ """
+                {
+                  "ghsaId": "GHSA-57j2-w4cx-62h2",
+                  "severity": "HIGH",
+                  "publishedAt": "2022-03-12T00:00:36Z",
+                  "updatedAt": "2024-03-15T00:24:56Z"
+                }
+                """, SecurityAdvisory.class);
+
+        final Vulnerability vuln = converter.convert(advisory);
+
+        assertThat(vuln).isNotNull();
+        assertThat(vuln.getEpssScore()).isNull();
+        assertThat(vuln.getEpssPercentile()).isNull();
+    }
+
+    @Test
+    void testConvertEpssPartialDataPercentileOnly() throws Exception {
+        // Only the rank/percentile field is present — epssScore must remain null.
+        final var advisory = jsonMapper.readValue(/* language=JSON */ """
+                {
+                  "ghsaId": "GHSA-57j2-w4cx-62h2",
+                  "severity": "HIGH",
+                  "publishedAt": "2022-03-12T00:00:36Z",
+                  "updatedAt": "2024-03-15T00:24:56Z",
+                  "epss": {
+                    "percentile": 0.66009
+                  }
+                }
+                """, SecurityAdvisory.class);
+
+        final Vulnerability vuln = converter.convert(advisory);
+
+        assertThat(vuln).isNotNull();
+        assertThat(vuln.getEpssScore()).isNull();
+        assertThat(vuln.getEpssPercentile()).isNotNull();
+        assertThat(vuln.getEpssPercentile().doubleValue()).isCloseTo(0.66009, offset(0.00001));
+    }
+
+    @Test
+    void testConvertWithdrawnAdvisoryReturnsNull() throws Exception {
+        final var advisory = jsonMapper.readValue(/* language=JSON */ """
+                {
+                  "ghsaId": "GHSA-57j2-w4cx-62h2",
+                  "severity": "HIGH",
+                  "publishedAt": "2022-03-12T00:00:00Z",
+                  "updatedAt": "2022-08-11T00:00:00Z",
+                  "withdrawnAt": "2023-01-01T00:00:00Z"
+                }
+                """, SecurityAdvisory.class);
+
+        assertThat(converter.convert(advisory)).isNull();
+    }
+
+    @Test
+    void testConvertSeverityMapping() throws Exception {
+        for (final var entry : new Object[][]{
+                {"LOW", Severity.LOW},
+                {"MODERATE", Severity.MEDIUM},
+                {"HIGH", Severity.HIGH},
+                {"CRITICAL", Severity.CRITICAL},
+        }) {
+            final String ghsaSeverity = (String) entry[0];
+            final Severity expected = (Severity) entry[1];
+
+            final var advisory = jsonMapper.readValue(/* language=JSON */ """
+                    {
+                      "ghsaId": "GHSA-57j2-w4cx-62h2",
+                      "severity": "%s",
+                      "publishedAt": "2022-03-12T00:00:00Z",
+                      "updatedAt": "2022-08-11T00:00:00Z"
+                    }
+                    """.formatted(ghsaSeverity), SecurityAdvisory.class);
+
+            assertThat(converter.convert(advisory).getSeverity())
+                    .as("severity for GHSA %s", ghsaSeverity)
+                    .isEqualTo(expected);
+        }
+    }
+}
diff --git a/src/test/java/org/dependencytrack/tasks/GitHubAdvisoryMirrorTaskTest.java b/src/test/java/org/dependencytrack/tasks/GitHubAdvisoryMirrorTaskTest.java

Original file line number	Diff line number	Diff line change
`@@ -46,6 +46,7 @@ class UpgradeItems {`
`46`	`46`	`UPGRADE_ITEMS.add(org.dependencytrack.upgrade.v4130.v4130_1Updater.class);`
`47`	`47`	`UPGRADE_ITEMS.add(org.dependencytrack.upgrade.v4131.v4131Updater.class);`
`48`	`48`	`UPGRADE_ITEMS.add(org.dependencytrack.upgrade.v4135.v4135Updater.class);`
	`49`	`+ UPGRADE_ITEMS.add(org.dependencytrack.upgrade.v4140.v4140Updater.class);`
`49`	`50`	`}`
`50`	`51`
`51`	`52`	`static List<Class<? extends UpgradeItem>> getUpgradeItems() {`