cve-lite-cli 1.36.0 → 1.37.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -40,7 +40,8 @@
40
40
  <br/>
41
41
 
42
42
  <p>
43
- 🏆 <strong>Ranked #5</strong> in <a href="https://www.helpnetsecurity.com/2026/07/08/20-latest-open-source-cybersecurity-tools/">Help Net Security's 20 open-source security tools</a> &nbsp;·&nbsp;
43
+ 🏆 <strong>Featured on <a href="https://www.youtube.com/watch?v=_Mmf3DLVuOQ">GitHub Open Source Friday</a></strong> &nbsp;·&nbsp;
44
+ <strong>Ranked #5</strong> in <a href="https://www.helpnetsecurity.com/2026/07/08/20-latest-open-source-cybersecurity-tools/">Help Net Security's 20 open-source security tools</a> &nbsp;·&nbsp;
44
45
  <strong><a href="https://www.bestpractices.dev/projects/12731">OpenSSF Best Practices</a></strong>
45
46
  </p>
46
47
 
@@ -129,6 +130,7 @@ cve-lite /path/to/project --fail-on high # exit non-zero on high severity and
129
130
  cve-lite /path/to/project --json # JSON output
130
131
  cve-lite /path/to/project --sarif # SARIF output for GitHub Code Scanning
131
132
  cve-lite /path/to/project --sbom spdx # SPDX 2.3 SBOM (also: --sbom cyclonedx)
133
+ cve-lite /path/to/project --sarif --output reports # write output files into ./reports
132
134
  cve-lite /path/to/project --report # interactive HTML dashboard
133
135
  cve-lite /path/to/project --check-overrides # audit override hygiene alongside the CVE scan
134
136
  cve-lite /path/to/project --check-maintenance # flag CVE-blocking version drag and npm-deprecated direct deps
