cve-lite-cli 1.41.5 → 1.42.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.
Files changed (72) hide show
  1. package/README.md +22 -19
  2. package/dist/advisory/detail-resolution.js +62 -0
  3. package/dist/advisory/local-db.js +90 -15
  4. package/dist/advisory/osv-advisory-source.js +113 -62
  5. package/dist/advisory/osv-sync.js +18 -16
  6. package/dist/advisory/sqlite.js +50 -0
  7. package/dist/audit-log/ndjson-writer.js +6 -3
  8. package/dist/audit-log/open-error.js +22 -0
  9. package/dist/cli/args.js +145 -87
  10. package/dist/cli/flags.js +2 -0
  11. package/dist/cli/help.js +6 -2
  12. package/dist/cli/overrides.js +5 -2
  13. package/dist/cli/validate.js +45 -5
  14. package/dist/constants.js +10 -0
  15. package/dist/index.js +15 -6
  16. package/dist/licenses/license-check.js +17 -4
  17. package/dist/osv/cache.js +7 -13
  18. package/dist/output/cyclonedx.js +57 -18
  19. package/dist/output/finding-display.js +8 -1
  20. package/dist/output/formatters.js +52 -11
  21. package/dist/output/html-reporter.js +40 -8
  22. package/dist/output/override-findings-terminal.js +21 -13
  23. package/dist/output/printers.js +185 -76
  24. package/dist/output/sarif.js +182 -16
  25. package/dist/output/spdx.js +15 -1
  26. package/dist/output/write-outputs.js +29 -20
  27. package/dist/overrides/context-builder.js +1 -7
  28. package/dist/overrides/detectors/oa005-nested-ineffective.js +6 -1
  29. package/dist/overrides/detectors/oa008-materialized.js +33 -10
  30. package/dist/overrides/detectors/oa009-stale-floor.js +2 -2
  31. package/dist/overrides/detectors/oa010-vulnerable-floor.js +19 -13
  32. package/dist/overrides/detectors/phantom-utils.js +2 -10
  33. package/dist/overrides/fixer.js +13 -2
  34. package/dist/overrides/index.js +1 -0
  35. package/dist/overrides/types.js +15 -1
  36. package/dist/parsers/bun-lock.js +6 -0
  37. package/dist/parsers/index.js +177 -40
  38. package/dist/parsers/multi-package.js +4 -0
  39. package/dist/parsers/package-lock.js +6 -2
  40. package/dist/parsers/pnpm-lock.js +4 -7
  41. package/dist/parsers/requirements-txt.js +185 -0
  42. package/dist/parsers/utils.js +11 -6
  43. package/dist/parsers/yarn-lock.js +1 -5
  44. package/dist/remediation/fix-commands.js +60 -36
  45. package/dist/remediation/parent-update-child-note.js +3 -2
  46. package/dist/scan/completeness.js +57 -4
  47. package/dist/scan/multi-folder-scan.js +27 -13
  48. package/dist/scan/single-scan.js +118 -37
  49. package/dist/scanner.js +59 -36
  50. package/dist/types.js +1 -1
  51. package/dist/utils/array.js +5 -0
  52. package/dist/utils/baseline.js +8 -2
  53. package/dist/utils/chalk.js +1 -3
  54. package/dist/utils/create-pr.js +2 -2
  55. package/dist/utils/debug-bundle.js +37 -22
  56. package/dist/utils/debug-project.js +6 -5
  57. package/dist/utils/debug-redaction.js +1 -1
  58. package/dist/utils/effective-options.js +5 -1
  59. package/dist/utils/finding.js +4 -0
  60. package/dist/utils/fix-runner.js +110 -36
  61. package/dist/utils/import-type-queries.js +5 -1
  62. package/dist/utils/install-command.js +6 -0
  63. package/dist/utils/malicious.js +11 -0
  64. package/dist/utils/package-identity.js +12 -2
  65. package/dist/utils/path-coverage.js +1 -5
  66. package/dist/utils/sanitize.js +59 -0
  67. package/dist/utils/sbom-format.js +17 -8
  68. package/dist/utils/severity.js +61 -7
  69. package/dist/utils/url.js +175 -0
  70. package/dist/utils/version.js +44 -0
  71. package/dist/utils/vuln.js +11 -14
  72. package/package.json +2 -4
@@ -2,41 +2,51 @@ import path from "node:path";
2
2
  import { loadPackages, buildNoPackagesMessage } from "../parsers/index.js";
3
3
  import { scanPackages, buildCoverageNotes, createAdvisorySource } from "../scanner.js";
4
4
  import { normalizeSeverity } from "../osv/severity.js";
5
- import { OVERRIDES_COMMAND, RATCHET_BASELINE_COMMIT_HINT } from "../constants.js";
5
+ import { OVERRIDES_COMMAND, RATCHET_BASELINE_COMMIT_HINT, DEFAULT_OSV_URL, DEFAULT_OSV_NPM_DUMP_URL } from "../constants.js";
6
6
  import { chalk } from "../utils/chalk.js";
7
7
  import { buildSuggestedFixCommandPlan } from "../remediation/fix-commands.js";
8
8
  import { scanProjectForPackageUsage, usageScanTruncationWarning } from "../usage/scanner.js";
9
9
  import { offlineDbSyncHint } from "../utils/network.js";
10
10
  import { formatAdvisoryDbFreshness } from "../utils/time.js";
11
11
  import { pluralize } from "../utils/string.js";
