cve-lite-cli 1.24.0 → 1.26.0-beta.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.
Files changed (77) hide show
  1. package/README.md +83 -2
  2. package/assets/OWASP_Logo_Black_TM.png +0 -0
  3. package/assets/logo-with-title-removebg-preview.png +0 -0
  4. package/dist/advisory/local-db.js +7 -1
  5. package/dist/advisory/osv-advisory-source.js +2 -1
  6. package/dist/audit-log/events.js +3 -0
  7. package/dist/audit-log/handle.js +20 -0
  8. package/dist/audit-log/index.js +16 -0
  9. package/dist/audit-log/ndjson-writer.js +28 -0
  10. package/dist/cli/args.js +75 -0
  11. package/dist/cli/fix-overrides-hook.js +64 -0
  12. package/dist/cli/help.js +24 -1
  13. package/dist/cli/overrides.js +67 -0
  14. package/dist/cli/validate.js +9 -1
  15. package/dist/index.js +310 -21
  16. package/dist/osv/cache.js +28 -4
  17. package/dist/output/formatters.js +22 -18
  18. package/dist/output/html-reporter.js +37 -8
  19. package/dist/output/logos.js +18 -0
  20. package/dist/output/multi-folder-html-reporter.js +3 -4
  21. package/dist/output/override-findings-html.js +63 -0
  22. package/dist/output/override-findings-json.js +3 -0
  23. package/dist/output/override-findings-sarif.js +52 -0
  24. package/dist/output/override-findings-terminal.js +106 -0
  25. package/dist/output/printers.js +66 -23
  26. package/dist/output/sarif.js +77 -8
  27. package/dist/output/write-outputs.js +7 -3
  28. package/dist/overrides/api.js +79 -0
  29. package/dist/overrides/composite.js +23 -0
  30. package/dist/overrides/context-builder.js +150 -0
  31. package/dist/overrides/context.js +3 -0
  32. package/dist/overrides/detectors/index.js +23 -0
  33. package/dist/overrides/detectors/oa001-orphaned-target.js +36 -0
  34. package/dist/overrides/detectors/oa002-floating-tag.js +40 -0
  35. package/dist/overrides/detectors/oa003-wrong-section.js +48 -0
  36. package/dist/overrides/detectors/oa004-surpassed-pin.js +49 -0
  37. package/dist/overrides/detectors/oa005-nested-ineffective.js +128 -0
  38. package/dist/overrides/detectors/oa006-coupled-platform-binary.js +170 -0
  39. package/dist/overrides/detectors/oa007-frozen-latest.js +69 -0
  40. package/dist/overrides/detectors/oa008-materialized.js +75 -0
  41. package/dist/overrides/detectors/platform-binary.js +37 -0
  42. package/dist/overrides/fixer.js +199 -0
  43. package/dist/overrides/index.js +5 -0
  44. package/dist/overrides/parsing/installed-tree.js +164 -0
  45. package/dist/overrides/parsing/json-pointer.js +8 -0
  46. package/dist/overrides/parsing/node-modules.js +19 -0
  47. package/dist/overrides/parsing/package-json.js +139 -0
  48. package/dist/overrides/parsing/registry.js +66 -0
  49. package/dist/overrides/types.js +2 -0
  50. package/dist/parsers/pnpm-lock.js +46 -3
  51. package/dist/parsers/yarn-lock.js +2 -2
  52. package/dist/remediation/fix-commands.js +59 -5
  53. package/dist/remediation/npm-registry.js +55 -43
  54. package/dist/remediation/npm-transitive-resolution.js +2 -2
  55. package/dist/remediation/transitive-chain-resolver.js +100 -0
  56. package/dist/scan/multi-folder-scan.js +37 -1
  57. package/dist/scanner.js +122 -46
  58. package/dist/types.js +13 -1
  59. package/dist/utils/baseline.js +16 -0
  60. package/dist/utils/create-pr.js +19 -4
  61. package/dist/utils/fix-runner.js +6 -0
  62. package/dist/utils/package-json.js +21 -0
  63. package/dist/utils/severity.js +16 -0
  64. package/dist/utils/string.js +34 -0
  65. package/dist/utils/validate-url.js +223 -0
  66. package/dist/utils/version.js +135 -2
  67. package/package.json +8 -2
  68. package/dist/learn/keypress.js +0 -50
  69. package/dist/learn/runner.js +0 -96
  70. package/dist/learn/scenario.js +0 -47
  71. package/dist/learn/session.js +0 -36
  72. package/dist/learn/types.js +0 -1
  73. package/dist/llm/client.js +0 -40
  74. package/dist/llm/config.js +0 -48
  75. package/dist/llm/explainer.js +0 -31
  76. package/dist/output/logo-base64.js +0 -1
  77. package/dist/output/owasp-logo-base64.js +0 -1
