cve-lite-cli 1.23.1 → 1.25.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.
Files changed (55) hide show
  1. package/README.md +56 -0
  2. package/dist/audit-log/events.js +3 -0
  3. package/dist/audit-log/handle.js +20 -0
  4. package/dist/audit-log/index.js +16 -0
  5. package/dist/audit-log/ndjson-writer.js +28 -0
  6. package/dist/cli/args.js +71 -3
  7. package/dist/cli/fix-overrides-hook.js +64 -0
  8. package/dist/cli/help.js +22 -0
  9. package/dist/cli/overrides.js +67 -0
  10. package/dist/index.js +270 -12
  11. package/dist/osv/cache.js +23 -3
  12. package/dist/output/formatters.js +23 -4
  13. package/dist/output/html-reporter.js +34 -4
  14. package/dist/output/override-findings-html.js +57 -0
  15. package/dist/output/override-findings-json.js +3 -0
  16. package/dist/output/override-findings-sarif.js +52 -0
  17. package/dist/output/override-findings-terminal.js +37 -0
  18. package/dist/output/printers.js +25 -8
  19. package/dist/output/sarif.js +77 -8
  20. package/dist/output/write-outputs.js +7 -3
  21. package/dist/overrides/api.js +79 -0
  22. package/dist/overrides/composite.js +23 -0
  23. package/dist/overrides/context-builder.js +150 -0
  24. package/dist/overrides/context.js +3 -0
  25. package/dist/overrides/detectors/index.js +23 -0
  26. package/dist/overrides/detectors/oa001-orphaned-target.js +36 -0
  27. package/dist/overrides/detectors/oa002-floating-tag.js +40 -0
  28. package/dist/overrides/detectors/oa003-wrong-section.js +48 -0
  29. package/dist/overrides/detectors/oa004-surpassed-pin.js +49 -0
  30. package/dist/overrides/detectors/oa005-nested-ineffective.js +128 -0
  31. package/dist/overrides/detectors/oa006-coupled-platform-binary.js +170 -0
  32. package/dist/overrides/detectors/oa007-frozen-latest.js +69 -0
  33. package/dist/overrides/detectors/oa008-materialized.js +75 -0
  34. package/dist/overrides/detectors/platform-binary.js +37 -0
  35. package/dist/overrides/fixer.js +199 -0
  36. package/dist/overrides/index.js +5 -0
  37. package/dist/overrides/parsing/installed-tree.js +164 -0
  38. package/dist/overrides/parsing/json-pointer.js +8 -0
  39. package/dist/overrides/parsing/node-modules.js +19 -0
  40. package/dist/overrides/parsing/package-json.js +139 -0
  41. package/dist/overrides/parsing/registry.js +66 -0
  42. package/dist/overrides/types.js +2 -0
  43. package/dist/parsers/yarn-lock.js +2 -2
  44. package/dist/remediation/fix-commands.js +110 -29
  45. package/dist/remediation/npm-registry.js +30 -0
  46. package/dist/remediation/npm-transitive-resolution.js +2 -2
  47. package/dist/remediation/transitive-chain-resolver.js +100 -0
  48. package/dist/scan/multi-folder-scan.js +26 -0
  49. package/dist/scanner.js +61 -5
  50. package/dist/types.js +13 -1
  51. package/dist/utils/baseline.js +16 -0
  52. package/dist/utils/create-pr.js +19 -4
  53. package/dist/utils/string.js +34 -0
  54. package/dist/utils/version.js +115 -0
  55. package/package.json +4 -2
package/README.md CHANGED
@@ -106,6 +106,7 @@ No account. No configuration. No source code leaves your machine.
106
106
  - **Offline advisory DB** — sync advisory data ahead of time and scan with zero runtime API calls, designed for enterprise and air-gapped environments
107
107
  - **Interactive HTML report** — generate a self-contained dashboard with severity cards, a searchable findings table, and copy-ready fix commands (`--report`)
108
108
  - **Auto-fix mode** — apply validated direct dependency fixes and rescan automatically (`--fix`)