@@ -142,7 +144,7 @@ For the full flag reference and exit codes see the [CLI Reference guide](https:/
142
144
 
143
145
  ## Override hygiene (`overrides`)
144
146
 
145
- `overrides` and `resolutions` are powerful, but they rot. CVE Lite CLI audits them across npm, pnpm, yarn, and bun, catching eleven classes of problem:
147
+ `overrides` and `resolutions` are powerful, but they rot. CVE Lite CLI audits them across npm, pnpm, yarn, and bun, catching twelve classes of problem:
146
148
 
147
149
  | Rule | What it catches |
148
150
  |---|---|
@@ -155,6 +157,7 @@ For the full flag reference and exit codes see the [CLI Reference guide](https:/
155
157
  | `OA007` | Frozen latest: registry has drifted past the pinned version (needs `--check-network`) |
156
158
  | `OA008` | Materialized vulnerable copy still on disk despite the override |
157
159
  | `OA009` | Stale floor: override range floor already met by all parent declarations |
160
+ | `OA010` | Vulnerable floor: override range admits a known-vulnerable version (needs `--check-network`) |
158
161
  | `PD001` | Override-only phantom: package imported in source but only present via an override pin |
159
162
  | `PD002` | Transitive-only phantom: package imported in source but only present as a transitive dependency |
160
163
 
@@ -386,7 +389,7 @@ Notable adopters include:
386
389
 
387
390
  ## Dependency footprint
388
391
 
389
- **Runtime:** `yaml` · `yarn-lockfile` · `better-sqlite3` · `fflate`
392
+ **Runtime:** `yaml` · `yarn-lockfile` · `better-sqlite3` · `fflate` · `semver`
390
393
 
391
394
  **Dev only:** `@types/node` · `tsx` · `typescript`
392
395
 
@@ -1,7 +1,7 @@
1
1
  import fs from "node:fs";
2
2
  import path from "node:path";
3
3
  import Database from "better-sqlite3";
4
- import { compareVersions, isPreReleaseVersion, looksLikeVersion } from "../utils/version.js";
4
+ import { compareVersions, isPreReleaseVersion, looksLikeVersion, normalizeAdvisoryVersion } from "../utils/version.js";
5
5
  const SCHEMA_SQL = `
6
6
  CREATE TABLE IF NOT EXISTS advisories (
7
7
  id TEXT PRIMARY KEY,
@@ -206,10 +206,20 @@ function versionAtOrAboveIntroduced(version, introduced) {
206
206
  return true;
207
207
  return isPreReleaseVersion(version) && releaseCore(version) === introduced;
208
208
  }
209
+ /** OSV range types whose boundaries are versions we can order. GIT uses commit hashes. */
210
+ const COMPARABLE_RANGE_TYPES = new Set(["ECOSYSTEM", "SEMVER"]);
209
211
  function versionMatchesRange(version, row) {
210
212
  const introduced = row.introduced;
211
- const fixed = row.fixed;
212
- const lastAffected = row.last_affected;
213
+ // Defence in depth behind the range-type filter, which stops these rows being
214
+ // written in the first place. A database built by an earlier version still
215
+ // holds them, and a bound that is not a version must never decide the answer
216
+ // by silently failing to exclude (#1191).
217
+ const fixed = normalizeAdvisoryVersion(row.fixed);
218
+ const lastAffected = normalizeAdvisoryVersion(row.last_affected);
219
+ if (row.fixed && !fixed)
220
+ return false;
221
+ if (row.last_affected && !lastAffected)
222
+ return false;
213
223
  if (introduced && introduced !== "0" && !versionAtOrAboveIntroduced(version, introduced)) {
214
224
  return false;
215
225
  }
@@ -230,6 +240,15 @@ function deriveAdvisoryPackageRows(vuln) {
230
240
  continue;
231
241
  }
232
242
  for (const range of affected.ranges ?? []) {
243
+ // A GIT range expresses its boundaries as commit hashes, which are not
244
+ // versions and cannot be ordered against one. Storing them anyway left
245
+ // `versionMatchesRange` comparing a version to a hash, where
246
+ // `compareVersions` returns an ordering rather than rejecting the input,
247
+ // so the range failed to exclude and a patched version was reported as
248
+ // vulnerable (#1191). Keep only the range types whose boundaries are
249
+ // versions.
250
+ if (range.type && !COMPARABLE_RANGE_TYPES.has(range.type))
251
+ continue;
233
252
  const events = range.events ?? [];
234
253
  let introduced = null;
235
254
  for (const event of events) {
@@ -1,3 +1,4 @@
1
+ import { satisfiesRange } from "../utils/version.js";
1
2
  const NPM_ADVISORY_URL = "https://registry.npmjs.org/-/npm/v1/security/advisories/bulk";
2
3
  function isValidAdvisory(a) {
3
4
  return (typeof a === "object" &&
@@ -6,8 +7,58 @@ function isValidAdvisory(a) {
6
7
  typeof a.title === "string" &&
7
8
  typeof a.vulnerable_versions === "string");
8
9
  }
10
+ /**
11
+ * The bulk endpoint does not send `ghsa_id`. It sends the advisory's GitHub URL,
12
+ * and the GHSA is the last segment of it.
13
+ *
14
+ * This matters more than a tidier identifier: the scanner drops an npm advisory
15
+ * whose id OSV already surfaced, so without the real GHSA every advisory arrived
16
+ * under a private `NPM-` id, matched nothing, and was counted twice.
17
+ */
18
+ function advisoryId(advisory) {
19
+ if (typeof advisory.ghsa_id === "string" && advisory.ghsa_id.length > 0)
20
+ return advisory.ghsa_id;
21
+ const fromUrl = advisory.url?.match(/GHSA-([a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4})/i);
22
+ // Casing has to match OSV exactly or the id match that drives dedup misses.
23
+ // OSV writes the prefix uppercase and the segments lowercase.
24
+ if (fromUrl)
25
+ return `GHSA-${fromUrl[1].toLowerCase()}`;
26
+ return `NPM-${advisory.id}`;
27
+ }
28
+ /**
29
+ * Turn npm's `vulnerable_versions` range into OSV events.
30
+ *
31
+ * `patched_versions` is what this used to read, and the bulk endpoint does not
32
+ * send that either, so every advisory carried `introduced: 0` and no upper bound.
33
+ * A range with no `fixed` cannot be evaluated, which is what made the fix-version
34
+ * validator report unknown coverage and give up.
35
+ *
36
+ * `<=` becomes `last_affected` rather than `fixed`, because `<=2.0.9` says 2.0.9
37
+ * is still vulnerable and `fixed: 2.0.9` would say the opposite.
38
+ */
39
+ function rangeEvents(advisory) {
40
+ let introduced = "0";
41
+ let upper = null;
42
+ for (const token of (advisory.vulnerable_versions ?? "").trim().split(/\s+/).filter(Boolean)) {
43
+ const value = token.replace(/^[<>]=?|^=/, "").trim();
44
+ if (!value || value === "*")
45
+ continue;
46
+ if (token.startsWith(">=") || token.startsWith(">"))
47
+ introduced = value;
48
+ else if (token.startsWith("<="))
49
+ upper = { last_affected: value };
50
+ else if (token.startsWith("<"))
51
+ upper = { fixed: value };
52
+ }
53
+ // Some npm surfaces do send patched_versions. Honour it when the vulnerable
54
+ // range left the window open.
55
+ if (!upper && advisory.patched_versions) {
56
+ upper = { fixed: advisory.patched_versions.replace(/^>=/, "").trim() };
57
+ }
58
+ return upper ? [{ introduced }, upper] : [{ introduced }];
59
+ }
9
60
  function normalizeAdvisory(advisory, pkgName) {
10
- const id = advisory.ghsa_id ?? `NPM-${advisory.id}`;
61
+ const id = advisoryId(advisory);
11
62
  return {
12
63
  id,
13
64
  aliases: advisory.cve_ids ?? [],
@@ -16,17 +67,7 @@ function normalizeAdvisory(advisory, pkgName) {
16
67
  affected: [
17
68
  {
18
69
  package: { ecosystem: "npm", name: pkgName },
19
- ranges: [
20
- {
21
- type: "ECOSYSTEM",
22
- events: [
23
- { introduced: "0" },
24
- ...(advisory.patched_versions
25
- ? [{ fixed: advisory.patched_versions.replace(/^>=/, "") }]
26
- : []),
27
- ],
28
- },
29
- ],
70
+ ranges: [{ type: "ECOSYSTEM", events: rangeEvents(advisory) }],
30
71
  },
31
72
  ],
32
73
  severity: [],
@@ -35,13 +76,25 @@ function normalizeAdvisory(advisory, pkgName) {
35
76
  },
36
77
  };
37
78
  }
79
+ /** Whether this advisory's declared range covers the version we are asking about. */
80
+ function coversVersion(advisory, version) {
81
+ const range = advisory.vulnerable_versions?.trim();
82
+ if (!range || range === "*")
83
+ return true;
84
+ return satisfiesRange(version, range);
85
+ }
38
86
  export async function queryNpmAdvisoryGaps(packages, options = {}) {
39
87
  if (options.offline || packages.length === 0)
40
88
  return [];
41
89
  const fetchImpl = options.fetchImpl ?? fetch;
90
+ // Every version, not one. Assigning rather than appending meant a tree holding
91
+ // six copies of a package asked about whichever came last, and the single
92
+ // answer was then handed to all six.
42
93
  const body = {};
43
94
  for (const pkg of packages) {
44
- body[pkg.name] = [pkg.version];
95
+ const versions = (body[pkg.name] ??= []);
96
+ if (!versions.includes(pkg.version))
97
+ versions.push(pkg.version);
45
98
  }
46
99
  let data;
47
100
  try {
@@ -68,6 +121,10 @@ export async function queryNpmAdvisoryGaps(packages, options = {}) {
68
121
  for (const raw of advisories) {
69
122
  if (!isValidAdvisory(raw))
70
123
  continue;
124
+ // The reply is per package and says nothing about which version each
125
+ // advisory belongs to, so the range has to decide.
126
+ if (!coversVersion(raw, pkg.version))
127
+ continue;
71
128
  vulns.push(normalizeAdvisory(raw, pkg.name));
72
129
  }
73
130
  if (vulns.length > 0)
@@ -1,3 +1,17 @@
1
1
  // Project-wide audit-log event vocabulary. NDJSON stream: one event per line.
2
2
  // All events share { ts, type, schemaVersion }.
3
3
  export const AUDIT_LOG_SCHEMA_VERSION = 1;
4
+ /** Fields for a cve.fix.applied audit event from a suggested-fix target. */
5
+ export function buildCveFixAppliedEvent(params) {
6
+ return {
7
+ ts: params.ts,
8
+ type: "cve.fix.applied",
9
+ schemaVersion: AUDIT_LOG_SCHEMA_VERSION,
10
+ package: params.package,
11
+ fromVersion: params.fromVersion,
12
+ toVersion: params.toVersion,
13
+ mechanism: params.mechanism,
14
+ ...(params.childPackage ? { childPackage: params.childPackage } : {}),
15
+ ...(params.childTargetVersion ? { childTargetVersion: params.childTargetVersion } : {}),
16
+ };
17
+ }
package/dist/cli/args.js CHANGED
@@ -301,11 +301,17 @@ export function parseArgs(argv) {
301
301
  continue;
302
302
  }
303
303
  if (arg === "--output") {
304
- options.output = argv[++i];
304
+ const val = argv[++i];
305
+ if (!val || val.startsWith("-"))
306
+ throw new Error("--output requires a directory argument");
307
+ options.output = val;
305
308
  continue;
306
309
  }
307
310
  if (arg.startsWith("--output=")) {
308
- options.output = arg.slice("--output=".length);
311
+ const val = arg.slice("--output=".length);
312
+ if (!val || val.startsWith("-"))
313
+ throw new Error("--output requires a directory argument");
314
+ options.output = val;
309
315
  continue;
310
316
  }
311
317
  if (arg === "--search-depth") {
package/dist/cli/help.js CHANGED
@@ -37,6 +37,7 @@ export function printHelp() {
37
37
  " --sbom <format> Write an SBOM: cyclonedx (1.6) or spdx (2.3), to a timestamped file",
38
38
  " --sbom-inventory-only Omit the vulnerability overlay from --sbom, leaving a pure inventory",
39
39
  " --cdx Alias for --sbom cyclonedx",
40
+ " --output <dir> Directory for --json, --sarif and --sbom files (default: current directory)",
40
41
  " --no-open Don't auto-open the report in the browser",
41
42
  " --fix Apply validated direct dependency fixes and rescan",
42
43
  " --ratchet Save current findings as baseline or, if baseline exists, only fail on new findings",
@@ -87,6 +88,7 @@ export function printHelp() {
87
88
  " cve-lite . --fail-on high Exit 1 if any high or critical findings are found",
88
89
  " cve-lite . --incomplete-policy error Exit 3 if detection data is incomplete",
89
90
  " cve-lite . --json Write findings to a timestamped JSON file",
91
+ " cve-lite . --sarif --output out Write the SARIF file into ./out",
90
92
  " cve-lite . --report Generate an interactive HTML report",
91
93
  " cve-lite . --fix Apply validated direct dependency fixes and rescan",
92
94
  " cve-lite . --offline Scan using the local advisory database (no network)",
@@ -46,6 +46,9 @@ export async function validateOptions(options) {
46
46
  if (options.report && options.json) {
47
47
  throw new Error("--report cannot be used with --json. Use --report to generate an HTML report, or --json to save scan results as JSON, not both.");
48
48
  }
49
+ if (options.output && !(options.json || options.sarif || resolveSbomFormat(options))) {
50
+ throw new Error("--output requires --json, --sarif or --sbom. Add one of them to write a file into the output directory, or remove --output.");
51
+ }
49
52
  if (options.caCert) {
50
53
  try {
51
54
  validateCaCertFile(options.caCert);
@@ -1,26 +1,37 @@
1
+ import { DEFAULT_BATCH_SIZE } from "../constants.js";
2
+ import { chunk } from "../utils/array.js";
1
3
  const EPSS_API_URL = "https://api.first.org/data/v1/epss";
2
- export async function fetchEpssScores(cveIds, fetchImpl = fetch) {
3
- const unique = [...new Set(cveIds.map(id => id.toUpperCase()).filter(id => id.startsWith("CVE-")))];
4
- if (unique.length === 0)
5
- return new Map();
4
+ async function fetchBatch(cveIds, fetchImpl) {
6
5
  try {
7
- const url = `${EPSS_API_URL}?cve=${unique.join(",")}`;
6
+ const url = `${EPSS_API_URL}?cve=${cveIds.join(",")}`;
8
7
  const response = await fetchImpl(url);
9
8
  if (!response.ok)
10
- return new Map();
9
+ return [];
11
10
  const json = await response.json();
12
- const result = new Map();
11
+ const scores = [];
13
12
  for (const item of json.data ?? []) {
14
13
  const epss = parseFloat(item.epss);
15
14
  const percentile = parseFloat(item.percentile);
16
15
  if (!isNaN(epss) && !isNaN(percentile)) {
17
16
  const cve = item.cve.toUpperCase();
18
- result.set(cve, { cve, epss, percentile });
17
+ scores.push({ cve, epss, percentile });
19
18
  }
20
19
  }
21
- return result;
20
+ return scores;
22
21
  }
23
22
  catch {
23
+ return [];
24
+ }
25
+ }
26
+ export async function fetchEpssScores(cveIds, fetchImpl = fetch) {
27
+ const unique = [...new Set(cveIds.map(id => id.toUpperCase()).filter(id => id.startsWith("CVE-")))];
28
+ if (unique.length === 0)
24
29
  return new Map();
30
+ const batches = chunk(unique, DEFAULT_BATCH_SIZE);
31
+ const scores = (await Promise.all(batches.map(batch => fetchBatch(batch, fetchImpl)))).flat();
32
+ const result = new Map();
33
+ for (const score of scores) {
34
+ result.set(score.cve, score);
25
35
  }
36
+ return result;
26
37
  }
@@ -1,5 +1,5 @@
1
1
  import { randomUUID } from "node:crypto";
2
- import { findSuggestedCommandForFinding } from "../remediation/fix-commands.js";
2
+ import { findFixTargetForFinding, findSuggestedCommandForFinding } from "../remediation/fix-commands.js";
3
3
  import { getRecommendedAction } from "./formatters.js";
4
4
  import { getCliVersion } from "../utils/version-info.js";
5
5
  import { buildPurl } from "../utils/purl.js";
@@ -49,6 +49,9 @@ export function buildCycloneDxBom(allPackages, findings, projectMeta, version, p
49
49
  addProperty("fix-version-published-at", finding.fixVersionPublishedAt);
50
50
  addProperty("versions-scanned", finding.validatedTargetScannedVersions);
51
51
  addProperty("versions-still-vulnerable", finding.validatedTargetKnownVulnerableVersions);
52
+ const planTarget = plan ? findFixTargetForFinding(plan, finding) : null;
53
+ addProperty("child-package", planTarget?.childPackage);
54
+ addProperty("child-target-version", planTarget?.childTargetVersion);
52
55
  vulnerabilities.push({
53
56
  id: cveId,
54
57
  source: {
@@ -94,8 +97,8 @@ export function buildCycloneDxBom(allPackages, findings, projectMeta, version, p
94
97
  vulnerabilities,
95
98
  };
96
99
  }
97
- export function writeCycloneDxReport(allPackages, findings, plan, projectMeta) {
100
+ export function writeCycloneDxReport(allPackages, findings, plan, projectMeta, outputDir) {
98
101
  const filename = `cve-lite-scan-${sbomTimestamp()}.cdx.json`;
99
102
  const bom = buildCycloneDxBom(allPackages, findings, projectMeta, getCliVersion(), plan);
100
- return writeSbomFile(filename, bom, "CycloneDX report");
103
+ return writeSbomFile(filename, bom, "CycloneDX report", outputDir);
101
104
  }
@@ -12,6 +12,7 @@ import { renderMaintenanceFindingsHtml } from "./maintenance-findings-html.js";
12
12
  import { renderLicenseFindingsHtml } from "./license-findings-html.js";
13
13
  import { PRIORITY_SIGNAL_LABELS, PRIORITY_SIGNAL_DESCRIPTIONS, PRIORITY_SIGNAL_LEGEND_DESCRIPTIONS } from "../utils/priority-signal.js";
14
14
  import { UNVERIFIED_PARENT_UPGRADE_NOTE } from "../remediation/fix-commands.js";
15
+ import { formatParentUpdateChildNote } from "../remediation/parent-update-child-note.js";
15
16
  import { getCompletenessImpact } from "../scan/completeness.js";
16
17
  export function serializeHtmlFinding(finding, plan) {
17
18
  return {
@@ -870,9 +871,12 @@ export function renderFixPlan(plan) {
870
871
  const displayVersion = t.targetVersion;
871
872
  const isMajor = t.currentVersion ? isBreakingUpgrade(t.currentVersion, t.targetVersion) : false;
872
873
  const breakBadge = isMajor ? ` <span class="break-badge">⚠ breaking</span>` : "";
873
- const versionHtml = t.currentVersion
874
- ? `<span class="fix-target-pkg">${escapeHtml(t.package)}@${escapeHtml(t.currentVersion)}</span><span class="fix-target-arrow">→</span><span class="fix-target-to">${escapeHtml(displayVersion)}</span>`
875
- : `<span class="fix-target-pkg">${escapeHtml(t.package)}</span><span class="fix-target-arrow">→</span><span class="fix-target-to">${escapeHtml(displayVersion)}</span>`;
874
+ const childNote = formatParentUpdateChildNote(t);
875
+ const versionHtml = childNote
876
+ ? `<span class="fix-target-pkg">${escapeHtml(t.package)}${t.currentVersion ? `@${escapeHtml(t.currentVersion)}` : ""}</span><span class="fix-target-note">${escapeHtml(childNote)}</span>`
877
+ : t.currentVersion
878
+ ? `<span class="fix-target-pkg">${escapeHtml(t.package)}@${escapeHtml(t.currentVersion)}</span><span class="fix-target-arrow">→</span><span class="fix-target-to">${escapeHtml(displayVersion)}</span>`
879
+ : `<span class="fix-target-pkg">${escapeHtml(t.package)}</span><span class="fix-target-arrow">→</span><span class="fix-target-to">${escapeHtml(displayVersion)}</span>`;
876
880
  const statsHtml = t.scannedVersions != null
877
881
  ? ` <span class="fix-target-stats">${t.scannedVersions} scanned${t.knownVulnerableVersions != null ? ` · ${t.knownVulnerableVersions} still vulnerable` : ""}</span>`
878
882
  : "";
@@ -0,0 +1,20 @@
1
+ import fs from "node:fs";
2
+ import path from "node:path";
3
+ /** Directory for --json, --sarif and --sbom files: the working directory, or --output resolved against it and created when missing. */
4
+ export function resolveOutputDir(output) {
5
+ if (!output)
6
+ return process.cwd();
7
+ const dir = path.resolve(process.cwd(), output);
8
+ try {
9
+ fs.mkdirSync(dir, { recursive: true });
10
+ }
11
+ catch (err) {
12
+ throw new Error(`Failed to create output directory ${dir}: ${err instanceof Error ? err.message : String(err)}`, { cause: err });
13
+ }
14
+ return dir;
15
+ }
16
+ /** Path printed for a written file: relative to the working directory, or absolute when it lies outside it. */
17
+ export function displayOutputPath(outputPath) {
18
+ const relative = path.relative(process.cwd(), outputPath);
19
+ return relative.startsWith("..") ? outputPath : relative;
20
+ }
@@ -1,5 +1,6 @@
1
1
  import { chalk, stripAnsi } from "../utils/chalk.js";
2
- import { buildSuggestedFixCommandPlan, findFixTargetForFinding, UNVERIFIED_PARENT_UPGRADE_NOTE } from "../remediation/fix-commands.js";
2
+ import { buildSuggestedFixCommandPlan, planVersionForFinding, UNVERIFIED_PARENT_UPGRADE_NOTE } from "../remediation/fix-commands.js";
3
+ import { formatParentUpdateChildNote } from "../remediation/parent-update-child-note.js";
3
4
  import { isBreakingUpgrade } from "../utils/version.js";
4
5
  import { getPrimaryParent } from "../utils/finding.js";
5
6
  import { countUniqueAdvisories, countProdFindings, formatRelationshipLabel, formatRelLabel, formatRootDependencySummary, formatFixCommandWithPublishDates, formatCooldownWarning, } from "./formatters.js";
@@ -381,8 +382,9 @@ function findingToTableRow(finding, plan, skippedKeys) {
381
382
  // Prefer the version the fix plan will actually install. A package that is both
382
383
  // a direct finding and the parent of other findings needs a higher version than
383
384
  // its own advisory requires, and showing the lower one here contradicted the fix
384
- // command sitting a few lines above.
385
- const planTarget = plan ? findFixTargetForFinding(plan, finding)?.targetVersion : undefined;
385
+ // command sitting a few lines above. For parent-update this is the child's
386
+ // destination, not the parent's unchanged version stored on targetVersion.
387
+ const planTarget = plan ? planVersionForFinding(plan, finding) : undefined;
386
388
  const ownFixVersion = finding.validatedFirstFixedVersion ?? finding.firstFixedVersion;
387
389
  const fixVersion = planTarget ?? ownFixVersion ?? null;
388
390
  return {
@@ -422,6 +424,18 @@ function formatTargetDisplay(finding, fixVersion, isSkipped) {
422
424
  return chalk.yellow("⚠ Malicious");
423
425
  return chalk.yellow("⚠ no fix");
424
426
  }
427
+ function fixTargetContext(target) {
428
+ const childNote = formatParentUpdateChildNote(target);
429
+ const reason = target.reason ?? target.adjustmentNote ?? null;
430
+ if (childNote && reason) {
431
+ if (target.childPackage && target.childTargetVersion
432
+ && reason.includes(`${target.childPackage}@${target.childTargetVersion}`)) {
433
+ return reason;
434
+ }
435
+ return `${childNote}. ${reason}`;
436
+ }
437
+ return childNote ?? reason;
438
+ }
425
439
  function fixTargetToTableRow(target, context) {
426
440
  return {
427
441
  package: target.package,
@@ -441,7 +455,7 @@ function fixTargetToTableRow(target, context) {
441
455
  epss: context?.epss ?? null,
442
456
  signal: context?.prioritySignal ?? null,
443
457
  ids: context?.ids,
444
- context: target.reason ?? target.adjustmentNote ?? null,
458
+ context: fixTargetContext(target),
445
459
  };
446
460
  }
447
461
  /** The bold summary row under a fix table: only the validation counts carry values. */
@@ -5,6 +5,7 @@ import { getRecommendedAction, formatCooldownWarning } from "./formatters.js";
5
5
  import { getCliVersion } from "../utils/version-info.js";
6
6
  import { severityToSarifLevel } from "../utils/severity.js";
7
7
  import { sarifFingerprintHash } from "../utils/sarif.js";
8
+ import { displayOutputPath } from "./output-dir.js";
8
9
  import { buildOverrideSarifComponent, buildOverrideSarifResults } from "./override-findings-sarif.js";
9
10
  import { buildMaintenanceSarifComponent, buildMaintenanceSarifResults } from "./maintenance-findings-sarif.js";
10
11
  import { buildLicenseSarifComponent, buildLicenseSarifResults } from "./license-findings-sarif.js";
@@ -88,7 +89,8 @@ export function buildSarifOutput(findings, lockfileUri, version, plan, overrideF
88
89
  // If the recommended fix for this finding lands on a version inside the
89
90
  // project's configured release cooldown, surface that on the result so it
90
91
  // reaches Code Scanning (message text for humans, property for tooling).
91
- const cooldown = plan ? findFixTargetForFinding(plan, finding)?.cooldownWarning ?? null : null;
92
+ const planTarget = plan ? findFixTargetForFinding(plan, finding) : null;
93
+ const cooldown = planTarget?.cooldownWarning ?? null;
92
94
  const location = {
93
95
  physicalLocation: {
94
96
  artifactLocation: { uri: lockfileUri, uriBaseId: "%SRCROOT%" },
@@ -133,6 +135,10 @@ export function buildSarifOutput(findings, lockfileUri, version, plan, overrideF
133
135
  if (finding.validatedTargetKnownVulnerableVersions != null) {
134
136
  resultProperties.versionsStillVulnerable = finding.validatedTargetKnownVulnerableVersions;
135
137
  }
138
+ if (planTarget?.childPackage)
139
+ resultProperties.childPackage = planTarget.childPackage;
140
+ if (planTarget?.childTargetVersion)
141
+ resultProperties.childTargetVersion = planTarget.childTargetVersion;
136
142
  results.push({
137
143
  ruleId,
138
144
  ruleIndex: ruleIndexMap.get(ruleId),
@@ -192,10 +198,10 @@ export function buildSarifOutput(findings, lockfileUri, version, plan, overrideF
192
198
  ],
193
199
  };
194
200
  }
195
- export function writeSarifReport(findings, lockfileUri, plan, overrideFindings, maintenanceFindings, licenseFindings) {
201
+ export function writeSarifReport(findings, lockfileUri, plan, overrideFindings, maintenanceFindings, licenseFindings, outputDir = process.cwd()) {
196
202
  const ts = new Date().toISOString().replace(/[:.]/g, "-").slice(0, 19);
197
203
  const filename = `cve-lite-scan-${ts}.sarif`;
198
- const outputPath = path.join(process.cwd(), filename);
204
+ const outputPath = path.join(outputDir, filename);
199
205
  const sarif = buildSarifOutput(findings, lockfileUri, getCliVersion(), plan, overrideFindings, maintenanceFindings, licenseFindings);
200
206
  try {
201
207
  fs.writeFileSync(outputPath, JSON.stringify(sarif, null, 2));
@@ -207,5 +213,5 @@ export function writeSarifReport(findings, lockfileUri, plan, overrideFindings,
207
213
  catch { /* best-effort cleanup */ }
208
214
  throw new Error(`Failed to write SARIF report to ${outputPath}: ${err instanceof Error ? err.message : String(err)}`, { cause: err });
209
215
  }
210
- return filename;
216
+ return displayOutputPath(outputPath);
211
217
  }
@@ -1,14 +1,16 @@
1
1
  import fs from "node:fs";
2
2
  import path from "node:path";
3
+ import { displayOutputPath } from "./output-dir.js";
3
4
  /**
4
- * Writes an SBOM document to a timestamped file in the working directory.
5
+ * Writes an SBOM document to a timestamped file in the output directory,
6
+ * which defaults to the working directory.
5
7
  *
6
8
  * A partial file left behind by a failed write would look like a valid SBOM to
7
9
  * whatever consumes it next, so the partial output is removed before the error
8
10
  * propagates.
9
11
  */
10
- export function writeSbomFile(filename, document, label) {
11
- const outputPath = path.join(process.cwd(), filename);
12
+ export function writeSbomFile(filename, document, label, outputDir = process.cwd()) {
13
+ const outputPath = path.join(outputDir, filename);
12
14
  try {
13
15
  fs.writeFileSync(outputPath, JSON.stringify(document, null, 2));
14
16
  }
@@ -19,7 +21,7 @@ export function writeSbomFile(filename, document, label) {
19
21
  catch { /* best-effort cleanup */ }
20
22
  throw new Error(`Failed to write ${label} to ${outputPath}: ${err instanceof Error ? err.message : String(err)}`, { cause: err });
21
23
  }
22
- return filename;
24
+ return displayOutputPath(outputPath);
23
25
  }
24
26
  /** Filesystem-safe UTC stamp shared by every SBOM filename. */
25
27
  export function sbomTimestamp() {
@@ -286,8 +286,8 @@ export function buildSpdxDocument(allPackages, findings, projectMeta, version, p
286
286
  relationships,
287
287
  };
288
288
  }
289
- export function writeSpdxReport(allPackages, findings, plan, projectMeta, options = {}) {
289
+ export function writeSpdxReport(allPackages, findings, plan, projectMeta, options = {}, outputDir) {
290
290
  const filename = `cve-lite-scan-${sbomTimestamp()}.spdx.json`;
291
291
  const doc = buildSpdxDocument(allPackages, findings, projectMeta, getCliVersion(), plan, options);
292
- return writeSbomFile(filename, doc, "SPDX SBOM");
292
+ return writeSbomFile(filename, doc, "SPDX SBOM", outputDir);
293
293
  }
@@ -10,6 +10,7 @@ import { resolveDependencyEdges } from "./sbom-dependency-edges.js";
10
10
  import { resolveSbomFormat } from "../utils/sbom-format.js";
11
11
  import { overrideFindingsToJson } from "./override-findings-json.js";
12
12
  import { maintenanceFindingsToJson } from "./maintenance-findings-json.js";
13
+ import { resolveOutputDir, displayOutputPath } from "./output-dir.js";
13
14
  function readProjectMeta(projectPath) {
14
15
  try {
15
16
  const pkgPath = path.join(projectPath, "package.json");
@@ -29,10 +30,11 @@ function readProjectMeta(projectPath) {
29
30
  }
30
31
  }
31
32
  export async function writeOutputs(options, scanState, scanInput, projectPath) {
33
+ const outputDir = resolveOutputDir(options.output);
32
34
  if (options.json) {
33
35
  const ts = new Date().toISOString().replace(/[:.]/g, "-").slice(0, 19);
34
36
  const jsonFilename = `cve-lite-scan-${ts}.json`;
35
- const jsonOutputPath = path.join(process.cwd(), jsonFilename);
37
+ const jsonOutputPath = path.join(outputDir, jsonFilename);
36
38
  const payload = {
37
39
  projectPath,
38
40
  mode: scanInput.mode,
@@ -58,11 +60,11 @@ export async function writeOutputs(options, scanState, scanInput, projectPath) {
58
60
  : {};
59
61
  const combined = { ...payload, ...overridePayload, ...maintenancePayload, ...licensePayload };
60
62
  fs.writeFileSync(jsonOutputPath, JSON.stringify(combined, null, 2));
61
- console.log(`${chalk.gray("JSON saved to")} ${chalk.cyan(jsonFilename)}`);
63
+ console.log(`${chalk.gray("JSON saved to")} ${chalk.cyan(displayOutputPath(jsonOutputPath))}`);
62
64
  }
63
65
  if (options.sarif) {
64
66
  const lockfileUri = deriveLockfileUri(scanInput);
65
- const sarifFilename = writeSarifReport(scanState.sorted, lockfileUri, scanState.suggestedFixCommands, scanState.overrideFindings, scanState.maintenanceFindings, scanState.licenseFindings);
67
+ const sarifFilename = writeSarifReport(scanState.sorted, lockfileUri, scanState.suggestedFixCommands, scanState.overrideFindings, scanState.maintenanceFindings, scanState.licenseFindings, outputDir);
66
68
  console.log(`${chalk.gray("SARIF report written to")} ${chalk.cyan(sarifFilename)}`);
67
69
  }
68
70
  const sbomFormat = resolveSbomFormat(options);
@@ -74,11 +76,11 @@ export async function writeOutputs(options, scanState, scanInput, projectPath) {
74
76
  // Resolved from the lockfile graph where available. Empty for pnpm,
75
77
  // Yarn and Bun, which falls back to path-derived edges.
76
78
  dependencyEdges: resolveDependencyEdges(scanInput, scanState.allPackages),
77
- });
79
+ }, outputDir);
78
80
  console.log(`${chalk.gray("SPDX SBOM written to")} ${chalk.cyan(spdxFilename)}`);
79
81
  }
80
82
  else {
81
- const cdxFilename = writeCycloneDxReport(scanState.allPackages, scanState.sorted, scanState.suggestedFixCommands, projectMeta);
83
+ const cdxFilename = writeCycloneDxReport(scanState.allPackages, scanState.sorted, scanState.suggestedFixCommands, projectMeta, outputDir);
82
84
  console.log(`${chalk.gray("CycloneDX BOM written to")} ${chalk.cyan(cdxFilename)}`);
83
85
  }
84
86
  }
@@ -1,4 +1,5 @@
1
1
  import { satisfiesRange, coerceVersion, compareVersions, looksLikeVersion, isValidRange } from "../../utils/version.js";
2
+ import { pluralize } from "../../utils/string.js";
2
3
  import { jsonPointer } from "../parsing/json-pointer.js";
3
4
  const RULE_ID = "OA008";
4
5
  /**
@@ -41,7 +42,7 @@ export function detect(ctx) {
41
42
  if (vulnerable.length === 0)
42
43
  continue;
43
44
  const versions = vulnerable.map(c => c.version);
44
- const distinct = Array.from(new Set(versions)).sort();
45
+ const distinct = Array.from(new Set(versions)).sort(compareVersions);
45
46
  findings.push({
46
47
  ruleId: RULE_ID,
47
48
  severity: "critical",
@@ -49,7 +50,7 @@ export function detect(ctx) {
49
50
  location: { file: "package.json", jsonPath: jsonPointer(entry.path) },
50
51
  message: "Override floor not applied - vulnerable copy still on disk",
51
52
  details: `Override demands ${entry.packageName} ${pinValue}, but ${vulnerable.length} ` +
52
- `installed copy${vulnerable.length === 1 ? "" : "ies"} (${distinct.join(", ")}) ` +
53
+ `installed ${pluralize(vulnerable.length, "copy", "copies")} (${distinct.join(", ")}) ` +
53
54
  `${vulnerable.length === 1 ? "is" : "are"} below the floor. ` +
54
55
  `The override is not effective everywhere - likely a parent declares this dep ` +
55
56
  `as exact and wins resolution.`,