cve-lite-cli 1.11.0 → 1.12.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
@@ -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,73 @@ 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
+ ```
377
+
378
+ ## Governance
379
+
380
+ CVE Lite CLI is an OWASP Incubator Project maintained by Sonu Kapoor as project lead. The project follows a single-maintainer (benevolent dictator) governance model. The project lead makes final decisions on scope, design direction, and releases after considering input from contributors and the wider community.
381
+
382
+ ### Roles
383
+
384
+ - **Project lead** — currently Sonu Kapoor. Owns the roadmap, sets release cadence, reviews and merges pull requests, and acts as the OWASP project leader for the Foundation.
385
+ - **Contributors** — anyone who opens an issue, proposes a pull request, or improves the documentation. No prior commit history is required to contribute, and contributions are welcome from outside OWASP.
386
+
387
+ ### Decision-making
388
+
389
+ - Significant changes (new features, breaking changes, scope decisions) start as a GitHub issue so the design can be discussed in public before code is written.
390
+ - Pull requests are reviewed by the project lead. Small fixes can land directly. Larger changes may require revision or follow-up issues.
391
+ - Releases are cut by the project lead when accumulated changes warrant a version bump, following the process in [CONTRIBUTING.md](https://github.com/OWASP/cve-lite-cli/blob/main/src/docs/CONTRIBUTING.md).
392
+
393
+ ### Dispute resolution
394
+
395
+ Technical disagreements are resolved by the project lead after weighing contributor input. Disputes that relate to community standards or [Code of Conduct](https://github.com/OWASP/cve-lite-cli/blob/main/CODE_OF_CONDUCT.md) enforcement can be escalated to the OWASP Foundation, which acts as a backstop for the project's community norms.
396
+
397
+ This governance model may evolve as the contributor base grows. Any change to the model will be documented here and announced via the GitHub repository.
398
+
399
+ ## Security and verification
400
+
401
+ CVE Lite CLI signs both the source code release and the build artifact for each release. Either signature is sufficient on its own.
402
+
403
+ **Source code (signed git tags).** Starting with releases after v1.12.1, every release tag is a GPG-signed annotated tag. The project lead's public key is published at [`https://github.com/sonukapoor.gpg`](https://github.com/sonukapoor.gpg). The private key is held only on the project lead's local machine — not on GitHub, not on the npm registry, not in CI. Verify with:
404
+
405
+ ```bash
406
+ curl -sSL https://github.com/sonukapoor.gpg | gpg --import
407
+ git tag -v vX.Y.Z
408
+ ```
409
+
410
+ **Release tarball (Sigstore Artifact Attestations).** Each GitHub release attaches an `cve-lite-cli-X.Y.Z.tgz` asset signed at build time via [GitHub Artifact Attestations](https://docs.github.com/en/actions/security-guides/using-artifact-attestations-to-establish-provenance-for-builds). The signing keys are ephemeral OIDC-issued keys generated per build, providing SLSA Level 2 equivalent build provenance. Verify with:
411
+
412
+ ```bash
413
+ gh attestation verify cve-lite-cli-X.Y.Z.tgz --repo OWASP/cve-lite-cli
414
+ ```
415
+
416
+ **npm-installed package.** The npm registry adds an ECDSA signature to every published package, independent of the project's own signing keys above:
417
+
418
+ ```bash
419
+ npm audit signatures
420
+ ```
421
+
422
+ For full verification details, fingerprints, and security issue reports, see [SECURITY.md](https://github.com/OWASP/cve-lite-cli/blob/main/src/docs/SECURITY.md). For the project's threat model, trust boundaries, and how common implementation weaknesses are countered, see the [Security Assurance Case](https://owasp.org/cve-lite-cli/docs/security-assurance-case).
359
423
 
360
424
  ## Contributing
361
425
 
@@ -381,6 +445,8 @@ Helpful feedback includes reproducible bug reports, real-world lockfile edge cas
381
445
 
382
446
  For security-related reporting: [SECURITY.md](https://github.com/OWASP/cve-lite-cli/blob/main/src/docs/SECURITY.md)
383
447
 
448
+ This project follows a [Code of Conduct](https://github.com/OWASP/cve-lite-cli/blob/main/CODE_OF_CONDUCT.md). Please review it before participating.
449
+
384
450
  If CVE Lite CLI helps your release workflow, a [GitHub star](https://github.com/OWASP/cve-lite-cli) helps more developers find it.
385
451
 
386
452
  ---
@@ -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");
@@ -293,13 +295,14 @@ async function scanProject(params) {
293
295
  if (params.options.onlyUsed) {
294
296
  finalFindings = finalFindings.filter(f => f.usage?.imported);
295
297
  }
298
+ const offline = !!params.options.offline || !!params.options.offlineDb;
296
299
  const sorted = sortFindingsForOutput(finalFindings);
297
- const coverage = buildCoverageNotes(params.scanInput, !!params.options.offline || !!params.options.offlineDb);
300
+ const coverage = buildCoverageNotes(params.scanInput, offline);
298
301
  const minSeverity = normalizeSeverity(params.options.minSeverity || "medium");
299
302
  const tableFindings = params.options.all
300
303
  ? sorted
301
304
  : sorted.filter(f => severityOrder[f.severity] >= severityOrder[minSeverity]);
302
- const suggestedFixCommands = buildSuggestedFixCommandPlan(sorted, params.scanInput);
305
+ const suggestedFixCommands = buildSuggestedFixCommandPlan(sorted, params.scanInput, { offline });
303
306
  return {
304
307
  sorted,
305
308
  coverage,
@@ -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";
@@ -118,7 +119,7 @@ export function summarizeNextAction(finding) {
118
119
  }
119
120
  return `Inspect the parent dependency chain for ${finding.pkg.name} and choose the safest available upgrade.`;
120
121
  }
121
- export function serializeFinding(finding) {
122
+ export function serializeFinding(finding, plan) {
122
123
  return {
123
124
  package: finding.pkg.name,
124
125
  version: finding.pkg.version,
@@ -130,6 +131,7 @@ export function serializeFinding(finding) {
130
131
  validatedTargetScannedVersions: finding.validatedTargetScannedVersions ?? null,
131
132
  validatedTargetKnownVulnerableVersions: finding.validatedTargetKnownVulnerableVersions ?? null,
132
133
  recommendedAction: getRecommendedAction(finding),
134
+ runnableFixCommand: plan ? findSuggestedCommandForFinding(plan, finding) : null,
133
135
  primaryParent: getPrimaryParent(finding),
134
136
  recommendedParentUpgrade: finding.recommendedParentUpgrade,
135
137
  recommendedNpmTransitiveRemediation: finding.recommendedNpmTransitiveRemediation ?? 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>
@@ -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";
@@ -124,8 +124,8 @@ export function printFixPlan(findings) {
124
124
  }
125
125
  }
126
126
  }
127
- export function printSuggestedFixCommands(findings, scanInput) {
128
- const plan = buildSuggestedFixCommandPlan(findings, scanInput);
127
+ export function printSuggestedFixCommands(findings, scanInput, options) {
128
+ const plan = buildSuggestedFixCommandPlan(findings, scanInput, options);
129
129
  if (!plan)
130
130
  return;
131
131
  if (plan.sections.length === 0)
@@ -170,8 +170,8 @@ export function printSuggestedFixCommands(findings, scanInput) {
170
170
  console.log(renderCommandCallout(section.command));
171
171
  }
172
172
  }
173
- export function printSuggestedFixCommandSkips(findings, scanInput) {
174
- const plan = buildSuggestedFixCommandPlan(findings, scanInput);
173
+ export function printSuggestedFixCommandSkips(findings, scanInput, options) {
174
+ const plan = buildSuggestedFixCommandPlan(findings, scanInput, options);
175
175
  if (!plan || plan.skipped.length === 0)
176
176
  return;
177
177
  const unpublishable = plan.skipped.filter(skipped => skipped.reason.includes("not published on npm"));
@@ -328,7 +328,7 @@ function truncate(value, width) {
328
328
  return value;
329
329
  return plain.slice(0, Math.max(0, width - 1)) + "…";
330
330
  }
331
- export function printCompactOutput(findings, scanInput) {
331
+ export function printCompactOutput(findings, scanInput, options) {
332
332
  console.log("");
333
333
  if (findings.length === 0) {
334
334
  console.log(chalk.greenBright("✔ Scan complete. No known vulnerabilities found."));
@@ -395,7 +395,7 @@ export function printCompactOutput(findings, scanInput) {
395
395
  }
396
396
  console.log("");
397
397
  }
398
- const plan = scanInput ? buildSuggestedFixCommandPlan(findings, scanInput) : null;
398
+ const plan = scanInput ? buildSuggestedFixCommandPlan(findings, scanInput, options) : null;
399
399
  if (plan) {
400
400
  if (plan?.sections.length) {
401
401
  console.log("────────────────────────────────");
@@ -533,35 +533,6 @@ function formatFixCommandSummary(plan) {
533
533
  function renderCommandCallout(command) {
534
534
  return chalk.bold.cyan(`> ${command}`);
535
535
  }
536
- function findSuggestedCommandForFinding(plan, finding) {
537
- const target = plan.targets.find(item => {
538
- if (finding.recommendedNpmTransitiveRemediation?.kind === "update-parent-within-range") {
539
- return (item.kind === "parent-update" &&
540
- item.package === finding.recommendedNpmTransitiveRemediation.package &&
541
- item.targetVersion === finding.recommendedNpmTransitiveRemediation.targetChildVersion);
542
- }
543
- if (finding.recommendedParentUpgrade) {
544
- return (item.package === finding.recommendedParentUpgrade.package &&
545
- item.targetVersion === finding.recommendedParentUpgrade.targetVersion);
546
- }
547
- const directTarget = finding.validatedFirstFixedVersion ?? finding.firstFixedVersion;
548
- return item.package === finding.pkg.name && item.targetVersion === directTarget;
549
- });
550
- if (!target)
551
- return null;
552
- if (target.command)
553
- return target.command;
554
- return `${packageManagerCommandPrefix(plan.packageManager)} ${target.package}@${target.targetVersion}`;
555
- }
556
- function packageManagerCommandPrefix(packageManager) {
557
- if (packageManager === "npm")
558
- return "npm install";
559
- if (packageManager === "pnpm")
560
- return "pnpm add";
561
- if (packageManager === "bun")
562
- return "bun add";
563
- return "yarn add";
564
- }
565
536
  function summarizeAdjustedValidation(targets) {
566
537
  let checked = 0;
567
538
  let vulnerable = 0;
@@ -1,10 +1,11 @@
1
1
  import { severityOrder } from "../constants.js";
2
2
  import { compareVersions, looksLikeVersion } from "../utils/version.js";
3
3
  import { getPrimaryParent } from "../utils/finding.js";
4
- export function buildSuggestedFixCommandPlan(findings, scanInput) {
4
+ export function buildSuggestedFixCommandPlan(findings, scanInput, options) {
5
5
  const packageManager = inferPackageManager(scanInput);
6
6
  if (!packageManager)
7
7
  return null;
8
+ const offline = !!options?.offline;
8
9
  const prioritizedFindings = [...findings]
9
10
  .filter(f => f.severity === "critical" || f.severity === "high")
10
11
  .sort((a, b) => {
@@ -47,9 +48,13 @@ export function buildSuggestedFixCommandPlan(findings, scanInput) {
47
48
  if (finding.relationship === "direct" || finding.relationship === "unknown") {
48
49
  const hasValidatedField = Object.prototype.hasOwnProperty.call(finding, "validatedFirstFixedVersion");
49
50
  const directTarget = finding.validatedFirstFixedVersion ?? finding.firstFixedVersion;
51
+ // In offline mode validateDirectFixTargets never runs, so an unset
52
+ // validatedFirstFixedVersion is "did not validate" rather than "validation
53
+ // failed" — fall back to the advisory hint instead of dropping the target.
54
+ const validatedFieldOk = offline || !hasValidatedField || finding.validatedFirstFixedVersion !== null;
50
55
  if (directTarget &&
51
56
  isUpgradeTarget(finding.pkg.version, directTarget) &&
52
- (!hasValidatedField || finding.validatedFirstFixedVersion !== null)) {
57
+ validatedFieldOk) {
53
58
  upsertTarget(targetsByPackage, {
54
59
  package: finding.pkg.name,
55
60
  currentVersion: finding.pkg.version,
@@ -250,6 +255,26 @@ function commandPrefix(packageManager) {
250
255
  return "bun add";
251
256
  return "yarn add";
252
257
  }
258
+ export function findSuggestedCommandForFinding(plan, finding) {
259
+ const target = plan.targets.find(item => {
260
+ if (finding.recommendedNpmTransitiveRemediation?.kind === "update-parent-within-range") {
261
+ return (item.kind === "parent-update" &&
262
+ item.package === finding.recommendedNpmTransitiveRemediation.package &&
263
+ item.targetVersion === finding.recommendedNpmTransitiveRemediation.targetChildVersion);
264
+ }
265
+ if (finding.recommendedParentUpgrade) {
266
+ return (item.package === finding.recommendedParentUpgrade.package &&
267
+ item.targetVersion === finding.recommendedParentUpgrade.targetVersion);
268
+ }
269
+ const directTarget = finding.validatedFirstFixedVersion ?? finding.firstFixedVersion;
270
+ return item.package === finding.pkg.name && item.targetVersion === directTarget;
271
+ });
272
+ if (!target)
273
+ return null;
274
+ if (target.command)
275
+ return target.command;
276
+ return `${commandPrefix(plan.packageManager)} ${target.package}@${target.targetVersion}`;
277
+ }
253
278
  function packageManagerSourceLabel(scanInput) {
254
279
  if (scanInput.filePath) {
255
280
  return scanInput.filePath.split(/[/\\]/).pop() ?? scanInput.source;
@@ -25,7 +25,10 @@ export async function resolveNpmTransitiveRemediation(args) {
25
25
  });
26
26
  if (!parentNodeId)
27
27
  return null;
28
- const safeCandidates = await findSafeChildCandidates(vulnerableName, args.finding.pkg.version, args.finding.validatedFirstFixedVersion ?? args.finding.firstFixedVersion);
28
+ const fixHint = args.finding.validatedFirstFixedVersion ?? args.finding.firstFixedVersion;
29
+ const safeCandidates = args.offline
30
+ ? buildOfflineSafeCandidates(args.finding.pkg.version, fixHint)
31
+ : await findSafeChildCandidates(vulnerableName, args.finding.pkg.version, fixHint);
29
32
  if (safeCandidates.length === 0)
30
33
  return null;
31
34
  const inRangeTarget = findSafeVersionWithinParentRange({
@@ -44,6 +47,11 @@ export async function resolveNpmTransitiveRemediation(args) {
44
47
  reason: `${directParentName}@${directParent.version} already allows ${vulnerableName}@${inRangeTarget} within the current dependency range`,
45
48
  };
46
49
  }
50
+ // The upgrade-parent-to-version path needs the parent's published manifests
51
+ // to find a newer parent version that no longer pulls in the vulnerable child.
52
+ // That data only comes from the npm registry, so it can't run offline.
53
+ if (args.offline)
54
+ return null;
47
55
  const parentPackument = await fetchPackument(directParentName);
48
56
  const parentVersions = Object.keys(parentPackument?.versions ?? {})
49
57
  .filter(looksLikeVersion)
@@ -109,6 +117,15 @@ function resolveDirectParentContext(viaPath, packages, directDependencyNames) {
109
117
  return null;
110
118
  return { directParentName, immediateParentName, directParent };
111
119
  }
120
+ function buildOfflineSafeCandidates(installedVersion, fixedVersionHint) {
121
+ if (!fixedVersionHint || !looksLikeVersion(fixedVersionHint))
122
+ return [];
123
+ if (isPreReleaseVersion(fixedVersionHint))
124
+ return [];
125
+ if (compareVersions(fixedVersionHint, installedVersion) <= 0)
126
+ return [];
127
+ return [fixedVersionHint];
128
+ }
112
129
  async function findSafeChildCandidates(packageName, installedVersion, fixedVersionHint) {
113
130
  const packument = await fetchPackument(packageName);
114
131
  if (!packument)
@@ -1,8 +1,12 @@
1
1
  import { compareVersions, isPreReleaseVersion, looksLikeVersion } from "../utils/version.js";
2
2
  import { fetchPackument } from "./npm-registry.js";
3
- export async function resolveRecommendedParentUpgrade(finding, packages, directDependencyNames) {
3
+ export async function resolveRecommendedParentUpgrade(finding, packages, directDependencyNames, options) {
4
4
  if (finding.relationship !== "transitive")
5
5
  return null;
6
+ // Both branches below need the parent's published manifests, which only the
7
+ // npm registry can supply; there's no offline-safe path for this resolver.
8
+ if (options?.offline)
9
+ return null;
6
10
  const viaPath = getBestPath(finding);
7
11
  if (!viaPath || viaPath.length < 3)
8
12
  return null;
package/dist/scanner.js CHANGED
@@ -185,15 +185,13 @@ export async function scanPackages(packages, batchSize, options, context) {
185
185
  recommendedNpmTransitiveRemediation: undefined,
186
186
  };
187
187
  });
188
- const npmTransitiveGraph = !offline && context?.scanSource === "package-lock" && context.scanFilePath
188
+ const npmTransitiveGraph = context?.scanSource === "package-lock" && context.scanFilePath
189
189
  ? createNpmTransitiveGraphFromLockfile(context.scanFilePath)
190
190
  : null;
191
191
  const npmRemediationCache = new Map();
192
192
  const parentUpgradeCache = new Map();
193
193
  const directValidationCount = offline ? 0 : findings.length;
194
- const transitiveRemediationCount = offline
195
- ? 0
196
- : findings.filter(finding => finding.relationship === "transitive").length;
194
+ const transitiveRemediationCount = findings.filter(finding => finding.relationship === "transitive").length;
197
195
  const analysisStepCount = directValidationCount + transitiveRemediationCount;
198
196
  if (analysisStepCount > 0) {
199
197
  const analysisSpinner = createSpinner("Analyzing vulnerability findings...", options);
@@ -209,7 +207,7 @@ export async function scanPackages(packages, batchSize, options, context) {
209
207
  });
210
208
  }
211
209
  for (const finding of findings) {
212
- if (finding.relationship !== "transitive" || offline)
210
+ if (finding.relationship !== "transitive")
213
211
  continue;
214
212
  updateAnalysisProgress("resolving remediation for", `${finding.pkg.name}@${finding.pkg.version}`);
215
213
  const remediationCacheKey = JSON.stringify({
@@ -231,6 +229,7 @@ export async function scanPackages(packages, batchSize, options, context) {
231
229
  graph: npmTransitiveGraph,
232
230
  packages,
233
231
  directDependencyNames: context?.directDependencyNames,
232
+ offline,
234
233
  });
235
234
  npmRemediationCache.set(remediationCacheKey, finding.recommendedNpmTransitiveRemediation ?? null);
236
235
  }
@@ -255,7 +254,7 @@ export async function scanPackages(packages, batchSize, options, context) {
255
254
  finding.recommendedParentUpgrade = parentUpgradeCache.get(remediationCacheKey) ?? undefined;
256
255
  }
257
256
  else {
258
- finding.recommendedParentUpgrade = await resolveRecommendedParentUpgrade(finding, packages, context?.directDependencyNames);
257
+ finding.recommendedParentUpgrade = await resolveRecommendedParentUpgrade(finding, packages, context?.directDependencyNames, { offline });
259
258
  parentUpgradeCache.set(remediationCacheKey, finding.recommendedParentUpgrade ?? null);
260
259
  }
261
260
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "cve-lite-cli",
3
- "version": "1.11.0",
3
+ "version": "1.12.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": {