109
+ - **Override hygiene checks** — audit npm/pnpm/yarn/bun `overrides` and `resolutions` for orphaned targets, floating tags, surpassed pins, ineffective nested overrides, and platform-binary coupling (`cve-lite overrides`, rules `OA001`-`OA008`)
109
110
  - **CI-ready** — `--fail-on high` exits non-zero on findings at or above a severity threshold; a first-party [GitHub Action](https://github.com/marketplace/actions/cve-lite-cli) is available on the Marketplace; `--sarif` writes SARIF 2.1.0 output for direct upload to GitHub Code Scanning; `--cdx` writes a CycloneDX 1.4 SBOM for Dependency-Track and compliance artifacts; `--json` integrates with SIEM tools and dashboards
110
111
  - **Minimal footprint** — four runtime dependencies, intentionally kept small for a security tool
111
112
 
@@ -309,6 +310,12 @@ cve-lite /path/to/project --verbose
309
310
  # Apply validated direct dependency fixes and rescan
310
311
  cve-lite /path/to/project --fix
311
312
 
313
+ # Audit override hygiene (OA001-OA008) across npm/pnpm/yarn/bun
314
+ cve-lite overrides /path/to/project
315
+
316
+ # Audit and auto-clean stale or ineffective overrides
317
+ cve-lite overrides /path/to/project --fix
318
+
312
319
  # Production dependencies only (where supported by the lockfile)
313
320
  cve-lite /path/to/project --prod-only
314
321
 
@@ -362,16 +369,65 @@ In the current version it:
362
369
  - applies only direct dependency fixes with a validated lowest known non-vulnerable target
363
370
  - uses `npm install`, `pnpm add`, `yarn add`, or `bun add` based on your lockfile
364
371
  - rescans automatically after applying fixes
372
+ - when combined with `--check-overrides`, also runs the override hygiene fix-and-verify hook after the CVE fixes: it applies fixable override findings, then re-audits the just-touched packages (`OA001`/`OA008`) to confirm no vulnerable copy is still nested under a parent dependency. Without `--check-overrides`, `--fix` only touches CVE fixes and never modifies your `overrides`
365
373
  - does **not** auto-apply transitive overrides or guarantee application compatibility
366
374
 
367
375
  ```bash
368
376
  npx cve-lite-cli /path/to/project --fix
369
377
  ```
370
378
 
379
+ **Exit codes.** `--fix` adds a dedicated exit code for a verify failure, so CI can tell "nothing to fix" apart from "the fix ran but did not take":
380
+
381
+ | Code | Meaning |
382
+ |---|---|
383
+ | `0` | no findings at or above `--fail-on` |
384
+ | `1` | findings present (CVE or override) at or above `--fail-on` |
385
+ | `2` | `--fix` applied but the post-fix verify pass detected the fix did not take |
386
+ | `3` | tool error (unreadable lockfile, unhandled exception) |
387
+
371
388
  See the [Fix mode guide](https://owasp.org/cve-lite-cli/docs/fix-mode) for output details and interpretation.
372
389
 
373
390
  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).
374
391
 
392
+ ## Override hygiene (`overrides`)
393
+
394
+ `overrides` and `resolutions` are powerful, but they rot. A pin you added to dodge a CVE last year can outlive its target, drift behind upstream, or quietly stop taking effect after a refactor, leaving a vulnerable copy still nested under a parent dependency. `cve-lite overrides [path]` audits that hygiene across npm, pnpm, yarn, and bun, reporting eight classes of problem (`OA001`-`OA008`):
395
+
396
+ | Rule | What it catches |
397
+ |---|---|
398
+ | `OA001` | Orphaned target: override for a package no longer in the tree |
399
+ | `OA002` | Floating tag: override pinned to a moving tag (`latest`, `next`) |
400
+ | `OA003` | Wrong section: override placed in the wrong container |
401
+ | `OA004` | Surpassed pin: the rest of the tree has moved past the pin |
402
+ | `OA005` | Nested ineffective override that never applies |
403
+ | `OA006` | Coupled platform binary: override fights a parent's exact pin |
404
+ | `OA007` | Frozen latest: registry has drifted past the pinned version (needs `--check-network`) |
405
+ | `OA008` | Materialized vulnerable copy still on disk despite the override |
406
+
407
+ ```bash
408
+ # Audit, severity-grouped terminal output
409
+ cve-lite overrides /path/to/project
410
+
411
+ # Structured JSON findings
412
+ cve-lite overrides /path/to/project --json
413
+
414
+ # Apply RFC 6902 patches for fixable findings
415
+ cve-lite overrides /path/to/project --fix
416
+
417
+ # Scope a run (or a fix) to a single rule
418
+ cve-lite overrides /path/to/project --rule OA001
419
+
420
+ # Enable the OA007 registry drift check (opt-in network)
421
+ cve-lite overrides /path/to/project --check-network
422
+
423
+ # Stream an NDJSON change-control log of every detection and fix
424
+ cve-lite overrides /path/to/project --audit-log ./override-audit.ndjson
425
+ ```
426
+
427
+ `--fix` applies fixes as RFC 6902 patches to `package.json`. A chokepoint guard means a fix can only remove, repin, move, or relocate an existing override; it can never invent a new override key. Suggest-only findings (OA004 cross-major, OA005.d/.e, all of OA008) and "proposed" fixes (the OA006 relocate floor) carry no auto-applied patch and are surfaced as recommendations. `--fail-on <severity>` sets the minimum severity that makes the command exit non-zero (default: `critical`).
428
+
429
+ Full per-rule reference, including the OA005 sub-codes, lives in [`docs/rules/`](docs/rules/README.md). For the programmatic API, see [`docs/api/overrides.md`](docs/api/overrides.md).
430
+
375
431
  ## AI assistant integration (`install-skill`)
376
432
 
377
433
  CVE Lite CLI can teach your AI coding assistant how to analyze scan results and produce a prioritized remediation plan. Run this once in your project root:
@@ -0,0 +1,3 @@
1
+ // Project-wide audit-log event vocabulary. NDJSON stream: one event per line.
2
+ // All events share { ts, type, schemaVersion }.
3
+ export const AUDIT_LOG_SCHEMA_VERSION = 1;
@@ -0,0 +1,20 @@
1
+ /**
2
+ * Zero-cost no-op handle. The default when audit logging is disabled.
3
+ * Single allocation, single function call per emit, no I/O, no allocation per call.
4
+ */
5
+ export class NullAuditLog {
6
+ isNoOp = true;
7
+ emit(_event) { }
8
+ close() { }
9
+ }
10
+ export const NULL_AUDIT_LOG = new NullAuditLog();
11
+ /**
12
+ * In-memory audit log used by tests to assert event sequences. Captures every
13
+ * emit; close is a no-op.
14
+ */
15
+ export class MemoryAuditLog {
16
+ isNoOp = false;
17
+ events = [];
18
+ emit(event) { this.events.push(event); }
19
+ close() { }
20
+ }
@@ -0,0 +1,16 @@
1
+ export { AUDIT_LOG_SCHEMA_VERSION } from "./events.js";
2
+ export { NullAuditLog, NULL_AUDIT_LOG, MemoryAuditLog } from "./handle.js";
3
+ export { NdjsonAuditLog } from "./ndjson-writer.js";
4
+ import { NULL_AUDIT_LOG } from "./handle.js";
5
+ import { NdjsonAuditLog } from "./ndjson-writer.js";
6
+ /**
7
+ * Build an audit-log handle from CLI options.
8
+ *
9
+ * `path` from `--audit-log <path>` or `CVE_LITE_AUDIT_LOG=<path>`. When undefined,
10
+ * returns the shared no-op handle.
11
+ */
12
+ export function createAuditLog(path) {
13
+ if (!path)
14
+ return NULL_AUDIT_LOG;
15
+ return new NdjsonAuditLog(path);
16
+ }
@@ -0,0 +1,28 @@
1
+ import { appendFileSync, closeSync, openSync } from "node:fs";
2
+ /**
3
+ * Append-only NDJSON writer. Opens the file once, appends one JSON object
4
+ * per line per emit, closes on demand.
5
+ */
6
+ export class NdjsonAuditLog {
7
+ isNoOp = false;
8
+ fd;
9
+ constructor(path) {
10
+ this.fd = openSync(path, "a");
11
+ }
12
+ emit(event) {
13
+ if (this.fd === null) {
14
+ throw new Error("NdjsonAuditLog: emit called on a closed handle");
15
+ }
16
+ appendFileSync(this.fd, JSON.stringify(event) + "\n");
17
+ }
18
+ close() {
19
+ if (this.fd === null)
20
+ return;
21
+ try {
22
+ closeSync(this.fd);
23
+ }
24
+ finally {
25
+ this.fd = null;
26
+ }
27
+ }
28
+ }
package/dist/cli/args.js CHANGED
@@ -82,6 +82,65 @@ export function parseArgs(argv) {
82
82
  }
83
83
  throw new Error(`Unknown config subcommand: ${sub ?? "(none)"}. Use: ${ConfigAction.Set}, ${ConfigAction.Unset}, ${ConfigAction.Show}`);
84
84
  }
