cve-lite-cli 1.37.0 → 1.38.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 (45) hide show
  1. package/README.md +20 -1
  2. package/dist/cli/args.js +120 -103
  3. package/dist/cli/flags.js +39 -0
  4. package/dist/cli/help.js +6 -3
  5. package/dist/cli/overrides.js +25 -19
  6. package/dist/cli/validate.js +31 -9
  7. package/dist/index.js +6 -1
  8. package/dist/output/compact-truncation.js +35 -0
  9. package/dist/output/formatters.js +10 -2
  10. package/dist/output/html-reporter.js +24 -12
  11. package/dist/output/multi-folder-html-reporter.js +26 -7
  12. package/dist/output/override-findings-html.js +24 -3
  13. package/dist/output/override-findings-json.js +5 -2
  14. package/dist/output/override-findings-sarif.js +1 -0
  15. package/dist/output/override-findings-terminal.js +21 -1
  16. package/dist/output/printers.js +34 -21
  17. package/dist/output/sarif.js +54 -3
  18. package/dist/output/scan-json.js +74 -0
  19. package/dist/output/skipped-override-rules.js +41 -0
  20. package/dist/output/write-outputs.js +16 -28
  21. package/dist/overrides/admitted-scan.js +12 -1
  22. package/dist/overrides/api.js +75 -21
  23. package/dist/overrides/context-builder.js +17 -2
  24. package/dist/overrides/detectors/index.js +2 -0
  25. package/dist/overrides/detectors/oa008-materialized.js +72 -13
  26. package/dist/overrides/detectors/oa009-stale-floor.js +12 -15
  27. package/dist/overrides/detectors/oa010-vulnerable-floor.js +5 -1
  28. package/dist/overrides/detectors/oa011-exceeds-range.js +128 -0
  29. package/dist/overrides/detectors/pd001-override-only-phantom.js +5 -4
  30. package/dist/overrides/detectors/pd002-transitive-only-phantom.js +5 -4
  31. package/dist/overrides/detectors/phantom-utils.js +29 -0
  32. package/dist/overrides/parsing/registry.js +79 -10
  33. package/dist/scan/multi-folder-scan.js +65 -51
  34. package/dist/scan/override-audit.js +49 -0
  35. package/dist/scan/single-scan.js +108 -33
  36. package/dist/scanner.js +8 -4
  37. package/dist/skills/content.js +4 -2
  38. package/dist/usage/scanner.js +219 -28
  39. package/dist/utils/contextual-signals.js +193 -0
  40. package/dist/utils/finding.js +5 -0
  41. package/dist/utils/package-json.js +66 -14
  42. package/dist/utils/severity.js +22 -0
  43. package/dist/utils/update-check.js +2 -1
  44. package/dist/utils/version.js +33 -19
  45. package/package.json +1 -1
