cve-lite-cli 1.4.0 → 1.5.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
@@ -15,6 +15,7 @@
15
15
 
16
16
  <p>
17
17
  <a href="#quick-start">Quick Start</a> •
18
+ <a href="#new-here-start-here">New Here? Start Here</a> •
18
19
  <a href="#features">Features</a> •
19
20
  <a href="#usage">Usage</a> •
20
21
  <a href="https://github.com/sonukapoor/cve-lite-cli/blob/main/src/docs/CONTRIBUTING.md">Contributing</a>
@@ -31,6 +32,7 @@
31
32
  <td valign="top">
32
33
  <strong>Overview</strong><br/>
33
34
  <a href="#what-is-cve-lite-cli">What is CVE Lite CLI</a><br/>
35
+ <a href="#new-here-start-here">New here? Start here</a><br/>
34
36
  <a href="#new-offline-advisory-db-support">Offline advisory DB support</a><br/>
35
37
  <a href="#why-offline-mode-matters">Why offline mode matters</a><br/>
36
38
  <a href="docs/case-studies/owasp-juice-shop.md">OWASP Juice Shop case study</a><br/>
@@ -80,6 +82,24 @@ It is designed to be:
80
82
 
81
83
  For real-world remediation examples, see the [OWASP Juice Shop case study](docs/case-studies/owasp-juice-shop.md) and the [NestJS case study](docs/case-studies/nestjs.md).
82
84
 