85
+ if (argv[0] === "overrides") {
86
+ let projectArg;
87
+ for (let i = 1; i < argv.length; i++) {
88
+ const arg = argv[i];
89
+ if (arg === "-h" || arg === "--help") {
90
+ options.help = true;
91
+ continue;
92
+ }
93
+ if (arg === "--json") {
94
+ options.json = true;
95
+ continue;
96
+ }
97
+ if (arg === "--fix") {
98
+ options.fix = true;
99
+ continue;
100
+ }
101
+ if (arg === "--check-network") {
102
+ options.checkNetwork = true;
103
+ continue;
104
+ }
105
+ if (arg === "--debug") {
106
+ options.debug = true;
107
+ continue;
108
+ }
109
+ if (arg === "--audit-log") {
110
+ options.auditLog = argv[++i];
111
+ continue;
112
+ }
113
+ if (arg.startsWith("--audit-log=")) {
114
+ options.auditLog = arg.slice("--audit-log=".length);
115
+ continue;
116
+ }
117
+ if (arg === "--rule") {
118
+ options.rule = argv[++i];
119
+ continue;
120
+ }
121
+ if (arg.startsWith("--rule=")) {
122
+ options.rule = arg.slice("--rule=".length);
123
+ continue;
124
+ }
125
+ if (arg === "--fail-on") {
126
+ options.failOn = argv[++i] ?? options.failOn;
127
+ continue;
128
+ }
129
+ if (arg.startsWith("--fail-on=")) {
130
+ options.failOn = arg.slice("--fail-on=".length);
131
+ continue;
132
+ }
133
+ if (arg.startsWith("-")) {
134
+ throw new Error(`Unknown option: ${arg}`);
135
+ }
136
+ if (!projectArg) {
137
+ projectArg = arg;
138
+ continue;
139
+ }
140
+ throw new Error(`Unexpected argument: ${arg}`);
141
+ }
142
+ return { command: "overrides", options, projectArg };
143
+ }
85
144
  let projectArg;
