From b041befae616717fa7ff994bc0e4685278c642ea Mon Sep 17 00:00:00 2001 From: Sonu Kapoor Date: Tue, 1 Sep 2026 17:02:52 -0400 Subject: [PATCH 1/6] feat: add EPSS Priority Signal combining severity and exploitation likelihood Introduces a four-tier priority classification per finding by combining CVSS-derived severity with EPSS exploitation likelihood percentile. Tiers: fix_now (high impact + top-10% EPSS), fix_soon (high impact), monitor (lower severity + top-10% EPSS), low_priority (all else). Null when no EPSS data is available. Surfaces in terminal compact mode (Fix Now label), verbose table (EPSS Priority column), JSON (prioritySignal field), and HTML report (column, detail badge with raw percentile, and four-tier legend). Closes #1066 --- examples/priority-signal/package-lock.json | 154 +++++++++++++++++++++ src/output/formatters.ts | 3 + src/output/html-reporter.ts | 92 ++++++++++-- src/output/multi-folder-html-reporter.ts | 9 +- src/output/printers.ts | 33 ++++- src/utils/priority-signal.ts | 48 +++++++ 6 files changed, 321 insertions(+), 18 deletions(-) create mode 100644 examples/priority-signal/package-lock.json create mode 100644 src/utils/priority-signal.ts diff --git a/examples/priority-signal/package-lock.json b/examples/priority-signal/package-lock.json new file mode 100644 index 00000000..a4ca9c95 --- /dev/null +++ b/examples/priority-signal/package-lock.json @@ -0,0 +1,154 @@ +{ + "name": "cve-lite-example-priority-signal", + "version": "1.0.0", + "lockfileVersion": 3, + "requires": true, + "packages": { + "": { + "name": "cve-lite-example-priority-signal", + "version": "1.0.0", + "license": "MIT", + "dependencies": { + "handlebars": "4.0.11", + "lodash": "4.17.20", + "mkdirp": "0.5.5", + "vm2": "3.9.17" + } + }, + "node_modules/handlebars": { + "version": "4.0.11", + "resolved": "https://registry.npmjs.org/handlebars/-/handlebars-4.0.11.tgz", + "license": "MIT", + "dependencies": { + "async": "^1.4.0", + "optimist": "^0.6.1", + "source-map": "^0.4.4", + "uglify-js": "^2.6" + }, + "engines": { + "node": ">=0.4.7" + } + }, + "node_modules/async": { + "version": "1.5.2", + "resolved": "https://registry.npmjs.org/async/-/async-1.5.2.tgz", + "license": "MIT" + }, + "node_modules/optimist": { + "version": "0.6.1", + "resolved": "https://registry.npmjs.org/optimist/-/optimist-0.6.1.tgz", + "license": "MIT/X11", + "dependencies": { + "minimist": "~0.0.1", + "wordwrap": "~0.0.2" + } + }, + "node_modules/wordwrap": { + "version": "0.0.3", + "resolved": "https://registry.npmjs.org/wordwrap/-/wordwrap-0.0.3.tgz", + "license": "MIT" + }, + "node_modules/source-map": { + "version": "0.4.4", + "resolved": "https://registry.npmjs.org/source-map/-/source-map-0.4.4.tgz", + "license": "BSD-3-Clause", + "dependencies": { + "amdefine": ">=0.0.4" + } + }, + "node_modules/amdefine": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/amdefine/-/amdefine-1.0.1.tgz", + "license": "BSD-3-Clause OR MIT" + }, + "node_modules/uglify-js": { + "version": "2.8.29", + "resolved": "https://registry.npmjs.org/uglify-js/-/uglify-js-2.8.29.tgz", + "license": "BSD-2-Clause", + "dependencies": { + "source-map": "~0.5.1", + "uglify-to-regexp": "~0.0.1", + "yargs": "~3.10.0" + } + }, + "node_modules/uglify-to-regexp": { + "version": "0.0.1", + "resolved": "https://registry.npmjs.org/uglify-to-regexp/-/uglify-to-regexp-0.0.1.tgz", + "license": "MIT" + }, + "node_modules/yargs": { + "version": "3.10.0", + "resolved": "https://registry.npmjs.org/yargs/-/yargs-3.10.0.tgz", + "license": "MIT", + "dependencies": { + "camelcase": "^1.0.1", + "cliui": "^2.1.0", + "decamelize": "^1.0.0", + "window-size": "0.1.0" + } + }, + "node_modules/camelcase": { + "version": "1.2.1", + "resolved": "https://registry.npmjs.org/camelcase/-/camelcase-1.2.1.tgz", + "license": "MIT" + }, + "node_modules/cliui": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/cliui/-/cliui-2.1.0.tgz", + "license": "ISC" + }, + "node_modules/decamelize": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/decamelize/-/decamelize-1.2.0.tgz", + "license": "MIT" + }, + "node_modules/window-size": { + "version": "0.1.0", + "resolved": "https://registry.npmjs.org/window-size/-/window-size-0.1.0.tgz", + "license": "MIT" + }, + "node_modules/lodash": { + "version": "4.17.20", + "resolved": "https://registry.npmjs.org/lodash/-/lodash-4.17.20.tgz", + "license": "MIT" + }, + "node_modules/mkdirp": { + "version": "0.5.5", + "resolved": "https://registry.npmjs.org/mkdirp/-/mkdirp-0.5.5.tgz", + "license": "MIT", + "dependencies": { + "minimist": "^1.2.5" + } + }, + "node_modules/minimist": { + "version": "1.2.5", + "resolved": "https://registry.npmjs.org/minimist/-/minimist-1.2.5.tgz", + "license": "MIT" + }, + "node_modules/vm2": { + "version": "3.9.17", + "resolved": "https://registry.npmjs.org/vm2/-/vm2-3.9.17.tgz", + "license": "MIT", + "dependencies": { + "acorn": "^8.7.0", + "acorn-walk": "^8.2.0" + }, + "engines": { + "node": ">=6.0" + } + }, + "node_modules/acorn": { + "version": "8.11.2", + "resolved": "https://registry.npmjs.org/acorn/-/acorn-8.11.2.tgz", + "license": "MIT" + }, + "node_modules/acorn-walk": { + "version": "8.3.1", + "resolved": "https://registry.npmjs.org/acorn-walk/-/acorn-walk-8.3.1.tgz", + "license": "MIT", + "dependencies": { + "acorn": "^8.11.0" + } + } + } +} diff --git a/src/output/formatters.ts b/src/output/formatters.ts index 17433d30..3c6f26b2 100644 --- a/src/output/formatters.ts +++ b/src/output/formatters.ts @@ -15,6 +15,7 @@ import { getPrimaryParent, getRootDependencies } from "../utils/finding.js"; import { calculatePathCoverage, formatDependencyPath } from "../utils/path-coverage.js"; import { pluralize } from "../utils/string.js"; import { hasMaliciousAdvisory } from "../utils/vuln.js"; +import { computePrioritySignal } from "../utils/priority-signal.js"; export function formatRelationshipLabel(value: string): string { if (value.startsWith("direct")) return chalk.green(value); @@ -304,6 +305,7 @@ export function serializeFinding(finding: Finding, plan?: SuggestedFixCommandPla recommendedNpmTransitiveRemediation: finding.recommendedNpmTransitiveRemediation ?? null, cves: finding.cveAliases, epssScores: finding.epssScores ?? null, + prioritySignal: computePrioritySignal(finding.severity, finding.epssScores) ?? null, dependencyPaths: finding.dependencyPaths, usage: finding.usage ?? null, maliciousUnverifiable: finding.maliciousUnverifiable ?? false, @@ -315,6 +317,7 @@ export function serializeFinding(finding: Finding, plan?: SuggestedFixCommandPla aliases: v.aliases ?? [], summary: v.summary ?? "", severity: inferSeverity(v), + cvssScore: (v.severity ?? []).find(s => s.type?.startsWith("CVSS"))?.score ?? null, })), }; } diff --git a/src/output/html-reporter.ts b/src/output/html-reporter.ts index 2fdbeb83..4b026299 100644 --- a/src/output/html-reporter.ts +++ b/src/output/html-reporter.ts @@ -11,6 +11,7 @@ import { renderOverrideFindingsHtml } from "./override-findings-html.js"; import { renderMaintenanceFindingsHtml } from "./maintenance-findings-html.js"; import { renderLicenseFindingsHtml } from "./license-findings-html.js"; import type { EpssScore, Finding, ScanCompleteness } from "../types.js"; +import { PRIORITY_SIGNAL_LABELS, PRIORITY_SIGNAL_DESCRIPTIONS, PRIORITY_SIGNAL_LEGEND_DESCRIPTIONS, type PrioritySignal } from "../utils/priority-signal.js"; import type { OverrideFinding } from "../overrides/types.js"; import type { MaintenanceFinding } from "../maintenance/types.js"; import type { LicenseFinding } from "../licenses/types.js"; @@ -259,7 +260,19 @@ button.header-link:hover{color:var(--link);border-color:var(--link)} .maintenance-risk table tbody tr{border-bottom:1px solid var(--border-sub)} .maintenance-risk table tbody tr:last-child{border-bottom:none} .maintenance-risk table tbody tr:hover{background:var(--surface)} -.maintenance-risk table tbody td{padding:11px 14px;font-size:13px;color:var(--text);vertical-align:middle}`; +.maintenance-risk table tbody td{padding:11px 14px;font-size:13px;color:var(--text);vertical-align:middle} +.priority-badge{display:inline-flex;align-items:center;gap:4px;font-size:10px;font-weight:700;text-transform:uppercase;letter-spacing:.4px;padding:2px 7px;border-radius:4px;white-space:nowrap} +.priority-badge.fix-now{background:#f8514922;color:#f85149;border:1px solid #f8514966} +.priority-badge.fix-soon{background:#fb850022;color:#fb8500;border:1px solid #fb850066} +.priority-badge.monitor{background:#388bfd22;color:#388bfd;border:1px solid #388bfd66} +.priority-badge.low-priority{background:#8b949e22;color:#8b949e;border:1px solid #8b949e66} +.priority-none{font-size:11px;color:var(--text-3)} +.epss-val{font-size:11px;color:var(--text-2);font-family:monospace;white-space:nowrap;cursor:help;border-bottom:1px dotted var(--text-3)} +.epss-val.hot{color:#a371f7;border-bottom-color:#a371f7} +.priority-legend{background:var(--surface);border:1px solid var(--border);border-radius:8px;padding:14px 18px;margin:0 32px 24px} +.priority-legend h4{font-size:11px;font-weight:600;text-transform:uppercase;letter-spacing:.4px;color:var(--text-2);margin-bottom:12px} +.priority-legend-grid{display:grid;grid-template-columns:repeat(auto-fit,minmax(260px,1fr));gap:10px} +.priority-legend-item{display:flex;align-items:flex-start;gap:10px;font-size:12px;color:var(--text-2);line-height:1.5}`; export function renderHtmlReport(data: ReportData): string { @@ -377,6 +390,8 @@ ${duplicatePackagesHtml} Package ↕ Fix available Severity ↓ + EPSS + EPSS Priority Type ↕ Root CVE / Advisory @@ -384,9 +399,10 @@ ${duplicatePackagesHtml} ${findingRowsHtml} - No findings match your search. + No findings match your search. +${renderPriorityLegendHtml(data.findings)} ${renderOverrideFindingsHtml(data.overrideFindings, data.projectPath)} ${renderMaintenanceFindingsHtml(data.maintenanceFindings)} @@ -549,14 +565,64 @@ function renderRelBadge(finding: SerializedFinding): string { return `${escapeHtml(finding.relationship)}`; } -function renderEpssHtml(epssScores: EpssScore[] | null | undefined): string { - if (!epssScores || epssScores.length === 0) return ""; - const best = epssScores.slice().sort((a, b) => b.epss - a.epss)[0]!; - const pct = (best.epss * 100).toFixed(1); +function renderPrioritySignalDetailHtml( + priority: PrioritySignal | null, + epssScores: EpssScore[] | null | undefined, +): string { + if (!priority) return ""; + const label = PRIORITY_SIGNAL_LABELS[priority]; + const desc = PRIORITY_SIGNAL_DESCRIPTIONS[priority]; + const cssClass = priority.replace(/_/g, "-"); + let epssLine = ""; + if (epssScores && epssScores.length > 0) { + const best = epssScores.slice().sort((a, b) => b.percentile - a.percentile)[0]!; + const top = (1 - best.percentile) * 100; + const topStr = top < 0.01 ? "<0.01" : top < 1 ? top.toFixed(2) : top.toFixed(1); + epssLine = `