12
- import { EXIT_ERROR } from "../types.js";
13
- import { formatAdvisorySourceLine, logInfo, logWarn, printCacheSummary, sortFindingsForOutput, } from "../output/formatters.js";
14
- import { GATE_CLASS_LABELS, countBySeverity, failingGateSummary } from "../utils/severity.js";
12
+ import { EXIT_ERROR, EXIT_OK } from "../types.js";
13
+ import { formatAdvisorySourceLine, logInfo, logWarn, logEmptyScan, printCacheSummary, sortFindingsForOutput, } from "../output/formatters.js";
14
+ import { GATE_CLASS_LABELS, countBySeverity, failingGateSummary, unresolvedGateNotice, vulnerabilityGateClasses, } from "../utils/severity.js";
15
15
  import { buildReportData, writeHtmlReport } from "../output/html-reporter.js";
16
16
  import { buildScanJson } from "../output/scan-json.js";
17
17
  import { writeOutputs } from "../output/write-outputs.js";
18
+ import { SQLiteUnavailableError } from "../advisory/sqlite.js";
18
19
  import { isOutputStdout } from "../output/output-dir.js";
19
20
  import { selectFindingsForTable } from "../output/finding-display.js";
20
- import { printActionSummary, printCompactOutput, printCoverage, printFinalStatus, printOverrideHint, printSkippedDependencies, printSuggestedFixCommands, printSuggestedFixCommandSkips, printSummary, printTable, } from "../output/printers.js";
21
+ import { printActionSummary, printCompactOutput, printCoverage, printFinalStatus, printOverrideHint, printSkippedDependencies, printSuggestedFixCommands, printSuggestedFixCommandSkips, printSummary, printTable, PYTHON_GATE_EXCLUSION_NOTE, } from "../output/printers.js";
21
22
  import { renderOverrideFindings, renderSkippedOverrideRules } from "../output/override-findings-terminal.js";
22
23
  import { detectDM001 } from "../maintenance/dm001-maintenance-risk.js";
23
24
  import { renderMaintenanceFindings } from "../output/maintenance-terminal.js";
24
25
  import { detectLicenseIssues } from "../licenses/license-check.js";
25
26
  import { renderLicenseFindings } from "../output/license-terminal.js";
26
27
  import { readDirectDependencyNames, hasOverrideEntries } from "../utils/package-json.js";
28
+ import { isGatableFinding } from "../utils/finding.js";
27
29
  import { applyFixesIfRequested, printFixModeSummary, writeFixResultJson, } from "../utils/fix-runner.js";
28
30
  import { runOverrideAudit } from "./override-audit.js";
29
31
  import { buildFixResultAppliedEntries, createPullRequestForFixes, } from "../utils/create-pr.js";
30
32
  import { buildCveFixAppliedEvent } from "../audit-log/events.js";
31
33
  import { readBaseline, writeBaseline, filterNewFindings, ratchetOutcome } from "../utils/baseline.js";
32
- import { formatDiagnosticMessage, getCompletenessImpact, shouldFailForIncompleteScan } from "./completeness.js";
34
+ import { formatDiagnosticMessage, getCompletenessImpact, printStaleCacheGateReason, shouldFailForIncompleteScan, } from "./completeness.js";
33
35
  import { packageManagerForSource, resolveRegistryConfig } from "../utils/registry-config.js";
34
36
  import { isNpmLockSource } from "../utils/package-manager-source.js";
