cve-lite-cli 1.10.0 → 1.12.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
@@ -36,9 +36,9 @@
36
36
  <a href="#quick-start">Quick Start</a> •
37
37
  <a href="#usage">Usage</a> •
38
38
  <a href="#what-it-looks-like">Screenshots</a> •
39
- <a href="docs/html-report.md">HTML Report</a> •
40
- <a href="docs/comparison.md">Compare</a> •
41
- <a href="docs/roadmap.md">Roadmap</a> •
39
+ <a href="https://owasp.org/cve-lite-cli/docs/html-report">HTML Report</a> •
40
+ <a href="https://owasp.org/cve-lite-cli/docs/comparison">Compare</a> •
41
+ <a href="https://owasp.org/cve-lite-cli/docs/roadmap">Roadmap</a> •
42
42
  <a href="https://github.com/OWASP/cve-lite-cli/blob/main/src/docs/CONTRIBUTING.md">Contributing</a>
43
43
  </p>
44
44
  </div>
@@ -82,6 +82,7 @@ No account. No configuration. No source code leaves your machine.
82
82
 
83
83
  - **Produces copy-and-run fix commands** — every finding comes with a package-manager-aware install command you can run immediately
84
84
  - **Distinguishes direct from transitive risk** — shows whether the vulnerability is in something you installed or buried three levels deep in a dependency chain
85
+ - **Explains parent update paths** — for transitive npm findings, recommends `npm update <parent>` when the current parent range can resolve a known non-vulnerable child, or a parent upgrade when the range itself must change
85
86
  - **Usage-aware reachability** — optionally uses static analysis to detect whether vulnerable packages are actually imported in your code, cutting noise with `--usage` and `--only-used`
86
87
  - **Offline advisory DB** — sync advisory data ahead of time and scan with zero runtime API calls, designed for enterprise and air-gapped environments
87
88
  - **Interactive HTML report** — generate a self-contained dashboard with severity cards, a searchable findings table, and copy-ready fix commands (`--report`)
@@ -109,8 +110,8 @@ No account. No configuration. No source code leaves your machine.
109
110
  </td>
110
111
  </tr>
111
112
  <tr>
112
- <td align="center"><sub>Default scan output · <a href="docs/how-to-read-verbose-output.md">verbose output guide</a></sub></td>
113
- <td align="center"><sub>Generated with <code>--report</code> · <a href="docs/html-report.md">HTML report guide</a></sub></td>
113
+ <td align="center"><sub>Default scan output · <a href="https://owasp.org/cve-lite-cli/docs/how-to-read-verbose-output">verbose output guide</a></sub></td>
114
+ <td align="center"><sub>Generated with <code>--report</code> · <a href="https://owasp.org/cve-lite-cli/docs/html-report">HTML report guide</a></sub></td>
114
115
  </tr>
115
116
  </table>
116
117
 
@@ -144,7 +145,7 @@ CVE Lite CLI fits at every stage of the development workflow, not just CI.
144
145
 