package/README.md CHANGED
@@ -3,6 +3,7 @@
3
3
  [![OWASP Lab Project](https://img.shields.io/badge/OWASP-Lab%20Project-48A646?logo=owasp)](https://owasp.org/cve-lite-cli)
4
4
  [![npm version](https://img.shields.io/npm/v/cve-lite-cli)](https://www.npmjs.com/package/cve-lite-cli)
5
5
  [![npm downloads](https://img.shields.io/npm/dm/cve-lite-cli)](https://www.npmjs.com/package/cve-lite-cli)
6
+ [![npm total downloads](https://img.shields.io/npm/d18m/cve-lite-cli?label=total%20downloads)](https://www.npmjs.com/package/cve-lite-cli)
6
7
  [![CI](https://img.shields.io/github/actions/workflow/status/OWASP/cve-lite-cli/ci.yml?branch=main)](https://github.com/OWASP/cve-lite-cli/actions)
7
8
  [![GitHub Marketplace](https://img.shields.io/badge/GitHub%20Marketplace-CVE%20Lite%20CLI-blue)](https://github.com/marketplace/actions/cve-lite-cli)
8
9
  [![License](https://img.shields.io/github/license/OWASP/cve-lite-cli)](https://github.com/OWASP/cve-lite-cli/blob/main/LICENSE)
@@ -120,6 +121,8 @@ npx cve-lite-cli /path/to/project
120
121
 
121
122
  No account. No configuration. No source code leaves your machine.
122
123
 
124
+ > **Note:** CVE Lite CLI includes [`better-sqlite3`](https://github.com/WiseLibs/better-sqlite3), a native SQLite binding used for the [local advisory database](https://owasp.org/cve-lite-cli/docs/offline-advisory-db). During installation, npm may download a prebuilt binary or compile one from source. This can produce extra console output — it is expected and is not CVE Lite CLI itself running an install script. See [Dependency footprint](#dependency-footprint) for details.
125
+
123
126
  ## Usage
124
127
 
125
128
  ```bash
@@ -144,7 +147,7 @@ For the full flag reference and exit codes see the [CLI Reference guide](https:/
144
147
 
145
148
  ## Override hygiene (`overrides`)
146
149
 
147
- `overrides` and `resolutions` are powerful, but they rot. CVE Lite CLI audits them across npm, pnpm, yarn, and bun, catching twelve classes of problem:
150
+ `overrides` and `resolutions` are powerful, but they rot. CVE Lite CLI audits them across npm, pnpm, yarn, and bun, catching thirteen classes of problem:
148
151
 
149
152
  | Rule | What it catches |
150
153
  |---|---|
@@ -158,6 +161,7 @@ For the full flag reference and exit codes see the [CLI Reference guide](https:/
158
161
  | `OA008` | Materialized vulnerable copy still on disk despite the override |
159
162
  | `OA009` | Stale floor: override range floor already met by all parent declarations |
160
163
  | `OA010` | Vulnerable floor: override range admits a known-vulnerable version (needs `--check-network`) |
164
+ | `OA011` | Exceeds declared range: override floor can resolve into a major version no parent permits |
161
165
  | `PD001` | Override-only phantom: package imported in source but only present via an override pin |
162
166
  | `PD002` | Transitive-only phantom: package imported in source but only present as a transitive dependency |
163
167
 
@@ -395,6 +399,21 @@ Notable adopters include:
395
399
 
396
400
  This is intentional. Because CVE Lite CLI is a security-oriented tool, runtime dependencies are kept minimal and reviewable.
397
401
 
402
+ ### Native dependency: `better-sqlite3`
403
+
404
+ `better-sqlite3` is a native Node.js addon that provides the SQLite binding for CVE Lite CLI's local advisory database. This database powers offline scanning (`--offline`, `--offline-db`), advisory sync (`cve-lite advisories sync`), and air-gapped workflows (`cve-lite advisories init`).
405
+
406
+ Because it includes compiled C/C++ code, npm must run an install script when installing `better-sqlite3`. During installation:
407
+
408
+ - **Prebuilt binary available:** `prebuild-install` downloads a prebuilt binary for your platform — fast, though npm may still print a deprecation warning for `prebuild-install` itself ([#519](https://github.com/OWASP/cve-lite-cli/issues/519)).
409
+ - **No prebuilt available:** the package falls back to compiling from source using `node-gyp`, which requires a C/C++ toolchain and produces more console output.
410
+
411
+ This install step belongs to `better-sqlite3`, not to CVE Lite CLI — the project itself does not define any `preinstall`, `install`, or `postinstall` hooks.
412
+
413
+ **npm install-script permissions:** Depending on your npm version and configuration, npm may prompt you to approve the install script before it runs. This is an npm security feature. Online scanning works even when the install script is blocked — the native binding is loaded lazily and only used by `--offline`, `--offline-db`, `cve-lite advisories sync`, and `cve-lite advisories init`. If you use any of those features, the `better-sqlite3` install script must be allowed to complete.
414
+
415
+ **npx behavior:** When using `npx cve-lite-cli`, a quiet run does not necessarily mean the install script was skipped. If npm's cache already contains the required prebuilt binary, installation is silent. On a cold cache, the same native install step runs.
416
+
398
417
  ## More documentation
399
418
 
400
419
  - [Troubleshooting guide](https://owasp.org/cve-lite-cli/docs/troubleshooting) - no lockfile found, zero results, slow advisory sync, offline DB errors, `--fix` skipping findings, CI failures
package/dist/cli/args.js CHANGED
@@ -1,4 +1,5 @@
1
1
  import { ConfigAction, ConfigKey } from "./config.js";
2
+ import { FLAG_ALL, FLAG_ALLOW_PRIVATE_OSV_URL, FLAG_AUDIT_LOG, FLAG_BASE, FLAG_BATCH_SIZE, FLAG_CA_CERT, FLAG_CACHE_DIR, FLAG_CDX, FLAG_CHECK_LICENSES, FLAG_CHECK_MAINTENANCE, FLAG_CHECK_NETWORK, FLAG_CHECK_OVERRIDES, FLAG_CREATE_PR, FLAG_DEBUG, FLAG_FAIL_ON, FLAG_FIX, FLAG_HELP, FLAG_INCOMPLETE_POLICY, FLAG_JSON, FLAG_MIN_SEVERITY, FLAG_NO_CACHE, FLAG_NO_OPEN, FLAG_OFFLINE, FLAG_OFFLINE_DB, FLAG_ONLY_USED, FLAG_OSV_URL, FLAG_OUTPUT, FLAG_PROD_ONLY, FLAG_RATCHET, FLAG_REPORT, FLAG_RULE, FLAG_SARIF, FLAG_SBOM, FLAG_SBOM_INVENTORY_ONLY, FLAG_SEARCH_DEPTH, FLAG_USAGE, FLAG_USAGE_HINTS, FLAG_VERBOSE, FLAG_VERSION, } from "./flags.js";
2
3
  /**
3
4
  * Accepted `--sbom` values. `spdx2.3` is an explicit alias for the version we
4
5
  * emit today, so a future `spdx3` can be added without changing what a plain
@@ -37,33 +38,35 @@ export function parseArgs(argv) {
37
38
  if (argv[0] === "advisories" && argv[1] === "sync") {
38
39
  for (let i = 2; i < argv.length; i++) {
39
40
  const arg = argv[i];
40
- if (arg === "-h" || arg === "--help") {
41
+ if (arg === "-h" || arg === FLAG_HELP) {
41
42
  options.help = true;
42
43
  continue;
43
44
  }
44
- if (arg === "-v" || arg === "--version") {
45
+ if (arg === "-v" || arg === FLAG_VERSION) {
45
46
  options.version = true;
46
47
  continue;
47
48
  }
48
- if (arg === "--output") {
49
+ if (arg === FLAG_OUTPUT) {
49
50
  options.output = argv[++i];
50
51
  continue;
51
52
  }
52
- if (arg.startsWith("--output=")) {
53
- options.output = arg.slice("--output=".length);
53
+ if (arg.startsWith(`${FLAG_OUTPUT}=`)) {
54
+ options.output = arg.slice(FLAG_OUTPUT.length + 1);
54
55
  continue;
55
56
  }
56
- if (arg === "--ca-cert") {
57
+ if (arg === FLAG_CA_CERT) {
57
58
  const val = argv[++i];
58
- if (!val)
59
+ if (!val) {
59
60
  throw new Error("--ca-cert requires a path argument");
61
+ }
60
62
  options.caCert = val;
61
63
  continue;
62
64
  }
63
- if (arg.startsWith("--ca-cert=")) {
64
- const val = arg.slice("--ca-cert=".length);
65
- if (!val)
65
+ if (arg.startsWith(`${FLAG_CA_CERT}=`)) {
66
+ const val = arg.slice(FLAG_CA_CERT.length + 1);
67
+ if (!val) {
66
68
  throw new Error("--ca-cert requires a path argument");
69
+ }
67
70
  options.caCert = val;
68
71
  continue;
69
72
  }
@@ -77,20 +80,20 @@ export function parseArgs(argv) {
77
80
  if (argv[0] === "advisories" && argv[1] === "init") {
78
81
  for (let i = 2; i < argv.length; i++) {
79
82
  const arg = argv[i];
80
- if (arg === "-h" || arg === "--help") {
83
+ if (arg === "-h" || arg === FLAG_HELP) {
81
84
  options.help = true;
82
85
  continue;
83
86
  }
84
- if (arg === "-v" || arg === "--version") {
87
+ if (arg === "-v" || arg === FLAG_VERSION) {
85
88
  options.version = true;
86
89
  continue;
87
90
  }
88
- if (arg === "--output") {
91
+ if (arg === FLAG_OUTPUT) {
89
92
  options.output = argv[++i];
90
93
  continue;
91
94
  }
92
- if (arg.startsWith("--output=")) {
93
- options.output = arg.slice("--output=".length);
95
+ if (arg.startsWith(`${FLAG_OUTPUT}=`)) {
96
+ options.output = arg.slice(FLAG_OUTPUT.length + 1);
94
97
  continue;
95
98
  }
96
99
  if (arg.startsWith("-")) {
@@ -103,7 +106,7 @@ export function parseArgs(argv) {
103
106
  if (argv[0] === "install-skill") {
104
107
  for (let i = 1; i < argv.length; i++) {
105
108
  const arg = argv[i];
106
- if (arg === "-h" || arg === "--help") {
109
+ if (arg === "-h" || arg === FLAG_HELP) {
107
110
  options.help = true;
108
111
  continue;
109
112
  }
@@ -122,16 +125,19 @@ export function parseArgs(argv) {
122
125
  if (sub === ConfigAction.Set) {
123
126
  const key = argv[2];
124
127
  const value = argv[3];
125
- if (key !== ConfigKey.CaCert)
128
+ if (key !== ConfigKey.CaCert) {
126
129
  throw new Error(`Unknown config key: ${key ?? "(none)"}. Valid keys: ${ConfigKey.CaCert}`);
127
- if (!value)
130
+ }
131
+ if (!value) {
128
132
  throw new Error(`cve-lite config set ${ConfigKey.CaCert} requires a path argument`);
133
+ }
129
134
  return { command: "config", options, configSubcommand: { action: ConfigAction.Set, key: ConfigKey.CaCert, value } };
130
135
  }
131
136
  if (sub === ConfigAction.Unset) {
132
137
  const key = argv[2];
133
- if (key !== ConfigKey.CaCert)
138
+ if (key !== ConfigKey.CaCert) {
134
139
  throw new Error(`Unknown config key: ${key ?? "(none)"}. Valid keys: ${ConfigKey.CaCert}`);
140
+ }
135
141
  return { command: "config", options, configSubcommand: { action: ConfigAction.Unset, key: ConfigKey.CaCert } };
136
142
  }
137
143
  throw new Error(`Unknown config subcommand: ${sub ?? "(none)"}. Use: ${ConfigAction.Set}, ${ConfigAction.Unset}, ${ConfigAction.Show}`);
@@ -140,48 +146,48 @@ export function parseArgs(argv) {
140
146
  let projectArg;
141
147
  for (let i = 1; i < argv.length; i++) {
142
148
  const arg = argv[i];
143
- if (arg === "-h" || arg === "--help") {
149
+ if (arg === "-h" || arg === FLAG_HELP) {
144
150
  options.help = true;
145
151
  continue;
146
152
  }
147
- if (arg === "--json") {
153
+ if (arg === FLAG_JSON) {
148
154
  options.json = true;
149
155
  continue;
150
156
  }
151
- if (arg === "--fix") {
157
+ if (arg === FLAG_FIX) {
152
158
  options.fix = true;
153
159
  continue;
154
160
  }
155
- if (arg === "--check-network") {
161
+ if (arg === FLAG_CHECK_NETWORK) {
156
162
  options.checkNetwork = true;
157
163
  continue;
158
164
  }
159
- if (arg === "--debug") {
165
+ if (arg === FLAG_DEBUG) {
160
166
  options.debug = true;
161
167
  continue;
162
168
  }
163
- if (arg === "--audit-log") {
169
+ if (arg === FLAG_AUDIT_LOG) {
164
170
  options.auditLog = argv[++i];
165
171
  continue;
166
172
  }
167
- if (arg.startsWith("--audit-log=")) {
168
- options.auditLog = arg.slice("--audit-log=".length);
173
+ if (arg.startsWith(`${FLAG_AUDIT_LOG}=`)) {
174
+ options.auditLog = arg.slice(FLAG_AUDIT_LOG.length + 1);
169
175
  continue;
170
176
  }
171
- if (arg === "--rule") {
177
+ if (arg === FLAG_RULE) {
172
178
  options.rule = argv[++i];
173
179
  continue;
174
180
  }
175
- if (arg.startsWith("--rule=")) {
176
- options.rule = arg.slice("--rule=".length);
181
+ if (arg.startsWith(`${FLAG_RULE}=`)) {
182
+ options.rule = arg.slice(FLAG_RULE.length + 1);
177
183
  continue;
178
184
  }
179
- if (arg === "--fail-on") {
185
+ if (arg === FLAG_FAIL_ON) {
180
186
  options.failOn = argv[++i] ?? options.failOn;
181
187
  continue;
182
188
  }
183
- if (arg.startsWith("--fail-on=")) {
184
- options.failOn = arg.slice("--fail-on=".length);
189
+ if (arg.startsWith(`${FLAG_FAIL_ON}=`)) {
190
+ options.failOn = arg.slice(FLAG_FAIL_ON.length + 1);
185
191
  continue;
186
192
  }
187
193
  if (arg.startsWith("-")) {
@@ -198,148 +204,152 @@ export function parseArgs(argv) {
198
204
  let projectArg;
199
205
  for (let i = 0; i < argv.length; i++) {
200
206
  const arg = argv[i];
201
- if (arg === "-h" || arg === "--help") {
207
+ if (arg === "-h" || arg === FLAG_HELP) {
202
208
  options.help = true;
203
209
  continue;
204
210
  }
205
- if (arg === "-v" || arg === "--version") {
211
+ if (arg === "-v" || arg === FLAG_VERSION) {
206
212
  options.version = true;
207
213
  continue;
208
214
  }
209
- if (arg === "--json") {
215
+ if (arg === FLAG_JSON) {
210
216
  options.json = true;
211
217
  continue;
212
218
  }
213
- if (arg === "--debug") {
219
+ if (arg === FLAG_DEBUG) {
214
220
  options.debug = true;
215
221
  continue;
216
222
  }
217
- if (arg === "--verbose") {
223
+ if (arg === FLAG_VERBOSE) {
218
224
  options.verbose = true;
219
225
  continue;
220
226
  }
221
- if (arg === "--fix") {
227
+ if (arg === FLAG_FIX) {
222
228
  options.fix = true;
223
229
  continue;
224
230
  }
225
- if (arg === "--ratchet") {
231
+ if (arg === FLAG_RATCHET) {
226
232
  options.ratchet = true;
227
233
  continue;
228
234
  }
229
- if (arg === "--create-pr") {
235
+ if (arg === FLAG_CREATE_PR) {
230
236
  options.createPr = true;
231
237
  continue;
232
238
  }
233
- if (arg === "--base") {
239
+ if (arg === FLAG_BASE) {
234
240
  const val = argv[++i];
235
- if (!val)
241
+ if (!val) {
236
242
  throw new Error("--base requires a branch name");
243
+ }
237
244
  options.prBase = val;
238
245
  continue;
239
246
  }
240
- if (arg.startsWith("--base=")) {
241
- const val = arg.slice("--base=".length);
242
- if (!val)
247
+ if (arg.startsWith(`${FLAG_BASE}=`)) {
248
+ const val = arg.slice(FLAG_BASE.length + 1);
249
+ if (!val) {
243
250
  throw new Error("--base requires a branch name");
251
+ }
244
252
  options.prBase = val;
245
253
  continue;
246
254
  }
247
- if (arg === "--prod-only") {
255
+ if (arg === FLAG_PROD_ONLY) {
248
256
  options.prodOnly = true;
249
257
  continue;
250
258
  }
251
- if (arg === "--offline") {
259
+ if (arg === FLAG_OFFLINE) {
252
260
  options.offline = true;
253
261
  continue;
254
262
  }
255
- if (arg === "--offline-db") {
263
+ if (arg === FLAG_OFFLINE_DB) {
256
264
  options.offlineDb = argv[++i];
257
265
  continue;
258
266
  }
259
- if (arg.startsWith("--offline-db=")) {
260
- options.offlineDb = arg.slice("--offline-db=".length);
267
+ if (arg.startsWith(`${FLAG_OFFLINE_DB}=`)) {
268
+ options.offlineDb = arg.slice(FLAG_OFFLINE_DB.length + 1);
261
269
  continue;
262
270
  }
263
- if (arg === "--all") {
271
+ if (arg === FLAG_ALL) {
264
272
  options.all = true;
265
273
  continue;
266
274
  }
267
- if (arg === "--fail-on") {
275
+ if (arg === FLAG_FAIL_ON) {
268
276
  options.failOn = argv[++i] ?? options.failOn;
269
277
  continue;
270
278
  }
271
- if (arg.startsWith("--fail-on=")) {
272
- options.failOn = arg.slice("--fail-on=".length);
279
+ if (arg.startsWith(`${FLAG_FAIL_ON}=`)) {
280
+ options.failOn = arg.slice(FLAG_FAIL_ON.length + 1);
273
281
  continue;
274
282
  }
275
- if (arg === "--batch-size") {
283
+ if (arg === FLAG_BATCH_SIZE) {
276
284
  options.batchSize = argv[++i] ?? options.batchSize;
277
285
  continue;
278
286
  }
279
- if (arg.startsWith("--batch-size=")) {
280
- options.batchSize = arg.slice("--batch-size=".length);
287
+ if (arg.startsWith(`${FLAG_BATCH_SIZE}=`)) {
288
+ options.batchSize = arg.slice(FLAG_BATCH_SIZE.length + 1);
281
289
  continue;
282
290
  }
283
- if (arg === "--cache-dir") {
291
+ if (arg === FLAG_CACHE_DIR) {
284
292
  options.cacheDir = argv[++i];
285
293
  continue;
286
294
  }
287
- if (arg.startsWith("--cache-dir=")) {
288
- options.cacheDir = arg.slice("--cache-dir=".length);
295
+ if (arg.startsWith(`${FLAG_CACHE_DIR}=`)) {
296
+ options.cacheDir = arg.slice(FLAG_CACHE_DIR.length + 1);
289
297
  continue;
290
298
  }
291
- if (arg === "--osv-url") {
299
+ if (arg === FLAG_OSV_URL) {
292
300
  options.osvUrl = argv[++i];
293
301
  continue;
294
302
  }
295
- if (arg.startsWith("--osv-url=")) {
296
- options.osvUrl = arg.slice("--osv-url=".length);
303
+ if (arg.startsWith(`${FLAG_OSV_URL}=`)) {
304
+ options.osvUrl = arg.slice(FLAG_OSV_URL.length + 1);
297
305
  continue;
298
306
  }
299
- if (arg === "--allow-private-osv-url") {
307
+ if (arg === FLAG_ALLOW_PRIVATE_OSV_URL) {
300
308
  options.allowPrivateOsvUrl = true;
301
309
  continue;
302
310
  }
303
- if (arg === "--output") {
311
+ if (arg === FLAG_OUTPUT) {
304
312
  const val = argv[++i];
305
- if (!val || val.startsWith("-"))
313
+ if (!val || val.startsWith("-")) {
306
314
  throw new Error("--output requires a directory argument");
315
+ }
307
316
  options.output = val;
308
317
  continue;
309
318
  }
310
- if (arg.startsWith("--output=")) {
311
- const val = arg.slice("--output=".length);
312
- if (!val || val.startsWith("-"))
319
+ if (arg.startsWith(`${FLAG_OUTPUT}=`)) {
320
+ const val = arg.slice(FLAG_OUTPUT.length + 1);
321
+ if (!val || val.startsWith("-")) {
313
322
  throw new Error("--output requires a directory argument");
323
+ }
314
324
  options.output = val;
315
325
  continue;
316
326
  }
317
- if (arg === "--search-depth") {
327
+ if (arg === FLAG_SEARCH_DEPTH) {
318
328
  options.searchDepth = argv[++i] ?? options.searchDepth;
319
329
  continue;
320
330
  }
321
- if (arg.startsWith("--search-depth=")) {
322
- options.searchDepth = arg.slice("--search-depth=".length);
331
+ if (arg.startsWith(`${FLAG_SEARCH_DEPTH}=`)) {
332
+ options.searchDepth = arg.slice(FLAG_SEARCH_DEPTH.length + 1);
323
333
  continue;
324
334
  }
325
- if (arg === "--min-severity") {
335
+ if (arg === FLAG_MIN_SEVERITY) {
326
336
  options.minSeverity = argv[++i] ?? options.minSeverity;
327
337
  continue;
328
338
  }
329
- if (arg.startsWith("--min-severity=")) {
330
- options.minSeverity = arg.slice("--min-severity=".length);
339
+ if (arg.startsWith(`${FLAG_MIN_SEVERITY}=`)) {
340
+ options.minSeverity = arg.slice(FLAG_MIN_SEVERITY.length + 1);
331
341
  continue;
332
342
  }
333
- if (arg === "--usage" || arg === "--usage-hints") {
343
+ if (arg === FLAG_USAGE || arg === FLAG_USAGE_HINTS) {
334
344
  options.usage = true;
335
345
  continue;
336
346
  }
337
- if (arg === "--only-used") {
347
+ if (arg === FLAG_ONLY_USED) {
338
348
  options.onlyUsed = true;
339
349
  options.usage = true;
340
350
  continue;
341
351
  }
342
- if (arg === "--report") {
352
+ if (arg === FLAG_REPORT) {
343
353
  const next = argv[i + 1];
344
354
  if (next !== undefined && !next.startsWith("-")) {
345
355
  options.report = next;
@@ -350,68 +360,75 @@ export function parseArgs(argv) {
350
360
  }
351
361
  continue;
352
362
  }
353
- if (arg.startsWith("--report=")) {
354
- options.report = arg.slice("--report=".length);
363
+ if (arg.startsWith(`${FLAG_REPORT}=`)) {
364
+ options.report = arg.slice(FLAG_REPORT.length + 1);
355
365
  continue;
356
366
  }
357
- if (arg === "--no-open") {
367
+ if (arg === FLAG_NO_OPEN) {
358
368
  options.noOpen = true;
359
369
  continue;
360
370
  }
361
- if (arg === "--no-cache") {
371
+ if (arg === FLAG_NO_CACHE) {
362
372
  options.noCache = true;
363
373
  continue;
364
374
  }
365
- if (arg === "--ca-cert") {
375
+ if (arg === FLAG_CA_CERT) {
366
376
  const val = argv[++i];
367
- if (!val)
377
+ if (!val) {
368
378
  throw new Error("--ca-cert requires a path argument");
379
+ }
369
380
  options.caCert = val;
370
381
  continue;
371
382
  }
372
- if (arg.startsWith("--ca-cert=")) {
373
- options.caCert = arg.slice("--ca-cert=".length);
383
+ if (arg.startsWith(`${FLAG_CA_CERT}=`)) {
384
+ options.caCert = arg.slice(FLAG_CA_CERT.length + 1);
374
385
  continue;
375
386
  }
376
- if (arg === "--sarif") {
387
+ if (arg === FLAG_SARIF) {
377
388
  options.sarif = true;
378
389
  continue;
379
390
  }
380
- if (arg === "--cdx") {
391
+ if (arg === FLAG_CDX) {
381
392
  // Permanent alias. --cdx shipped before --sbom existed and stays supported.
382
393
  options.cdx = true;
383
394
  options.sbom = "cyclonedx";
384
395
  continue;
385
396
  }
386
- if (arg === "--sbom") {
397
+ if (arg === FLAG_SBOM) {
387
398
  options.sbom = parseSbomFormat(argv[++i]);
388
399
  continue;
389
400
  }
390
- if (arg.startsWith("--sbom=")) {
391
- options.sbom = parseSbomFormat(arg.slice("--sbom=".length));
401
+ if (arg.startsWith(`${FLAG_SBOM}=`)) {
402
+ options.sbom = parseSbomFormat(arg.slice(FLAG_SBOM.length + 1));
392
403
  continue;
393
404
  }
394
- if (arg === "--sbom-inventory-only") {
405
+ if (arg === FLAG_SBOM_INVENTORY_ONLY) {
395
406
  options.sbomInventoryOnly = true;
396
407
  continue;
397
408
  }
398
- if (arg === "--audit-log") {
409
+ if (arg === FLAG_AUDIT_LOG) {
399
410
  options.auditLog = argv[++i];
400
411
  continue;
401
412
  }
402
- if (arg.startsWith("--audit-log=")) {
403
- options.auditLog = arg.slice("--audit-log=".length);
413
+ if (arg.startsWith(`${FLAG_AUDIT_LOG}=`)) {
414
+ options.auditLog = arg.slice(FLAG_AUDIT_LOG.length + 1);
404
415
  continue;
405
416
  }
406
- if (arg === "--check-overrides") {
417
+ if (arg === FLAG_CHECK_OVERRIDES) {
407
418
  options.checkOverrides = true;
408
419
  continue;
409
420
  }
410
- if (arg === "--check-maintenance") {
421
+ if (arg === FLAG_CHECK_NETWORK) {
422
+ // Accepted on the scan path as well as the `overrides` subcommand. Without it
423
+ // OA007 and OA010 cannot run, and the scan used to reject the flag outright.
424
+ options.checkNetwork = true;
425
+ continue;
426
+ }
427
+ if (arg === FLAG_CHECK_MAINTENANCE) {
411
428
  options.checkMaintenance = true;
412
429
  continue;
413
430
  }
414
- if (arg === "--incomplete-policy") {
431
+ if (arg === FLAG_INCOMPLETE_POLICY) {
415
432
  const value = argv[++i];
416
433
  if (value !== "warn" && value !== "error") {
417
434
  throw new Error("--incomplete-policy must be one of: warn, error");
@@ -419,15 +436,15 @@ export function parseArgs(argv) {
419
436
  options.incompletePolicy = value;
420
437
  continue;
421
438
  }
422
- if (arg.startsWith("--incomplete-policy=")) {
423
- const value = arg.slice("--incomplete-policy=".length);
439
+ if (arg.startsWith(`${FLAG_INCOMPLETE_POLICY}=`)) {
440
+ const value = arg.slice(FLAG_INCOMPLETE_POLICY.length + 1);
424
441
  if (value !== "warn" && value !== "error") {
425
442
  throw new Error("--incomplete-policy must be one of: warn, error");
426
443
  }
427
444
  options.incompletePolicy = value;
428
445
  continue;
429
446
  }
430
- if (arg === "--check-licenses") {
447
+ if (arg === FLAG_CHECK_LICENSES) {
431
448
  options.checkLicenses = true;
432
449
  continue;
433
450
  }
@@ -441,7 +458,7 @@ export function parseArgs(argv) {
441
458
  throw new Error(`Unexpected argument: ${arg}`);
442
459
  }
443
460
  if (options.sbom && options.report) {
444
- const flag = options.cdx ? "--cdx" : "--sbom";
461
+ const flag = options.cdx ? FLAG_CDX : FLAG_SBOM;
445
462
  throw new Error(`cannot combine ${flag} and --report`);
446
463
  }
447
464
  if (options.sbomInventoryOnly && !options.sbom) {
@@ -0,0 +1,39 @@
1
+ export const FLAG_ALL = "--all";
2
+ export const FLAG_ALLOW_PRIVATE_OSV_URL = "--allow-private-osv-url";
3
+ export const FLAG_AUDIT_LOG = "--audit-log";
4
+ export const FLAG_BASE = "--base";
5
+ export const FLAG_BATCH_SIZE = "--batch-size";
6
+ export const FLAG_CA_CERT = "--ca-cert";
7
+ export const FLAG_CACHE_DIR = "--cache-dir";
8
+ export const FLAG_CDX = "--cdx";
9
+ export const FLAG_CHECK_LICENSES = "--check-licenses";
10
+ export const FLAG_CHECK_MAINTENANCE = "--check-maintenance";
11
+ export const FLAG_CHECK_NETWORK = "--check-network";
12
+ export const FLAG_CHECK_OVERRIDES = "--check-overrides";
13
+ export const FLAG_CREATE_PR = "--create-pr";
14
+ export const FLAG_DEBUG = "--debug";
15
+ export const FLAG_FAIL_ON = "--fail-on";
16
+ export const FLAG_FIX = "--fix";
17
+ export const FLAG_HELP = "--help";
18
+ export const FLAG_INCOMPLETE_POLICY = "--incomplete-policy";
19
+ export const FLAG_JSON = "--json";
20
+ export const FLAG_MIN_SEVERITY = "--min-severity";
21
+ export const FLAG_NO_CACHE = "--no-cache";
22
+ export const FLAG_NO_OPEN = "--no-open";
23
+ export const FLAG_OFFLINE = "--offline";
24
+ export const FLAG_OFFLINE_DB = "--offline-db";
25
+ export const FLAG_ONLY_USED = "--only-used";
26
+ export const FLAG_OSV_URL = "--osv-url";
27
+ export const FLAG_OUTPUT = "--output";
28
+ export const FLAG_PROD_ONLY = "--prod-only";
29
+ export const FLAG_RATCHET = "--ratchet";
30
+ export const FLAG_REPORT = "--report";
31
+ export const FLAG_RULE = "--rule";
32
+ export const FLAG_SARIF = "--sarif";
33
+ export const FLAG_SBOM = "--sbom";
34
+ export const FLAG_SBOM_INVENTORY_ONLY = "--sbom-inventory-only";
35
+ export const FLAG_SEARCH_DEPTH = "--search-depth";
36
+ export const FLAG_USAGE = "--usage";
37
+ export const FLAG_USAGE_HINTS = "--usage-hints";
38
+ export const FLAG_VERBOSE = "--verbose";
39
+ export const FLAG_VERSION = "--version";
package/dist/cli/help.js CHANGED
@@ -49,8 +49,11 @@ export function printHelp() {
49
49
  " --debug Write verbose runtime/network diagnostics to a timestamped log file",
50
50
  " --verbose Show detailed output with fix plan, paths, and full table",
51
51
  " --prod-only Exclude dev dependencies where available",
52
- " --check-overrides Also audit package.json overrides (OA001-OA010, PD001-PD002); findings",
52
+ " --check-overrides Also audit package.json overrides (OA001-OA011, PD001-PD002); findings",
53
53
  " print, thread to JSON/SARIF/HTML, and count toward --fail-on",
54
+ " --check-network Let the network-backed override rules run (OA007 registry drift,",
55
+ " OA010 vulnerable floor). Requires --check-overrides; without it",
56
+ " both rules are reported as skipped rather than passing silently",
54
57
  " --check-maintenance Also flag direct deps that block a transitive CVE fix via a major-version",
55
58
  " drag, or are marked deprecated on npm (DM001); counts toward --fail-on",
56
59
  " --check-licenses Also detect copyleft (LC001) and unknown (LC002) licenses; informational",
@@ -102,12 +105,12 @@ export function printOverridesHelp() {
102
105
  const lines = [
103
106
  `${OVERRIDES_COMMAND} [path] [flags]`,
104
107
  "",
105
- "Audit package.json overrides and phantom dependency imports (OA001-OA010, PD001-PD002).",
108
+ "Audit package.json overrides and phantom dependency imports (OA001-OA011, PD001-PD002).",
106
109
  "",
107
110
  "Flags:",
108
111
  " --json Emit findings as JSON",
109
112
  " --fix Apply RFC 6902 patches for findings with auto-fix",
110
- " --rule <id> Only run a specific rule (OA001-OA010, PD001-PD002)",
113
+ " --rule <id> Only run a specific rule (OA001-OA011, PD001-PD002)",
111
114
  " --check-network Enable OA007 registry drift + OA010 admitted-range checks (opt-in network)",
112
115
  " --audit-log <path> Stream NDJSON change-control to <path>",
113
116
  " --fail-on <severity> Exit non-zero at or above this severity (default: critical)",