cve-lite-cli 1.4.0 → 1.5.1

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 (direct command groups apply to manifest-declared dependencies)
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.
@@ -219,7 +239,7 @@ The most important section to look for in the output is:
219
239
  🛠 Copy And Run These Fix Commands
220
240
  ```
221
241
 
222
- That is one of the clearest differentiators in CVE Lite CLI. Instead of only showing advisories and severity counts, the tool tries to turn the findings into concrete commands developers can copy and run immediately.
242
+ That is one of the clearest differentiators in CVE Lite CLI. Instead of only showing advisories and severity counts, the tool tries to turn findings into concrete commands developers can copy and run immediately for manifest-declared direct dependencies, while still showing parent-upgrade guidance for transitive issues when available.
223
243
 
224
244
  For example, the tool can now suggest a concrete next command such as:
225
245
 
@@ -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**
@@ -504,7 +526,16 @@ The commands are:
504
526
  - package-manager-aware
505
527
  - grouped by severity and fix type
506
528
  - designed to be copied directly from the terminal
529
+ - direct command groups are limited to dependencies declared in the scanned root manifest
507
530
  - shown before the deeper remediation detail in verbose mode
531
+ - when enough advisory data exists, targeted to the lowest known non-vulnerable version with transparent version-scan counts in verbose output
532
+
533
+ In practice, this helps avoid repeated install-and-rescan loops.
534
+ 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.
535
+
536
+ 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)).
537
+
538
+ 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
539
 
509
540
  ### 4. Top priority fixes
510
541
 
@@ -512,7 +543,7 @@ The CLI highlights the most important issues first, so developers can focus on t
512
543
 
513
544
  ### 5. Suggested fix plan
514
545
 
515
- CVE Lite CLI organizes likely remediation work into a practical sequence, such as:
546
+ CVE Lite CLI organizes likely dependency remediation work into a practical sequence, such as:
516
547
 
517
548
  - direct critical and high issues first
518
549
  - urgent transitive issues next
@@ -616,7 +647,7 @@ jobs:
616
647
  runs-on: ubuntu-latest
617
648
  steps:
618
649
  - uses: actions/checkout@v4
619
- - uses: sonukapoor/cve-lite-cli@v1.2.0
650
+ - uses: sonukapoor/cve-lite-cli@v1
620
651
  with:
621
652
  verbose: "true"
622
653
  fail-on: high
@@ -635,7 +666,7 @@ jobs:
635
666
  runs-on: ubuntu-latest
636
667
  steps:
637
668
  - uses: actions/checkout@v4
638
- - uses: sonukapoor/cve-lite-cli@v1.2.0
669
+ - uses: sonukapoor/cve-lite-cli@v1
639
670
  with:
640
671
  sync-advisories: "true"
641
672
  offline: "true"
@@ -758,7 +789,7 @@ Compared with other tools in this space, CVE Lite CLI focuses on:
758
789
  - **free to use**
759
790
  - **fast to run**
760
791
  - **easy to understand**
761
- - **practical remediation guidance** instead of just raw advisory dumps
792
+ - **practical dependency remediation guidance** instead of just raw advisory dumps
762
793
  - **clear direct vs transitive visibility**
763
794
  - **top priority fixes** and a suggested fix plan
764
795
  - support for **npm**, **pnpm**, and **Yarn** lockfiles
@@ -769,9 +800,9 @@ Compared with other tools in this space, CVE Lite CLI focuses on:
769
800
 
770
801
  ### At a glance
771
802
 
772
- | Tool | Best at | Ecosystem scope | Lockfile support | Guided remediation | JSON/SARIF | Best fit |
803
+ | Tool | Best at | Ecosystem scope | Lockfile support | Dependency remediation guidance | JSON/SARIF | Best fit |
773
804
  |---|---|---|---|---|---|---|
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 |
805
+ | **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
806
  | `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