145
146
  CVE Lite CLI scans its own dependencies in CI. See [`self-scan.yml`](https://github.com/OWASP/cve-lite-cli/blob/main/.github/workflows/self-scan.yml).
146
147
 
147
- For full CI patterns including offline workflows, git hooks, and scripted automation, see the [CI and Workflow Integration guide](docs/ci-integration.md).
148
+ For full CI patterns including offline workflows, git hooks, and scripted automation, see the [CI and Workflow Integration guide](https://owasp.org/cve-lite-cli/docs/ci-integration).
148
149
 
149
150
  ## How it compares
150
151
 
@@ -157,21 +158,24 @@ For full CI patterns including offline workflows, git hooks, and scripted automa
157
158
  | Usage-aware reachability scanning | ✅ | ❌ | ❌ | ✅ | ⚠️ |
158
159
  | Direct vs transitive visibility | ✅ | ⚠️ | ✅ | ✅ | ✅ |
159
160
  | Copy-and-run fix commands | ✅ | ❌ | ❌ | ✅ | ⚠️ |
161
+ | Transitive parent update guidance | ✅ | ❌ | ⚠️ | ⚠️ | ⚠️ |
160
162
  | Suggested remediation plan | ✅ | ❌ | ⚠️ | ✅ | ⚠️ |
161
163
  | JSON output | ✅ | ✅ | ✅ | ✅ | ✅ |
162
164
  | Offline/local advisory DB | ✅ | ❌ | ⚠️ | ❌ | ❌ |
163
165
 
164
166
  <sub>✅ = built-in strength · ⚠️ = partial or workflow-dependent · ❌ = not a core strength</sub>
165
167
 
166
- For detailed per-tool analysis, see [Comparison with other tools](docs/comparison.md).
168
+ The transitive parent guidance is a key difference: CVE Lite CLI avoids recommending direct installs for packages that are only present transitively. For npm lockfiles, it can identify when `npm update <parent>` is enough to re-resolve a known non-vulnerable child within the current parent range, and when the parent package itself needs an upgrade.
169
+
170
+ For detailed per-tool analysis, see [Comparison with other tools](https://owasp.org/cve-lite-cli/docs/comparison).
167
171
 
168
172
  ## Real-world validation
169
173
 
170
174
  CVE Lite CLI has been evaluated against real open-source projects to verify that it surfaces meaningful issues — including non-obvious transitive vulnerabilities and complex upgrade paths — not just low-signal advisory matches.
171
175
 
172
- - [OWASP Juice Shop](docs/case-studies/owasp-juice-shop.md) — scanning a deliberately vulnerable application with known dependency issues
173
- - [NestJS](docs/case-studies/nestjs.md) — working through a real transitive dependency remediation sequence across a widely-used Node.js framework
174
- - [Analog](docs/case-studies/analog.md) — scanning a modern pnpm v9 Angular monorepo (3,367 packages) with unexpected toolchain vulnerabilities
176
+ - [OWASP Juice Shop](https://owasp.org/cve-lite-cli/docs/case-studies/owasp-juice-shop) — scanning a deliberately vulnerable application with known dependency issues
177
+ - [NestJS](https://owasp.org/cve-lite-cli/docs/case-studies/nestjs) — working through a real transitive dependency remediation sequence across a widely-used Node.js framework
178
+ - [Analog](https://owasp.org/cve-lite-cli/docs/case-studies/analog) — scanning a modern pnpm v9 Angular monorepo (3,367 packages) with unexpected toolchain vulnerabilities
175
179
 
176
180
  These are not demos. They are documented scans against real codebases with real findings, recorded before and after applying fix commands.
177
181
 
@@ -213,7 +217,7 @@ The CLI is the foundation. The model — local-first, actionable, developer-nati
213
217
 
214
218
  JSON and SARIF outputs make findings consumable by editors, dashboards, and automated workflows today. The next phase of the project is oriented around tighter developer integration: surfacing vulnerabilities at the point of dependency installation, not just at scan time; deeper IDE integration; and team-level visibility without requiring a cloud platform.
215
219
 
216
- See [roadmap.md](docs/roadmap.md) for the current plan.
220
+ See the [Roadmap](https://owasp.org/cve-lite-cli/docs/roadmap) for the current plan.
217
221
 
218
222
  ## Usage
219
223
 
@@ -286,7 +290,9 @@ In the current version it:
286
290
  npx cve-lite-cli /path/to/project --fix
287
291
  ```
288
292
 
289
- See the [Fix mode guide](docs/fix-mode.md) for output details and interpretation.
293
+ See the [Fix mode guide](https://owasp.org/cve-lite-cli/docs/fix-mode) for output details and interpretation.
294
+
295
+ For a deeper explanation of how the CLI chooses direct upgrades, parent upgrades, and npm `update` recommendations for transitive findings, see the [Remediation Strategy guide](https://owasp.org/cve-lite-cli/docs/remediation-strategy).
290
296
 
291
297
  ## HTML vulnerability report (`--report`)
292
298
 
@@ -297,7 +303,7 @@ cve-lite /path/to/project --report
297
303
  cve-lite /path/to/project --report ./my-report --no-open
298
304
  ```
299
305
 
300
- See the [HTML Report guide](docs/html-report.md) for the full option reference and output details.
306
+ See the [HTML Report guide](https://owasp.org/cve-lite-cli/docs/html-report) for the full option reference and output details.
301
307
 
302
308
  ## Offline support
303
309
 
@@ -313,7 +319,7 @@ cve-lite . --offline
313
319
 
314
320
  Syncing ~217,065 advisory records runs in under 9 seconds after bulk SQLite ingestion optimizations — roughly **9.9x faster** than the initial implementation.
315
321
 
316
- See the [Offline Advisory DB guide](docs/offline-advisory-db.md) for the full workflow including CI, scheduled refresh, and controlled-network patterns.
322
+ See the [Offline Advisory DB guide](https://owasp.org/cve-lite-cli/docs/offline-advisory-db) for the full workflow including CI, scheduled refresh, and controlled-network patterns.
317
323
 
318
324
  ## Who uses it
319
325
 
@@ -325,7 +331,7 @@ CVE Lite CLI is a good fit for:
325
331
  - **Enterprise teams with restricted networks** — offline advisory DB workflow removes the need for runtime outbound calls during scans
326
332
  - **Teams running npm, pnpm, Yarn, and Bun** — unified scanning across all four package managers in one tool
327
333
 
328
- See the [CI and Workflow Integration guide](docs/ci-integration.md) for concrete patterns across these scenarios.
334
+ See the [CI and Workflow Integration guide](https://owasp.org/cve-lite-cli/docs/ci-integration) for concrete patterns across these scenarios.
329
335
 
330
336
  ## Current limitations
331
337
 
@@ -347,15 +353,27 @@ This is intentional. Because CVE Lite CLI is a security-oriented tool, runtime d
347
353
 
348
354
  ## Roadmap
349
355
 
350
- See [roadmap.md](docs/roadmap.md) for the full plan. Phases 1 and 2 are complete. Phase 3 (ecosystem coverage: Bun, Deno, parser improvements) is in progress.
356
+ See the [Roadmap](https://owasp.org/cve-lite-cli/docs/roadmap) for the full plan. Phases 1 and 2 are complete. Phase 3 (ecosystem coverage: Bun, Deno, parser improvements) is in progress.
351
357
 
352
358
  ## Troubleshooting
353
359
 
354
- See [troubleshooting.md](docs/troubleshooting.md) for common issues: no lockfile found, zero results, slow advisory sync, offline DB errors, `--fix` skipping findings, and CI failures.
360
+ See the [Troubleshooting guide](https://owasp.org/cve-lite-cli/docs/troubleshooting) for common issues: no lockfile found, zero results, slow advisory sync, offline DB errors, `--fix` skipping findings, and CI failures.
355
361
 
356
362
  ## Parser coverage
357
363
 
358
- See [parser-coverage.md](docs/parser-coverage.md) for supported lockfile formats, selection priority, the `package.json` fallback, and known edge cases including monorepos and private registries.
364
+ See the [Parser Coverage guide](https://owasp.org/cve-lite-cli/docs/parser-coverage) for supported lockfile formats, selection priority, the `package.json` fallback, and known edge cases including monorepos and private registries.
365
+
366
+ See the [Remediation Strategy guide](https://owasp.org/cve-lite-cli/docs/remediation-strategy) for how CVE Lite CLI chooses package upgrade targets and parent update paths.
367
+
368
+ ## Website
369
+
370
+ The public documentation site is published at [owasp.org/cve-lite-cli](https://owasp.org/cve-lite-cli/) and is built with Docusaurus from [`website/`](website/). All public guides and case studies live under [`website/docs/`](website/docs/) — that folder is the single source of truth for user-facing documentation.
371
+
372
+ ```bash
373
+ cd website
374
+ npm install
375
+ npm run build
376
+ ```
359
377
 
360
378
  ## Contributing
361
379
 
@@ -75,6 +75,12 @@ export async function syncOsvAdvisories(options = {}) {
75
75
  if (!vuln.id) {
76
76
  continue;
77
77
  }
78
+ // OSV's /v1/querybatch endpoint excludes withdrawn advisories at query
79
+ // time; mirror that here so offline scans don't surface false positives
80
+ // from advisories that have been retracted.
81
+ if (vuln.withdrawn) {
82
+ continue;
83
+ }
78
84
  parsedVulns.push(vuln);
79
85
  advisoryCount += 1;
80
86
  if (advisoryCount === 1 ||
package/dist/index.js CHANGED
@@ -193,17 +193,18 @@ if (parsedArgs) {
193
193
  notes: [...scanInput.notes, ...scanState.coverage],
194
194
  warnings: scanInput.warnings,
195
195
  skippedDependencies: scanInput.skippedDependencies,
196
- findings: scanState.sorted.map(serializeFinding)
196
+ findings: scanState.sorted.map(finding => serializeFinding(finding, scanState.suggestedFixCommands))
197
197
  }, null, 2));
198
198
  }
199
199
  else if (options.verbose) {
200
200
  // Verbose output - show all details
201
+ const offline = !!options.offline || !!options.offlineDb;
201
202
  printSummary(scanState.sorted, packages.length, scanInput);
202
203
  printActionSummary(scanState.sorted);
203
- printSuggestedFixCommands(scanState.sorted, scanInput);
204
+ printSuggestedFixCommands(scanState.sorted, scanInput, { offline });
204
205
  printPriorityFixes(scanState.sorted);
205
206
  printFixPlan(scanState.sorted);
206
- printSuggestedFixCommandSkips(scanState.sorted, scanInput);
207
+ printSuggestedFixCommandSkips(scanState.sorted, scanInput, { offline });
207
208
  printCoverage([...scanInput.notes, ...scanState.coverage]);
208
209
  if (scanInput.skippedDependencies.length > 0) {
209
210
  printSkippedDependencies(scanInput.skippedDependencies);
@@ -222,7 +223,8 @@ if (parsedArgs) {
222
223
  }
223
224
  else {
224
225
  // Simplified output - cleaner, focused view
225
- printCompactOutput(scanState.sorted, scanInput);
226
+ const offline = !!options.offline || !!options.offlineDb;
227
+ printCompactOutput(scanState.sorted, scanInput, { offline });
226
228
  }
227
229
  if (options.report) {
228
230
  const outputDir = path.resolve(typeof options.report === "string" ? options.report : "./cve-report");
@@ -270,7 +272,11 @@ function formatAdvisorySourceLine(sourceLabel) {
270
272
  }
271
273
  async function scanProject(params) {
272
274
  const directDependencyNames = readDirectDependencyNames(params.projectPath, !!params.options.prodOnly);
273
- const findings = await scanPackages(params.scanInput.packages, params.batchSize, params.options, { directDependencyNames });
275
+ const findings = await scanPackages(params.scanInput.packages, params.batchSize, params.options, {
276
+ directDependencyNames,
277
+ scanSource: params.scanInput.source,
278
+ scanFilePath: params.scanInput.filePath,
279
+ });
274
280
  if (params.options.usage) {
275
281
  console.log(chalk.gray(`Scanning project source for usage hints...`));
276
282
  const pkgNames = new Set(findings.map(f => f.pkg.name));
@@ -289,13 +295,14 @@ async function scanProject(params) {
289
295
  if (params.options.onlyUsed) {
290
296
  finalFindings = finalFindings.filter(f => f.usage?.imported);
291
297
  }
298
+ const offline = !!params.options.offline || !!params.options.offlineDb;
292
299
  const sorted = sortFindingsForOutput(finalFindings);
293
- const coverage = buildCoverageNotes(params.scanInput, !!params.options.offline || !!params.options.offlineDb);
300
+ const coverage = buildCoverageNotes(params.scanInput, offline);
294
301
  const minSeverity = normalizeSeverity(params.options.minSeverity || "medium");
295
302
  const tableFindings = params.options.all
296
303
  ? sorted
297
304
  : sorted.filter(f => severityOrder[f.severity] >= severityOrder[minSeverity]);
298
- const suggestedFixCommands = buildSuggestedFixCommandPlan(sorted, params.scanInput);
305
+ const suggestedFixCommands = buildSuggestedFixCommandPlan(sorted, params.scanInput, { offline });
299
306
  return {
300
307
  sorted,
301
308
  coverage,
@@ -446,21 +453,18 @@ function readDirectDependencyNames(projectPath, prodOnly) {
446
453
  return null;
447
454
  }
448
455
  try {
449
- const raw = JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
450
456
  const directNames = new Set();
451
- const sections = [
452
- raw?.dependencies,
453
- raw?.optionalDependencies,
454
- ];
455
- if (!prodOnly) {
456
- sections.push(raw?.devDependencies);
457
+ const rootManifest = readPackageJsonObject(packageJsonPath);
458
+ if (!rootManifest) {
459
+ return null;
457
460
  }
458
- for (const section of sections) {
459
- if (!section || typeof section !== "object")
461
+ addDependencyNamesFromManifest(directNames, rootManifest, prodOnly);
462
+ const workspacePatterns = readWorkspacePatterns(rootManifest);
463
+ for (const workspacePackageJsonPath of resolveWorkspacePackageJsonPaths(projectPath, workspacePatterns)) {
464
+ const workspaceManifest = readPackageJsonObject(workspacePackageJsonPath);
465
+ if (!workspaceManifest)
460
466
  continue;
461
- for (const name of Object.keys(section)) {
462
- directNames.add(name);
463
- }
467
+ addDependencyNamesFromManifest(directNames, workspaceManifest, prodOnly);
464
468
  }
465
469
  return directNames;
466
470
  }
@@ -468,6 +472,89 @@ function readDirectDependencyNames(projectPath, prodOnly) {
468
472
  return null;
469
473
  }
470
474
  }
475
+ function readPackageJsonObject(filePath) {
476
+ try {
477
+ const raw = JSON.parse(fs.readFileSync(filePath, "utf8"));
478
+ return raw && typeof raw === "object" ? raw : null;
479
+ }
480
+ catch {
481
+ return null;
482
+ }
483
+ }
484
+ function addDependencyNamesFromManifest(target, manifest, prodOnly) {
485
+ const sections = [
486
+ isRecord(manifest.dependencies) ? manifest.dependencies : undefined,
487
+ isRecord(manifest.optionalDependencies) ? manifest.optionalDependencies : undefined,
488
+ ];
489
+ if (!prodOnly) {
490
+ sections.push(isRecord(manifest.devDependencies) ? manifest.devDependencies : undefined);
491
+ }
492
+ for (const section of sections) {
493
+ if (!section)
494
+ continue;
495
+ for (const name of Object.keys(section)) {
496
+ target.add(name);
497
+ }
498
+ }
499
+ }
500
+ function readWorkspacePatterns(manifest) {
501
+ const workspaces = manifest.workspaces;
502
+ if (Array.isArray(workspaces)) {
503
+ return workspaces.filter((value) => typeof value === "string");
504
+ }
505
+ if (isRecord(workspaces) && Array.isArray(workspaces.packages)) {
506
+ return workspaces.packages.filter((value) => typeof value === "string");
507
+ }
508
+ return [];
509
+ }
510
+ function resolveWorkspacePackageJsonPaths(projectPath, patterns) {
511
+ const matches = new Set();
512
+ for (const pattern of patterns) {
513
+ const normalized = pattern.replace(/\\/g, "/").replace(/\/+$/, "");
514
+ if (!normalized)
515
+ continue;
516
+ for (const relativeDir of expandWorkspacePattern(projectPath, normalized.split("/").filter(Boolean), "")) {
517
+ const packageJsonPath = path.join(projectPath, relativeDir, "package.json");
518
+ if (fs.existsSync(packageJsonPath)) {
519
+ matches.add(packageJsonPath);
520
+ }
521
+ }
522
+ }
523
+ return [...matches];
524
+ }
525
+ function expandWorkspacePattern(projectPath, segments, currentRelativePath) {
526
+ if (segments.length === 0) {
527
+ return currentRelativePath ? [currentRelativePath] : [];
528
+ }
529
+ const [segment, ...rest] = segments;
530
+ if (segment === "*") {
531
+ const baseDir = currentRelativePath ? path.join(projectPath, currentRelativePath) : projectPath;
532
+ let entries = [];
533
+ try {
534
+ entries = fs.readdirSync(baseDir, { withFileTypes: true });
535
+ }
536
+ catch {
537
+ return [];
538
+ }
539
+ return entries
540
+ .filter(entry => entry.isDirectory())
541
+ .flatMap(entry => {
542
+ const nextRelativePath = currentRelativePath
543
+ ? path.join(currentRelativePath, entry.name)
544
+ : entry.name;
545
+ return expandWorkspacePattern(projectPath, rest, nextRelativePath);
546
+ });
547
+ }
548
+ const nextRelativePath = currentRelativePath ? path.join(currentRelativePath, segment) : segment;
549
+ const nextAbsolutePath = path.join(projectPath, nextRelativePath);
550
+ if (!fs.existsSync(nextAbsolutePath) || !fs.statSync(nextAbsolutePath).isDirectory()) {
551
+ return [];
552
+ }
553
+ return expandWorkspacePattern(projectPath, rest, nextRelativePath);
554
+ }
555
+ function isRecord(value) {
556
+ return !!value && typeof value === "object" && !Array.isArray(value);
557
+ }
471
558
  function formatAdvisoryDbFreshness(lastSyncAt) {
472
559
  if (!lastSyncAt) {
473
560
  return chalk.yellow("unknown");
@@ -1,3 +1,4 @@
1
+ import { findSuggestedCommandForFinding } from "../remediation/fix-commands.js";
1
2
  import { chalk } from "../utils/chalk.js";
2
3
  import { severityOrder } from "../constants.js";
3
4
  import { loadCache } from "../osv/cache.js";
@@ -31,6 +32,13 @@ export function getRecommendedAction(finding) {
31
32
  if (finding.relationship === "direct") {
32
33
  return `Review and upgrade ${finding.pkg.name} directly in this project.`;
33
34
  }
35
+ if (finding.recommendedNpmTransitiveRemediation?.kind === "update-parent-within-range") {
36
+ return `Update ${finding.recommendedNpmTransitiveRemediation.package} within its current dependency range to pull in vulnerable ${finding.pkg.name}@${finding.recommendedNpmTransitiveRemediation.targetChildVersion}.`;
37
+ }
38
+ if (finding.recommendedNpmTransitiveRemediation?.kind === "upgrade-parent-to-version" &&
39
+ finding.recommendedNpmTransitiveRemediation.targetVersion) {
40
+ return `Upgrade ${finding.recommendedNpmTransitiveRemediation.package} from ${finding.recommendedNpmTransitiveRemediation.currentVersion} to ${finding.recommendedNpmTransitiveRemediation.targetVersion} to stop pulling in vulnerable ${finding.pkg.name}.`;
41
+ }
34
42
  if (finding.recommendedParentUpgrade) {
35
43
  return `Upgrade ${finding.recommendedParentUpgrade.package} from ${finding.recommendedParentUpgrade.currentVersion} to ${finding.recommendedParentUpgrade.targetVersion} to stop pulling in vulnerable ${finding.pkg.name}.`;
36
44
  }
@@ -54,6 +62,12 @@ export function summarizeRisk(finding) {
54
62
  else if (finding.severity === "high" && finding.relationship === "direct") {
55
63
  risk = "High-severity direct dependency. A direct upgrade is likely the fastest path.";
56
64
  }
65
+ else if (finding.relationship === "transitive" && finding.recommendedNpmTransitiveRemediation?.kind === "update-parent-within-range") {
66
+ risk = `Transitive issue. The current parent range can already absorb a safe ${finding.pkg.name} update via ${finding.recommendedNpmTransitiveRemediation.package}.`;
67
+ }
68
+ else if (finding.relationship === "transitive" && finding.recommendedNpmTransitiveRemediation?.kind === "upgrade-parent-to-version") {
69
+ risk = `Transitive issue. A specific parent upgrade target was found for ${finding.recommendedNpmTransitiveRemediation.package}.`;
70
+ }
57
71
  else if (finding.relationship === "transitive" && finding.recommendedParentUpgrade) {
58
72
  risk = `Transitive issue. A specific parent upgrade target was found for ${finding.recommendedParentUpgrade.package}.`;
59
73
  }
@@ -86,6 +100,13 @@ export function summarizeNextAction(finding) {
86
100
  if (finding.relationship === "direct") {
87
101
  return `Review and upgrade ${finding.pkg.name} directly in this project.`;
88
102
  }
103
+ if (finding.recommendedNpmTransitiveRemediation?.kind === "update-parent-within-range") {
104
+ return `Update ${finding.recommendedNpmTransitiveRemediation.package} within its current dependency range.`;
105
+ }
106
+ if (finding.recommendedNpmTransitiveRemediation?.kind === "upgrade-parent-to-version" &&
107
+ finding.recommendedNpmTransitiveRemediation.targetVersion) {
108
+ return `Upgrade ${finding.recommendedNpmTransitiveRemediation.package} ${finding.recommendedNpmTransitiveRemediation.currentVersion} -> ${finding.recommendedNpmTransitiveRemediation.targetVersion}.`;
109
+ }
89
110
  if (finding.recommendedParentUpgrade) {
90
111
  return `Upgrade ${finding.recommendedParentUpgrade.package} ${finding.recommendedParentUpgrade.currentVersion} -> ${finding.recommendedParentUpgrade.targetVersion}.`;
91
112
  }
@@ -98,7 +119,7 @@ export function summarizeNextAction(finding) {
98
119
  }
99
120
  return `Inspect the parent dependency chain for ${finding.pkg.name} and choose the safest available upgrade.`;
100
121
  }
101
- export function serializeFinding(finding) {
122
+ export function serializeFinding(finding, plan) {
102
123
  return {
103
124
  package: finding.pkg.name,
104
125
  version: finding.pkg.version,
@@ -110,8 +131,10 @@ export function serializeFinding(finding) {
110
131
  validatedTargetScannedVersions: finding.validatedTargetScannedVersions ?? null,
111
132
  validatedTargetKnownVulnerableVersions: finding.validatedTargetKnownVulnerableVersions ?? null,
112
133
  recommendedAction: getRecommendedAction(finding),
134
+ runnableFixCommand: plan ? findSuggestedCommandForFinding(plan, finding) : null,
113
135
  primaryParent: getPrimaryParent(finding),
114
136
  recommendedParentUpgrade: finding.recommendedParentUpgrade,
137
+ recommendedNpmTransitiveRemediation: finding.recommendedNpmTransitiveRemediation ?? null,
115
138
  cves: finding.cveAliases,
116
139
  dependencyPaths: finding.dependencyPaths,
117
140
  usage: finding.usage ?? null,
@@ -13,7 +13,7 @@ export function buildReportData(params) {
13
13
  packageManager: params.packageManager,
14
14
  lockfileSource: params.lockfileSource,
15
15
  packageCount: params.packageCount,
16
- findings: params.findings.map(serializeFinding),
16
+ findings: params.findings.map(finding => serializeFinding(finding, params.suggestedFixCommands)),
17
17
  suggestedFixCommands: params.suggestedFixCommands,
18
18
  notes: params.notes,
19
19
  warnings: params.warnings,
@@ -144,6 +144,7 @@ button.header-link:hover{color:#58a6ff;border-color:#58a6ff}
144
144
  .fix-cmd-inline{display:flex;align-items:center;gap:8px;background:#161b22;border:1px solid #30363d;border-radius:6px;padding:8px 12px;margin-top:4px}
145
145
  .fix-cmd-inline code{flex:1;font-family:monospace;font-size:12px;color:#3fb950}
146
146
  .fix-cmd-inline .copy-btn{font-size:11px;color:#8b949e;background:#21262d;border:1px solid #30363d;border-radius:4px;padding:3px 8px;cursor:pointer}
147
+ .fix-cmd-note{margin:4px 0 0;font-size:12px;color:#8b949e;font-style:italic;line-height:1.5}
147
148
  .report-footer{margin:0 32px 32px;padding:12px 0;border-top:1px solid #21262d;display:flex;justify-content:space-between;font-size:11px;color:#8b949e}
148
149
  .scan-notes{margin:0 32px 16px}
149
150
  .scan-notes-toggle{display:flex;align-items:center;gap:6px;font-size:11px;color:#8b949e;background:none;border:none;cursor:pointer;padding:0}
@@ -394,8 +395,14 @@ function renderFindingRow(finding, idx) {
394
395
  return `<span class="dep-node${isLast ? " vulnerable" : ""}">${escapeHtml(node)}</span>${isLast ? "" : '<span class="dep-arrow">→</span>'}`;
395
396
  }).join("")
396
397
  : `<span class="dep-node">${escapeHtml(finding.package)}</span>`;
397
- const fixCommand = finding.recommendedAction ?? "";
398
398
  const description = finding.vulnerabilities[0]?.summary ?? "";
399
+ const runnable = finding.runnableFixCommand ?? null;
400
+ const recommendedActionHtml = runnable
401
+ ? `<div class="fix-cmd-inline">
402
+ <code>${escapeHtml(runnable)}</code>
403
+ <button class="copy-btn" data-cmd="${escapeHtml(runnable)}">Copy</button>
404
+ </div>`
405
+ : `<p class="fix-cmd-note">${escapeHtml(finding.recommendedAction ?? "")}</p>`;
399
406
  return ` <tr id="row-${idx}" onclick="toggleRow(${idx})">
400
407
  <td><span class="expand-icon" id="icon-${idx}">▶</span></td>
401
408
  <td><div class="pkg-name">${escapeHtml(finding.package)}</div><div class="pkg-version">${escapeHtml(finding.version)}</div></td>
@@ -417,10 +424,7 @@ function renderFindingRow(finding, idx) {
417
424
  </div>
418
425
  <div class="detail-col">
419
426
  <h4>Recommended action</h4>
420
- <div class="fix-cmd-inline">
421
- <code>${escapeHtml(fixCommand)}</code>
422
- <button class="copy-btn" data-cmd="${escapeHtml(fixCommand)}">Copy</button>
423
- </div>
427
+ ${recommendedActionHtml}
424
428
  </div>
425
429
  </div>
426
430
  </td>
@@ -499,11 +503,11 @@ export async function writeHtmlReport(params) {
499
503
  fs.writeFileSync(jsonPath, JSON.stringify(params.data, null, 2), "utf8");
500
504
  fs.writeFileSync(indexPath, renderHtmlReport(params.data), "utf8");
501
505
  if (params.autoOpen) {
502
- await openInBrowser(indexPath);
506
+ openInBrowser(indexPath);
503
507
  }
504
508
  return { reportPath: indexPath };
505
509
  }
506
- async function openInBrowser(filePath) {
510
+ function openInBrowser(filePath) {
507
511
  if (!path.isAbsolute(filePath))
508
512
  return;
509
513
  const cmd = process.platform === "darwin"
@@ -514,11 +518,11 @@ async function openInBrowser(filePath) {
514
518
  const args = process.platform === "win32"
515
519
  ? ["/c", "start", "", filePath]
516
520
  : [filePath];
517
- return new Promise(resolve => {
521
+ try {
518
522
  const child = spawn(cmd, args, { stdio: "ignore", detached: true, shell: false });
519
523
  child.unref();
520
- const timer = setTimeout(resolve, 1500);
521
- child.on("error", () => { clearTimeout(timer); resolve(); });
522
- child.on("close", () => { clearTimeout(timer); resolve(); });
523
- });
524
+ }
525
+ catch {
526
+ // Best-effort only: report creation should not fail if the OS open command is unavailable.
527
+ }
524
528
  }
@@ -1,6 +1,6 @@
1
1
  import { chalk, stripAnsi } from "../utils/chalk.js";
2
2
  import { severityOrder } from "../constants.js";
3
- import { buildSuggestedFixCommandPlan } from "../remediation/fix-commands.js";
3
+ import { buildSuggestedFixCommandPlan, findSuggestedCommandForFinding } from "../remediation/fix-commands.js";
4
4
  import { isMajorVersionBump } from "../utils/version.js";
5
5
  import { getPrimaryParent } from "../utils/finding.js";
6
6
  import { formatSeverityLabel, formatRelationshipLabel, getRecommendedAction, summarizeRisk, summarizeNextAction } from "./formatters.js";
@@ -71,7 +71,10 @@ export function printPriorityFixes(findings) {
71
71
  const parent = getPrimaryParent(finding);
72
72
  if (parent)
73
73
  console.log(` Parent: ${parent}`);
74
- if (finding.recommendedParentUpgrade) {
74
+ if (finding.recommendedNpmTransitiveRemediation?.kind === "update-parent-within-range") {
75
+ console.log(` Target: npm update ${finding.recommendedNpmTransitiveRemediation.package} (pulls in ${finding.pkg.name}@${finding.recommendedNpmTransitiveRemediation.targetChildVersion} within range)`);
76
+ }
77
+ else if (finding.recommendedParentUpgrade) {
75
78
  console.log(` Target: ${finding.recommendedParentUpgrade.package} ${finding.recommendedParentUpgrade.currentVersion} -> ${finding.recommendedParentUpgrade.targetVersion}`);
76
79
  }
77
80
  console.log(` Next: ${summarizeNextAction(finding)}`);
@@ -121,8 +124,8 @@ export function printFixPlan(findings) {
121
124
  }
122
125
  }
123
126
  }
124
- export function printSuggestedFixCommands(findings, scanInput) {
125
- const plan = buildSuggestedFixCommandPlan(findings, scanInput);
127
+ export function printSuggestedFixCommands(findings, scanInput, options) {
128
+ const plan = buildSuggestedFixCommandPlan(findings, scanInput, options);
126
129
  if (!plan)
127
130
  return;
128
131
  if (plan.sections.length === 0)
@@ -146,7 +149,7 @@ export function printSuggestedFixCommands(findings, scanInput) {
146
149
  }
147
150
  else if (section.kind === "urgent") {
148
151
  const directTargets = section.targets.filter(t => t.kind === "direct");
149
- const parentUpgradeTargets = section.targets.filter(t => t.kind === "parent-upgrade");
152
+ const parentUpgradeTargets = section.targets.filter(t => t.kind === "parent-upgrade" || t.kind === "parent-update");
150
153
  if (directTargets.length > 0) {
151
154
  const validationSummary = summarizeAdjustedValidation(directTargets);
152
155
  const remainingNotes = [];
@@ -167,8 +170,8 @@ export function printSuggestedFixCommands(findings, scanInput) {
167
170
  console.log(renderCommandCallout(section.command));
168
171
  }
169
172
  }
170
- export function printSuggestedFixCommandSkips(findings, scanInput) {
171
- const plan = buildSuggestedFixCommandPlan(findings, scanInput);
173
+ export function printSuggestedFixCommandSkips(findings, scanInput, options) {
174
+ const plan = buildSuggestedFixCommandPlan(findings, scanInput, options);
172
175
  if (!plan || plan.skipped.length === 0)
173
176
  return;
174
177
  const unpublishable = plan.skipped.filter(skipped => skipped.reason.includes("not published on npm"));
@@ -288,7 +291,10 @@ export function printPathHints(findings) {
288
291
  for (const example of examples) {
289
292
  console.log(` ${chalk.gray(example)}`);
290
293
  }
291
- if (finding.recommendedParentUpgrade) {
294
+ if (finding.recommendedNpmTransitiveRemediation?.kind === "update-parent-within-range") {
295
+ console.log(` Recommended parent update: ${chalk.bold.cyan(`npm update ${finding.recommendedNpmTransitiveRemediation.package}`)}`);
296
+ }
297
+ else if (finding.recommendedParentUpgrade) {
292
298
  console.log(` Recommended parent upgrade: ${chalk.bold.cyan(finding.recommendedParentUpgrade.package)} ${finding.recommendedParentUpgrade.currentVersion} -> ${finding.recommendedParentUpgrade.targetVersion}`);
293
299
  }
294
300
  }
@@ -322,7 +328,7 @@ function truncate(value, width) {
322
328
  return value;
323
329
  return plain.slice(0, Math.max(0, width - 1)) + "…";
324
330
  }
325
- export function printCompactOutput(findings, scanInput) {
331
+ export function printCompactOutput(findings, scanInput, options) {
326
332
  console.log("");
327
333
  if (findings.length === 0) {
328
334
  console.log(chalk.greenBright("✔ Scan complete. No known vulnerabilities found."));
@@ -355,7 +361,10 @@ export function printCompactOutput(findings, scanInput) {
355
361
  }
356
362
  console.log(`${formatSeverityLabel(sevLabel)} ${chalk.whiteBright(finding.pkg.name)}@${finding.pkg.version}`);
357
363
  console.log(` ${typeLabel}${usageContext}`);
358
- if (finding.recommendedParentUpgrade) {
364
+ if (finding.recommendedNpmTransitiveRemediation?.kind === "update-parent-within-range") {
365
+ console.log(` ${chalk.gray(`Fix: update ${finding.recommendedNpmTransitiveRemediation.package} within its current dependency range`)}`);
366
+ }
367
+ else if (finding.recommendedParentUpgrade) {
359
368
  console.log(` ${chalk.gray(`Fix: upgrade ${finding.recommendedParentUpgrade.package} to ${finding.recommendedParentUpgrade.targetVersion}`)}`);
360
369
  }
361
370
  else if (finding.firstFixedVersion) {
@@ -386,7 +395,7 @@ export function printCompactOutput(findings, scanInput) {
386
395
  }
387
396
  console.log("");
388
397
  }
389
- const plan = scanInput ? buildSuggestedFixCommandPlan(findings, scanInput) : null;
398
+ const plan = scanInput ? buildSuggestedFixCommandPlan(findings, scanInput, options) : null;
390
399
  if (plan) {
391
400
  if (plan?.sections.length) {
392
401
  console.log("────────────────────────────────");
@@ -425,6 +434,9 @@ export function printCompactOutput(findings, scanInput) {
425
434
  else if (topFinding.relationship === "direct") {
426
435
  console.log(`Upgrade ${chalk.whiteBright(topFinding.pkg.name)} to latest safe version`);
427
436
  }
437
+ else if (topFinding.recommendedNpmTransitiveRemediation?.kind === "update-parent-within-range") {
438
+ console.log(`Update ${chalk.whiteBright(topFinding.recommendedNpmTransitiveRemediation.package)} within current range`);
439
+ }
428
440
  else if (topFinding.recommendedParentUpgrade) {
429
441
  console.log(`Upgrade ${chalk.whiteBright(topFinding.recommendedParentUpgrade.package)} ${topFinding.recommendedParentUpgrade.currentVersion} → ${topFinding.recommendedParentUpgrade.targetVersion}`);
430
442
  }
@@ -521,28 +533,6 @@ function formatFixCommandSummary(plan) {
521
533
  function renderCommandCallout(command) {
522
534
  return chalk.bold.cyan(`> ${command}`);
523
535
  }
524
- function findSuggestedCommandForFinding(plan, finding) {
525
- const target = plan.targets.find(item => {
526
- if (finding.recommendedParentUpgrade) {
527
- return (item.package === finding.recommendedParentUpgrade.package &&
528
- item.targetVersion === finding.recommendedParentUpgrade.targetVersion);
529
- }
530
- const directTarget = finding.validatedFirstFixedVersion ?? finding.firstFixedVersion;
531
- return item.package === finding.pkg.name && item.targetVersion === directTarget;
532
- });
533
- if (!target)
534
- return null;
535
- return `${packageManagerCommandPrefix(plan.packageManager)} ${target.package}@${target.targetVersion}`;
536
- }
537
- function packageManagerCommandPrefix(packageManager) {
538
- if (packageManager === "npm")
539
- return "npm install";
540
- if (packageManager === "pnpm")
541
- return "pnpm add";
542
- if (packageManager === "bun")
543
- return "bun add";
544
- return "yarn add";
545
- }
546
536
  function summarizeAdjustedValidation(targets) {
547
537
  let checked = 0;
548
538
  let vulnerable = 0;
@@ -622,7 +612,7 @@ function printParentUpgradeTargetsTable(targets, widthsOverride) {
622
612
  return [
623
613
  target.package,
624
614
  target.currentVersion ?? "-",
625
- chalk.cyan(target.targetVersion),
615
+ chalk.cyan(target.displayTargetVersion ?? target.targetVersion),
626
616
  usageText,
627
617
  chalk.gray(target.reason),
628
618
  ];
@@ -675,7 +665,7 @@ function computeSharedDirectTableWidths(sections) {
675
665
  return computeTableWidths(headers, rows);
676
666
  }
677
667
  function shouldRenderParentUpgradeTable(targets) {
678
- return targets.length > 0 && targets.every(target => target.kind === "parent-upgrade");
668
+ return targets.length > 0 && targets.every(target => target.kind === "parent-upgrade" || target.kind === "parent-update");
679
669
  }
680
670
  function computeSharedParentUpgradeTableWidths(sections) {
681
671
  const parentSections = sections.filter(section => shouldRenderParentUpgradeTable(section.targets));
@@ -692,7 +682,7 @@ function computeSharedParentUpgradeTableWidths(sections) {
692
682
  rows.push([
693
683
  target.package,
694
684
  target.currentVersion ?? "-",
695
- target.targetVersion,
685
+ target.displayTargetVersion ?? target.targetVersion,
696
686
  usageText,
697
687
  target.reason,
698
688
  ]);