85
+ ## New here? Start here
86
+
87
+ 1. run one scan on a real project with `npx cve-lite-cli /path/to/project --verbose`
88
+ 2. review direct vs transitive findings and the `Copy And Run These Fix Commands` section
89
+ 3. compare the output with your current scanner workflow
90
+ 4. check a real walkthrough:
91
+ - [OWASP Juice Shop case study](docs/case-studies/owasp-juice-shop.md)
92
+ - [NestJS case study](docs/case-studies/nestjs.md)
93
+
94
+ If CVE Lite CLI helps your release workflow, a GitHub star helps more developers discover it: [Star CVE Lite CLI](https://github.com/sonukapoor/cve-lite-cli).
95
+
96
+ If you want to shape the roadmap, open an issue with feedback on:
97
+
98
+ - whether the direct vs transitive split is useful in practice
99
+ - where remediation guidance is still missing
100
+ - what increases or decreases trust in a CLI security tool
101
+ - what would make frontend-heavy CI workflows smoother
102
+
83
103
  ## New: Offline advisory DB support
84
104
 
85
105
  CVE Lite CLI now supports a local advisory database workflow for teams that cannot allow runtime outbound advisory API calls.
@@ -231,7 +251,7 @@ The exact command adapts to the dependency file used for the scan, so `package-l
231
251
 
232
252
  For deeper investigation, running with `--verbose` provides the fuller remediation context, including the `Copy And Run These Fix Commands` section, dependency paths, parent upgrade guidance for transitive issues when available, a complete fix plan, skipped-item context for unresolved urgent findings, and a detailed table view.
233
253
 
234
- That is the core idea: install it, point it at your project, and immediately get a practical fix plan instead of a wall of raw advisories.
254
+ That is the core idea: install it, point it at your project, and immediately get a practical dependency fix plan instead of a wall of raw advisories.
235
255
 
236
256
  That local loop matters a lot in practice. In the NestJS case study, one dependency path required several `tar` upgrades in sequence as the dependency graph changed after each install. If a team only relied on pipeline scanners, they would likely:
237
257
 
@@ -307,7 +327,7 @@ The project emphasizes:
307
327
 
308
328
  - npm, pnpm, and Yarn lockfile support
309
329
  - direct vs transitive visibility
310
- - top-priority fixes and a suggested remediation plan
330
+ - top-priority fixes and a suggested dependency remediation plan
311
331
  - JSON output for automation
312
332
  - offline scanning through a local advisory database
313
333
  - configurable advisory endpoint support via `--osv-url` for internal proxies or mirrors
@@ -324,7 +344,7 @@ Its role is narrower and workflow-focused:
324
344
  - focused on JavaScript and TypeScript dependency scanning
325
345
  - designed for fast local checks and simple CI release gates
326
346
  - centered on direct vs transitive visibility
327
- - built to highlight top-priority fixes and a suggested remediation plan
347
+ - built to highlight top-priority fixes and a suggested dependency remediation plan
328
348
  - intentionally lightweight in runtime footprint and setup
329
349
 
330
350
  The closest OWASP comparisons are:
@@ -429,6 +449,8 @@ It is important to be precise about the current scope:
429
449
 
430
450
  So the practical model is: **local lockfile scan + advisory matching**. When malicious versions are published to OSV or mirrored through a compatible internal endpoint, CVE Lite CLI can flag those exact versions during a scan.
431
451
 
452
+ If a malicious package was installed and executed, upgrading or removing the dependency may not be sufficient on its own; teams should treat that as a potential security incident and follow their incident-response process.
453
+
432
454
  ## How it works
433
455
 
434
456
  ### Architectural Philosophy
@@ -450,8 +472,8 @@ CVE Lite CLI is designed as a **local-first, metadata-only** scanner. Unlike tra
450
472
 
451
473
  - **fast, low-friction workflow**
452
474
  Run it locally against a project without adopting a large security platform.
453
- - **practical remediation guidance**
454
- It does not stop at raw advisory output. It highlights top-priority fixes, suggests a fix plan, and generates package-manager-aware commands developers can copy and run when confident upgrade targets exist.
475
+ - **practical dependency remediation guidance**
476
+ It does not stop at raw advisory output. It highlights top-priority fixes, suggests a dependency fix plan, and generates package-manager-aware commands developers can copy and run when confident upgrade targets exist. When advisory and registry data allow, it recommends the lowest known non-vulnerable version and shows transparent scan/exclusion counts for checked package versions.
455
477
  - **direct vs transitive visibility**
456
478
  The output makes it easier to see whether the risk comes from something you installed directly or from a nested package.
457
479
  - **developer-first**
@@ -505,6 +527,14 @@ The commands are:
505
527
  - grouped by severity and fix type
506
528
  - designed to be copied directly from the terminal
507
529
  - shown before the deeper remediation detail in verbose mode
530
+ - when enough advisory data exists, targeted to the lowest known non-vulnerable version with transparent version-scan counts in verbose output
531
+
532
+ In practice, this helps avoid repeated install-and-rescan loops.
533
+ Example: if advisory metadata suggests `tar@7.5.3`, CVE Lite CLI validates that target against known advisory ranges. If `7.5.3` is still known vulnerable, it checks the next published versions (`7.5.4`, `7.5.5`, and so on) until it finds the lowest known non-vulnerable version. The verbose output then shows how many versions were scanned and how many were excluded as still known vulnerable.
534
+
535
+ In the NestJS walkthrough, that validation flow scanned 22 package versions for a `tar` remediation path and excluded 21 as still known vulnerable before selecting the lowest known non-vulnerable target (see the [NestJS case study](docs/case-studies/nestjs.md)).
536
+
537
+ This gives developers a more direct remediation path instead of repeatedly upgrading, rescanning, and discovering that the next version is still affected. In slower CI-only workflows, that trial-and-error cycle can otherwise take much longer.
508
538
 
509
539
  ### 4. Top priority fixes
510
540
 
@@ -512,7 +542,7 @@ The CLI highlights the most important issues first, so developers can focus on t
512
542
 
513
543
  ### 5. Suggested fix plan
514
544
 
515
- CVE Lite CLI organizes likely remediation work into a practical sequence, such as:
545
+ CVE Lite CLI organizes likely dependency remediation work into a practical sequence, such as:
516
546
 
517
547
  - direct critical and high issues first
518
548
  - urgent transitive issues next
@@ -616,7 +646,7 @@ jobs:
616
646
  runs-on: ubuntu-latest
617
647
  steps:
618
648
  - uses: actions/checkout@v4
619
- - uses: sonukapoor/cve-lite-cli@v1.2.0
649
+ - uses: sonukapoor/cve-lite-cli@v1
620
650
  with:
621
651
  verbose: "true"
622
652
  fail-on: high
@@ -635,7 +665,7 @@ jobs:
635
665
  runs-on: ubuntu-latest
636
666
  steps:
637
667
  - uses: actions/checkout@v4
638
- - uses: sonukapoor/cve-lite-cli@v1.2.0
668
+ - uses: sonukapoor/cve-lite-cli@v1
639
669
  with:
640
670
  sync-advisories: "true"
641
671
  offline: "true"
@@ -758,7 +788,7 @@ Compared with other tools in this space, CVE Lite CLI focuses on:
758
788
  - **free to use**
759
789
  - **fast to run**
760
790
  - **easy to understand**
761
- - **practical remediation guidance** instead of just raw advisory dumps
791
+ - **practical dependency remediation guidance** instead of just raw advisory dumps
762
792
  - **clear direct vs transitive visibility**
763
793
  - **top priority fixes** and a suggested fix plan
764
794
  - support for **npm**, **pnpm**, and **Yarn** lockfiles
@@ -769,9 +799,9 @@ Compared with other tools in this space, CVE Lite CLI focuses on:
769
799
 
770
800
  ### At a glance
771
801
 
772
- | Tool | Best at | Ecosystem scope | Lockfile support | Guided remediation | JSON/SARIF | Best fit |
802
+ | Tool | Best at | Ecosystem scope | Lockfile support | Dependency remediation guidance | JSON/SARIF | Best fit |
773
803
  |---|---|---|---|---|---|---|
774
- | **CVE Lite CLI** | Fast, developer-friendly pre-release CVE scanning | Focused on JS/TS | npm, pnpm, Yarn | **Yes** | **Yes** | Developers and small teams who want a free, practical release-time check |
804
+ | **CVE Lite CLI** | Fast, developer-friendly pre-release CVE scanning | Focused on JS/TS | npm, pnpm, Yarn | **Dependency fix guidance** | **Yes** | Developers and small teams who want a free, practical release-time check |
775
805
  | `npm audit` | Built-in npm auditing | npm-centric | npm | Basic remediation info | Limited compared to dedicated scanner workflows | Teams already living fully inside npm |
776
806
  | OSV-Scanner | Broad multi-ecosystem scanning | Broad | Many ecosystems and lockfiles | More general-purpose | Strong machine-readable workflows | Teams needing wider ecosystem coverage |
777
807
  | Snyk CLI | Broader enterprise security workflows | Broad | Strong ecosystem coverage | Strong commercial guidance | Strong | Teams adopting a larger security platform |
@@ -96,6 +96,8 @@ export function serializeFinding(finding) {
96
96
  firstFixedVersion: finding.firstFixedVersion,
97
97
  validatedFirstFixedVersion: finding.validatedFirstFixedVersion ?? null,
98
98
  fixVersionValidationNote: finding.fixVersionValidationNote ?? null,
99
+ validatedTargetScannedVersions: finding.validatedTargetScannedVersions ?? null,
100
+ validatedTargetKnownVulnerableVersions: finding.validatedTargetKnownVulnerableVersions ?? null,
99
101
  recommendedAction: getRecommendedAction(finding),
100
102
  primaryParent: getPrimaryParent(finding),
101
103
  recommendedParentUpgrade: finding.recommendedParentUpgrade,
@@ -121,6 +121,7 @@ export function printSuggestedFixCommands(findings, scanInput) {
121
121
  return;
122
122
  if (plan.sections.length === 0)
123
123
  return;
124
+ const sharedDirectTableWidths = computeSharedDirectTableWidths(plan.sections);
124
125
  console.log("");
125
126
  console.log(chalk.bold.yellow("🛠 Copy And Run These Fix Commands"));
126
127
  console.log(`${chalk.gray("Detected package manager:")} ${chalk.cyan(plan.packageManager)} ${chalk.gray(`(${plan.sourceLabel})`)}`);
@@ -128,11 +129,12 @@ export function printSuggestedFixCommands(findings, scanInput) {
128
129
  for (const section of plan.sections) {
129
130
  console.log("");
130
131
  console.log(colorFixSectionTitle(section.severity, section.title));
131
- if (section.kind === "direct-adjusted") {
132
- for (const target of section.targets) {
133
- if (!target.adjustmentNote)
134
- continue;
135
- console.log(chalk.gray(` Note: ${target.adjustmentNote}`));
132
+ if (section.kind === "direct" || section.kind === "direct-adjusted") {
133
+ const validationSummary = summarizeAdjustedValidation(section.targets);
134
+ const remainingNotes = [];
135
+ printDirectTargetsTable(section.targets, remainingNotes, validationSummary, sharedDirectTableWidths);
136
+ for (const note of remainingNotes) {
137
+ console.log(chalk.gray(` Note: ${note}`));
136
138
  }
137
139
  }
138
140
  console.log(renderCommandCallout(section.command));
@@ -324,6 +326,10 @@ export function printCompactOutput(findings, scanInput) {
324
326
  console.log("────────────────────────────────\n");
325
327
  console.log(`${chalk.gray("Detected package manager:")} ${chalk.cyan(plan.packageManager)} ${chalk.gray(`(${plan.sourceLabel})`)}`);
326
328
  console.log(formatFixCommandSummary(plan));
329
+ const compactValidationSummary = summarizeAdjustedValidation(plan.targets);
330
+ if (compactValidationSummary.checked > 0) {
331
+ console.log(chalk.gray(`Validation: scanned ${compactValidationSummary.checked} package version${compactValidationSummary.checked === 1 ? "" : "s"}; ${compactValidationSummary.vulnerable} ${compactValidationSummary.vulnerable === 1 ? "is" : "are"} still known vulnerable.`));
332
+ }
327
333
  console.log("");
328
334
  for (const section of plan.sections.slice(0, 3)) {
329
335
  console.log(`${section.title}`);
@@ -467,3 +473,87 @@ function packageManagerCommandPrefix(packageManager) {
467
473
  return "pnpm add";
468
474
  return "yarn add";
469
475
  }
476
+ function summarizeAdjustedValidation(targets) {
477
+ let checked = 0;
478
+ let vulnerable = 0;
479
+ for (const target of targets) {
480
+ if (target.scannedVersions === null || target.scannedVersions === undefined)
481
+ continue;
482
+ checked += target.scannedVersions;
483
+ vulnerable += target.knownVulnerableVersions ?? 0;
484
+ }
485
+ return { checked, vulnerable };
486
+ }
487
+ function printDirectTargetsTable(targets, remainingNotes, validationSummary, widthsOverride) {
488
+ const headers = ["Package", "Current", "Recommended target", "Versions scanned", "Still known vulnerable"];
489
+ const rows = targets.map(target => {
490
+ if (target.adjustmentNote) {
491
+ const isCountedVulnerabilityNote = target.scannedVersions !== null &&
492
+ target.scannedVersions !== undefined &&
493
+ target.adjustmentNote.includes("is still known vulnerable for");
494
+ if (!isCountedVulnerabilityNote) {
495
+ remainingNotes.push(target.adjustmentNote);
496
+ }
497
+ }
498
+ return [
499
+ target.package,
500
+ target.currentVersion ?? "-",
501
+ chalk.cyan(target.targetVersion),
502
+ target.scannedVersions !== null && target.scannedVersions !== undefined
503
+ ? chalk.blue(String(target.scannedVersions))
504
+ : "-",
505
+ target.knownVulnerableVersions !== null && target.knownVulnerableVersions !== undefined
506
+ ? target.knownVulnerableVersions > 0
507
+ ? chalk.yellow(String(target.knownVulnerableVersions))
508
+ : chalk.green(String(target.knownVulnerableVersions))
509
+ : "-",
510
+ ];
511
+ });
512
+ if (rows.length === 0)
513
+ return;
514
+ const widths = widthsOverride ?? computeTableWidths(headers, rows);
515
+ const line = (left, mid, right) => left + widths.map(w => "─".repeat(w + 2)).join(mid) + right;
516
+ console.log(line("┌", "┬", "┐"));
517
+ console.log(renderRow(headers, widths));
518
+ console.log(line("├", "┼", "┤"));
519
+ for (const row of rows) {
520
+ console.log(renderRow(row.map(value => String(value)), widths));
521
+ }
522
+ if (validationSummary) {
523
+ console.log(line("├", "┼", "┤"));
524
+ console.log(renderRow([
525
+ chalk.bold("Total"),
526
+ "-",
527
+ "-",
528
+ chalk.blue(String(validationSummary.checked)),
529
+ validationSummary.vulnerable > 0
530
+ ? chalk.yellow(String(validationSummary.vulnerable))
531
+ : chalk.green(String(validationSummary.vulnerable)),
532
+ ], widths));
533
+ }
534
+ console.log(line("└", "┴", "┘"));
535
+ }
536
+ function computeTableWidths(headers, rows) {
537
+ return headers.map((header, index) => Math.min(40, Math.max(header.length, ...rows.map(row => stripAnsi(String(row[index])).length))));
538
+ }
539
+ function computeSharedDirectTableWidths(sections) {
540
+ const directSections = sections.filter(section => section.kind === "direct" || section.kind === "direct-adjusted");
541
+ if (directSections.length === 0)
542
+ return undefined;
543
+ const headers = ["Package", "Current", "Recommended target", "Versions scanned", "Still known vulnerable"];
544
+ const rows = [];
545
+ for (const section of directSections) {
546
+ for (const target of section.targets) {
547
+ rows.push([
548
+ target.package,
549
+ target.currentVersion ?? "-",
550
+ target.targetVersion,
551
+ target.scannedVersions !== null && target.scannedVersions !== undefined ? String(target.scannedVersions) : "-",
552
+ target.knownVulnerableVersions !== null && target.knownVulnerableVersions !== undefined ? String(target.knownVulnerableVersions) : "-",
553
+ ]);
554
+ }
555
+ const summary = summarizeAdjustedValidation(section.targets);
556
+ rows.push(["Total", "-", "-", String(summary.checked), String(summary.vulnerable)]);
557
+ }
558
+ return computeTableWidths(headers, rows);
559
+ }
@@ -43,7 +43,10 @@ export function buildSuggestedFixCommandPlan(findings, scanInput) {
43
43
  (!hasValidatedField || finding.validatedFirstFixedVersion !== null)) {
44
44
  upsertTarget(targetsByPackage, {
45
45
  package: finding.pkg.name,
46
+ currentVersion: finding.pkg.version,
46
47
  targetVersion: directTarget,
48
+ scannedVersions: finding.validatedTargetScannedVersions ?? null,
49
+ knownVulnerableVersions: finding.validatedTargetKnownVulnerableVersions ?? null,
47
50
  kind: "direct",
48
51
  urgent,
49
52
  severity: finding.severity,
@@ -92,6 +95,8 @@ export function buildSuggestedFixCommandPlan(findings, scanInput) {
92
95
  upsertTarget(targetsByPackage, {
93
96
  package: finding.recommendedParentUpgrade.package,
94
97
  targetVersion: finding.recommendedParentUpgrade.targetVersion,
98
+ scannedVersions: null,
99
+ knownVulnerableVersions: null,
95
100
  kind: "parent-upgrade",
96
101
  urgent,
97
102
  severity: finding.severity,
@@ -192,6 +197,8 @@ function upsertTarget(targetsByPackage, next) {
192
197
  if (compareVersions(next.targetVersion, existing.targetVersion) > 0) {
193
198
  merged.targetVersion = next.targetVersion;
194
199
  merged.reason = next.reason;
200
+ merged.scannedVersions = next.scannedVersions ?? merged.scannedVersions ?? null;
201
+ merged.knownVulnerableVersions = next.knownVulnerableVersions ?? merged.knownVulnerableVersions ?? null;
195
202
  }
196
203
  targetsByPackage.set(next.package, merged);
197
204
  return;
@@ -200,6 +207,8 @@ function upsertTarget(targetsByPackage, next) {
200
207
  merged.targetVersion = next.targetVersion;
201
208
  merged.reason = next.reason;
202
209
  merged.adjustmentNote = next.adjustmentNote ?? merged.adjustmentNote;
210
+ merged.scannedVersions = next.scannedVersions ?? merged.scannedVersions ?? null;
211
+ merged.knownVulnerableVersions = next.knownVulnerableVersions ?? merged.knownVulnerableVersions ?? null;
203
212
  }
204
213
  targetsByPackage.set(next.package, merged);
205
214
  }
@@ -39,6 +39,9 @@ export async function resolvePublishedFixVersion(packageName, fixedVersionHint)
39
39
  resolvedVersion: null,
40
40
  note: `Fixed-version hint ${fixedVersionHint} could not be verified against the npm registry for ${packageName}.`,
41
41
  verified: false,
42
+ candidatesChecked: 0,
43
+ candidatesKnownVulnerable: 0,
44
+ candidatesUnknownCoverage: 0,
42
45
  };
43
46
  }
44
47
  const publishedVersions = Object.keys(packument.versions ?? {})
@@ -49,6 +52,9 @@ export async function resolvePublishedFixVersion(packageName, fixedVersionHint)
49
52
  resolvedVersion: fixedVersionHint,
50
53
  note: null,
51
54
  verified: true,
55
+ candidatesChecked: 0,
56
+ candidatesKnownVulnerable: 0,
57
+ candidatesUnknownCoverage: 0,
52
58
  };
53
59
  }
54
60
  const nearestPublishedVersion = publishedVersions.find(version => compareVersions(version, fixedVersionHint) >= 0) ?? null;
@@ -57,11 +63,196 @@ export async function resolvePublishedFixVersion(packageName, fixedVersionHint)
57
63
  resolvedVersion: nearestPublishedVersion,
58
64
  note: `Advisory fixed-version hint ${fixedVersionHint} is not published on npm for ${packageName}; using nearest published version ${nearestPublishedVersion}.`,
59
65
  verified: true,
66
+ candidatesChecked: 0,
67
+ candidatesKnownVulnerable: 0,
68
+ candidatesUnknownCoverage: 0,
60
69
  };
61
70
  }
62
71
  return {
63
72
  resolvedVersion: null,
64
73
  note: `Advisory fixed-version hint ${fixedVersionHint} is not published on npm for ${packageName}, and no published version >= ${fixedVersionHint} was found.`,
65
74
  verified: true,
75
+ candidatesChecked: 0,
76
+ candidatesKnownVulnerable: 0,
77
+ candidatesUnknownCoverage: 0,
66
78
  };
67
79
  }
80
+ export async function resolveLowestKnownNonVulnerableVersion(packageName, installedVersion, vulnerabilities) {
81
+ if (!looksLikeVersion(installedVersion)) {
82
+ return {
83
+ resolvedVersion: null,
84
+ note: `Installed version ${installedVersion} for ${packageName} could not be evaluated as an exact semver version.`,
85
+ verified: false,
86
+ candidatesChecked: 0,
87
+ candidatesKnownVulnerable: 0,
88
+ candidatesUnknownCoverage: 0,
89
+ };
90
+ }
91
+ if (vulnerabilities.length === 0) {
92
+ return {
93
+ resolvedVersion: null,
94
+ note: `No advisory details were available to validate a lowest known non-vulnerable version for ${packageName}.`,
95
+ verified: false,
96
+ candidatesChecked: 0,
97
+ candidatesKnownVulnerable: 0,
98
+ candidatesUnknownCoverage: 0,
99
+ };
100
+ }
101
+ const packument = await fetchPackument(packageName);
102
+ if (!packument) {
103
+ return {
104
+ resolvedVersion: null,
105
+ note: `Published versions for ${packageName} could not be verified against the npm registry.`,
106
+ verified: false,
107
+ candidatesChecked: 0,
108
+ candidatesKnownVulnerable: 0,
109
+ candidatesUnknownCoverage: 0,
110
+ };
111
+ }
112
+ const candidates = Object.keys(packument.versions ?? {})
113
+ .filter(looksLikeVersion)
114
+ .filter(version => compareVersions(version, installedVersion) > 0)
115
+ .sort(compareVersions);
116
+ if (candidates.length === 0) {
117
+ return {
118
+ resolvedVersion: null,
119
+ note: `No published versions above ${installedVersion} were found for ${packageName}.`,
120
+ verified: true,
121
+ candidatesChecked: 0,
122
+ candidatesKnownVulnerable: 0,
123
+ candidatesUnknownCoverage: 0,
124
+ };
125
+ }
126
+ let candidatesChecked = 0;
127
+ let candidatesKnownVulnerable = 0;
128
+ let candidatesUnknownCoverage = 0;
129
+ let sawUnknownCoverage = false;
130
+ for (const candidate of candidates) {
131
+ candidatesChecked += 1;
132
+ let affected = false;
133
+ let unknown = false;
134
+ for (const vuln of vulnerabilities) {
135
+ const impacted = isVersionAffectedByVulnerability(packageName, candidate, vuln);
136
+ if (impacted === true) {
137
+ affected = true;
138
+ break;
139
+ }
140
+ if (impacted === null) {
141
+ unknown = true;
142
+ }
143
+ }
144
+ if (affected) {
145
+ candidatesKnownVulnerable += 1;
146
+ continue;
147
+ }
148
+ if (unknown) {
149
+ sawUnknownCoverage = true;
150
+ candidatesUnknownCoverage += 1;
151
+ continue;
152
+ }
153
+ return {
154
+ resolvedVersion: candidate,
155
+ note: null,
156
+ verified: true,
157
+ candidatesChecked,
158
+ candidatesKnownVulnerable,
159
+ candidatesUnknownCoverage,
160
+ };
161
+ }
162
+ if (sawUnknownCoverage) {
163
+ return {
164
+ resolvedVersion: null,
165
+ note: `Advisory range data for ${packageName} is incomplete, so a lowest known non-vulnerable version could not be confirmed.`,
166
+ verified: false,
167
+ candidatesChecked,
168
+ candidatesKnownVulnerable,
169
+ candidatesUnknownCoverage,
170
+ };
171
+ }
172
+ return {
173
+ resolvedVersion: null,
174
+ note: `No known non-vulnerable published version was found above ${installedVersion} for ${packageName}.`,
175
+ verified: true,
176
+ candidatesChecked,
177
+ candidatesKnownVulnerable,
178
+ candidatesUnknownCoverage,
179
+ };
180
+ }
181
+ function isVersionAffectedByVulnerability(packageName, version, vuln) {
182
+ const affectedEntries = vuln.affected ?? [];
183
+ if (affectedEntries.length === 0)
184
+ return null;
185
+ const matchingEntries = affectedEntries.filter(entry => {
186
+ const affectedName = entry.package?.name;
187
+ const affectedEcosystem = entry.package?.ecosystem?.toLowerCase();
188
+ if (affectedName && affectedName !== packageName)
189
+ return false;
190
+ if (affectedEcosystem && affectedEcosystem !== "npm")
191
+ return false;
192
+ return true;
193
+ });
194
+ if (matchingEntries.length === 0)
195
+ return null;
196
+ let sawUnknown = false;
197
+ for (const entry of matchingEntries) {
198
+ const ranges = entry.ranges ?? [];
199
+ if (ranges.length === 0) {
200
+ sawUnknown = true;
201
+ continue;
202
+ }
203
+ for (const range of ranges) {
204
+ if (range.type && range.type !== "SEMVER") {
205
+ sawUnknown = true;
206
+ continue;
207
+ }
208
+ const impacted = isVersionAffectedByEvents(version, range.events ?? []);
209
+ if (impacted === true)
210
+ return true;
211
+ if (impacted === null)
212
+ sawUnknown = true;
213
+ }
214
+ }
215
+ return sawUnknown ? null : false;
216
+ }
217
+ function isVersionAffectedByEvents(version, events) {
218
+ if (events.length === 0)
219
+ return null;
220
+ let introduced = null;
221
+ let sawComparableWindow = false;
222
+ for (const event of events) {
223
+ if (event.introduced !== undefined) {
224
+ if (event.introduced !== "0" && !looksLikeVersion(event.introduced)) {
225
+ return null;
226
+ }
227
+ introduced = event.introduced;
228
+ }
229
+ if (event.fixed !== undefined || event.last_affected !== undefined) {
230
+ if (event.fixed && !looksLikeVersion(event.fixed))
231
+ return null;
232
+ if (event.last_affected && !looksLikeVersion(event.last_affected))
233
+ return null;
234
+ sawComparableWindow = true;
235
+ const lowerBoundOk = introduced === null || introduced === "0" || compareVersions(version, introduced) >= 0;
236
+ const upperBoundOk = event.fixed
237
+ ? compareVersions(version, event.fixed) < 0
238
+ : event.last_affected
239
+ ? compareVersions(version, event.last_affected) <= 0
240
+ : true;
241
+ if (lowerBoundOk && upperBoundOk) {
242
+ return true;
243
+ }
244
+ introduced = null;
245
+ }
246
+ }
247
+ if (introduced !== null) {
248
+ if (introduced !== "0" && !looksLikeVersion(introduced))
249
+ return null;
250
+ sawComparableWindow = true;
251
+ const lowerBoundOk = introduced === "0" || compareVersions(version, introduced) >= 0;
252
+ if (lowerBoundOk)
253
+ return true;
254
+ }
255
+ if (!sawComparableWindow)
256
+ return null;
257
+ return false;
258
+ }
@@ -20,7 +20,7 @@ export async function resolveRecommendedParentUpgrade(finding, packages) {
20
20
  directParentVersion: directParent.version,
21
21
  vulnerableName,
22
22
  vulnerableInstalledVersion: finding.pkg.version,
23
- vulnerableFixedVersion: finding.firstFixedVersion,
23
+ vulnerableFixedVersion: finding.validatedFirstFixedVersion ?? finding.firstFixedVersion,
24
24
  viaPath,
25
25
  });
26
26
  }
package/dist/scanner.js CHANGED
@@ -8,7 +8,7 @@ import { LocalAdvisorySource } from "./advisory/local-advisory-source.js";
8
8
  import { LocalAdvisoryDatabase } from "./advisory/local-db.js";
9
9
  import { ADVISORY_DB_STALE_AFTER_MS, getDefaultAdvisoryDbPath } from "./advisory/osv-sync.js";
10
10
  import { resolveRecommendedParentUpgrade } from "./remediation/parent-upgrade.js";
11
- import { resolvePublishedFixVersion } from "./remediation/npm-registry.js";
11
+ import { resolveLowestKnownNonVulnerableVersion, resolvePublishedFixVersion } from "./remediation/npm-registry.js";
12
12
  export function createAdvisorySource(options) {
13
13
  const offline = !!options?.offline || !!options?.offlineDb;
14
14
  if (offline) {
@@ -177,6 +177,8 @@ export async function scanPackages(packages, batchSize, options) {
177
177
  firstFixedVersion,
178
178
  validatedFirstFixedVersion: null,
179
179
  fixVersionValidationNote: null,
180
+ validatedTargetScannedVersions: null,
181
+ validatedTargetKnownVulnerableVersions: null,
180
182
  recommendedParentUpgrade: undefined,
181
183
  };
182
184
  });
@@ -204,15 +206,40 @@ export async function scanPackages(packages, batchSize, options) {
204
206
  }
205
207
  }
206
208
  async function validateDirectFixTargets(findings) {
207
- const directCandidates = findings.filter(finding => (finding.relationship === "direct" || finding.relationship === "unknown") &&
208
- Boolean(finding.firstFixedVersion));
209
+ const directCandidates = findings.filter(finding => finding.vulnerabilities.length > 0);
209
210
  for (const finding of directCandidates) {
210
- const targetVersion = finding.firstFixedVersion;
211
- if (!targetVersion)
211
+ const lowestKnownResolution = await resolveLowestKnownNonVulnerableVersion(finding.pkg.name, finding.pkg.version, finding.vulnerabilities);
212
+ const fixedVersionHint = finding.firstFixedVersion;
213
+ if (lowestKnownResolution.resolvedVersion) {
214
+ finding.validatedFirstFixedVersion = lowestKnownResolution.resolvedVersion;
215
+ finding.validatedTargetScannedVersions = lowestKnownResolution.candidatesChecked;
216
+ finding.validatedTargetKnownVulnerableVersions = lowestKnownResolution.candidatesKnownVulnerable;
217
+ if (!fixedVersionHint || fixedVersionHint === lowestKnownResolution.resolvedVersion) {
218
+ finding.fixVersionValidationNote = null;
219
+ continue;
220
+ }
221
+ const hintResolution = await resolvePublishedFixVersion(finding.pkg.name, fixedVersionHint);
222
+ if (hintResolution.resolvedVersion === lowestKnownResolution.resolvedVersion &&
223
+ hintResolution.note) {
224
+ finding.fixVersionValidationNote = hintResolution.note;
225
+ continue;
226
+ }
227
+ finding.fixVersionValidationNote =
228
+ `Advisory fixed-version hint ${fixedVersionHint} is still known vulnerable for ${finding.pkg.name}; scanned ${lowestKnownResolution.candidatesChecked} package version${lowestKnownResolution.candidatesChecked === 1 ? "" : "s"} above current version (${lowestKnownResolution.candidatesKnownVulnerable} still known vulnerable); using lowest known non-vulnerable version ${lowestKnownResolution.resolvedVersion}.`;
212
229
  continue;
213
- const resolution = await resolvePublishedFixVersion(finding.pkg.name, targetVersion);
230
+ }
231
+ if (!fixedVersionHint) {
232
+ finding.validatedFirstFixedVersion = null;
233
+ finding.fixVersionValidationNote = lowestKnownResolution.note;
234
+ finding.validatedTargetScannedVersions = null;
235
+ finding.validatedTargetKnownVulnerableVersions = null;
236
+ continue;
237
+ }
238
+ const resolution = await resolvePublishedFixVersion(finding.pkg.name, fixedVersionHint);
214
239
  finding.validatedFirstFixedVersion = resolution.resolvedVersion;
215
- finding.fixVersionValidationNote = resolution.note;
240
+ finding.fixVersionValidationNote = resolution.note ?? lowestKnownResolution.note;
241
+ finding.validatedTargetScannedVersions = null;
242
+ finding.validatedTargetKnownVulnerableVersions = null;
216
243
  }
217
244
  }
218
245
  function isAdvisoryDbStale(metadata) {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "cve-lite-cli",
3
- "version": "1.4.0",
3
+ "version": "1.5.0",
4
4
  "description": "Developer-friendly CLI for scanning JS/TS projects for dependency vulnerabilities using local lockfiles and OSV",
5
5
  "type": "module",
6
6
  "bin": {