807
  | OSV-Scanner | Broad multi-ecosystem scanning | Broad | Many ecosystems and lockfiles | More general-purpose | Strong machine-readable workflows | Teams needing wider ecosystem coverage |
777
808
  | Snyk CLI | Broader enterprise security workflows | Broad | Strong ecosystem coverage | Strong commercial guidance | Strong | Teams adopting a larger security platform |
package/dist/index.js CHANGED
@@ -1,4 +1,5 @@
1
1
  #!/usr/bin/env node
2
+ import fs from "node:fs";
2
3
  import path from "node:path";
3
4
  import process from "node:process";
4
5
  import { parseArgs } from "./cli/args.js";
@@ -131,7 +132,8 @@ if (parsedArgs) {
131
132
  process.exit(0);
132
133
  return;
133
134
  }
134
- const findings = await scanPackages(packages, batchSize, options);
135
+ const directDependencyNames = readDirectDependencyNames(projectPath, !!options.prodOnly);
136
+ const findings = await scanPackages(packages, batchSize, options, { directDependencyNames });
135
137
  const sorted = findings.sort((a, b) => severityOrder[b.severity] - severityOrder[a.severity]);
136
138
  const coverage = buildCoverageNotes(scanInput, !!options.offline || !!options.offlineDb);
137
139
  const minSeverity = normalizeSeverity(options.minSeverity || "medium");
@@ -197,6 +199,34 @@ function formatAdvisorySourceLine(sourceLabel) {
197
199
  }
198
200
  return `${match[1]} (${chalk.cyan(match[2])})`;
199
201
  }