${escapeHtml(best.cve)} - top ${topStr}% exploitation likelihood (EPSS: ${(best.epss * 100).toFixed(2)}%)

`; + } + return `

EPSS Priority Signal

+

${escapeHtml(label)}  ${escapeHtml(desc)}

+ ${epssLine}`; +} + +export function renderPriorityLegendHtml(findings: SerializedFinding[]): string { + const hasEpss = findings.some(f => f.epssScores && f.epssScores.length > 0); + if (!hasEpss) return ""; + const items: Array<{ signal: PrioritySignal; label: string; desc: string }> = [ + { signal: "fix_now", label: PRIORITY_SIGNAL_LABELS.fix_now, desc: PRIORITY_SIGNAL_LEGEND_DESCRIPTIONS.fix_now }, + { signal: "fix_soon", label: PRIORITY_SIGNAL_LABELS.fix_soon, desc: PRIORITY_SIGNAL_LEGEND_DESCRIPTIONS.fix_soon }, + { signal: "monitor", label: PRIORITY_SIGNAL_LABELS.monitor, desc: PRIORITY_SIGNAL_LEGEND_DESCRIPTIONS.monitor }, + { signal: "low_priority", label: PRIORITY_SIGNAL_LABELS.low_priority, desc: PRIORITY_SIGNAL_LEGEND_DESCRIPTIONS.low_priority }, + ]; + const itemsHtml = items.map(({ signal, label, desc }) => { + const cssClass = signal.replace(/_/g, "-"); + return `
${escapeHtml(label)}${escapeHtml(desc)}
`; + }).join("\n"); + return `
+

