cve-lite-cli 1.27.0 → 1.28.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
@@ -97,7 +97,9 @@ cve-lite /path/to/project --json # JSON output
97
97
  cve-lite /path/to/project --sarif # SARIF output for GitHub Code Scanning
98
98
  cve-lite /path/to/project --report # interactive HTML dashboard
99
99
  cve-lite /path/to/project --check-overrides # audit override hygiene alongside the CVE scan
100
+ cve-lite /path/to/project --check-maintenance # flag CVE-blocking version drag and npm-deprecated direct deps
100
101
  cve-lite advisories sync # sync advisory DB for offline use
102
+ cve-lite advisories init # create an empty advisory DB to populate yourself
101
103
  cve-lite /path/to/project --offline # scan with no runtime API calls
102
104
  ```
103
105
 
@@ -131,6 +133,20 @@ cve-lite /path/to/project --check-overrides # CVE scan + hygiene in one pass
131
133
 
132
134
  For the full guide with per-rule examples and CI patterns, see the [Override Hygiene Auditing guide](https://owasp.org/cve-lite-cli/docs/override-hygiene).
133
135
 
136
+ ## Release cooldown awareness
137
+
138
+ Package managers added a release cooldown to skip the danger window right after a version is published, when a hijacked release is live but not yet caught (the `chalk`/`debug` compromise sat live for about two hours). CVE Lite CLI reads the cooldown your project already configures and warns when a recommended fix is newer than that window, so it never quietly pushes you onto a version your own package manager would refuse to install.
139
+
140
+ ```
141
+ High severity fix commands
142
+ ⚠ Published 2026-07-01, newer than your configured 365 day release cooldown (.npmrc); your package manager would hold this version - validate before overriding.
143
+ > npm install linkify-it@5.0.2 (published 2026-07-01)
144
+ ```
145
+
146
+ The warning is advisory and on by default (no flag, no exit-code change). It reads `min-release-age` (npm), `minimumReleaseAge` (pnpm), or `npmMinimalAgeGate` (Yarn); it never invents a window.
147
+
148
+ For the full guide, see the [Release Cooldown Awareness guide](https://owasp.org/cve-lite-cli/docs/release-cooldown).
149
+
134
150
  ## What it looks like
135
151
 
136
152
  <table>
@@ -323,6 +339,7 @@ This is intentional. Because CVE Lite CLI is a security-oriented tool, runtime d
323
339
  - [Troubleshooting guide](https://owasp.org/cve-lite-cli/docs/troubleshooting) - no lockfile found, zero results, slow advisory sync, offline DB errors, `--fix` skipping findings, CI failures
324
340
  - [Parser Coverage guide](https://owasp.org/cve-lite-cli/docs/parser-coverage) - supported lockfile formats, selection priority, `package.json` fallback, monorepos, private registries
325
341
  - [Remediation Strategy guide](https://owasp.org/cve-lite-cli/docs/remediation-strategy) - how CVE Lite CLI chooses upgrade targets and parent update paths
342
+ - [Release Cooldown Awareness guide](https://owasp.org/cve-lite-cli/docs/release-cooldown) - how CVE Lite CLI reads your package manager's cooldown and warns on fix versions newer than the window you trust
326
343
 
327
344
  ## Security and verification
328
345
 
@@ -2,9 +2,11 @@ import { extractErrorMessage } from "../utils/network.js";
2
2
  export class OsvAdvisorySource {
3
3
  baseUrl;
4
4
  debugLog;
5
- constructor(baseUrl = "https://api.osv.dev", debugLog) {
5
+ fetchImpl;
6
+ constructor(baseUrl = "https://api.osv.dev", debugLog, fetchImpl) {
6
7
  this.baseUrl = baseUrl;
7
8
  this.debugLog = debugLog;
9
+ this.fetchImpl = fetchImpl ?? fetch;
8
10
  }
9
11
  async queryBatch(packages, meta) {
10
12
  const requestUrl = `${this.baseUrl}/v1/querybatch`;
@@ -35,7 +37,7 @@ export class OsvAdvisorySource {
35
37
  })),
36
38
  });
37
39
  }
38
- const response = await fetch(requestUrl, {
40
+ const response = await this.fetchImpl(requestUrl, {
39
41
  method: "POST",
40
42
  headers: {
41
43
  "Content-Type": "application/json",
@@ -90,7 +92,7 @@ export class OsvAdvisorySource {
90
92
  headers: {},
91
93
  });
92
94
  }
93
- const response = await fetch(requestUrl, { redirect: "error" });
95
+ const response = await this.fetchImpl(requestUrl, { redirect: "error" });
94
96
  if (this.debugLog) {
95
97
  this.debugLog("OSV response", {
96
98
  method: "GET",
@@ -0,0 +1,24 @@
1
+ import { existsSync } from "node:fs";
2
+ import { LocalAdvisoryDatabase } from "../advisory/local-db.js";
3
+ import { getDefaultAdvisoryDbPath } from "../advisory/osv-sync.js";
4
+ /**
5
+ * Creates an empty local advisory database with the current schema and no data.
6
+ * This is for air-gapped users who cannot run `advisories sync`: they run
7
+ * `advisories init`, populate the database from their own sources, and then scan
8
+ * with `--offline-db`.
9
+ *
10
+ * Returns the resolved path of the database that was created. Throws if a file
11
+ * already exists at that path, so an existing (possibly populated) database is
12
+ * never silently reused.
13
+ */
14
+ export function initAdvisoryDatabase(outputPath) {
15
+ const dbPath = getDefaultAdvisoryDbPath(outputPath);
16
+ if (existsSync(dbPath)) {
17
+ throw new Error(`${dbPath} already exists. Delete it or choose a different --output path before running init.`);
18
+ }
19
+ // Opening a writable database runs the schema (CREATE TABLE IF NOT EXISTS),
20
+ // which is exactly an empty, correctly-shaped database.
21
+ const db = new LocalAdvisoryDatabase(dbPath);
22
+ db.close();
23
+ return dbPath;
24
+ }
package/dist/cli/args.js CHANGED
@@ -52,6 +52,32 @@ export function parseArgs(argv) {
52
52
  }
53
53
  return { command: "advisories-sync", options };
54
54
  }
55
+ if (argv[0] === "advisories" && argv[1] === "init") {
56
+ for (let i = 2; i < argv.length; i++) {
57
+ const arg = argv[i];
58
+ if (arg === "-h" || arg === "--help") {
59
+ options.help = true;
60
+ continue;
61
+ }
62
+ if (arg === "-v" || arg === "--version") {
63
+ options.version = true;
64
+ continue;
65
+ }
66
+ if (arg === "--output") {
67
+ options.output = argv[++i];
68
+ continue;
69
+ }
70
+ if (arg.startsWith("--output=")) {
71
+ options.output = arg.slice("--output=".length);
72
+ continue;
73
+ }
74
+ if (arg.startsWith("-")) {
75
+ throw new Error(`Unknown option: ${arg}`);
76
+ }
77
+ throw new Error(`Unexpected argument: ${arg}`);
78
+ }
79
+ return { command: "advisories-init", options };
80
+ }
55
81
  if (argv[0] === "install-skill") {
56
82
  for (let i = 1; i < argv.length; i++) {
57
83
  const arg = argv[i];
@@ -339,6 +365,10 @@ export function parseArgs(argv) {
339
365
  options.checkOverrides = true;
340
366
  continue;
341
367
  }
368
+ if (arg === "--check-maintenance") {
369
+ options.checkMaintenance = true;
370
+ continue;
371
+ }
342
372
  if (arg.startsWith("-")) {
343
373
  throw new Error(`Unknown option: ${arg}`);
344
374
  }
package/dist/cli/help.js CHANGED
@@ -24,6 +24,7 @@ export function printHelp() {
24
24
  "Usage:",
25
25
  " cve-lite [projectPath] [options]",
26
26
  " cve-lite advisories sync [options]",
27
+ " cve-lite advisories init [options]",
27
28
  " cve-lite install-skill",
28
29
  " cve-lite config <set|unset|show> [key] [value]",
29
30
  " cve-lite overrides [path] [flags]",
@@ -46,6 +47,8 @@ export function printHelp() {
46
47
  " --prod-only Exclude dev dependencies where available",
47
48
  " --check-overrides Also audit package.json overrides (OA001-OA009, PD001-PD002); findings",
48
49
  " print, thread to JSON/SARIF/HTML, and count toward --fail-on",
50
+ " --check-maintenance Also flag direct deps that block a transitive CVE fix via a major-version",
51
+ " drag, or are marked deprecated on npm (DM001); counts toward --fail-on",
49
52
  " --fail-on <severity> Exit non-zero at or above severity (default: critical)",
50
53
  " --batch-size <number> OSV batch size (default: 100)",
51
54
  " --usage Scan project source files to check if vulnerable dependencies are imported",
@@ -58,7 +61,7 @@ export function printHelp() {
58
61
  " --all Show all findings in the main table",
59
62
  " --min-severity <level> Minimum severity shown in table (default: medium)",
60
63
  "",
61
- "Advisory sync options:",
64
+ "Advisory sync/init options:",
62
65
  " --output <path> Write the local advisory database to this path",
63
66
  "",
64
67
  "Other commands:",
@@ -80,7 +83,8 @@ export function printHelp() {
80
83
  " cve-lite . --report Generate an interactive HTML report",
81
84
  " cve-lite . --fix Apply validated direct dependency fixes and rescan",
82
85
  " cve-lite . --offline Scan using the local advisory database (no network)",
83
- " cve-lite advisories sync Sync the local advisory database"
86
+ " cve-lite advisories sync Sync the local advisory database",
87
+ " cve-lite advisories init Create an empty advisory database to populate yourself"
84
88
  ];
85
89
  console.log(lines.join("\n"));
86
90
  }
package/dist/constants.js CHANGED
@@ -8,6 +8,7 @@ export const severityOrder = {
8
8
  };
9
9
  export const DEFAULT_BATCH_SIZE = 100;
10
10
  export const DEFAULT_SEARCH_DEPTH = 4;
11
+ export const CACHE_TTL_MS = 30 * 60 * 1000; // 30 minutes
11
12
  export const NPM_PUBLIC_REGISTRY = "https://registry.npmjs.org/";
12
13
  export const MAL_PRIVATE_REGISTRY_MESSAGE = "This package has a MAL- advisory but resolved from a private registry - unverifiable whether this advisory applies to your artifact. Inspect the source manually.";
13
14
  export const MAL_PRIVATE_REGISTRY_COMPACT_MESSAGE = "MAL- advisory could not be confirmed for this artifact.";
package/dist/index.js CHANGED
@@ -16,7 +16,7 @@ import { createDebugLogger } from "./output/debug.js";
16
16
  import { buildSuggestedFixCommandPlan } from "./remediation/fix-commands.js";
17
17
  import { scanProjectForPackageUsage } from "./usage/scanner.js";
18
18
  import { getCliVersion } from "./utils/version-info.js";
19
- import { getNetworkErrorHint, offlineDbSyncHint } from "./utils/network.js";
19
+ import { getNetworkErrorHint, offlineDbSyncHint, createCertAwareFetch } from "./utils/network.js";
20
20
  import { formatAdvisoryDbFreshness } from "./utils/time.js";
21
21
  import { pluralize, nearestCommand } from "./utils/string.js";
22
22
  import { EXIT_ERROR } from "./types.js";
@@ -27,6 +27,8 @@ import { writeOutputs } from "./output/write-outputs.js";
27
27
  import { selectFindingsForTable } from "./output/finding-display.js";
28
28
  import { printActionSummary, printCompactOutput, printCoverage, printFinalStatus, printOverrideHint, printSkippedDependencies, printSuggestedFixCommands, printSuggestedFixCommandSkips, printSummary, printTable, } from "./output/printers.js";
29
29
  import { renderOverrideFindings } from "./output/override-findings-terminal.js";
30
+ import { detectDM001 } from "./maintenance/dm001-maintenance-risk.js";
31
+ import { renderMaintenanceFindings } from "./output/maintenance-terminal.js";
30
32
  import { installSkill } from "./skills/install.js";
31
33
  import { readConfig, validateCaCertFile } from "./cli/config.js";
32
34
  import { runConfigCommand } from "./cli/config-command.js";
@@ -125,6 +127,7 @@ if (parsedArgs) {
125
127
  }
126
128
  process.env.NODE_EXTRA_CA_CERTS = resolvedCaCert;
127
129
  }
130
+ const certFetch = resolvedCaCert ? createCertAwareFetch(resolvedCaCert) : undefined;
128
131
  debugLog("Config loaded", {
129
132
  caCert: resolvedCaCert ?? null,
130
133
  nodeExtraCaCerts: process.env.NODE_EXTRA_CA_CERTS ?? null,
@@ -134,6 +137,7 @@ if (parsedArgs) {
134
137
  const usePlainProgressLogs = !process.stdout.isTTY || !!options.json;
135
138
  const result = await syncOsvAdvisories({
136
139
  outputPath: options.output,
140
+ fetchImpl: certFetch,
137
141
  onProgress: event => {
138
142
  if (event.phase === "complete") {
139
143
  return;
@@ -155,6 +159,20 @@ if (parsedArgs) {
155
159
  process.exit(0);
156
160
  return;
157
161
  }
162
+ if (command === "advisories-init") {
163
+ try {
164
+ const { initAdvisoryDatabase } = await import("./cli/advisories-init.js");
165
+ const dbPath = initAdvisoryDatabase(options.output);
166
+ console.log(`${chalk.gray("Advisory database:")} created an empty advisory database at ${chalk.cyan(dbPath)}`);
167
+ console.log(chalk.gray(`Populate it from your own sources, then scan with \`--offline-db ${dbPath}\`.`));
168
+ process.exit(0);
169
+ }
170
+ catch (error) {
171
+ console.error(chalk.red(`Error: ${error instanceof Error ? error.message : String(error)}`));
172
+ process.exit(1);
173
+ }
174
+ return;
175
+ }
158
176
  if (command === "install-skill") {
159
177
  installSkill(process.cwd());
160
178
  process.exit(0);
@@ -184,7 +202,7 @@ if (parsedArgs) {
184
202
  // route to dedicated multi-folder handler instead of single-lockfile scan
185
203
  const nestedLockfiles = findNestedLockfiles(projectPath, searchDepth);
186
204
  if (!hasRootLockfile(projectPath) && nestedLockfiles.length >= 2) {
187
- const exitCode = await handleMultiFolderScan({ projectRoot: projectPath, batchSize, options });
205
+ const exitCode = await handleMultiFolderScan({ projectRoot: projectPath, batchSize, options, fetchImpl: certFetch });
188
206
  auditLogHandle.close();
189
207
  process.exit(exitCode);
190
208
  }
@@ -197,6 +215,7 @@ if (parsedArgs) {
197
215
  offline: options.offline,
198
216
  offlineDb: options.offlineDb,
199
217
  debugLog,
218
+ fetchImpl: certFetch,
200
219
  });
201
220
  advisorySourceLine = advisorySource.sourceLabel;
202
221
  debugLog("Advisory source", {
@@ -297,6 +316,7 @@ if (parsedArgs) {
297
316
  options,
298
317
  projectPath,
299
318
  debugLog,
319
+ fetchImpl: certFetch,
300
320
  });
301
321
  const findingsBeforeFixList = scanState.sorted;
302
322
  const findingsBeforeFix = findingsBeforeFixList.length;
@@ -323,6 +343,7 @@ if (parsedArgs) {
323
343
  const auditResult = await audit(overrideCtx, { checkNetwork: !!options.checkNetwork });
324
344
  overrideFindings = auditResult.findings;
325
345
  }
346
+ let maintenanceFindings = [];
326
347
  // Emit cve.detected for each CVE finding
327
348
  for (const f of scanState.sorted) {
328
349
  auditLogHandle.emit({
@@ -368,6 +389,7 @@ if (parsedArgs) {
368
389
  options,
369
390
  projectPath,
370
391
  debugLog,
392
+ fetchImpl: certFetch,
371
393
  });
372
394
  }
373
395
  }
@@ -549,6 +571,17 @@ if (parsedArgs) {
549
571
  scanState.tableFindings = scanState.tableFindings.filter(f => filtered.newFindings.some(nf => nf.pkg.name === f.pkg.name && nf.pkg.version === f.pkg.version));
550
572
  suppressedCount = filtered.suppressedCount;
551
573
  }
574
+ // Maintenance risk findings are derived from CVE findings (via
575
+ // recommendedParentUpgrade), so they must be computed from the same
576
+ // baseline-filtered set everything below uses (JSON, rendering,
577
+ // --fail-on). Computing this earlier - before the baseline filter above -
578
+ // let a DM001 finding on an already-baselined CVE keep failing
579
+ // --fail-on forever, even as printFinalStatus reported a clean scan.
580
+ // This point is unreached in --ratchet mode (which always exits above
581
+ // via process.exit), so packument fetches never run wastefully there.
582
+ if (options.checkMaintenance) {
583
+ maintenanceFindings = await detectDM001(scanState.sorted, !!options.offline || !!options.offlineDb);
584
+ }
552
585
  await writeOutputs(options, {
553
586
  sorted: scanState.sorted,
554
587
  allPackages: scanState.allPackages,
@@ -557,6 +590,7 @@ if (parsedArgs) {
557
590
  minSeverity: scanState.minSeverity,
558
591
  tableFindings: scanState.tableFindings,
559
592
  overrideFindings,
593
+ maintenanceFindings,
560
594
  }, scanInput, projectPath);
561
595
  if (!(options.json || options.sarif || options.cdx) || options.verbose) {
562
596
  const offline = !!options.offline || !!options.offlineDb;
@@ -585,6 +619,9 @@ if (parsedArgs) {
585
619
  if (options.checkOverrides && overrideFindings.length > 0) {
586
620
  console.log("\n" + renderOverrideFindings(overrideFindings, { verbose: true, projectPath }));
587
621
  }
622
+ if (options.checkMaintenance && maintenanceFindings.length > 0) {
623
+ console.log("\n" + renderMaintenanceFindings(maintenanceFindings, { verbose: true }));
624
+ }
588
625
  printCoverage([...scanInput.notes, ...scanState.coverage]);
589
626
  printFinalStatus(scanState.sorted, overrideCount);
590
627
  if (showOverrideHint)
@@ -598,6 +635,9 @@ if (parsedArgs) {
598
635
  if (options.checkOverrides) {
599
636
  console.log("\n" + renderOverrideFindings(overrideFindings, { verbose: false, projectPath }));
600
637
  }
638
+ if (options.checkMaintenance && maintenanceFindings.length > 0) {
639
+ console.log("\n" + renderMaintenanceFindings(maintenanceFindings, { verbose: false }));
640
+ }
601
641
  if (showOverrideHint)
602
642
  printOverrideHint();
603
643
  }
@@ -615,9 +655,12 @@ if (parsedArgs) {
615
655
  suggestedFixCommands: scanState.suggestedFixCommands,
616
656
  notes: [...scanInput.notes, ...scanState.coverage],
617
657
  warnings: scanInput.warnings,
658
+ skippedDependencies: scanInput.skippedDependencies,
618
659
  // undefined (not []) when override checking was not requested, so the HTML
619
660
  // report omits the Override hygiene panel entirely on a plain scan.
620
661
  overrideFindings: options.checkOverrides ? overrideFindings : undefined,
662
+ // Same undefined-vs-[] convention as overrideFindings above.
663
+ maintenanceFindings: options.checkMaintenance ? maintenanceFindings : undefined,
621
664
  });
622
665
  const { reportPath } = await writeHtmlReport({
623
666
  outputDir,
@@ -646,7 +689,8 @@ if (parsedArgs) {
646
689
  // override findings, giving a false sense of protection. overrideFindings is empty
647
690
  // unless --check-overrides (and non-ratchet), so this is a no-op otherwise.
648
691
  const shouldFail = reachesFailOn(scanState.sorted, options.failOn) ||
649
- reachesFailOn(overrideFindings, options.failOn);
692
+ reachesFailOn(overrideFindings, options.failOn) ||
693
+ reachesFailOn(maintenanceFindings, options.failOn);
650
694
  // In fix mode, remaining transitive findings cannot be auto-fixed.
651
695
  // Exiting non-zero would prevent the Action PR step from running.
652
696
  const exitCode = shouldFail && !options.fix ? 1 : 0;
@@ -691,7 +735,7 @@ async function scanProject(params) {
691
735
  directDependencyNames,
692
736
  scanSource: params.scanInput.source,
693
737
  scanFilePath: params.scanInput.filePath,
694
- }, params.debugLog);
738
+ }, params.debugLog, params.fetchImpl);
695
739
  if (params.options.usage) {
696
740
  logInfo(`Scanning project source for usage hints...`, params.options);
697
741
  const usageStartedAt = Date.now();
@@ -0,0 +1,63 @@
1
+ import { fetchPackument } from "../remediation/npm-registry.js";
2
+ const SEVERITY_ORDER_MAP = { high: 0 };
3
+ function majorOf(version) {
4
+ return parseInt(version.split(".")[0] ?? "0", 10);
5
+ }
6
+ export async function detectDM001(findings, isOffline) {
7
+ // Step 1: Collect drag candidates (transitive findings requiring a major-version parent bump)
8
+ const candidates = new Map();
9
+ for (const finding of findings) {
10
+ if (finding.relationship !== "transitive" || finding.recommendedParentUpgrade == null)
11
+ continue;
12
+ const { package: parentName, currentVersion, targetVersion } = finding.recommendedParentUpgrade;
13
+ if (majorOf(targetVersion) === majorOf(currentVersion))
14
+ continue;
15
+ if (!candidates.has(parentName)) {
16
+ candidates.set(parentName, { parentVersion: currentVersion, dragSignals: [] });
17
+ }
18
+ candidates.get(parentName).dragSignals.push({
19
+ constrainedPackage: finding.pkg.name,
20
+ installedVersion: finding.pkg.version,
21
+ fixVersion: finding.firstFixedVersion ?? finding.recommendedParentUpgrade.targetVersion,
22
+ parentTargetVersion: finding.recommendedParentUpgrade.targetVersion,
23
+ cveId: finding.cveAliases[0] ?? finding.vulnerabilities[0]?.id ?? "",
24
+ });
25
+ }
26
+ if (candidates.size === 0)
27
+ return [];
28
+ // Step 2: Check deprecated status for each candidate (skip when offline)
29
+ const results = [];
30
+ for (const [parentName, candidate] of candidates) {
31
+ let deprecated;
32
+ if (!isOffline) {
33
+ try {
34
+ const packument = await fetchPackument(parentName);
35
+ if (packument) {
36
+ const latestVersion = packument["dist-tags"]?.latest ?? "";
37
+ const deprecatedMsg = latestVersion
38
+ ? (packument.versions?.[latestVersion]?.deprecated ?? "")
39
+ : "";
40
+ if (deprecatedMsg)
41
+ deprecated = { message: deprecatedMsg };
42
+ }
43
+ }
44
+ catch {
45
+ // Network error - emit drag finding without deprecated signal
46
+ }
47
+ }
48
+ const pkgList = candidate.dragSignals.map(d => d.constrainedPackage).join(", ");
49
+ const message = `Constrains ${pkgList} - blocks CVE fix requiring major upgrade`;
50
+ results.push({
51
+ ruleId: "DM001",
52
+ severity: "high",
53
+ package: { name: parentName, version: candidate.parentVersion },
54
+ drag: candidate.dragSignals,
55
+ deprecated,
56
+ message,
57
+ });
58
+ }
59
+ return results.sort((a, b) => {
60
+ const sDiff = (SEVERITY_ORDER_MAP[a.severity] ?? 4) - (SEVERITY_ORDER_MAP[b.severity] ?? 4);
61
+ return sDiff !== 0 ? sDiff : a.package.name.localeCompare(b.package.name);
62
+ });
63
+ }
@@ -0,0 +1 @@
1
+ export {};
package/dist/osv/cache.js CHANGED
@@ -1,8 +1,30 @@
1
1
  import fs from "node:fs";
2
2
  import path from "node:path";
3
3
  import os from "node:os";
4
+ import { CACHE_TTL_MS } from "../constants.js";
4
5
  function createEmptyCache() {
5
- return { version: 3, createdAt: new Date().toISOString(), entries: {}, queryEntries: {}, npmVersionEntries: {} };
6
+ return { version: 4, createdAt: new Date().toISOString(), entries: {}, queryEntries: {}, npmVersionEntries: {} };
7
+ }
8
+ // v4 stores detail records as { vuln, cachedAt }. v1-v3 stored the OsvVuln (or
9
+ // null for a known-empty lookup) directly, with no timestamp. Legacy records are
10
+ // wrapped with an epoch-0 cachedAt so they read as stale and get refreshed on the
11
+ // next scan, matching how the queryEntries v2->v3 migration backdates its records.
12
+ function wrapLegacyDetailEntries(raw) {
13
+ const epoch = new Date(0).toISOString();
14
+ const entries = {};
15
+ for (const [id, value] of Object.entries(raw ?? {})) {
16
+ entries[id] = { vuln: value ?? null, cachedAt: epoch };
17
+ }
18
+ return entries;
19
+ }
20
+ function readDetailEntries(raw) {
21
+ const entries = {};
22
+ for (const [id, value] of Object.entries(raw ?? {})) {
23
+ if (value && typeof value === "object" && "vuln" in value && "cachedAt" in value) {
24
+ entries[id] = value;
25
+ }
26
+ }
27
+ return entries;
6
28
  }
7
29
  export function getCacheFilePath(cacheDirOverride) {
8
30
  const baseDir = cacheDirOverride
@@ -12,7 +34,7 @@ export function getCacheFilePath(cacheDirOverride) {
12
34
  return path.join(baseDir, "osv-vulns.json");
13
35
  }
14
36
  export function isEntryStale(entry, nowMs) {
15
- return nowMs - new Date(entry.cachedAt).getTime() > 30 * 60 * 1000;
37
+ return nowMs - new Date(entry.cachedAt).getTime() > CACHE_TTL_MS;
16
38
  }
17
39
  export function loadCache(cacheDirOverride, debugLog) {
18
40
  const filePath = getCacheFilePath(cacheDirOverride);
@@ -31,64 +53,40 @@ export function loadCache(cacheDirOverride, debugLog) {
31
53
  debugLog?.("Cache load failed", { path: filePath, reason: "invalid root object" });
32
54
  return createEmptyCache();
33
55
  }
34
- const entries = (parsed.entries && typeof parsed.entries === "object")
35
- ? parsed.entries
36
- : {};
37
- // v2: queryEntries values are string[] — migrate to { vulnIds, cachedAt: epoch }
38
- if (parsed.version === 2) {
56
+ const version = parsed.version;
57
+ const rawEntries = parsed.entries;
58
+ // Detail records: v4 already carries { vuln, cachedAt }; v1-v3 stored the record
59
+ // directly and are wrapped (and backdated) so the TTL applies uniformly.
60
+ const entries = version === 4 ? readDetailEntries(rawEntries) : wrapLegacyDetailEntries(rawEntries);
61
+ // Query records: v2 stored string[]; v3 and v4 store { vulnIds, cachedAt }; v1/unknown had none.
62
+ const queryEntries = {};
63
+ if (version === 2) {
39
64
  const rawQuery = parsed.queryEntries;
40
- const queryEntries = {};
65
+ const epoch = new Date(0).toISOString();
41
66
  for (const [key, vulnIds] of Object.entries(rawQuery ?? {})) {
42
- queryEntries[key] = { vulnIds: Array.isArray(vulnIds) ? vulnIds : [], cachedAt: new Date(0).toISOString() };
67
+ queryEntries[key] = { vulnIds: Array.isArray(vulnIds) ? vulnIds : [], cachedAt: epoch };
43
68
  }
44
- const migrated = {
45
- version: 3,
46
- createdAt: String(parsed.createdAt ?? new Date().toISOString()),
47
- entries,
48
- queryEntries,
49
- npmVersionEntries: {},
50
- };
51
- debugLog?.("Cache loaded", {
52
- path: filePath,
53
- queryEntries: Object.keys(migrated.queryEntries).length,
54
- detailEntries: Object.keys(migrated.entries).length,
55
- migratedFrom: 2,
56
- });
57
- return migrated;
58
- }
59
- // v1 or unknown: no queryEntries
60
- if (parsed.version !== 3) {
61
- const upgraded = {
62
- version: 3,
63
- createdAt: new Date().toISOString(),
64
- entries,
65
- queryEntries: {},
66
- npmVersionEntries: {},
67
- };
68
- debugLog?.("Cache loaded", {
69
- path: filePath,
70
- queryEntries: 0,
71
- detailEntries: Object.keys(upgraded.entries).length,
72
- migratedFrom: parsed.version ?? "unknown",
73
- });
74
- return upgraded;
75
69
  }
76
- const rawQuery = parsed.queryEntries;
77
- const queryEntries = {};
78
- for (const [key, value] of Object.entries(rawQuery ?? {})) {
79
- if (value && typeof value === "object" && "vulnIds" in value && "cachedAt" in value) {
80
- queryEntries[key] = value;
70
+ else if (version === 3 || version === 4) {
71
+ const rawQuery = parsed.queryEntries;
72
+ for (const [key, value] of Object.entries(rawQuery ?? {})) {
73
+ if (value && typeof value === "object" && "vulnIds" in value && "cachedAt" in value) {
74
+ queryEntries[key] = value;
75
+ }
81
76
  }
82
77
  }
83
- const rawNpmVersions = parsed.npmVersionEntries;
78
+ // npm publish-date records exist from v3 onward.
84
79
  const npmVersionEntries = {};
85
- for (const [key, value] of Object.entries(rawNpmVersions ?? {})) {
86
- if (value && typeof value === "object" && "publishedAt" in value && "cachedAt" in value) {
87
- npmVersionEntries[key] = value;
80
+ if (version === 3 || version === 4) {
81
+ const rawNpmVersions = parsed.npmVersionEntries;
82
+ for (const [key, value] of Object.entries(rawNpmVersions ?? {})) {
83
+ if (value && typeof value === "object" && "publishedAt" in value && "cachedAt" in value) {
84
+ npmVersionEntries[key] = value;
85
+ }
88
86
  }
89
87
  }
90
88
  const loaded = {
91
- version: 3,
89
+ version: 4,
92
90
  createdAt: String(parsed.createdAt ?? new Date().toISOString()),
93
91
  entries,
94
92
  queryEntries,
@@ -98,6 +96,7 @@ export function loadCache(cacheDirOverride, debugLog) {
98
96
  path: filePath,
99
97
  queryEntries: Object.keys(loaded.queryEntries).length,
100
98
  detailEntries: Object.keys(loaded.entries).length,
99
+ ...(version === 4 ? {} : { migratedFrom: version ?? "unknown" }),
101
100
  });
102
101
  return loaded;
103
102
  }
@@ -1,4 +1,4 @@
1
- import { findSuggestedCommandForFinding } from "../remediation/fix-commands.js";
1
+ import { findFixTargetForFinding, findSuggestedCommandForFinding } from "../remediation/fix-commands.js";
2
2
  import { chalk } from "../utils/chalk.js";
3
3
  import { severityOrder, MAL_PRIVATE_REGISTRY_MESSAGE, MAL_GIT_SOURCE_PINNED_MESSAGE, MAL_GIT_SOURCE_FLOATING_MESSAGE, } from "../constants.js";
4
4
  import { loadCache } from "../osv/cache.js";
@@ -191,6 +191,9 @@ export function summarizeNextAction(finding) {
191
191
  export function formatFixVersionPublishDate(iso) {
192
192
  return iso.slice(0, 10);
193
193
  }
194
+ export function formatCooldownWarning(warning) {
195
+ return `Published ${formatFixVersionPublishDate(warning.publishedAt)}, newer than your configured ${warning.windowLabel} release cooldown (${warning.sourceFile}); your package manager would hold this version - validate before overriding.`;
196
+ }
194
197
  export function formatFixCommandPublishSuffix(targets) {
195
198
  const dated = targets.filter(target => target.kind === "direct" && target.fixVersionPublishedAt);
196
199
  if (dated.length === 0)
@@ -216,6 +219,7 @@ export function serializeFinding(finding, plan) {
216
219
  validatedFirstFixedVersion: finding.validatedFirstFixedVersion ?? null,
217
220
  fixVersionValidationNote: finding.fixVersionValidationNote ?? null,
218
221
  fixVersionPublishedAt: finding.fixVersionPublishedAt ?? null,
222
+ cooldownWarning: plan ? (findFixTargetForFinding(plan, finding)?.cooldownWarning ?? null) : null,
219
223
  validatedTargetScannedVersions: finding.validatedTargetScannedVersions ?? null,
220
224
  validatedTargetKnownVulnerableVersions: finding.validatedTargetKnownVulnerableVersions ?? null,
221
225
  recommendedAction: getRecommendedAction(finding),
@@ -229,6 +233,7 @@ export function serializeFinding(finding, plan) {
229
233
  maliciousUnverifiable: finding.maliciousUnverifiable ?? false,
230
234
  maliciousGitSource: finding.maliciousGitSource ?? false,
231
235
  maliciousGitSourcePinned: finding.maliciousGitSourcePinned ?? false,
236
+ unresolvedAdvisoryIds: finding.unresolvedAdvisoryIds ?? [],
232
237
  vulnerabilities: finding.vulnerabilities.map(v => ({
233
238
  id: v.id,
234
239
  aliases: v.aliases ?? [],
@@ -241,8 +246,8 @@ export function printCacheSummary(cacheDirOverride, options) {
241
246
  if (options?.json)
242
247
  return;
243
248
  const cache = loadCache(cacheDirOverride);
244
- const advisoryCount = Object.entries(cache.entries).filter(([, value]) => Boolean(value)).length;
245
- const emptyCount = Object.entries(cache.entries).filter(([, value]) => value === null).length;
249
+ const advisoryCount = Object.values(cache.entries).filter(entry => entry.vuln).length;
250
+ const emptyCount = Object.values(cache.entries).filter(entry => entry.vuln === null).length;
246
251
  const packageQueryCount = Object.keys(cache.queryEntries).length;
247
252
  const totalCount = advisoryCount + emptyCount;
248
253
  if (totalCount === 0 && packageQueryCount === 0)