202
+ function readDirectDependencyNames(projectPath, prodOnly) {
203
+ const packageJsonPath = path.join(projectPath, "package.json");
204
+ if (!fs.existsSync(packageJsonPath)) {
205
+ return null;
206
+ }
207
+ try {
208
+ const raw = JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
209
+ const directNames = new Set();
210
+ const sections = [
211
+ raw?.dependencies,
212
+ raw?.optionalDependencies,
213
+ ];
214
+ if (!prodOnly) {
215
+ sections.push(raw?.devDependencies);
216
+ }
217
+ for (const section of sections) {
218
+ if (!section || typeof section !== "object")
219
+ continue;
220
+ for (const name of Object.keys(section)) {
221
+ directNames.add(name);
222
+ }
223
+ }
224
+ return directNames;
225
+ }
226
+ catch {
227
+ return null;
228
+ }
229
+ }
200
230
  function formatAdvisoryDbFreshness(lastSyncAt) {
201
231
  if (!lastSyncAt) {
202
232
  return chalk.yellow("unknown");
@@ -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,8 @@ export function printSuggestedFixCommands(findings, scanInput) {
121
121
  return;
122
122
  if (plan.sections.length === 0)
123
123
  return;
124
+ const sharedDirectTableWidths = computeSharedDirectTableWidths(plan.sections);
125
+ const sharedParentUpgradeTableWidths = computeSharedParentUpgradeTableWidths(plan.sections);
124
126
  console.log("");
125
127
  console.log(chalk.bold.yellow("🛠 Copy And Run These Fix Commands"));
126
128
  console.log(`${chalk.gray("Detected package manager:")} ${chalk.cyan(plan.packageManager)} ${chalk.gray(`(${plan.sourceLabel})`)}`);
@@ -128,13 +130,17 @@ export function printSuggestedFixCommands(findings, scanInput) {
128
130
  for (const section of plan.sections) {
129
131
  console.log("");
130
132
  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}`));
133
+ if (section.kind === "direct" || section.kind === "direct-adjusted") {
134
+ const validationSummary = summarizeAdjustedValidation(section.targets);
135
+ const remainingNotes = [];
136
+ printDirectTargetsTable(section.targets, remainingNotes, validationSummary, sharedDirectTableWidths);
137
+ for (const note of remainingNotes) {
138
+ console.log(chalk.gray(` Note: ${note}`));
136
139
  }
137
140
  }
141
+ else if (shouldRenderParentUpgradeTable(section.targets)) {
142
+ printParentUpgradeTargetsTable(section.targets, sharedParentUpgradeTableWidths);
143
+ }
138
144
  console.log(renderCommandCallout(section.command));
139
145
  }
140
146
  }
@@ -324,6 +330,10 @@ export function printCompactOutput(findings, scanInput) {
324
330
  console.log("────────────────────────────────\n");
325
331
  console.log(`${chalk.gray("Detected package manager:")} ${chalk.cyan(plan.packageManager)} ${chalk.gray(`(${plan.sourceLabel})`)}`);
326
332
  console.log(formatFixCommandSummary(plan));
333
+ const compactValidationSummary = summarizeAdjustedValidation(plan.targets);
334
+ if (compactValidationSummary.checked > 0) {
335
+ console.log(chalk.gray(`Validation: scanned ${compactValidationSummary.checked} package version${compactValidationSummary.checked === 1 ? "" : "s"}; ${compactValidationSummary.vulnerable} ${compactValidationSummary.vulnerable === 1 ? "is" : "are"} still known vulnerable.`));
336
+ }
327
337
  console.log("");
328
338
  for (const section of plan.sections.slice(0, 3)) {
329
339
  console.log(`${section.title}`);
@@ -467,3 +477,128 @@ function packageManagerCommandPrefix(packageManager) {
467
477
  return "pnpm add";
468
478
  return "yarn add";
469
479
  }
480
+ function summarizeAdjustedValidation(targets) {
481
+ let checked = 0;
482
+ let vulnerable = 0;
483
+ for (const target of targets) {
484
+ if (target.scannedVersions === null || target.scannedVersions === undefined)
485
+ continue;
486
+ checked += target.scannedVersions;
487
+ vulnerable += target.knownVulnerableVersions ?? 0;
488
+ }
489
+ return { checked, vulnerable };
490
+ }
491
+ function printDirectTargetsTable(targets, remainingNotes, validationSummary, widthsOverride) {
492
+ const headers = ["Package", "Current", "Recommended target", "Versions scanned", "Still known vulnerable"];
493
+ const rows = targets.map(target => {
494
+ if (target.adjustmentNote) {
495
+ const isCountedVulnerabilityNote = target.scannedVersions !== null &&
496
+ target.scannedVersions !== undefined &&
497
+ target.adjustmentNote.includes("is still known vulnerable for");
498
+ if (!isCountedVulnerabilityNote) {
499
+ remainingNotes.push(target.adjustmentNote);
500
+ }
501
+ }
502
+ return [
503
+ target.package,
504
+ target.currentVersion ?? "-",
505
+ chalk.cyan(target.targetVersion),
506
+ target.scannedVersions !== null && target.scannedVersions !== undefined
507
+ ? chalk.blue(String(target.scannedVersions))
508
+ : "-",
509
+ target.knownVulnerableVersions !== null && target.knownVulnerableVersions !== undefined
510
+ ? target.knownVulnerableVersions > 0
511
+ ? chalk.yellow(String(target.knownVulnerableVersions))
512
+ : chalk.green(String(target.knownVulnerableVersions))
513
+ : "-",
514
+ ];
515
+ });
516
+ if (rows.length === 0)
517
+ return;
518
+ const widths = widthsOverride ?? computeTableWidths(headers, rows);
519
+ const line = (left, mid, right) => left + widths.map(w => "─".repeat(w + 2)).join(mid) + right;
520
+ console.log(line("┌", "┬", "┐"));
521
+ console.log(renderRow(headers, widths));
522
+ console.log(line("├", "┼", "┤"));
523
+ for (const row of rows) {
524
+ console.log(renderRow(row.map(value => String(value)), widths));
525
+ }
526
+ if (validationSummary) {
527
+ console.log(line("├", "┼", "┤"));
528
+ console.log(renderRow([
529
+ chalk.bold("Total"),
530
+ "-",
531
+ "-",
532
+ chalk.blue(String(validationSummary.checked)),
533
+ validationSummary.vulnerable > 0
534
+ ? chalk.yellow(String(validationSummary.vulnerable))
535
+ : chalk.green(String(validationSummary.vulnerable)),
536
+ ], widths));
537
+ }
538
+ console.log(line("└", "┴", "┘"));
539
+ }
540
+ function printParentUpgradeTargetsTable(targets, widthsOverride) {
541
+ const headers = ["Package", "Current", "Recommended target", "Context"];
542
+ const rows = targets.map(target => [
543
+ target.package,
544
+ target.currentVersion ?? "-",
545
+ chalk.cyan(target.targetVersion),
546
+ chalk.gray(target.reason),
547
+ ]);
548
+ if (rows.length === 0)
549
+ return;
550
+ const widths = widthsOverride ?? computeTableWidths(headers, rows);
551
+ const line = (left, mid, right) => left + widths.map(w => "─".repeat(w + 2)).join(mid) + right;
552
+ console.log(line("┌", "┬", "┐"));
553
+ console.log(renderRow(headers, widths));
554
+ console.log(line("├", "┼", "┤"));
555
+ for (const row of rows) {
556
+ console.log(renderRow(row.map(value => String(value)), widths));
557
+ }
558
+ console.log(line("└", "┴", "┘"));
559
+ }
560
+ function computeTableWidths(headers, rows) {
561
+ return headers.map((header, index) => Math.min(40, Math.max(header.length, ...rows.map(row => stripAnsi(String(row[index])).length))));
562
+ }
563
+ function computeSharedDirectTableWidths(sections) {
564
+ const directSections = sections.filter(section => section.kind === "direct" || section.kind === "direct-adjusted");
565
+ if (directSections.length === 0)
566
+ return undefined;
567
+ const headers = ["Package", "Current", "Recommended target", "Versions scanned", "Still known vulnerable"];
568
+ const rows = [];
569
+ for (const section of directSections) {
570
+ for (const target of section.targets) {
571
+ rows.push([
572
+ target.package,
573
+ target.currentVersion ?? "-",
574
+ target.targetVersion,
575
+ target.scannedVersions !== null && target.scannedVersions !== undefined ? String(target.scannedVersions) : "-",
576
+ target.knownVulnerableVersions !== null && target.knownVulnerableVersions !== undefined ? String(target.knownVulnerableVersions) : "-",
577
+ ]);
578
+ }
579
+ const summary = summarizeAdjustedValidation(section.targets);
580
+ rows.push(["Total", "-", "-", String(summary.checked), String(summary.vulnerable)]);
581
+ }
582
+ return computeTableWidths(headers, rows);
583
+ }
584
+ function shouldRenderParentUpgradeTable(targets) {
585
+ return targets.length > 0 && targets.every(target => target.kind === "parent-upgrade");
586
+ }
587
+ function computeSharedParentUpgradeTableWidths(sections) {
588
+ const parentSections = sections.filter(section => shouldRenderParentUpgradeTable(section.targets));
589
+ if (parentSections.length === 0)
590
+ return undefined;
591
+ const headers = ["Package", "Current", "Recommended target", "Context"];
592
+ const rows = [];
593
+ for (const section of parentSections) {
594
+ for (const target of section.targets) {
595
+ rows.push([
596
+ target.package,
597
+ target.currentVersion ?? "-",
598
+ target.targetVersion,
599
+ target.reason,
600
+ ]);
601
+ }
602
+ }
603
+ return computeTableWidths(headers, rows);
604
+ }
@@ -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,
@@ -91,7 +94,10 @@ export function buildSuggestedFixCommandPlan(findings, scanInput) {
91
94
  isUpgradeTarget(finding.recommendedParentUpgrade.currentVersion, finding.recommendedParentUpgrade.targetVersion)) {
92
95
  upsertTarget(targetsByPackage, {
93
96
  package: finding.recommendedParentUpgrade.package,
97
+ currentVersion: finding.recommendedParentUpgrade.currentVersion,
94
98
  targetVersion: finding.recommendedParentUpgrade.targetVersion,
99
+ scannedVersions: null,
100
+ knownVulnerableVersions: null,
95
101
  kind: "parent-upgrade",
96
102
  urgent,
97
103
  severity: finding.severity,
@@ -191,15 +197,21 @@ function upsertTarget(targetsByPackage, next) {
191
197
  if (looksLikeVersion(existing.targetVersion) && looksLikeVersion(next.targetVersion)) {
192
198
  if (compareVersions(next.targetVersion, existing.targetVersion) > 0) {
193
199
  merged.targetVersion = next.targetVersion;
200
+ merged.currentVersion = next.currentVersion ?? merged.currentVersion;
194
201
  merged.reason = next.reason;
202
+ merged.scannedVersions = next.scannedVersions ?? merged.scannedVersions ?? null;
203
+ merged.knownVulnerableVersions = next.knownVulnerableVersions ?? merged.knownVulnerableVersions ?? null;
195
204
  }
196
205
  targetsByPackage.set(next.package, merged);
197
206
  return;
198
207
  }
199
208
  if (next.kind === "direct" && existing.kind !== "direct") {
209
+ merged.currentVersion = next.currentVersion ?? merged.currentVersion;
200
210
  merged.targetVersion = next.targetVersion;
201
211
  merged.reason = next.reason;
202
212
  merged.adjustmentNote = next.adjustmentNote ?? merged.adjustmentNote;
213
+ merged.scannedVersions = next.scannedVersions ?? merged.scannedVersions ?? null;
214
+ merged.knownVulnerableVersions = next.knownVulnerableVersions ?? merged.knownVulnerableVersions ?? null;
203
215
  }
204
216
  targetsByPackage.set(next.package, merged);
205
217
  }
@@ -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) {
@@ -37,7 +37,7 @@ export function createAdvisorySource(options) {
37
37
  function getPackageCacheKey(pkg) {
38
38
  return `${pkg.ecosystem}:${pkg.name}@${pkg.version}`;
39
39
  }
40
- export async function scanPackages(packages, batchSize, options) {
40
+ export async function scanPackages(packages, batchSize, options, context) {
41
41
  const sourceContext = createAdvisorySource({
42
42
  osvUrl: options.osvUrl,
43
43
  offline: options.offline,
@@ -165,7 +165,7 @@ export async function scanPackages(packages, batchSize, options) {
165
165
  const severity = maxSeverity(vulnerabilities);
166
166
  const cveAliases = unique(vulnerabilities.flatMap(v => (v.aliases ?? []).filter(a => a.startsWith("CVE-"))));
167
167
  const dependencyPaths = result.pkg.paths ?? [];
168
- const relationship = classifyRelationship(dependencyPaths);
168
+ const relationship = classifyRelationship(dependencyPaths, result.pkg.name, context?.directDependencyNames);
169
169
  const firstFixedVersion = findFirstFixedVersion(vulnerabilities);
170
170
  return {
171
171
  pkg: result.pkg,
@@ -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) {
@@ -225,9 +252,13 @@ function isAdvisoryDbStale(metadata) {
225
252
  }
226
253
  return Date.now() - timestamp > ADVISORY_DB_STALE_AFTER_MS;
227
254
  }
228
- function classifyRelationship(paths) {
255
+ function classifyRelationship(paths, packageName, directDependencyNames) {
256
+ if (packageName && directDependencyNames?.has(packageName))
257
+ return "direct";
229
258
  if (paths.length === 0)
230
259
  return "unknown";
260
+ if (directDependencyNames)
261
+ return "transitive";
231
262
  const shortest = Math.min(...paths.map(p => p.length));
232
263
  if (shortest <= 2)
233
264
  return "direct";
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.1",
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": {