86
145
  for (let i = 0; i < argv.length; i++) {
87
146
  const arg = argv[i];
@@ -258,6 +317,18 @@ export function parseArgs(argv) {
258
317
  options.cdx = true;
259
318
  continue;
260
319
  }
320
+ if (arg === "--audit-log") {
321
+ options.auditLog = argv[++i];
322
+ continue;
323
+ }
324
+ if (arg.startsWith("--audit-log=")) {
325
+ options.auditLog = arg.slice("--audit-log=".length);
326
+ continue;
327
+ }
328
+ if (arg === "--check-overrides") {
329
+ options.checkOverrides = true;
330
+ continue;
331
+ }
261
332
  if (arg.startsWith("-")) {
262
333
  throw new Error(`Unknown option: ${arg}`);
263
334
  }
@@ -267,9 +338,6 @@ export function parseArgs(argv) {
267
338
  }
268
339
  throw new Error(`Unexpected argument: ${arg}`);
269
340
  }
270
- if (options.sarif && options.report) {
271
- throw new Error("cannot combine --sarif and --report");
272
- }
273
341
  if (options.cdx && options.report) {
274
342
  throw new Error("cannot combine --cdx and --report");
275
343
  }
@@ -0,0 +1,64 @@
1
+ import { audit, verify, applyFix, buildOverrideContext } from "../overrides/index.js";
2
+ export async function runOverridesFixHook(args) {
3
+ const ctx = buildOverrideContext(args.projectPath, {
4
+ auditLog: args.auditLog,
5
+ logger: args.logger,
6
+ checkNetwork: false,
7
+ });
8
+ const auditResult = await audit(ctx, { checkNetwork: false });
9
+ // Tier 1 only by default: "proposed" fixes (OA006 relocate, inferred floor) are
10
+ // surfaced as recommendations, not auto-applied during the post-CVE-fix hook.
11
+ let fixable = auditResult.findings.filter((f) => f.fix?.type === "rfc6902" && f.fix.tier !== "proposed");
12
+ if (args.filterFindings)
13
+ fixable = args.filterFindings(fixable);
14
+ let appliedTargets = [];
15
+ let applied = 0;
16
+ let skipped = 0;
17
+ if (fixable.length > 0) {
18
+ const report = applyFix({
19
+ projectPath: args.projectPath,
20
+ findings: fixable,
21
+ auditLog: args.auditLog,
22
+ dryRun: false,
23
+ });
24
+ applied = report.appliedPatches.length;
25
+ skipped = report.skipped.length;
26
+ appliedTargets = report.appliedPatches.map((p) => ({ name: p.package }));
27
+ }
28
+ // Verify the union of CVE-touched and OA-touched targets.
29
+ const verifyTargets = dedupeTargets([
30
+ ...(args.cveFixTargets ?? []),
31
+ ...appliedTargets,
32
+ ]);
33
+ if (verifyTargets.length === 0) {
34
+ return { applied, skipped, verifyOk: true, verifyFailures: [] };
35
+ }
36
+ // Rebuild context after the on-disk package.json changed.
37
+ const ctxAfter = buildOverrideContext(args.projectPath, {
38
+ auditLog: args.auditLog,
39
+ logger: args.logger,
40
+ checkNetwork: false,
41
+ });
42
+ const verifyResult = await verify(verifyTargets, ctxAfter);
43
+ return {
44
+ applied,
45
+ skipped,
46
+ verifyOk: verifyResult.ok,
47
+ verifyFailures: verifyResult.findings.map((f) => ({
48
+ ruleId: f.ruleId,
49
+ package: f.package.name,
50
+ reason: f.message,
51
+ })),
52
+ };
53
+ }
54
+ function dedupeTargets(targets) {
55
+ const seen = new Set();
56
+ const out = [];
57
+ for (const t of targets) {
58
+ if (seen.has(t.name))
59
+ continue;
60
+ seen.add(t.name);
61
+ out.push(t);
62
+ }
63
+ return out;
64
+ }
package/dist/cli/help.js CHANGED
@@ -26,6 +26,7 @@ export function printHelp() {
26
26
  " cve-lite advisories sync [options]",
27
27
  " cve-lite install-skill",
28
28
  " cve-lite config <set|unset|show> [key] [value]",
29
+ " cve-lite overrides [path] [flags]",
29
30
  "",
30
31
  "Scan options:",
31
32
  " --json Save scan results to a timestamped JSON file",
@@ -42,6 +43,8 @@ export function printHelp() {
42
43
  " --debug Write verbose runtime/network diagnostics to a timestamped log file",
43
44
  " --verbose Show detailed output with fix plan, paths, and full table",
44
45
  " --prod-only Exclude dev dependencies where available",
46
+ " --check-overrides Also audit package.json overrides (OA001-OA008); findings",
47
+ " print, thread to JSON/SARIF/HTML, and count toward --fail-on",
45
48
  " --fail-on <severity> Exit non-zero at or above severity (default: critical)",
46
49
  " --batch-size <number> OSV batch size (default: 100)",
47
50
  " --usage Scan project source files to check if vulnerable dependencies are imported",
@@ -80,3 +83,22 @@ export function printHelp() {
80
83
  ];
81
84
  console.log(lines.join("\n"));
82
85
  }
86
+ export function printOverridesHelp() {
87
+ printBanner();
88
+ const lines = [
89
+ "cve-lite overrides [path] [flags]",
90
+ "",
91
+ "Audit package.json overrides for hygiene problems (OA001-OA008).",
92
+ "",
93
+ "Flags:",
94
+ " --json Emit findings as JSON",
95
+ " --fix Apply RFC 6902 patches for findings with auto-fix",
96
+ " --rule <id> Only run a specific rule (OA001-OA008)",
97
+ " --check-network Enable OA007 registry drift check (opt-in network)",
98
+ " --audit-log <path> Stream NDJSON change-control to <path>",
99
+ " --fail-on <severity> Exit non-zero at or above this severity (default: critical)",
100
+ " --debug Enable debug logging",
101
+ " -h, --help Show this help"
102
+ ];
103
+ console.log(lines.join("\n"));
104
+ }
@@ -0,0 +1,67 @@
1
+ import { resolve } from "node:path";
2
+ import { buildOverrideContext, audit, applyFix } from "../overrides/index.js";
3
+ import { createAuditLog } from "../audit-log/index.js";
4
+ import { EXIT_OK, EXIT_FINDINGS, EXIT_ERROR } from "../types.js";
5
+ import { renderOverrideFindings } from "../output/formatters.js";
6
+ export async function runOverrides({ projectArg, options, logger, auditLog: injectedAuditLog }) {
7
+ const projectPath = resolve(projectArg ?? ".");
8
+ const ownsAuditLog = !injectedAuditLog;
9
+ const auditLog = injectedAuditLog ?? createAuditLog(options.auditLog ?? process.env.CVE_LITE_AUDIT_LOG);
10
+ try {
11
+ const ctx = buildOverrideContext(projectPath, {
12
+ auditLog,
13
+ logger,
14
+ checkNetwork: options.checkNetwork === true,
15
+ });
16
+ const result = await audit(ctx, { checkNetwork: options.checkNetwork === true });
17
+ let findings = result.findings;
18
+ if (options.rule) {
19
+ findings = findings.filter((f) => f.ruleId === options.rule);
20
+ }
21
+ if (options.fix) {
22
+ // Tier 1 only by default: "proposed" fixes write an inferred value (OA006
23
+ // relocate floor) and are surfaced as recommendations, not auto-applied.
24
+ const fixable = findings.filter((f) => f.fix?.type === "rfc6902" && f.fix.tier !== "proposed");
25
+ if (fixable.length > 0) {
26
+ const report = applyFix({
27
+ projectPath,
28
+ findings: fixable,
29
+ auditLog,
30
+ dryRun: false,
31
+ });
32
+ if (options.json) {
33
+ process.stdout.write(JSON.stringify({ findings, fixReport: report }, null, 2) + "\n");
34
+ }
35
+ else {
36
+ logger.info(`Applied ${report.appliedPatches.length} fix${report.appliedPatches.length === 1 ? "" : "es"}; skipped ${report.skipped.length}.`);
37
+ process.stdout.write(renderOverrideFindings(findings) + "\n");
38
+ }
39
+ return findings.length > 0 && reachedFailOn(findings, options.failOn)
40
+ ? EXIT_FINDINGS
41
+ : EXIT_OK;
42
+ }
43
+ }
44
+ if (options.json) {
45
+ process.stdout.write(JSON.stringify({ findings }, null, 2) + "\n");
46
+ }
47
+ else {
48
+ process.stdout.write(renderOverrideFindings(findings) + "\n");
49
+ }
50
+ return findings.length > 0 && reachedFailOn(findings, options.failOn)
51
+ ? EXIT_FINDINGS
52
+ : EXIT_OK;
53
+ }
54
+ catch (err) {
55
+ logger.error(`overrides: ${err instanceof Error ? err.message : String(err)}`);
56
+ return EXIT_ERROR;
57
+ }
58
+ finally {
59
+ if (ownsAuditLog)
60
+ auditLog.close();
61
+ }
62
+ }
63
+ function reachedFailOn(findings, failOn) {
64
+ const rank = { info: 0, low: 1, medium: 2, high: 3, critical: 4 };
65
+ const threshold = rank[failOn] ?? rank.critical;
66
+ return findings.some((f) => (rank[f.severity] ?? 0) >= threshold);
67
+ }