package/README.md CHANGED
@@ -17,7 +17,7 @@
17
17
 
18
18
  **🏆 Officially recognized as an [OWASP Lab Project](https://owasp.org/cve-lite-cli)**
19
19
 
20
- <p>Vulnerability scanning that belongs in your terminal — not your CI pipeline.<br/>Scan your lockfile, get copy-and-run fix commands, and ship clean code.</p>
20
+ <p>Vulnerability scanning that starts in your terminal and fits cleanly into CI.<br/>Scan your lockfile, get copy-and-run fix commands, and ship clean code.</p>
21
21
 
22
22
  <strong>Scan. Understand. Fix.</strong>
23
23
 
@@ -40,7 +40,7 @@
40
40
  <a href="https://owasp.org/cve-lite-cli/docs/html-report">HTML Report</a> •
41
41
  <a href="https://owasp.org/cve-lite-cli/docs/comparison">Compare</a> •
42
42
  <a href="https://owasp.org/cve-lite-cli/docs/roadmap">Roadmap</a> •
43
- <a href="https://github.com/OWASP/cve-lite-cli/blob/main/src/docs/CONTRIBUTING.md">Contributing</a> •
43
+ <a href="https://github.com/OWASP/cve-lite-cli/blob/main/src/docs/CONTRIBUTING.md">Contributing</a> •
44
44
  <a href="https://owasp.org/slack/invite">Join Slack</a>
45
45
  </p>
46
46
  </div>
@@ -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 (`--check-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
 
@@ -196,6 +197,7 @@ No other free tool combines all of the following: lockfile scanning across npm,
196
197
  | SARIF / GitHub Code Scanning output | ✅ | ❌ | ✅ | ✅ | ❌ |
197
198
  | JSON output | ✅ | ✅ | ✅ | ✅ | ✅ |
198
199
  | Offline/local advisory DB | ✅ | ❌ | ⚠️ | ❌ | ❌ |
200
+ | Override hygiene auditing | ✅ | ❌ | ❌ | ❌ | ❌ |
199
201
 
200
202
  <sub>✅ = built-in strength · ⚠️ = partial or workflow-dependent · ❌ = not a core strength</sub>
201
203
 
@@ -239,6 +241,7 @@ If you maintain an open-source JavaScript or TypeScript project and want CVE Lit
239
241
 
240
242
  ## Press
241
243
 
244
+ - **[Sniff out stale AI override advice with this open source CLI](https://www.theregister.com/security/2026/06/23/sniff-out-stale-ai-override-advice-with-this-open-source-cli/5259853)** — The Register (Thomas Claburn, Senior Reporter), June 2026
242
245
  - **[OWASP Adopts CVE Lite CLI to Boost Dependency Scanning](https://devops.com/owasp-adopts-cve-lite-cli-to-boost-dependency-scanning/)** — DevOps.com, May 2026
243
246
  - **[CVE Lite CLI repère les dépendances à risque](https://www.lemondeinformatique.fr/actualites/lire-cve-lite-cli-repere-les-dependances-a-risque-100270.html)** — Le Monde Informatique (France), May 2026
244
247
  - **[Lieferketten-Angriff: 5.500 GitHub-Repos in 6 Stunden kompromittiert](https://www.ad-hoc-news.de/wissenschaft/lieferketten-angriff-5-500-github-repos-in-6-stunden-kompromittiert/69418833)** — ad-hoc-news (Germany), May 2026 (references CVE Lite CLI)
@@ -309,6 +312,12 @@ cve-lite /path/to/project --verbose
309
312
  # Apply validated direct dependency fixes and rescan
310
313
  cve-lite /path/to/project --fix
311
314
 
315
+ # Audit override hygiene (OA001-OA008) across npm/pnpm/yarn/bun
316
+ cve-lite /path/to/project --check-overrides
317
+
318
+ # Audit and auto-clean stale or ineffective overrides
319
+ cve-lite /path/to/project --check-overrides --fix
320
+
312
321
  # Production dependencies only (where supported by the lockfile)
313
322
  cve-lite /path/to/project --prod-only
314
323
 
@@ -343,6 +352,9 @@ cve-lite /path/to/project --offline-db /path/to/advisories.db
343
352
  # Use a custom advisory endpoint
344
353
  cve-lite /path/to/project --osv-url https://security.company.internal/osv
345
354
 
355
+ # Allow custom endpoint to resolve to private/reserved IPs (for internal mirrors)
356
+ cve-lite /path/to/project --osv-url https://internal-mirror.company.local/osv --allow-private-osv-url
357
+
346
358
  # Show version
347
359
  cve-lite --version
348
360
 
@@ -362,16 +374,65 @@ In the current version it:
362
374
  - applies only direct dependency fixes with a validated lowest known non-vulnerable target
363
375
  - uses `npm install`, `pnpm add`, `yarn add`, or `bun add` based on your lockfile
364
376
  - rescans automatically after applying fixes
377
+ - 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
378
  - does **not** auto-apply transitive overrides or guarantee application compatibility
366
379
 
367
380
  ```bash
368
381
  npx cve-lite-cli /path/to/project --fix
369
382
  ```
370
383
 
384
+ **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":
385
+
386
+ | Code | Meaning |
387
+ |---|---|
388
+ | `0` | no findings at or above `--fail-on` |
389
+ | `1` | findings present (CVE or override) at or above `--fail-on` |
390
+ | `2` | `--fix` applied but the post-fix verify pass detected the fix did not take |
391
+ | `3` | tool error (unreadable lockfile, unhandled exception) |
392
+
371
393
  See the [Fix mode guide](https://owasp.org/cve-lite-cli/docs/fix-mode) for output details and interpretation.
372
394
 
373
395
  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
396
 
397
+ ## Override hygiene (`overrides`)
398
+
399
+ `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. `--check-overrides` audits that hygiene across npm, pnpm, yarn, and bun, reporting eight classes of problem (`OA001`-`OA008`):
400
+
401
+ | Rule | What it catches |
402
+ |---|---|
403
+ | `OA001` | Orphaned target: override for a package no longer in the tree |
404
+ | `OA002` | Floating tag: override pinned to a moving tag (`latest`, `next`) |
405
+ | `OA003` | Wrong section: override placed in the wrong container |
406
+ | `OA004` | Surpassed pin: the rest of the tree has moved past the pin |
407
+ | `OA005` | Nested ineffective override that never applies |
408
+ | `OA006` | Coupled platform binary: override fights a parent's exact pin |
409
+ | `OA007` | Frozen latest: registry has drifted past the pinned version (needs `--check-network`) |
410
+ | `OA008` | Materialized vulnerable copy still on disk despite the override |
411
+
412
+ ```bash
413
+ # Audit, severity-grouped terminal output
414
+ cve-lite /path/to/project --check-overrides
415
+
416
+ # Structured JSON findings
417
+ cve-lite /path/to/project --check-overrides --json
418
+
419
+ # Apply RFC 6902 patches for fixable findings
420
+ cve-lite /path/to/project --check-overrides --fix
421
+
422
+ # Scope a run (or a fix) to a single rule
423
+ cve-lite /path/to/project --check-overrides --rule OA001
424
+
425
+ # Enable the OA007 registry drift check (opt-in network)
426
+ cve-lite /path/to/project --check-overrides --check-network
427
+
428
+ # Stream an NDJSON change-control log of every detection and fix
429
+ cve-lite /path/to/project --check-overrides --audit-log ./override-audit.ndjson
430
+ ```
431
+
432
+ `--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`).
433
+
434
+ For the full guide with diagrams, per-rule examples, and CI patterns, see the [Override Hygiene Auditing guide](https://owasp.org/cve-lite-cli/docs/override-hygiene). Full per-rule reference including OA005 sub-codes lives in [`docs/rules/`](docs/rules/README.md). For the programmatic API, see [`docs/api/overrides.md`](docs/api/overrides.md).
435
+
375
436
  ## AI assistant integration (`install-skill`)
376
437
 
377
438
  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:
@@ -440,6 +501,22 @@ See the [CI and Workflow Integration guide](https://owasp.org/cve-lite-cli/docs/
440
501
 
441
502
  Using CVE Lite CLI at your company or in your projects? [Share your use case in the community thread](https://github.com/OWASP/cve-lite-cli/discussions/481) - we'd love to hear about it.
442
503
 
504
+ ## Community and adoption
505
+
506
+ CVE Lite CLI is used in production across organizations and independent developers in multiple countries. Confirmed users span government digital services, enterprise engineering platforms, open-source libraries, and security education.
507
+
508
+ Notable adopters include:
509
+
510
+ - **Moody's** (via Bitovi) - embedded in the shared CI/CD pipeline serving 600+ UI repositories
511
+ - **Discord** - evaluated by the Staff Product Security Engineering team
512
+ - **Vertica** - used by developers and SRE teams across projects
513
+ - **DINUM** (France) - integrated across four French government digital service repositories, including official AI training infrastructure for civil servants
514
+ - **DGAFP** (France) - Ministry for Civil Service, used as a pre-commit hook on a public-sector HR chatbot
515
+ - **Government of British Columbia** (Canada) - running as a required merge gate alongside Trivy at the Ministry of Citizens' Services
516
+ - **Valibot** and **Formish** - integrated as a GitHub Action and dev script with branch protection
517
+
518
+ For a full view of adoption evidence and press coverage, see [`docs/community/impact.md`](docs/community/impact.md).
519
+
443
520
  ## Current limitations
444
521
 
445
522
  - does not detect malicious packages before they appear in advisory data
@@ -574,6 +651,10 @@ New here? See [CONTRIBUTING.md](https://github.com/OWASP/cve-lite-cli/blob/main/
574
651
 
575
652
  ---
576
653
 
654
+ **Maintainer note:** CVE Lite CLI is an OWASP Lab Project maintained by [Sonu Kapoor](https://github.com/sonukapoor). The goal is to build a tool the security and developer community trusts and returns to - not a product that requires vendor lock-in or a dashboard to be useful. If you find a real-world lockfile edge case, a remediation gap, or a workflow that doesn't fit, open an issue. Real-world feedback from real projects is the most valuable input this project gets. See [CONTRIBUTING.md](https://github.com/OWASP/cve-lite-cli/blob/main/src/docs/CONTRIBUTING.md) for how to get involved.
655
+
656
+ ---
657
+
577
658
  *Most tools tell you what's wrong. CVE Lite CLI tells you what to run.*
578
659
 
579
660
  ## License
Binary file
@@ -155,7 +155,13 @@ export class LocalAdvisoryDatabase {
155
155
  const row = this.getVulnerabilityStatement.get(id);
156
156
  if (!row)
157
157
  return null;
158
- return JSON.parse(row.osv_json);
158
+ try {
159
+ return JSON.parse(row.osv_json);
160
+ }
161
+ catch (error) {
162
+ console.warn(`Failed to parse advisory JSON for ${id}: ${error instanceof Error ? error.message : String(error)}`);
163
+ return null;
164
+ }
159
165
  }
160
166
  findMatchingVulnerabilityIds(pkg) {
161
167
  if (!looksLikeVersion(pkg.version)) {
@@ -41,6 +41,7 @@ export class OsvAdvisorySource {
41
41
  "Content-Type": "application/json",
42
42
  },
43
43
  body: JSON.stringify(payload),
44
+ redirect: "error",
44
45
  });
45
46
  if (this.debugLog) {
46
47
  this.debugLog("OSV response", {
@@ -89,7 +90,7 @@ export class OsvAdvisorySource {
89
90
  headers: {},
90
91
  });
91
92
  }
92
- const response = await fetch(requestUrl);
93
+ const response = await fetch(requestUrl, { redirect: "error" });
93
94
  if (this.debugLog) {
94
95
  this.debugLog("OSV response", {
95
96
  method: "GET",
@@ -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];
@@ -183,6 +242,10 @@ export function parseArgs(argv) {
183
242
  options.osvUrl = arg.slice("--osv-url=".length);
184
243
  continue;
185
244
  }
245
+ if (arg === "--allow-private-osv-url") {
246
+ options.allowPrivateOsvUrl = true;
247
+ continue;
248
+ }
186
249
  if (arg === "--output") {
187
250
  options.output = argv[++i];
188
251
  continue;
@@ -258,6 +321,18 @@ export function parseArgs(argv) {
258
321
  options.cdx = true;
259
322
  continue;
260
323
  }
324
+ if (arg === "--audit-log") {
325
+ options.auditLog = argv[++i];
326
+ continue;
327
+ }
328
+ if (arg.startsWith("--audit-log=")) {
329
+ options.auditLog = arg.slice("--audit-log=".length);
330
+ continue;
331
+ }
332
+ if (arg === "--check-overrides") {
333
+ options.checkOverrides = true;
334
+ continue;
335
+ }
261
336
  if (arg.startsWith("-")) {
262
337
  throw new Error(`Unknown option: ${arg}`);
263
338
  }
@@ -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",
@@ -37,11 +38,14 @@ export function printHelp() {
37
38
  " --ratchet Save current findings as baseline or, if baseline exists, only fail on new findings",
38
39
  " --create-pr After --fix, commit changes and open a GitHub pull request (requires gh)",
39
40
  " --base <branch> Base branch for --create-pr (default: main)",
40
- " --osv-url <url> Use a custom OSV-compatible advisory endpoint",
41
+ " --osv-url <url> Use a custom OSV-compatible advisory endpoint (HTTPS only)",
42
+ " --allow-private-osv-url Allow --osv-url to resolve to private/reserved IPs",
41
43
  " --ca-cert <path> Path to a CA certificate file for corporate SSL proxies",
42
44
  " --debug Write verbose runtime/network diagnostics to a timestamped log file",
43
45
  " --verbose Show detailed output with fix plan, paths, and full table",
44
46
  " --prod-only Exclude dev dependencies where available",
47
+ " --check-overrides Also audit package.json overrides (OA001-OA008); findings",
48
+ " print, thread to JSON/SARIF/HTML, and count toward --fail-on",
45
49
  " --fail-on <severity> Exit non-zero at or above severity (default: critical)",
46
50
  " --batch-size <number> OSV batch size (default: 100)",
47
51
  " --usage Scan project source files to check if vulnerable dependencies are imported",
@@ -80,3 +84,22 @@ export function printHelp() {
80
84
  ];
81
85
  console.log(lines.join("\n"));
82
86
  }
87
+ export function printOverridesHelp() {
88
+ printBanner();
89
+ const lines = [
90
+ "cve-lite overrides [path] [flags]",
91
+ "",
92
+ "Audit package.json overrides for hygiene problems (OA001-OA008).",
93
+ "",
94
+ "Flags:",
95
+ " --json Emit findings as JSON",
96
+ " --fix Apply RFC 6902 patches for findings with auto-fix",
97
+ " --rule <id> Only run a specific rule (OA001-OA008)",
98
+ " --check-network Enable OA007 registry drift check (opt-in network)",
99
+ " --audit-log <path> Stream NDJSON change-control to <path>",
100
+ " --fail-on <severity> Exit non-zero at or above this severity (default: critical)",
101
+ " --debug Enable debug logging",
102
+ " -h, --help Show this help"
103
+ ];
104
+ console.log(lines.join("\n"));
105
+ }
@@ -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/override-findings-terminal.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
+ }
@@ -1,11 +1,16 @@
1
1
  import { validateCaCertFile } from "./config.js";
2
- export function validateOptions(options) {
2
+ import { validateOsvUrl } from "../utils/validate-url.js";
3
+ export async function validateOptions(options) {
4
+ if (options.allowPrivateOsvUrl && !options.osvUrl) {
5
+ throw new Error("--allow-private-osv-url requires --osv-url");
6
+ }
3
7
  if ((options.offline || options.offlineDb) && options.osvUrl) {
4
8
  throw new Error("--offline/--offline-db cannot be used with --osv-url");
5
9
  }
6
10
  if (options.noCache && (options.offline || options.offlineDb)) {
7
11
  throw new Error("--no-cache cannot be used with --offline or --offline-db");
8
12
  }
13
+ let ssrfWarning;
9
14
  if (options.osvUrl) {
10
15
  try {
11
16
  new URL(options.osvUrl);
@@ -13,6 +18,8 @@ export function validateOptions(options) {
13
18
  catch {
14
19
  throw new Error(`Invalid value for --osv-url: ${options.osvUrl}`);
15
20
  }
21
+ // SSRF defense: validate scheme, IP, and allow-private flag
22
+ ssrfWarning = await validateOsvUrl(options.osvUrl, !!options.allowPrivateOsvUrl);
16
23
  }
17
24
  if (options.fix && options.json) {
18
25
  throw new Error("--fix cannot be used with --json");
@@ -37,4 +44,5 @@ export function validateOptions(options) {
37
44
  throw new Error(`--ca-cert: ${err instanceof Error ? err.message : String(err)}`);
38
45
  }
39
46
  }
47
+ return ssrfWarning;
40
48
  }