Priority Signal - severity x exploitation likelihood

+
+${itemsHtml} +
+

EPSS = Exploit Prediction Scoring System (FIRST.org). "top X%" = this CVE is among the X% most likely to be exploited across all published CVEs. "-" is shown in the EPSS and EPSS Priority columns when EPSS data is unavailable for a finding.

+
`; +} + +function renderEpssColumnHtml(epssScores: EpssScore[] | null | undefined): string { + if (!epssScores || epssScores.length === 0) return `-`; + const best = epssScores.slice().sort((a, b) => b.percentile - a.percentile)[0]!; const top = (1 - best.percentile) * 100; const topStr = top < 0.01 ? "<0.01" : top < 1 ? top.toFixed(2) : top.toFixed(1); - return `

EPSS

-

${escapeHtml(pct)}% exploitation probability - ${escapeHtml(best.cve)} (top ${topStr}% of all CVEs)

`; + const isHot = best.percentile >= 0.90; + const hotClass = isHot ? " hot" : ""; + const tooltip = `This CVE is more likely to be exploited than ${(best.percentile * 100).toFixed(0)}% of all published CVEs (EPSS score: ${(best.epss * 100).toFixed(2)}%)`; + return `top ${topStr}%`; +} + +function renderPriorityColumnHtml(priority: PrioritySignal | null): string { + if (!priority) return `-`; + const label = PRIORITY_SIGNAL_LABELS[priority]; + const cssClass = priority.replace(/_/g, "-"); + return `${escapeHtml(label)}`; } export function renderFindingRow(finding: SerializedFinding, idx: number, skippedKeys?: ReadonlySet): string { @@ -604,17 +670,23 @@ export function renderFindingRow(finding: SerializedFinding, idx: number, skippe const rootDepsHtml = finding.rootDependencies.length > 0 ? finding.rootDependencies.map(name => `${escapeHtml(name)}`).join(", ") : `-`; + + const epssHtml = renderEpssColumnHtml(finding.epssScores); + const priorityHtml = renderPriorityColumnHtml(finding.prioritySignal); + return ` ▶
${escapeHtml(finding.package)}
${escapeHtml(finding.version)}
${fixHtml} ${escapeHtml(finding.severity)} + ${epssHtml} + ${priorityHtml} ${renderRelBadge(finding)} ${rootDepsHtml} ${cveLinks} - +

Description