37
+ function pythonGateExclusionNotes(findings) {
38
+ return findings.some(finding => !isGatableFinding(finding))
39
+ ? [PYTHON_GATE_EXCLUSION_NOTE]
40
+ : [];
41
+ }
35
42
  export async function handleSingleFolderScan(params) {
36
43
  const { projectPath, projectArg, batchSize, searchDepth, options, debugLog, fetchImpl, auditLog, scanStartedAt, cliVersion, onScanJsonPath, } = params;
44
+ let scanInput = loadPackages(projectPath, !!options.prodOnly, searchDepth, { python: !!options.python });
45
+ let packages = scanInput.packages;
37
46
  let advisorySourceLine = "";
38
47
  let advisoryDbFreshnessLine = null;
39
48
  let advisoryDbWarning = null;
49
+ let advisoryDbMetadata = null;
40
50
  try {
41
51
  const advisorySource = createAdvisorySource({
42
52
  osvUrl: options.osvUrl,
@@ -45,14 +55,17 @@ export async function handleSingleFolderScan(params) {
45
55
  debugLog,
46
56
  fetchImpl,
47
57
  });
48
- advisorySourceLine = advisorySource.sourceLabel;
58
+ advisorySourceLine = options.python && !options.osvUrl && !advisorySource.offline
59
+ ? `OSV (${DEFAULT_OSV_URL})`
60
+ : advisorySource.sourceLabel;
49
61
  debugLog("Advisory source", {
50
62
  mode: advisorySource.offline ? "offline" : "online",
51
- url: options.osvUrl ?? (advisorySource.offline ? null : "https://api.osv.dev"),
63
+ url: options.osvUrl ?? (advisorySource.offline ? null : DEFAULT_OSV_URL),
52
64
  label: advisorySourceLine,
53
65
  });
54
66
  if (advisorySource.offline) {
55
67
  const metadata = advisorySource.advisoryDbMetadata;
68
+ advisoryDbMetadata = metadata;
56
69
  advisoryDbFreshnessLine = formatAdvisoryDbFreshness(metadata?.lastSyncAt ?? null);
57
70
  if (advisorySource.advisoryDbIsStale) {
58
71
  advisoryDbWarning = metadata?.lastSyncAt
@@ -63,12 +76,15 @@ export async function handleSingleFolderScan(params) {
63
76
  advisorySource.cleanup();
64
77
  }
65
78
  catch (error) {
79
+ if (error instanceof SQLiteUnavailableError)
80
+ throw error;
66
81
  if (options.offline || options.offlineDb) {
67
82
  const reason = error instanceof Error ? error.message : String(error);
68
83
  throw new Error(`Offline advisory database is not available: ${reason}\n${offlineDbSyncHint(options.offlineDb).join("\n")}`);
69
84
  }
70
85
  throw error;
71
86
  }
87
+ const sbomAdvisoryMetadata = buildSbomAdvisoryMetadata(options, advisoryDbMetadata);
72
88
  if (!options.json && !options.ratchet && !isOutputStdout(options.output)) {
73
89
  if (options.offline || options.offlineDb) {
74
90
  console.log(chalk.gray("Offline mode:") + " " + chalk.yellow("enabled") + " " + chalk.gray("(no external advisory calls will be made)"));
@@ -83,8 +99,6 @@ export async function handleSingleFolderScan(params) {
83
99
  if (advisoryDbWarning) {
84
100
  logWarn(advisoryDbWarning, options);
85
101
  }
86
- let scanInput = loadPackages(projectPath, !!options.prodOnly, searchDepth);
87
- let packages = scanInput.packages;
88
102
  // Reported only when the project configured one, so an unconfigured scan says nothing
89
103
  // new. An adopter whose results differ from public npm can then see why without asking.
90
104
  const reportedRegistry = resolveRegistryConfig({
@@ -131,17 +145,25 @@ export async function handleSingleFolderScan(params) {
131
145
  }
132
146
  }
133
147
  if (packages.length === 0) {
134
- debugLog("Scan skipped", { reason: "no packages found", projectPath });
135
- logWarn(buildNoPackagesMessage(projectPath), options);
136
- auditLog.emit({
137
- ts: new Date().toISOString(),
138
- type: "scan.finished",
139
- schemaVersion: 1,
140
- durationMs: Date.now() - scanStartTime,
141
- findingsCount: 0,
142
- exitCode: 0,
143
- });
144
- return 0;
148
+ debugLog("Scan packages empty", { reason: "no packages found", projectPath });
149
+ // A Python input whose every line was skipped is not a clean scan: continue to
150
+ // scanProject so the skipped entries become detection-gap diagnostics instead
151
+ // of an early "no packages" success.
152
+ const hasSkippedPythonInput = !!options.python &&
153
+ (scanInput.skippedDependencies.length > 0 || (scanInput.unscannedFiles?.length ?? 0) > 0);
154
+ if (!hasSkippedPythonInput) {
155
+ const exitCode = options.allowEmpty ? EXIT_OK : EXIT_ERROR;
156
+ logEmptyScan(buildNoPackagesMessage(projectPath, options), exitCode, options);
157
+ auditLog.emit({
158
+ ts: new Date().toISOString(),
159
+ type: "scan.finished",
160
+ schemaVersion: 1,
161
+ durationMs: Date.now() - scanStartTime,
162
+ findingsCount: 0,
163
+ exitCode,
164
+ });
165
+ return exitCode;
166
+ }
145
167
  }
146
168
  if (!options.json && !options.ratchet && !isOutputStdout(options.output))
147
169
  console.log();
@@ -155,8 +177,9 @@ export async function handleSingleFolderScan(params) {
155
177
  });
156
178
  const findingsBeforeFixList = scanState.sorted;
157
179
  const findingsBeforeFix = findingsBeforeFixList.length;
180
+ let findingsBeforeBaseline = scanState.sorted;
158
181
  let fixResult = null;
159
- let baseline = readBaseline(projectArg ?? ".");
182
+ let baseline = readBaseline(projectArg ?? projectPath ?? ".");
160
183
  let suppressedCount = 0;
161
184
  // Collect override findings if --check-overrides is set.
162
185
  // Boundary: override hygiene is independent of the CVE ratchet/baseline. The
@@ -212,20 +235,21 @@ export async function handleSingleFolderScan(params) {
212
235
  });
213
236
  if (fixResult.appliedFixCount > 0) {
214
237
  console.log(`${chalk.cyan("⠋")} ${chalk.gray("Rescanning project...")}`);
215
- scanInput = loadPackages(projectPath, !!options.prodOnly, searchDepth);
238
+ scanInput = loadPackages(projectPath, !!options.prodOnly, searchDepth, { python: !!options.python });
216
239
  packages = scanInput.packages;
217
240
  if (packages.length === 0) {
218
241
  debugLog("Scan skipped", { reason: "no packages found after fix rescan", projectPath });
219
- logWarn(buildNoPackagesMessage(projectPath), options);
242
+ const exitCode = options.allowEmpty ? EXIT_OK : EXIT_ERROR;
243
+ logEmptyScan(buildNoPackagesMessage(projectPath, options), exitCode, options);
220
244
  auditLog.emit({
221
245
  ts: new Date().toISOString(),
222
246
  type: "scan.finished",
223
247
  schemaVersion: 1,
224
248
  durationMs: Date.now() - scanStartTime,
225
249
  findingsCount: 0,
226
- exitCode: 0,
250
+ exitCode,
227
251
  });
228
- return 0;
252
+ return exitCode;
229
253
  }
230
254
  scanState = await scanProject({
231
255
  scanInput,
@@ -235,6 +259,7 @@ export async function handleSingleFolderScan(params) {
235
259
  debugLog,
236
260
  fetchImpl,
237
261
  });
262
+ findingsBeforeBaseline = scanState.sorted;
238
263
  }
239
264
  }
240
265
  let overridesFixHookResult = null;
@@ -363,14 +388,21 @@ export async function handleSingleFolderScan(params) {
363
388
  // This writes from inside the ratchet block rather than falling through, deliberately:
364
389
  // the code between here and that call re-applies the baseline filter for non-ratchet runs,
365
390
  // so falling through would filter an already-filtered set.
366
- const finishRatchetRun = async (reported, accepted, exitCode) => {
391
+ const finishRatchetRun = async (reported, accepted, ratchetExitCode) => {
392
+ // Cached details stood in for a failed lookup, so the baseline was judged on
393
+ // severities that may be out of date; a strict gate fails here too (#1443).
394
+ const incompleteFailure = shouldFailForIncompleteScan(scanState.completeness, options.incompletePolicy);
395
+ if (incompleteFailure) {
396
+ printStaleCacheGateReason(scanState.completeness, !!options.json || isOutputStdout(options.output));
397
+ }
398
+ const exitCode = incompleteFailure ? EXIT_ERROR : ratchetExitCode;
367
399
  await writeOutputs(options, {
368
400
  registry: reportedRegistry,
369
401
  sorted: reported,
370
402
  acceptedFindings: accepted,
371
403
  allPackages: scanState.allPackages,
372
404
  suggestedFixCommands: scanState.suggestedFixCommands,
373
- coverage: scanState.coverage,
405
+ coverage: [...scanState.coverage, ...pythonGateExclusionNotes(scanState.sorted)],
374
406
  minSeverity: scanState.minSeverity,
375
407
  tableFindings: scanState.tableFindings,
376
408
  completeness: scanState.completeness,
@@ -381,6 +413,7 @@ export async function handleSingleFolderScan(params) {
381
413
  maintenanceFindings: [],
382
414
  licenseFindings: [],
383
415
  licenseLimitedToDirectOnly: false,
416
+ advisoryMetadata: sbomAdvisoryMetadata,
384
417
  }, scanInput, projectPath);
385
418
  auditLog.emit({
386
419
  ts: new Date().toISOString(),
@@ -412,7 +445,7 @@ export async function handleSingleFolderScan(params) {
412
445
  }
413
446
  const outcome = ratchetOutcome(baseline, scanState.sorted);
414
447
  if (outcome.action === "save") {
415
- writeBaseline(projectArg ?? ".", scanState.sorted);
448
+ writeBaseline(projectArg ?? projectPath ?? ".", scanState.sorted);
416
449
  const count = scanState.sorted.length;
417
450
  if (!isStdout) {
418
451
  console.log(chalk.green(`✓ Baseline saved to .cve-lite/baseline.json with ${count} ${count === 1 ? "finding" : "findings"}. Future scans will only report findings above this baseline.`));
@@ -421,7 +454,7 @@ export async function handleSingleFolderScan(params) {
421
454
  }
422
455
  }
423
456
  // A missing baseline accepts no debt, including on fresh CI checkouts.
424
- const gateLine = failingGateSummary([{ label: GATE_CLASS_LABELS.vulnerability, findings: scanState.sorted }], options.failOn);
457
+ const gateLine = failingGateSummary(vulnerabilityGateClasses(scanState.sorted.filter(isGatableFinding)), options.failOn);
425
458
  if (gateLine && !options.json && !isStdout && !options.fix) {
426
459
  console.log(chalk.red(gateLine));
427
460
  }
@@ -434,6 +467,7 @@ export async function handleSingleFolderScan(params) {
434
467
  }
435
468
  const { newFindings, suppressedCount: sc } = outcome;
436
469
  const suppressedLabel = `${sc} existing ${sc === 1 ? "finding" : "findings"} suppressed`;
470
+ const gatableNewFindings = newFindings.filter(isGatableFinding);
437
471
  if (newFindings.length === 0) {
438
472
  if (!isStdout) {
439
473
  console.log(chalk.green(`No new findings above baseline - ${suppressedLabel}`));
@@ -448,14 +482,18 @@ export async function handleSingleFolderScan(params) {
448
482
  const ids = f.vulnerabilities.map(v => v.id).join(", ");
449
483
  console.log(` ${chalk.yellow(f.severity)} ${f.pkg.name}@${f.pkg.version}${ids ? ` (${ids})` : ""}`);
450
484
  }
451
- console.log(chalk.gray("To accept these, re-baseline intentionally by deleting .cve-lite/baseline.json and re-running --ratchet."));
485
+ if (gatableNewFindings.length > 0) {
486
+ console.log(chalk.gray("To accept these, re-baseline intentionally by deleting .cve-lite/baseline.json and re-running --ratchet."));
487
+ }
452
488
  }
453
489
  // The build fails here because something new appeared, which is exactly the run where a
454
490
  // machine-readable artefact matters most, and it produced none.
455
491
  const acceptedHere = scanState.sorted.filter(f => !newFindings.includes(f));
456
- return finishRatchetRun(newFindings, acceptedHere, 1);
492
+ const exitCode = gatableNewFindings.length > 0 ? 1 : 0;
493
+ return finishRatchetRun(newFindings, acceptedHere, exitCode);
457
494
  }
458
495
  // auto-apply baseline if it exists - filter before output
496
+ findingsBeforeBaseline = scanState.sorted;
459
497
  if (baseline) {
460
498
  const filtered = filterNewFindings(scanState.sorted, baseline);
461
499
  scanState.sorted = filtered.newFindings;
@@ -483,6 +521,7 @@ export async function handleSingleFolderScan(params) {
483
521
  directDeps,
484
522
  isNpm: isNpmLockSource(scanInput.source),
485
523
  isOffline: !!options.offline || !!options.offlineDb,
524
+ prodOnly: options.prodOnly,
486
525
  });
487
526
  licenseFindings = licenseResult.findings;
488
527
  licenseLimitedToDirectOnly = licenseResult.limitedToDirectOnly;
@@ -492,7 +531,7 @@ export async function handleSingleFolderScan(params) {
492
531
  sorted: scanState.sorted,
493
532
  allPackages: scanState.allPackages,
494
533
  suggestedFixCommands: scanState.suggestedFixCommands,
495
- coverage: scanState.coverage,
534
+ coverage: [...scanState.coverage, ...pythonGateExclusionNotes(scanState.sorted)],
496
535
  minSeverity: scanState.minSeverity,
497
536
  tableFindings: scanState.tableFindings,
498
537
  completeness: scanState.completeness,
@@ -503,6 +542,7 @@ export async function handleSingleFolderScan(params) {
503
542
  maintenanceFindings,
504
543
  licenseFindings,
505
544
  licenseLimitedToDirectOnly,
545
+ advisoryMetadata: sbomAdvisoryMetadata,
506
546
  }, scanInput, projectPath);
507
547
  if (scanJsonPath)
508
548
  onScanJsonPath?.(scanJsonPath);
@@ -584,7 +624,7 @@ export async function handleSingleFolderScan(params) {
584
624
  packageCount: packages.length,
585
625
  findings: scanState.sorted,
586
626
  suggestedFixCommands: scanState.suggestedFixCommands,
587
- notes: [...scanInput.notes, ...scanState.coverage],
627
+ notes: [...scanInput.notes, ...scanState.coverage, ...pythonGateExclusionNotes(scanState.sorted)],
588
628
  warnings: scanInput.warnings,
589
629
  skippedDependencies: scanInput.skippedDependencies,
590
630
  // undefined (not []) when override checking was not requested, so the HTML
@@ -608,7 +648,7 @@ export async function handleSingleFolderScan(params) {
608
648
  registry: reportedRegistry,
609
649
  findings: scanState.sorted,
610
650
  suggestedFixCommands: scanState.suggestedFixCommands,
611
- coverage: scanState.coverage,
651
+ coverage: [...scanState.coverage, ...pythonGateExclusionNotes(scanState.sorted)],
612
652
  completeness: scanState.completeness,
613
653
  overrideFindings,
614
654
  // Gated on the flag deliberately, unlike overrideFindings above. An absent
@@ -652,16 +692,23 @@ export async function handleSingleFolderScan(params) {
652
692
  // The gate and the line that explains it come from one call, so the exit code
653
693
  // and the printed reason cannot drift apart.
654
694
  const gateLine = failingGateSummary([
655
- { label: GATE_CLASS_LABELS.vulnerability, findings: scanState.sorted },
695
+ ...vulnerabilityGateClasses(scanState.sorted.filter(isGatableFinding)),
656
696
  { label: GATE_CLASS_LABELS.overrideHygiene, findings: overrideFindings },
657
697
  { label: GATE_CLASS_LABELS.maintenanceRisk, findings: maintenanceFindings },
658
698
  ], options.failOn);
659
699
  const shouldFail = gateLine !== null;
660
700
  if (gateLine && !options.json && !isOutputStdout(options.output) && !options.fix)
661
701
  console.log(chalk.red(gateLine));
702
+ const unresolvedNotice = unresolvedGateNotice(findingsBeforeBaseline, options.failOn, options.incompletePolicy);
703
+ if (unresolvedNotice && !options.json && !isOutputStdout(options.output) && !options.fix) {
704
+ console.log(chalk.yellow(unresolvedNotice));
705
+ }
662
706
  // In fix mode, remaining transitive findings cannot be auto-fixed.
663
707
  // Exiting non-zero would prevent the Action PR step from running.
664
708
  const incompleteFailure = shouldFailForIncompleteScan(scanState.completeness, options.incompletePolicy);
709
+ if (incompleteFailure) {
710
+ printStaleCacheGateReason(scanState.completeness, !!options.json || isOutputStdout(options.output));
711
+ }
665
712
  const exitCode = incompleteFailure
666
713
  ? EXIT_ERROR
667
714
  : shouldFail && !options.fix
@@ -679,12 +726,36 @@ export async function handleSingleFolderScan(params) {
679
726
  return exitCode;
680
727
  }
681
728
  export async function scanProject(params) {
682
- const directDependencyNames = readDirectDependencyNames(params.projectPath, !!params.options.prodOnly);
729
+ const directDependencyNames = params.options.python
730
+ ? null
731
+ : readDirectDependencyNames(params.projectPath, !!params.options.prodOnly);
683
732
  const { findings, completeness } = await scanPackages(params.scanInput.packages, params.batchSize, params.options, {
684
733
  directDependencyNames,
685
734
  scanSource: params.scanInput.source,
686
735
  scanFilePath: params.scanInput.filePath,
687
736
  }, params.debugLog, params.fetchImpl);
737
+ if (params.scanInput.source === "requirements-txt" && params.scanInput.skippedDependencies.length > 0) {
738
+ completeness.complete = false;
739
+ const count = params.scanInput.skippedDependencies.length;
740
+ completeness.diagnostics.push({
741
+ code: "SKIPPED_DEPENDENCY",
742
+ severity: "warning",
743
+ message: formatDiagnosticMessage("SKIPPED_DEPENDENCY", count),
744
+ impact: "detection",
745
+ count,
746
+ });
747
+ }
748
+ const unscannedFilesCount = params.scanInput.unscannedFiles?.length ?? 0;
749
+ if (unscannedFilesCount > 0) {
750
+ completeness.complete = false;
751
+ completeness.diagnostics.push({
752
+ code: "UNSCANNED_REQUIREMENTS_FILE",
753
+ severity: "warning",
754
+ message: formatDiagnosticMessage("UNSCANNED_REQUIREMENTS_FILE", unscannedFilesCount),
755
+ impact: "detection",
756
+ count: unscannedFilesCount,
757
+ });
758
+ }
688
759
  let usageTruncated = false;
689
760
  if (params.options.usage) {
690
761
  logInfo(`Scanning project source for usage hints...`, params.options);
@@ -770,3 +841,13 @@ export async function scanProject(params) {
770
841
  completeness,
771
842
  };
772
843
  }
844
+ export function buildSbomAdvisoryMetadata(options, advisoryDbMetadata) {
845
+ const isOffline = Boolean(options.offline || options.offlineDb);
846
+ return {
847
+ offline: isOffline,
848
+ syncTimestamp: advisoryDbMetadata?.lastSyncAt ?? null,
849
+ sourceUrl: isOffline
850
+ ? (advisoryDbMetadata?.sourceUrl === DEFAULT_OSV_NPM_DUMP_URL ? DEFAULT_OSV_NPM_DUMP_URL : null)
851
+ : (!options.osvUrl || options.osvUrl === DEFAULT_OSV_URL ? DEFAULT_OSV_URL : null),
852
+ };
853
+ }
package/dist/scanner.js CHANGED
@@ -4,7 +4,7 @@ import { fetchEpssScores } from "./epss/client.js";
4
4
  import { chunk, runWithConcurrency } from "./utils/array.js";
5
5
  import { isPrivateRegistrySource, isGitSource, hasCommitShaPinning } from "./utils/advisory.js";
6
6
  import { collapseAliasedDuplicates, extractCveAliases, hasMaliciousAdvisory } from "./utils/vuln.js";
7
- import { compareVersions, isPep440Ecosystem, isPreReleaseVersion, looksLikeVersion, normalizeAdvisoryVersion } from "./utils/version.js";
7
+ import { compareVersions, isPep440Ecosystem, isPreReleaseVersion, looksLikeVersion, normalizeAdvisoryVersion, normalizePep503PackageName } from "./utils/version.js";
8
8
  import { pep440UnreadableApplies, readPep440Range, versionInPep440Window } from "./utils/versions/osv-range.js";
9
9
  import { loadCache, saveCache, isEntryStale } from "./osv/cache.js";
10
10
  import { maxSeverity } from "./osv/severity.js";
@@ -33,7 +33,8 @@ import path from "node:path";
33
33
  import { resolveRegistryConfig } from "./utils/registry-config.js";
34
34
  import { extractErrorMessage } from "./utils/network.js";
35
35
  import { logWarn } from "./output/formatters.js";
36
- import { formatDiagnosticMessage } from "./scan/completeness.js";
36
+ import { formatDiagnosticMessage, isCompleteGivenDiagnostics } from "./scan/completeness.js";
37
+ import { resolveAdvisoryDetail } from "./advisory/detail-resolution.js";
37
38
  import { packageInstanceKey, registryPackage, registryPackageName } from "./utils/package-identity.js";
38
39
  /**
39
40
  * Advisory id namespaces OSV does not serve. Ids with these prefixes come from
@@ -69,14 +70,6 @@ export function createAdvisorySource(options) {
69
70
  function getPackageCacheKey(pkg) {
70
71
  return `${pkg.ecosystem}:${registryPackageName(pkg)}@${pkg.version}`;
71
72
  }
72
- function isTransientFailure(error) {
73
- if (!(error instanceof Error))
74
- return true;
75
- const msg = error.message;
76
- if (msg.includes(" 404 ") || msg.includes(" 410 "))
77
- return false;
78
- return true;
79
- }
80
73
  function mergeResultsByPackage(results) {
81
74
  const map = new Map();
82
75
  for (const result of results) {
@@ -284,6 +277,8 @@ export async function scanPackages(packages, batchSize, options, context, debugL
284
277
  const transientDetailIds = new Set();
285
278
  const offlineMissingDetailIds = new Set();
286
279
  const confirmedMissingDetailIds = new Set();
280
+ // Advisory id -> when the cached copy that stood in for a failed lookup was fetched.
281
+ const staleDetailCachedAt = new Map();
287
282
  if (idSet.size > 0 && !offline) {
288
283
  // Only ask OSV for ids OSV can own. The npm registry advisory source
289
284
  // (#1056) contributes NPM-prefixed ids from its own namespace, and
@@ -323,24 +318,37 @@ export async function scanPackages(packages, batchSize, options, context, debugL
323
318
  detailSpinner.update(`Fetching ${uncachedIds.length} vulnerability details...`);
324
319
  const cachedAt = new Date().toISOString();
325
320
  await runWithConcurrency(uncachedIds, 10, async (id) => {
326
- try {
327
- const detail = await advisorySource.getVuln(id);
328
- vulnMap.set(id, detail);
329
- cache.entries[id] = { vuln: detail, cachedAt };
330
- }
331
- catch (error) {
332
- if (isTransientFailure(error)) {
321
+ // --no-cache promises fresh data only, so it gets the retries but
322
+ // never the stale fallback.
323
+ const staleEntry = options.noCache ? undefined : cache.entries[id];
324
+ const resolution = await resolveAdvisoryDetail({
325
+ id,
326
+ fetchDetail: (advisoryId) => advisorySource.getVuln(advisoryId),
327
+ staleEntry,
328
+ });
329
+ switch (resolution.kind) {
330
+ case "fresh":
331
+ vulnMap.set(id, resolution.vuln);
332
+ cache.entries[id] = { vuln: resolution.vuln, cachedAt };
333
+ break;
334
+ case "stale":
335
+ // Left as it is in the cache, so it keeps its real age.
336
+ vulnMap.set(id, resolution.vuln);
337
+ staleDetailCachedAt.set(id, resolution.cachedAt);
338
+ log("OSV detail served from stale cache", { advisoryId: id, cachedAt: resolution.cachedAt });
339
+ break;
340
+ case "confirmed-missing":
341
+ confirmedMissingDetailIds.add(id);
342
+ cache.entries[id] = { vuln: null, cachedAt };
343
+ log("OSV detail confirmed missing", { advisoryId: id });
344
+ break;
345
+ case "transient":
333
346
  transientDetailIds.add(id);
334
347
  log("OSV detail transient failure", {
335
348
  advisoryId: id,
336
- error: extractErrorMessage(error),
349
+ error: extractErrorMessage(resolution.error),
337
350
  });
338
- }
339
- else {
340
- confirmedMissingDetailIds.add(id);
341
- cache.entries[id] = { vuln: null, cachedAt };
342
- log("OSV detail confirmed missing", { advisoryId: id });
343
- }
351
+ break;
344
352
  }
345
353
  });
346
354
  }
@@ -394,7 +402,9 @@ export async function scanPackages(packages, batchSize, options, context, debugL
394
402
  // formats and the HTML report all see one list.
395
403
  const vulnerabilities = collapseAliasedDuplicates(result.vulnIds.map(id => vulnMap.get(id)).filter((v) => Boolean(v)));
396
404
  const unresolvedIds = result.vulnIds.filter(id => !vulnMap.has(id));
397
- const severity = maxSeverity(vulnerabilities);
405
+ const severity = vulnerabilities.length === 0 && unresolvedIds.length > 0
406
+ ? "unknown"
407
+ : maxSeverity(vulnerabilities);
398
408
  const cveAliases = extractCveAliases(vulnerabilities);
399
409
  const dependencyPaths = result.pkg.paths ?? [];
400
410
  const relationship = classifyRelationship(dependencyPaths, result.pkg.name, context?.directDependencyNames);
@@ -537,7 +547,7 @@ export async function scanPackages(packages, batchSize, options, context, debugL
537
547
  }, async () => {
538
548
  const npmRemediationCache = new Map();
539
549
  const parentUpgradeCache = new Map();
540
- const directValidationCount = offline ? 0 : findings.length;
550
+ const directValidationCount = offline ? 0 : findings.filter(f => !isPep440Ecosystem(f.pkg.ecosystem)).length;
541
551
  for (const finding of findings) {
542
552
  if (finding.relationship === "direct")
543
553
  directCount++;
@@ -747,6 +757,7 @@ export async function scanPackages(packages, batchSize, options, context, debugL
747
757
  transientDetailIds,
748
758
  offlineMissingDetailIds,
749
759
  confirmedMissingDetailIds,
760
+ staleDetailCachedAt,
750
761
  packumentFailures,
751
762
  remediationFailures,
752
763
  chainResolutionFailureCount,
@@ -754,7 +765,7 @@ export async function scanPackages(packages, batchSize, options, context, debugL
754
765
  unreadableFixPackages: findings.filter(finding => finding.advisoryBoundaryUnreadable).length,
755
766
  });
756
767
  const completeness = {
757
- complete: diagnostics.length === 0,
768
+ complete: isCompleteGivenDiagnostics(diagnostics),
758
769
  diagnostics,
759
770
  };
760
771
  if (!offline) {
@@ -855,7 +866,7 @@ function loadLockParentGraph(source, filePath, log) {
855
866
  return null;
856
867
  }
857
868
  async function validateDirectFixTargets(findings, onFinding, options) {
858
- const directCandidates = findings.filter(finding => finding.vulnerabilities.length > 0);
869
+ const directCandidates = findings.filter(finding => finding.vulnerabilities.length > 0 && !isPep440Ecosystem(finding.pkg.ecosystem));
859
870
  const results = await runWithConcurrency(directCandidates, 8, async (finding) => {
860
871
  onFinding?.(finding);
861
872
  return validateOneDirectFixTarget(finding, options);
@@ -863,7 +874,7 @@ async function validateDirectFixTargets(findings, onFinding, options) {
863
874
  return results.some(Boolean);
864
875
  }
865
876
  async function validateOneDirectFixTarget(finding, options) {
866
- if (finding.advisoryBoundaryUnreadable)
877
+ if (isPep440Ecosystem(finding.pkg.ecosystem) || finding.advisoryBoundaryUnreadable)
867
878
  return false;
868
879
  let npmVersionCacheUpdated = false;
869
880
  const debugLog = options?.debugLog;
@@ -988,8 +999,16 @@ function classifyRelationship(paths, packageName, directDependencyNames) {
988
999
  */
989
1000
  function affectedEntryMatchesPackage(affected, packageName, ecosystem) {
990
1001
  const affectedName = affected.package?.name;
991
- if (affectedName && affectedName !== packageName)
992
- return false;
1002
+ if (affectedName) {
1003
+ if (isPep440Ecosystem(ecosystem)) {
1004
+ if (normalizePep503PackageName(affectedName) !== normalizePep503PackageName(packageName)) {
1005
+ return false;
1006
+ }
1007
+ }
1008
+ else if (affectedName !== packageName) {
1009
+ return false;
1010
+ }
1011
+ }
993
1012
  const affectedEcosystem = affected.package?.ecosystem?.toLowerCase();
994
1013
  if (affectedEcosystem && affectedEcosystem !== ecosystem.toLowerCase())
995
1014
  return false;
@@ -1179,22 +1198,25 @@ function selectPep440FixedVersion(vulns, packageName, ecosystem, installedVersio
1179
1198
  }
1180
1199
  function buildCompletenessDiagnostics(params) {
1181
1200
  const diagnostics = [];
1182
- function addDiagnostic(code, count, impact, affectedPackageCount) {
1201
+ function addDiagnostic(code, count, impact, affectedPackageCount, oldestCachedAt) {
1183
1202
  if (count === 0)
1184
1203
  return;
1185
1204
  diagnostics.push({
1186
1205
  code,
1187
1206
  severity: "warning",
1188
- message: formatDiagnosticMessage(code, count, affectedPackageCount, impact),
1207
+ message: formatDiagnosticMessage(code, count, affectedPackageCount, impact, oldestCachedAt),
1189
1208
  impact,
1190
1209
  count,
1191
1210
  ...(affectedPackageCount === undefined ? {} : { affectedPackageCount }),
1211
+ ...(oldestCachedAt === undefined ? {} : { oldestCachedAt }),
1192
1212
  });
1193
1213
  }
1194
1214
  const remediationTotal = [...params.remediationFailures.values()].reduce((sum, c) => sum + c, 0);
1195
1215
  addDiagnostic("OSV_DETAIL_TRANSIENT_FAILURE", params.transientDetailIds.size, "detection");
1196
1216
  addDiagnostic("OSV_DETAIL_OFFLINE_MISSING", params.offlineMissingDetailIds.size, "detection");
1197
1217
  addDiagnostic("OSV_DETAIL_CONFIRMED_MISSING", params.confirmedMissingDetailIds.size, "detection");
1218
+ const staleDates = [...params.staleDetailCachedAt.values()].sort();
1219
+ addDiagnostic("OSV_DETAIL_STALE_CACHE_USED", staleDates.length, "freshness", undefined, staleDates[0]);
1198
1220
  addDiagnostic("PACKUMENT_FETCH_FAILURE", params.packumentFailures.size, "remediation");
1199
1221
  addDiagnostic("REMEDIATION_FAILURE", remediationTotal, "remediation", params.remediationFailures.size);
1200
1222
  addDiagnostic("CHAIN_RESOLUTION_FAILURE", params.chainResolutionFailureCount, "remediation");
@@ -1221,10 +1243,11 @@ async function enrichWithEpssScores(findings, fetchImpl) {
1221
1243
  export function buildCoverageNotes(scanInput, offline) {
1222
1244
  const notes = [
1223
1245
  "CVE Lite CLI checks package versions against OSV advisories. It does not prove exploitability or runtime reachability.",
1224
- "Installed node_modules contents are not verified in this scan.",
1225
- "Container images, binaries, secrets, and IaC files are not scanned.",
1226
- "Monorepo workspace boundaries are only partially modeled in this version.",
1227
1246
  ];
1247
+ if (scanInput.source !== "requirements-txt") {
1248
+ notes.push("Installed node_modules contents are not verified in this scan.");
1249
+ }
1250
+ notes.push("Container images, binaries, secrets, and IaC files are not scanned.", "Monorepo workspace boundaries are only partially modeled in this version.");
1228
1251
  if (scanInput.mode === "manifest-fallback") {
1229
1252
  notes.push("Manifest fallback is limited to direct dependencies pinned to exact versions. It does not resolve transitive dependencies from package.json alone.");
1230
1253
  }
package/dist/types.js CHANGED
@@ -5,7 +5,7 @@
5
5
  * 1 - findings present (CVE or override) above threshold
6
6
  * 2 - --fix applied but verify() detected the fix did not take
7
7
  * (operationally distinct from 1: "fix ran but did not work")
8
- * 3 - tool error (unhandled exception, unreadable lockfile, etc.) or incomplete scan (--incomplete-policy=error)
8
+ * 3 - tool error (unhandled exception, unreadable lockfile, no scannable packages, etc.) or incomplete scan (--incomplete-policy=error)
9
9
  */
10
10
  export const EXIT_OK = 0;
11
11
  export const EXIT_FINDINGS = 1;
@@ -20,6 +20,11 @@ export function uniquePathArrays(paths) {
20
20
  }
21
21
  return output;
22
22
  }
23
+ export function pathsEqual(left, right) {
24
+ if (left.length !== right.length)
25
+ return false;
26
+ return left.every((value, index) => value === right[index]);
27
+ }
23
28
  export async function runWithConcurrency(items, limit, fn, options) {
24
29
  const results = new Array(items.length);
25
30
  const queue = items.map((item, index) => ({ item, index }));
@@ -2,8 +2,14 @@ import fs from "node:fs";
2
2
  import path from "node:path";
3
3
  const BASELINE_DIR = ".cve-lite";
4
4
  const BASELINE_FILE = "baseline.json";
5
+ function baselineDir(projectRoot) {
6
+ const root = fs.existsSync(projectRoot) && fs.statSync(projectRoot).isFile()
7
+ ? path.dirname(projectRoot)
8
+ : projectRoot;
9
+ return path.join(root, BASELINE_DIR);
10
+ }
5
11
  function baselinePath(projectRoot) {
6
- return path.join(projectRoot, BASELINE_DIR, BASELINE_FILE);
12
+ return path.join(baselineDir(projectRoot), BASELINE_FILE);
7
13
  }
8
14
  export function readBaseline(projectRoot) {
9
15
  const filePath = baselinePath(projectRoot);
@@ -17,7 +23,7 @@ export function readBaseline(projectRoot) {
17
23
  }
18
24
  }
19
25
  export function writeBaseline(projectRoot, findings) {
20
- const dir = path.join(projectRoot, BASELINE_DIR);
26
+ const dir = baselineDir(projectRoot);
21
27
  if (!fs.existsSync(dir)) {
22
28
  fs.mkdirSync(dir, { recursive: true });
23
29
  }
@@ -44,6 +44,4 @@ export const chalk = {
44
44
  white: (text) => paint(ansi.white, text),
45
45
  whiteBright: (text) => paint(ansi.whiteBright, text)
46
46
  };
47
- export function stripAnsi(text) {
48
- return text.replace(/\x1b\[[0-9;]*m/g, "");
49
- }
47
+ export { stripAnsi } from "./sanitize.js";