@@ -632,7 +704,7 @@ export function renderFindingRow(finding: SerializedFinding, idx: number, skippe

${escapeHtml(finding.riskSummary)}

Next action

${escapeHtml(finding.nextAction)}

- ${renderEpssHtml(finding.epssScores)} + ${renderPrioritySignalDetailHtml(finding.prioritySignal, finding.epssScores)}
diff --git a/src/output/multi-folder-html-reporter.ts b/src/output/multi-folder-html-reporter.ts index 72cc3ff4..f8559655 100644 --- a/src/output/multi-folder-html-reporter.ts +++ b/src/output/multi-folder-html-reporter.ts @@ -10,6 +10,7 @@ import { renderFixPlan, renderCompletenessBanner, serializeHtmlFinding, + renderPriorityLegendHtml, } from "./html-reporter.js"; import type { SerializedFinding } from "./html-reporter.js"; import { renderOverrideFindingsHtml } from "./override-findings-html.js"; @@ -134,7 +135,7 @@ function renderFolderSection( : ""; const emptyRow = result.sorted.length === 0 - ? `No findings` + ? `No findings` : ""; return ` @@ -170,6 +171,8 @@ function renderFolderSection( Package ↕ Fix available Severity ↓ + EPSS + EPSS Priority Type ↕ Root CVE / Advisory @@ -177,7 +180,7 @@ function renderFolderSection( ${emptyRow}${findingRowsHtml} - No findings match your search. + No findings match your search. @@ -334,6 +337,8 @@ ${aggregateBannerHtml} ${folderSectionsHtml} +${renderPriorityLegendHtml(reportData.findings)} +
Generated by cve-lite v${escapeHtml(params.cliVersion)} ${folderCount} ${pluralize(folderCount, "folder")}  ·  ${totalFindings} findings  ·  ${totalCVEs} CVEs diff --git a/src/output/printers.ts b/src/output/printers.ts index a6b83051..46ca0c80 100644 --- a/src/output/printers.ts +++ b/src/output/printers.ts @@ -17,6 +17,7 @@ import { formatSeverityLabel } from "../utils/severity.js"; import { pluralize } from "../utils/string.js"; import { hasMaliciousAdvisory } from "../utils/vuln.js"; import { selectFindingsForCompact } from "./finding-display.js"; +import { computePrioritySignal, PRIORITY_SIGNAL_LABELS, PRIORITY_SIGNAL_TABLE_LABELS, PRIORITY_SIGNAL_DESCRIPTIONS, type PrioritySignal } from "../utils/priority-signal.js"; import { renderLicenseFindings } from "./license-terminal.js"; import { getCompletenessImpact } from "../scan/completeness.js"; import { @@ -236,8 +237,18 @@ export function printSkippedDependencies(skipped: string[]) { } } +function formatPrioritySignal(signal: PrioritySignal | null): string { + if (!signal) return chalk.gray("-"); + const label = PRIORITY_SIGNAL_TABLE_LABELS[signal]; + if (signal === "fix_now") return chalk.red(label); + if (signal === "fix_soon") return chalk.yellow(label); + if (signal === "monitor") return chalk.blue(label); + return chalk.gray(label); +} + export function printTable(findings: Finding[], threshold: SeverityLabel | null, skippedKeys?: ReadonlySet) { - const headers = ["Package", "Version", "Severity", "Type", "Root", "Usage", "Fixed", "EPSS", "IDs"]; + const headers = ["Package", "Version", "Severity", "Type", "Root", "Usage", "Fixed", "EPSS", "EPSS Priority", "IDs"]; + const rowSignals: Array = []; const rawRows = findings.map(f => { let usageText = "n/a"; if (f.usage) { @@ -260,10 +271,14 @@ export function printTable(findings: Finding[], threshold: SeverityLabel | null, fixedDisplay = chalk.yellow("⚠ no fix"); } let epssDisplay = "-"; + let signal: PrioritySignal | null = null; if (f.epssScores && f.epssScores.length > 0) { - const best = f.epssScores.slice().sort((a, b) => b.epss - a.epss)[0]!; + const best = f.epssScores.slice().sort((a, b) => b.percentile - a.percentile)[0]!; epssDisplay = `${(best.epss * 100).toFixed(1)}%`; + signal = computePrioritySignal(f.severity, f.epssScores); } + rowSignals.push(signal); + const priorityDisplay = signal ? PRIORITY_SIGNAL_TABLE_LABELS[signal] : "-"; return [ f.pkg.name, f.pkg.version, @@ -273,6 +288,7 @@ export function printTable(findings: Finding[], threshold: SeverityLabel | null, usageText, fixedDisplay, epssDisplay, + priorityDisplay, f.vulnerabilities.map(v => v.id).join(", ") ]; }); @@ -293,7 +309,7 @@ export function printTable(findings: Finding[], threshold: SeverityLabel | null, console.log(renderRow(headers, widths)); console.log(line("├", "┼", "┤")); - for (const row of rawRows) { + rawRows.forEach((row, idx) => { let usageDecorated = String(row[5]); if (usageDecorated.includes("file(s)")) usageDecorated = chalk.red(usageDecorated); else if (usageDecorated.includes("unused")) usageDecorated = chalk.green(usageDecorated); @@ -308,10 +324,11 @@ export function printTable(findings: Finding[], threshold: SeverityLabel | null, usageDecorated, row[6], chalk.gray(String(row[7])), - row[8] + formatPrioritySignal(rowSignals[idx] ?? null), + row[9], ]; console.log(renderRow(decorated, widths)); - } + }); console.log(line("└", "┴", "┘")); @@ -518,11 +535,15 @@ export function printCompactOutput( console.log(`${formatSeverityLabel(sevLabel)} ${chalk.whiteBright(finding.pkg.name)}@${finding.pkg.version}`); console.log(` ${typeLabel}${usageContext}`); if (finding.epssScores && finding.epssScores.length > 0) { - const best = finding.epssScores.slice().sort((a, b) => b.epss - a.epss)[0]!; + const best = finding.epssScores.slice().sort((a, b) => b.percentile - a.percentile)[0]!; const pct = (best.epss * 100).toFixed(1); const top = ((1 - best.percentile) * 100); const topStr = top < 0.01 ? "<0.01" : top < 1 ? top.toFixed(2) : top.toFixed(1); console.log(` ${chalk.gray(`EPSS: ${pct}% exploitation probability - ${best.cve} (top ${topStr}% of all CVEs)`)}`); + const priority = computePrioritySignal(finding.severity, finding.epssScores); + if (priority === "fix_now") { + console.log(` ${chalk.red(PRIORITY_SIGNAL_LABELS.fix_now)} - ${PRIORITY_SIGNAL_DESCRIPTIONS[priority]}`); + } } const isMalicious = hasMaliciousAdvisory(finding.vulnerabilities); diff --git a/src/utils/priority-signal.ts b/src/utils/priority-signal.ts new file mode 100644 index 00000000..bac6cfd4 --- /dev/null +++ b/src/utils/priority-signal.ts @@ -0,0 +1,48 @@ +import type { EpssScore, SeverityLabel } from "../types.js"; + +export type PrioritySignal = "fix_now" | "fix_soon" | "monitor" | "low_priority"; + +const EPSS_HIGH_EXPLOITATION_THRESHOLD = 0.90; + +export const PRIORITY_SIGNAL_LABELS: Record = { + fix_now: "⚡ Fix Now", + fix_soon: "Fix Soon", + monitor: "Monitor", + low_priority: "Low Priority", +}; + +// Emoji-free labels for fixed-width table columns (⚡ is 2-wide in terminals but 1 in JS string.length, breaking padEnd alignment) +export const PRIORITY_SIGNAL_TABLE_LABELS: Record = { + fix_now: "Fix Now", + fix_soon: "Fix Soon", + monitor: "Monitor", + low_priority: "Low Priority", +}; + +export const PRIORITY_SIGNAL_DESCRIPTIONS: Record = { + fix_now: "Critical or high severity + top 10% EPSS exploitation likelihood", + fix_soon: "Critical or high severity, EPSS not top 10%", + monitor: "Medium or lower severity, EPSS top 10% - watch closely", + low_priority: "Medium or lower severity, EPSS not top 10%", +}; + +export const PRIORITY_SIGNAL_LEGEND_DESCRIPTIONS: Record = { + fix_now: "Critical or high severity and EPSS top 10% - high impact, actively exploited class of CVE", + fix_soon: "Critical or high severity, EPSS not top 10% - high impact but exploitation is less common", + monitor: "Medium or lower, EPSS top 10% - lower impact but exploitation is active", + low_priority: "Medium or lower, EPSS not top 10% - address in normal maintenance cycle", +}; + +export function computePrioritySignal( + severity: SeverityLabel, + epssScores: EpssScore[] | null | undefined, +): PrioritySignal | null { + if (!epssScores || epssScores.length === 0) return null; + const highImpact = severity === "critical" || severity === "high"; + const maxPercentile = Math.max(...epssScores.map(e => e.percentile)); + const highExploitation = maxPercentile >= EPSS_HIGH_EXPLOITATION_THRESHOLD; + if (highImpact && highExploitation) return "fix_now"; + if (highImpact) return "fix_soon"; + if (highExploitation) return "monitor"; + return "low_priority"; +} From c451c5dda85e3059104f7c3b67645c4a6e4b9e0d Mon Sep 17 00:00:00 2001 From: Sonu Kapoor Date: Tue, 1 Sep 2026 17:02:55 -0400 Subject: [PATCH 2/6] test: add coverage for EPSS Priority Signal classification and serialization --- tests/multi-folder-html-reporter.test.ts | 3 +- tests/output.test.ts | 57 ++++++++++++++++ tests/utils/priority-signal.test.ts | 87 ++++++++++++++++++++++++ 3 files changed, 146 insertions(+), 1 deletion(-) create mode 100644 tests/utils/priority-signal.test.ts diff --git a/tests/multi-folder-html-reporter.test.ts b/tests/multi-folder-html-reporter.test.ts index 4f9c587d..6b082ca2 100644 --- a/tests/multi-folder-html-reporter.test.ts +++ b/tests/multi-folder-html-reporter.test.ts @@ -324,6 +324,7 @@ describe("writeMultiFolderHtmlReport", () => { expect(html).toContain("Root"); expect(html).toContain('express'); expect(html).not.toContain('colspan="6"'); - expect(html).toContain('colspan="7"'); + expect(html).not.toContain('colspan="7"'); + expect(html).toContain('colspan="9"'); }); }); diff --git a/tests/output.test.ts b/tests/output.test.ts index 7bf7dd31..c898f4be 100644 --- a/tests/output.test.ts +++ b/tests/output.test.ts @@ -301,12 +301,69 @@ describe("output formatters", () => { expect(serialized).not.toHaveProperty("nextAction"); }); + it("includes cvssScore in serialized vulnerability when CVSS severity entry is present", () => { + const finding = createFinding({ + vulnerabilities: [{ + id: "OSV-123", + aliases: ["CVE-2026-0001"], + summary: "Prototype pollution", + severity: [{ type: "CVSS_V3", score: "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H" }], + }], + }); + const serialized = serializeFinding(finding); + + expect(serialized.vulnerabilities[0]?.cvssScore).toBe("CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H"); + }); + + it("sets cvssScore to null in serialized vulnerability when no CVSS severity entry is present", () => { + const finding = createFinding({ + vulnerabilities: [{ + id: "OSV-123", + aliases: ["CVE-2026-0001"], + summary: "Prototype pollution", + severity: [{ score: "9.8" }], + }], + }); + const serialized = serializeFinding(finding); + + expect(serialized.vulnerabilities[0]?.cvssScore).toBeNull(); + }); + it("serializes unresolved advisory IDs", () => { const finding = createFinding({ unresolvedAdvisoryIds: ["OSV-MISSING"] }); expect(serializeFinding(finding).unresolvedAdvisoryIds).toEqual(["OSV-MISSING"]); }); + it("sets prioritySignal to null when no EPSS scores", () => { + const finding = createFinding({ epssScores: null }); + expect(serializeFinding(finding).prioritySignal).toBeNull(); + }); + + it("sets prioritySignal to fix_now for critical severity with high EPSS percentile", () => { + const finding = createFinding({ + severity: "critical", + epssScores: [{ cve: "CVE-2026-0001", epss: 0.009, percentile: 0.96 }], + }); + expect(serializeFinding(finding).prioritySignal).toBe("fix_now"); + }); + + it("sets prioritySignal to fix_soon for critical severity with low EPSS percentile", () => { + const finding = createFinding({ + severity: "critical", + epssScores: [{ cve: "CVE-2026-0001", epss: 0.001, percentile: 0.50 }], + }); + expect(serializeFinding(finding).prioritySignal).toBe("fix_soon"); + }); + + it("sets prioritySignal to monitor for medium severity with high EPSS percentile", () => { + const finding = createFinding({ + severity: "medium", + epssScores: [{ cve: "CVE-2026-0001", epss: 0.005, percentile: 0.93 }], + }); + expect(serializeFinding(finding).prioritySignal).toBe("monitor"); + }); + it("includes dev:true in serialized finding when pkg.dev is true", () => { const finding = createFinding({ pkg: { name: "lodash", version: "4.17.20", ecosystem: "npm", dev: true }, diff --git a/tests/utils/priority-signal.test.ts b/tests/utils/priority-signal.test.ts new file mode 100644 index 00000000..8c32d342 --- /dev/null +++ b/tests/utils/priority-signal.test.ts @@ -0,0 +1,87 @@ +import { computePrioritySignal } from "../../src/utils/priority-signal.js"; +import type { EpssScore } from "../../src/types.js"; + +function epss(percentile: number): EpssScore[] { + return [{ cve: "CVE-2024-0001", epss: percentile * 0.01, percentile }]; +} + +describe("computePrioritySignal", () => { + it("returns null when epssScores is null", () => { + expect(computePrioritySignal("critical", null)).toBeNull(); + }); + + it("returns null when epssScores is undefined", () => { + expect(computePrioritySignal("high", undefined)).toBeNull(); + }); + + it("returns null when epssScores is empty", () => { + expect(computePrioritySignal("critical", [])).toBeNull(); + }); + + it("returns fix_now for critical + percentile >= 0.90", () => { + expect(computePrioritySignal("critical", epss(0.96))).toBe("fix_now"); + }); + + it("returns fix_now for high + percentile >= 0.90", () => { + expect(computePrioritySignal("high", epss(0.91))).toBe("fix_now"); + }); + + it("returns fix_now at exactly the 0.90 boundary", () => { + expect(computePrioritySignal("critical", epss(0.90))).toBe("fix_now"); + }); + + it("returns fix_soon for critical + percentile < 0.90", () => { + expect(computePrioritySignal("critical", epss(0.89))).toBe("fix_soon"); + }); + + it("returns fix_soon for high + percentile < 0.90", () => { + expect(computePrioritySignal("high", epss(0.10))).toBe("fix_soon"); + }); + + it("returns monitor for medium + percentile >= 0.90", () => { + expect(computePrioritySignal("medium", epss(0.93))).toBe("monitor"); + }); + + it("returns monitor for low + percentile >= 0.90", () => { + expect(computePrioritySignal("low", epss(0.95))).toBe("monitor"); + }); + + it("returns low_priority for medium + percentile < 0.90", () => { + expect(computePrioritySignal("medium", epss(0.50))).toBe("low_priority"); + }); + + it("returns low_priority for low + percentile < 0.90", () => { + expect(computePrioritySignal("low", epss(0.01))).toBe("low_priority"); + }); + + it("uses max percentile across multiple EPSS entries", () => { + const scores: EpssScore[] = [ + { cve: "CVE-2024-0001", epss: 0.001, percentile: 0.50 }, + { cve: "CVE-2024-0002", epss: 0.009, percentile: 0.92 }, + ]; + // critical + max(0.50, 0.92) = 0.92 >= 0.90 → fix_now + expect(computePrioritySignal("critical", scores)).toBe("fix_now"); + }); + + it("just below boundary is fix_soon for high severity", () => { + expect(computePrioritySignal("high", epss(0.8999))).toBe("fix_soon"); + }); + + // "unknown" and "none" are valid SeverityLabel values (unscored advisories). + // They are not critical/high, so they fall into the lower-impact tiers. + it("returns monitor for unknown severity + percentile >= 0.90", () => { + expect(computePrioritySignal("unknown", epss(0.95))).toBe("monitor"); + }); + + it("returns low_priority for unknown severity + percentile < 0.90", () => { + expect(computePrioritySignal("unknown", epss(0.50))).toBe("low_priority"); + }); + + it("returns monitor for none severity + percentile >= 0.90", () => { + expect(computePrioritySignal("none", epss(0.92))).toBe("monitor"); + }); + + it("returns low_priority for none severity + percentile < 0.90", () => { + expect(computePrioritySignal("none", epss(0.10))).toBe("low_priority"); + }); +}); From 93e1ab2bf76ecb096b59c9aea845587b834bab9a Mon Sep 17 00:00:00 2001 From: Sonu Kapoor Date: Tue, 1 Sep 2026 17:02:59 -0400 Subject: [PATCH 3/6] docs: document EPSS Priority Signal in cli-reference --- website/docs/cli-reference.md | 21 ++++++++++++++++++--- 1 file changed, 18 insertions(+), 3 deletions(-) diff --git a/website/docs/cli-reference.md b/website/docs/cli-reference.md index 380365a3..512bbaf2 100644 --- a/website/docs/cli-reference.md +++ b/website/docs/cli-reference.md @@ -35,13 +35,28 @@ cve-lite install-skill | Flag | Default | Description | Example | |---|---|---|---| -| `--verbose` | off | Full output: severity table, fix plan, findings table, coverage notes | `cve-lite . --verbose` | -| `--json` | off | Machine-readable JSON output (suppresses all other output) | `cve-lite . --json` | +| `--verbose` | off | Full output: severity table, fix plan, findings table (with EPSS and EPSS Priority columns), coverage notes | `cve-lite . --verbose` | +| `--json` | off | Machine-readable JSON output (suppresses all other output); each finding includes `epssScores` and `prioritySignal` when EPSS data is available | `cve-lite . --json` | | `--sarif` | off | Write SARIF 2.1.0 output to a timestamped `.sarif` file; can be combined with `--json` and `--report` | `cve-lite . --sarif` | | `--cdx` | off | Write CycloneDX 1.4 SBOM to a timestamped `.cdx.json` file; can be combined with `--json` and `--sarif`; cannot be combined with `--report` | `cve-lite . --cdx` | -| `--report[=]` | off / `./cve-report` | Generate an HTML report; optional path sets output directory (default `./cve-report`); opens in browser by default; cannot be used with `--json` | `cve-lite . --report`
`cve-lite . --report ./reports` | +| `--report[=]` | off / `./cve-report` | Generate an HTML report with EPSS and EPSS Priority columns and an interactive priority legend; optional path sets output directory (default `./cve-report`); opens in browser by default; cannot be used with `--json` | `cve-lite . --report`
`cve-lite . --report ./reports` | | `--no-open` | off | Generate the HTML report without opening it in the browser | `cve-lite . --report --no-open` | +### EPSS Priority Signal + +When EPSS data is available for a finding, CVE Lite CLI combines CVSS-derived severity with the EPSS exploitation likelihood percentile to produce a single actionable priority tier. EPSS is the [Exploit Prediction Scoring System](https://www.first.org/epss/) from FIRST.org - it scores how likely a CVE is to be exploited in the next 30 days relative to all published CVEs. + +| Tier | Condition | Meaning | +|---|---|---| +| `fix_now` | Critical or high severity + EPSS top 10% | High impact and actively exploited class of CVE - address immediately | +| `fix_soon` | Critical or high severity, EPSS not top 10% | High impact but exploitation is less common - schedule a fix | +| `monitor` | Medium or lower severity, EPSS top 10% | Lower impact but exploitation is active - watch closely | +| `low_priority` | Medium or lower severity, EPSS not top 10% | Address in normal maintenance cycle | + +The tier is `null` in JSON output when no EPSS data is available for a finding (typically when a finding has no CVE alias that resolves against the FIRST.org API). In terminal and HTML output, those cells show `-`. + +In terminal compact mode, only `fix_now` findings are flagged inline with `⚡ Fix Now`. In verbose mode and the HTML report, all four tiers appear in a dedicated EPSS Priority column alongside the raw EPSS percentile. + --- ## Offline options From 7081bc16a54cb0d24254f74f6b2c8fe93f87e6b1 Mon Sep 17 00:00:00 2001 From: Sonu Kapoor Date: Tue, 1 Sep 2026 18:39:31 -0400 Subject: [PATCH 4/6] chore: update browserslist to 4.28.8 (clears GHSA-73wf, GHSA-c83g high advisories) --- package-lock.json | 46 +++++++++++++++++++++++----------------------- 1 file changed, 23 insertions(+), 23 deletions(-) diff --git a/package-lock.json b/package-lock.json index cfcec4d5..3293e426 100644 --- a/package-lock.json +++ b/package-lock.json @@ -2184,9 +2184,9 @@ "license": "MIT" }, "node_modules/baseline-browser-mapping": { - "version": "2.10.37", - "resolved": "https://registry.npmjs.org/baseline-browser-mapping/-/baseline-browser-mapping-2.10.37.tgz", - "integrity": "sha512-girxaJ7WZssDOFhzCGZTDKoTa1gk6A1TbflaYTpykLJ4UU9Fz9kx1aREM8JCuoVHbL8X8T/mJg7w2oYSq72Oig==", + "version": "2.11.20", + "resolved": "https://registry.npmjs.org/baseline-browser-mapping/-/baseline-browser-mapping-2.11.20.tgz", + "integrity": "sha512-H0ulySigv6icDJ1F7SjtdCD6PrhTpdYCmP0CactWy1+ekh0AFd0o1Wn5T8b+hnTmdBx19u9yhL6wvCylXMY7zw==", "dev": true, "license": "Apache-2.0", "bin": { @@ -2241,9 +2241,9 @@ } }, "node_modules/browserslist": { - "version": "4.28.2", - "resolved": "https://registry.npmjs.org/browserslist/-/browserslist-4.28.2.tgz", - "integrity": "sha512-48xSriZYYg+8qXna9kwqjIVzuQxi+KYWp2+5nCYnYKPTr0LvD89Jqk2Or5ogxz0NUMfIjhh2lIUX/LyX9B4oIg==", + "version": "4.28.8", + "resolved": "https://registry.npmjs.org/browserslist/-/browserslist-4.28.8.tgz", + "integrity": "sha512-V2NpofLblG64mfOtSgDhOJESZEGogzDMBv/q+W6oc4LXWP/q75eOXoOaaOu1EOadB9U4Bwx/e0yzbvwKH8zalA==", "dev": true, "funding": [ { @@ -2261,11 +2261,11 @@ ], "license": "MIT", "dependencies": { - "baseline-browser-mapping": "^2.10.12", - "caniuse-lite": "^1.0.30001782", - "electron-to-chromium": "^1.5.328", - "node-releases": "^2.0.36", - "update-browserslist-db": "^1.2.3" + "baseline-browser-mapping": "^2.11.12", + "caniuse-lite": "^1.0.30001809", + "electron-to-chromium": "^1.5.402", + "node-releases": "^2.0.53", + "update-browserslist-db": "^1.3.0" }, "bin": { "browserslist": "cli.js" @@ -2349,9 +2349,9 @@ } }, "node_modules/caniuse-lite": { - "version": "1.0.30001799", - "resolved": "https://registry.npmjs.org/caniuse-lite/-/caniuse-lite-1.0.30001799.tgz", - "integrity": "sha512-hG1bReV+OUU+MOqK4t/ZWI0tZOyz3rqS9XuhOUz1cIcbwBKjOyJEJuw9ER5JuNyqxNk8u/JUVbGibBOL1yrjFw==", + "version": "1.0.30001810", + "resolved": "https://registry.npmjs.org/caniuse-lite/-/caniuse-lite-1.0.30001810.tgz", + "integrity": "sha512-TITQPUkaz+aVk5GL6NhOdwk1aEaNTSDPsGFWrTuhKGtjTF70jL/Oht2W4c6rXUe5fu7Ie19VIahAXHIIiWWNeg==", "dev": true, "funding": [ { @@ -2664,9 +2664,9 @@ "license": "MIT" }, "node_modules/electron-to-chromium": { - "version": "1.5.375", - "resolved": "https://registry.npmjs.org/electron-to-chromium/-/electron-to-chromium-1.5.375.tgz", - "integrity": "sha512-ZWP5eB4BVPW/ZYo9252hQZHZ5XavtsTgpbhcmMmRwymavC5AsLWQWBPaKMeNd2LW0KGby5HPXvj7+sr4ta5j/Q==", + "version": "1.5.420", + "resolved": "https://registry.npmjs.org/electron-to-chromium/-/electron-to-chromium-1.5.420.tgz", + "integrity": "sha512-2yD6XreGusOfNV+dUcvipJEXc3n/n7fgr7996aszTG+YY5E4mqM4tOq/3uhP129cazL9YHbVWSpc79ePotWtPA==", "dev": true, "license": "ISC" }, @@ -4174,9 +4174,9 @@ "license": "MIT" }, "node_modules/node-releases": { - "version": "2.0.47", - "resolved": "https://registry.npmjs.org/node-releases/-/node-releases-2.0.47.tgz", - "integrity": "sha512-Uzmd6LXpouKo8EUK68IjH4+E01w/hXyV3R3g/geCJo+rXLNfh1xucB+LOzYEOQPSiUK3h/xZf0cQGcSsmyL2Og==", + "version": "2.0.54", + "resolved": "https://registry.npmjs.org/node-releases/-/node-releases-2.0.54.tgz", + "integrity": "sha512-YHs7BmmcsdAI5Ozuf8JZo6PT0mv2GIWC9vMfvUC3dp65M8hn7Ux8CPL+2oBI7juNuj9d0ndhTcznq2ODBps9cQ==", "dev": true, "license": "MIT", "engines": { @@ -5264,9 +5264,9 @@ } }, "node_modules/update-browserslist-db": { - "version": "1.2.3", - "resolved": "https://registry.npmjs.org/update-browserslist-db/-/update-browserslist-db-1.2.3.tgz", - "integrity": "sha512-Js0m9cx+qOgDxo0eMiFGEueWztz+d4+M3rGlmKPT+T4IS/jP4ylw3Nwpu6cpTTP8R1MAC1kF4VbdLt3ARf209w==", + "version": "1.3.2", + "resolved": "https://registry.npmjs.org/update-browserslist-db/-/update-browserslist-db-1.3.2.tgz", + "integrity": "sha512-UQ+MSxlhRm1bzjhU+DcuXfjFO1FzNtqhK5+9Yvlp90ItDLk5vT932A0rFu619nf7RVS+Y/VeaUW1jaRDqZ8VJw==", "dev": true, "funding": [ { From c1fbac853b50f9832b40c59001e08b34e93be3f0 Mon Sep 17 00:00:00 2001 From: Sonu Kapoor Date: Tue, 1 Sep 2026 18:46:10 -0400 Subject: [PATCH 5/6] fix: count unique packages in scan header, not advisory rows --- src/output/printers.ts | 5 +++-- tests/output.test.ts | 12 ++++++++++++ 2 files changed, 15 insertions(+), 2 deletions(-) diff --git a/src/output/printers.ts b/src/output/printers.ts index 46ca0c80..5f73e249 100644 --- a/src/output/printers.ts +++ b/src/output/printers.ts @@ -43,7 +43,8 @@ export function printSummary(findings: Finding[], packageCount: number, scanInpu } const totalCVEs = countUniqueAdvisories(findings); - const pkgLabel = findings.length === 1 ? "package" : "packages"; + const uniquePkgCount = new Set(findings.map(f => `${f.pkg.name}@${f.pkg.version}`)).size; + const pkgLabel = uniquePkgCount === 1 ? "package" : "packages"; const cveLabel = totalCVEs === 1 ? "CVE" : "CVEs"; const counts = { @@ -54,7 +55,7 @@ export function printSummary(findings: Finding[], packageCount: number, scanInpu unknown: findings.filter(f => f.severity === "unknown").length }; - console.log(chalk.redBright(`✗ Found ${findings.length} ${pkgLabel} (${totalCVEs} ${cveLabel}) with known OSV matches from ${scanInput.source}`)); + console.log(chalk.redBright(`✗ Found ${uniquePkgCount} ${pkgLabel} (${totalCVEs} ${cveLabel}) with known OSV matches from ${scanInput.source}`)); console.log(renderSeverityTable(counts)); } diff --git a/tests/output.test.ts b/tests/output.test.ts index c898f4be..c66af852 100644 --- a/tests/output.test.ts +++ b/tests/output.test.ts @@ -1363,6 +1363,18 @@ describe("output printers", () => { expect(lines.join("\n")).toContain("1 issue comes through other dependencies."); }); + it("counts unique packages not advisory rows in the header", () => { + const samePkg = { name: "browserslist", version: "4.28.2", ecosystem: "npm" as const, paths: [["project", "browserslist"]] }; + const findings = [ + createFinding({ pkg: samePkg, vulnerabilities: [{ id: "GHSA-73wf-gq98-2v4g", severity: [] }] }), + createFinding({ pkg: samePkg, vulnerabilities: [{ id: "NPM-1153171", severity: [] }] }), + ]; + + const lines = captureLogs(() => printSummary(findings, 10, createScanInput())); + + expect(lines[0]).toContain("✗ Found 1 package"); + }); + it("keeps plural verbs in the action summary", () => { const findings = [ createFinding({ relationship: "direct" }), From 74f27f33fbd06b0a0134d2e49c8cb5a21225d120 Mon Sep 17 00:00:00 2001 From: Sonu Kapoor Date: Tue, 1 Sep 2026 18:50:30 -0400 Subject: [PATCH 6/6] docs: add EPSS priority signal to README feature list and comparison table --- README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 00fa7fb3..3891be62 100644 --- a/README.md +++ b/README.md @@ -210,7 +210,7 @@ The closer a security tool is to a developer's natural workflow, the more likely ## How it compares -No other free tool combines all of the following: lockfile scanning across npm, pnpm, Yarn, and Bun; parent-aware transitive remediation that tells you which package to upgrade (not just which one is vulnerable); fix version validation before suggesting an upgrade; a fully offline advisory DB for restricted environments; and CVE + license compliance scanning in a single pass. +No other free tool combines all of the following: lockfile scanning across npm, pnpm, Yarn, and Bun; parent-aware transitive remediation that tells you which package to upgrade (not just which one is vulnerable); fix version validation before suggesting an upgrade; a fully offline advisory DB for restricted environments; CVE + license compliance scanning in a single pass; and an EPSS priority signal that combines CVSS severity with exploitation likelihood into four actionable tiers. | Capability | CVE Lite CLI | npm audit | OSV-Scanner | Snyk CLI | Socket CLI | |---|:---:|:---:|:---:|:---:|:---:| @@ -232,6 +232,7 @@ No other free tool combines all of the following: lockfile scanning across npm, | [Override hygiene auditing](https://owasp.org/cve-lite-cli/docs/override-hygiene) | ✅ | ❌ | ❌ | ❌ | ❌ | | [Maintenance-risk detection (CVE-fix drag)](https://owasp.org/cve-lite-cli/docs/maintenance-risk) | ✅ | ❌ | ❌ | ❌ | ❌ | | [License compliance scanning (copyleft / unknown)](https://owasp.org/cve-lite-cli/docs/cli-reference#license-scanning-options) | ✅ | ❌ | ❌ | ⚠️ | ⚠️ | +| [Priority signal: CVSS severity × EPSS exploitation likelihood](https://owasp.org/cve-lite-cli/docs/cli-reference#epss-priority-signal) | ✅ | ❌ | ❌ | ⚠️ | ❌ | ✅ = built-in strength · ⚠️ = partial or workflow-dependent · ❌ = not a core strength