cve-lite-cli 1.27.0 → 1.29.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 (41) hide show
  1. package/README.md +45 -3
  2. package/dist/advisory/osv-advisory-source.js +5 -3
  3. package/dist/cli/advisories-init.js +24 -0
  4. package/dist/cli/args.js +30 -0
  5. package/dist/cli/help.js +6 -2
  6. package/dist/cli/validate.js +6 -0
  7. package/dist/constants.js +1 -0
  8. package/dist/index.js +67 -7
  9. package/dist/maintenance/dm001-maintenance-risk.js +122 -0
  10. package/dist/maintenance/score.js +51 -0
  11. package/dist/maintenance/types.js +1 -0
  12. package/dist/osv/cache.js +49 -50
  13. package/dist/output/formatters.js +10 -4
  14. package/dist/output/html-reporter.js +163 -14
  15. package/dist/output/maintenance-findings-html.js +60 -0
  16. package/dist/output/maintenance-findings-json.js +3 -0
  17. package/dist/output/maintenance-findings-sarif.js +58 -0
  18. package/dist/output/maintenance-terminal.js +138 -0
  19. package/dist/output/multi-folder-html-reporter.js +61 -5
  20. package/dist/output/multi-folder-printer.js +11 -2
  21. package/dist/output/override-findings-html.js +22 -32
  22. package/dist/output/printers.js +95 -22
  23. package/dist/output/sarif.js +23 -7
  24. package/dist/output/spinner.js +5 -0
  25. package/dist/output/write-outputs.js +7 -2
  26. package/dist/parsers/bun-lock.js +47 -7
  27. package/dist/parsers/npm-lock-graph.js +90 -12
  28. package/dist/parsers/pnpm-lock.js +42 -6
  29. package/dist/parsers/utils.js +0 -15
  30. package/dist/parsers/yarn-lock.js +140 -58
  31. package/dist/remediation/cooldown.js +74 -0
  32. package/dist/remediation/fix-commands.js +42 -2
  33. package/dist/remediation/npm-registry.js +70 -42
  34. package/dist/remediation/parent-upgrade.js +114 -18
  35. package/dist/scan/completeness.js +49 -0
  36. package/dist/scan/multi-folder-scan.js +193 -13
  37. package/dist/scanner.js +284 -165
  38. package/dist/usage/scanner.js +12 -2
  39. package/dist/utils/network.js +66 -0
  40. package/dist/utils/vuln.js +16 -0
  41. package/package.json +2 -2
package/README.md CHANGED
@@ -97,7 +97,9 @@ cve-lite /path/to/project --json # JSON output
97
97
  cve-lite /path/to/project --sarif # SARIF output for GitHub Code Scanning
98
98
  cve-lite /path/to/project --report # interactive HTML dashboard
99
99
  cve-lite /path/to/project --check-overrides # audit override hygiene alongside the CVE scan
100
+ cve-lite /path/to/project --check-maintenance # flag CVE-blocking version drag and npm-deprecated direct deps
100
101
  cve-lite advisories sync # sync advisory DB for offline use
102
+ cve-lite advisories init # create an empty advisory DB to populate yourself
101
103
  cve-lite /path/to/project --offline # scan with no runtime API calls
102
104
  ```
103
105
 
@@ -131,6 +133,38 @@ cve-lite /path/to/project --check-overrides # CVE scan + hygiene in one pass
131
133
 
132
134
  For the full guide with per-rule examples and CI patterns, see the [Override Hygiene Auditing guide](https://owasp.org/cve-lite-cli/docs/override-hygiene).
133
135
 
136
+ ## Maintenance risk (`--check-maintenance`)
137
+
138
+ A CVE scanner tells you a transitive package is vulnerable. It does not tell you *why you can't fix it* - often a direct dependency of yours pins it below the fix, and clearing it needs a breaking major upgrade the scanner never mentions. The DM001 rule surfaces exactly that, plus direct dependencies npm has marked deprecated.
139
+
140
+ | Signal | Severity | What it means |
141
+ |---|---|---|
142
+ | Constraint drag | high | A direct dependency blocks a transitive CVE fix behind a major-version upgrade |
143
+ | Deprecated on npm | medium | A direct dependency is deprecated - no fix is coming through a normal update |
144
+
145
+ Packages that have not published in years get a `Last release` context line; release age is informational, not a severity signal on its own.
146
+
147
+ ```bash
148
+ cve-lite /path/to/project --check-maintenance # CVE scan + maintenance risk
149
+ cve-lite /path/to/project --check-maintenance --fail-on high
150
+ ```
151
+
152
+ For the full guide, see the [Maintenance Risk Detection guide](https://owasp.org/cve-lite-cli/docs/maintenance-risk).
153
+
154
+ ## Release cooldown awareness
155
+
156
+ Package managers added a release cooldown to skip the danger window right after a version is published, when a hijacked release is live but not yet caught (the `chalk`/`debug` compromise sat live for about two hours). CVE Lite CLI reads the cooldown your project already configures and warns when a recommended fix is newer than that window, so it never quietly pushes you onto a version your own package manager would refuse to install.
157
+
158
+ ```
159
+ High severity fix commands
160
+ ⚠ Published 2026-07-01, newer than your configured 365 day release cooldown (.npmrc); your package manager would hold this version - validate before overriding.
161
+ > npm install linkify-it@5.0.2 (published 2026-07-01)
162
+ ```
163
+
164
+ The warning is advisory and on by default (no flag, no exit-code change). It reads `min-release-age` (npm), `minimumReleaseAge` (pnpm), or `npmMinimalAgeGate` (Yarn); it never invents a window.
165
+
166
+ For the full guide, see the [Release Cooldown Awareness guide](https://owasp.org/cve-lite-cli/docs/release-cooldown).
167
+
134
168
  ## What it looks like
135
169
 
136
170
  <table>
@@ -195,6 +229,7 @@ No other free tool combines all of the following: lockfile scanning across npm,
195
229
  | JSON output | ✅ | ✅ | ✅ | ✅ | ✅ |
196
230
  | Offline/local advisory DB | ✅ | ❌ | ⚠️ | ❌ | ❌ |
197
231
  | Override hygiene auditing | ✅ | ❌ | ❌ | ❌ | ❌ |
232
+ | Maintenance-risk detection (CVE-fix drag) | ✅ | ❌ | ❌ | ❌ | ❌ |
198
233
 
199
234
  <sub>✅ = built-in strength · ⚠️ = partial or workflow-dependent · ❌ = not a core strength</sub>
200
235
 
@@ -222,7 +257,7 @@ jobs:
222
257
  fix:
223
258
  runs-on: ubuntu-latest
224
259
  steps:
225
- - uses: actions/checkout@v4
260
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
226
261
  with:
227
262
  ref: ${{ github.event.repository.default_branch }}
228
263
  - uses: OWASP/cve-lite-cli@v1
@@ -323,6 +358,7 @@ This is intentional. Because CVE Lite CLI is a security-oriented tool, runtime d
323
358
  - [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
324
359
  - [Parser Coverage guide](https://owasp.org/cve-lite-cli/docs/parser-coverage) - supported lockfile formats, selection priority, `package.json` fallback, monorepos, private registries
325
360
  - [Remediation Strategy guide](https://owasp.org/cve-lite-cli/docs/remediation-strategy) - how CVE Lite CLI chooses upgrade targets and parent update paths
361
+ - [Release Cooldown Awareness guide](https://owasp.org/cve-lite-cli/docs/release-cooldown) - how CVE Lite CLI reads your package manager's cooldown and warns on fix versions newer than the window you trust
326
362
 
327
363
  ## Security and verification
328
364
 
@@ -333,7 +369,7 @@ gh attestation verify cve-lite-cli-X.Y.Z.tgz --repo OWASP/cve-lite-cli
333
369
  npm audit signatures
334
370
  ```
335
371
 
336
- For full details, fingerprints, and the project's threat model, see [SECURITY.md](https://github.com/OWASP/cve-lite-cli/blob/main/src/docs/SECURITY.md) and the [Security Assurance Case](https://owasp.org/cve-lite-cli/docs/security-assurance-case).
372
+ For full details, fingerprints, and the project's threat model, see [SECURITY.md](https://github.com/OWASP/cve-lite-cli/blob/main/SECURITY.md) and the [Security Assurance Case](https://owasp.org/cve-lite-cli/docs/security-assurance-case).
337
373
 
338
374
  For governance details - roles, decision-making, and dispute resolution - see [CONTRIBUTING.md](https://github.com/OWASP/cve-lite-cli/blob/main/src/docs/CONTRIBUTING.md).
339
375
 
@@ -361,7 +397,7 @@ Helpful feedback includes reproducible bug reports, real-world lockfile edge cas
361
397
 
362
398
  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).
363
399
 
364
- For security-related reporting: [SECURITY.md](https://github.com/OWASP/cve-lite-cli/blob/main/src/docs/SECURITY.md)
400
+ For security-related reporting: [SECURITY.md](https://github.com/OWASP/cve-lite-cli/blob/main/SECURITY.md)
365
401
 
366
402
  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.
367
403
 
@@ -383,6 +419,12 @@ Thanks to everyone who helps improve CVE Lite CLI - issues, pull requests, docum
383
419
 
384
420
  New here? See [CONTRIBUTING.md](https://github.com/OWASP/cve-lite-cli/blob/main/src/docs/CONTRIBUTING.md) to get started, and review the [Code of Conduct](https://github.com/OWASP/cve-lite-cli/blob/main/CODE_OF_CONDUCT.md) before participating.
385
421
 
422
+ ## Sponsors
423
+
424
+ Thank you to those who sponsor CVE Lite CLI and help keep it maintained:
425
+
426
+ - [Arkadii Yakovets](https://github.com/arkid15r)
427
+
386
428
  ---
387
429
 
388
430
  **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.
@@ -2,9 +2,11 @@ import { extractErrorMessage } from "../utils/network.js";
2
2
  export class OsvAdvisorySource {
3
3
  baseUrl;
4
4
  debugLog;
5
- constructor(baseUrl = "https://api.osv.dev", debugLog) {
5
+ fetchImpl;
6
+ constructor(baseUrl = "https://api.osv.dev", debugLog, fetchImpl) {
6
7
  this.baseUrl = baseUrl;
7
8
  this.debugLog = debugLog;
9
+ this.fetchImpl = fetchImpl ?? fetch;
8
10
  }
9
11
  async queryBatch(packages, meta) {
10
12
  const requestUrl = `${this.baseUrl}/v1/querybatch`;
@@ -35,7 +37,7 @@ export class OsvAdvisorySource {
35
37
  })),
36
38
  });
37
39
  }
38
- const response = await fetch(requestUrl, {
40
+ const response = await this.fetchImpl(requestUrl, {
39
41
  method: "POST",
40
42
  headers: {
41
43
  "Content-Type": "application/json",
@@ -90,7 +92,7 @@ export class OsvAdvisorySource {
90
92
  headers: {},
91
93
  });
92
94
  }
93
- const response = await fetch(requestUrl, { redirect: "error" });
95
+ const response = await this.fetchImpl(requestUrl, { redirect: "error" });
94
96
  if (this.debugLog) {
95
97
  this.debugLog("OSV response", {
96
98
  method: "GET",
@@ -0,0 +1,24 @@
1
+ import { existsSync } from "node:fs";
2
+ import { LocalAdvisoryDatabase } from "../advisory/local-db.js";
3
+ import { getDefaultAdvisoryDbPath } from "../advisory/osv-sync.js";
4
+ /**
5
+ * Creates an empty local advisory database with the current schema and no data.
6
+ * This is for air-gapped users who cannot run `advisories sync`: they run
7
+ * `advisories init`, populate the database from their own sources, and then scan
8
+ * with `--offline-db`.
9
+ *
10
+ * Returns the resolved path of the database that was created. Throws if a file
11
+ * already exists at that path, so an existing (possibly populated) database is
12
+ * never silently reused.
13
+ */
14
+ export function initAdvisoryDatabase(outputPath) {
15
+ const dbPath = getDefaultAdvisoryDbPath(outputPath);
16
+ if (existsSync(dbPath)) {
17
+ throw new Error(`${dbPath} already exists. Delete it or choose a different --output path before running init.`);
18
+ }
19
+ // Opening a writable database runs the schema (CREATE TABLE IF NOT EXISTS),
20
+ // which is exactly an empty, correctly-shaped database.
21
+ const db = new LocalAdvisoryDatabase(dbPath);
22
+ db.close();
23
+ return dbPath;
24
+ }
package/dist/cli/args.js CHANGED
@@ -52,6 +52,32 @@ export function parseArgs(argv) {
52
52
  }
53
53
  return { command: "advisories-sync", options };
54
54
  }
55
+ if (argv[0] === "advisories" && argv[1] === "init") {
56
+ for (let i = 2; i < argv.length; i++) {
57
+ const arg = argv[i];
58
+ if (arg === "-h" || arg === "--help") {
59
+ options.help = true;
60
+ continue;
61
+ }
62
+ if (arg === "-v" || arg === "--version") {
63
+ options.version = true;
64
+ continue;
65
+ }
66
+ if (arg === "--output") {
67
+ options.output = argv[++i];
68
+ continue;
69
+ }
70
+ if (arg.startsWith("--output=")) {
71
+ options.output = arg.slice("--output=".length);
72
+ continue;
73
+ }
74
+ if (arg.startsWith("-")) {
75
+ throw new Error(`Unknown option: ${arg}`);
76
+ }
77
+ throw new Error(`Unexpected argument: ${arg}`);
78
+ }
79
+ return { command: "advisories-init", options };
80
+ }
55
81
  if (argv[0] === "install-skill") {
56
82
  for (let i = 1; i < argv.length; i++) {
57
83
  const arg = argv[i];
@@ -339,6 +365,10 @@ export function parseArgs(argv) {
339
365
  options.checkOverrides = true;
340
366
  continue;
341
367
  }
368
+ if (arg === "--check-maintenance") {
369
+ options.checkMaintenance = true;
370
+ continue;
371
+ }
342
372
  if (arg.startsWith("-")) {
343
373
  throw new Error(`Unknown option: ${arg}`);
344
374
  }
package/dist/cli/help.js CHANGED
@@ -24,6 +24,7 @@ export function printHelp() {
24
24
  "Usage:",
25
25
  " cve-lite [projectPath] [options]",
26
26
  " cve-lite advisories sync [options]",
27
+ " cve-lite advisories init [options]",
27
28
  " cve-lite install-skill",
28
29
  " cve-lite config <set|unset|show> [key] [value]",
29
30
  " cve-lite overrides [path] [flags]",
@@ -46,6 +47,8 @@ export function printHelp() {
46
47
  " --prod-only Exclude dev dependencies where available",
47
48
  " --check-overrides Also audit package.json overrides (OA001-OA009, PD001-PD002); findings",
48
49
  " print, thread to JSON/SARIF/HTML, and count toward --fail-on",
50
+ " --check-maintenance Also flag direct deps that block a transitive CVE fix via a major-version",
51
+ " drag, or are marked deprecated on npm (DM001); counts toward --fail-on",
49
52
  " --fail-on <severity> Exit non-zero at or above severity (default: critical)",
50
53
  " --batch-size <number> OSV batch size (default: 100)",
51
54
  " --usage Scan project source files to check if vulnerable dependencies are imported",
@@ -58,7 +61,7 @@ export function printHelp() {
58
61
  " --all Show all findings in the main table",
59
62
  " --min-severity <level> Minimum severity shown in table (default: medium)",
60
63
  "",
61
- "Advisory sync options:",
64
+ "Advisory sync/init options:",
62
65
  " --output <path> Write the local advisory database to this path",
63
66
  "",
64
67
  "Other commands:",
@@ -80,7 +83,8 @@ export function printHelp() {
80
83
  " cve-lite . --report Generate an interactive HTML report",
81
84
  " cve-lite . --fix Apply validated direct dependency fixes and rescan",
82
85
  " cve-lite . --offline Scan using the local advisory database (no network)",
83
- " cve-lite advisories sync Sync the local advisory database"
86
+ " cve-lite advisories sync Sync the local advisory database",
87
+ " cve-lite advisories init Create an empty advisory database to populate yourself"
84
88
  ];
85
89
  console.log(lines.join("\n"));
86
90
  }
@@ -24,6 +24,12 @@ export async function validateOptions(options) {
24
24
  if (options.fix && options.json) {
25
25
  throw new Error("--fix cannot be used with --json");
26
26
  }
27
+ if (options.fix && options.sarif) {
28
+ throw new Error("--fix cannot be used with --sarif");
29
+ }
30
+ if (options.fix && options.cdx) {
31
+ throw new Error("--fix cannot be used with --cdx");
32
+ }
27
33
  if (options.createPr && !options.fix) {
28
34
  throw new Error("--create-pr requires --fix");
29
35
  }
package/dist/constants.js CHANGED
@@ -8,6 +8,7 @@ export const severityOrder = {
8
8
  };
9
9
  export const DEFAULT_BATCH_SIZE = 100;
10
10
  export const DEFAULT_SEARCH_DEPTH = 4;
11
+ export const CACHE_TTL_MS = 30 * 60 * 1000; // 30 minutes
11
12
  export const NPM_PUBLIC_REGISTRY = "https://registry.npmjs.org/";
12
13
  export const MAL_PRIVATE_REGISTRY_MESSAGE = "This package has a MAL- advisory but resolved from a private registry - unverifiable whether this advisory applies to your artifact. Inspect the source manually.";
13
14
  export const MAL_PRIVATE_REGISTRY_COMPACT_MESSAGE = "MAL- advisory could not be confirmed for this artifact.";
package/dist/index.js CHANGED
@@ -16,7 +16,7 @@ import { createDebugLogger } from "./output/debug.js";
16
16
  import { buildSuggestedFixCommandPlan } from "./remediation/fix-commands.js";
17
17
  import { scanProjectForPackageUsage } from "./usage/scanner.js";
18
18
  import { getCliVersion } from "./utils/version-info.js";
19
- import { getNetworkErrorHint, offlineDbSyncHint } from "./utils/network.js";
19
+ import { getNetworkErrorHint, offlineDbSyncHint, createCertAwareFetch } from "./utils/network.js";
20
20
  import { formatAdvisoryDbFreshness } from "./utils/time.js";
21
21
  import { pluralize, nearestCommand } from "./utils/string.js";
22
22
  import { EXIT_ERROR } from "./types.js";
@@ -27,6 +27,8 @@ import { writeOutputs } from "./output/write-outputs.js";
27
27
  import { selectFindingsForTable } from "./output/finding-display.js";
28
28
  import { printActionSummary, printCompactOutput, printCoverage, printFinalStatus, printOverrideHint, printSkippedDependencies, printSuggestedFixCommands, printSuggestedFixCommandSkips, printSummary, printTable, } from "./output/printers.js";
29
29
  import { renderOverrideFindings } from "./output/override-findings-terminal.js";
30
+ import { detectDM001 } from "./maintenance/dm001-maintenance-risk.js";
31
+ import { renderMaintenanceFindings } from "./output/maintenance-terminal.js";
30
32
  import { installSkill } from "./skills/install.js";
31
33
  import { readConfig, validateCaCertFile } from "./cli/config.js";
32
34
  import { runConfigCommand } from "./cli/config-command.js";
@@ -125,6 +127,7 @@ if (parsedArgs) {
125
127
  }
126
128
  process.env.NODE_EXTRA_CA_CERTS = resolvedCaCert;
127
129
  }
130
+ const certFetch = resolvedCaCert ? createCertAwareFetch(resolvedCaCert) : undefined;
128
131
  debugLog("Config loaded", {
129
132
  caCert: resolvedCaCert ?? null,
130
133
  nodeExtraCaCerts: process.env.NODE_EXTRA_CA_CERTS ?? null,
@@ -134,6 +137,7 @@ if (parsedArgs) {
134
137
  const usePlainProgressLogs = !process.stdout.isTTY || !!options.json;
135
138
  const result = await syncOsvAdvisories({
136
139
  outputPath: options.output,
140
+ fetchImpl: certFetch,
137
141
  onProgress: event => {
138
142
  if (event.phase === "complete") {
139
143
  return;
@@ -155,6 +159,20 @@ if (parsedArgs) {
155
159
  process.exit(0);
156
160
  return;
157
161
  }
162
+ if (command === "advisories-init") {
163
+ try {
164
+ const { initAdvisoryDatabase } = await import("./cli/advisories-init.js");
165
+ const dbPath = initAdvisoryDatabase(options.output);
166
+ console.log(`${chalk.gray("Advisory database:")} created an empty advisory database at ${chalk.cyan(dbPath)}`);
167
+ console.log(chalk.gray(`Populate it from your own sources, then scan with \`--offline-db ${dbPath}\`.`));
168
+ process.exit(0);
169
+ }
170
+ catch (error) {
171
+ console.error(chalk.red(`Error: ${error instanceof Error ? error.message : String(error)}`));
172
+ process.exit(1);
173
+ }
174
+ return;
175
+ }
158
176
  if (command === "install-skill") {
159
177
  installSkill(process.cwd());
160
178
  process.exit(0);
@@ -184,7 +202,13 @@ if (parsedArgs) {
184
202
  // route to dedicated multi-folder handler instead of single-lockfile scan
185
203
  const nestedLockfiles = findNestedLockfiles(projectPath, searchDepth);
186
204
  if (!hasRootLockfile(projectPath) && nestedLockfiles.length >= 2) {
187
- const exitCode = await handleMultiFolderScan({ projectRoot: projectPath, batchSize, options });
205
+ const exitCode = await handleMultiFolderScan({
206
+ projectRoot: projectPath,
207
+ batchSize,
208
+ options,
209
+ fetchImpl: certFetch,
210
+ auditLog: auditLogHandle,
211
+ });
188
212
  auditLogHandle.close();
189
213
  process.exit(exitCode);
190
214
  }
@@ -197,6 +221,7 @@ if (parsedArgs) {
197
221
  offline: options.offline,
198
222
  offlineDb: options.offlineDb,
199
223
  debugLog,
224
+ fetchImpl: certFetch,
200
225
  });
201
226
  advisorySourceLine = advisorySource.sourceLabel;
202
227
  debugLog("Advisory source", {
@@ -297,6 +322,7 @@ if (parsedArgs) {
297
322
  options,
298
323
  projectPath,
299
324
  debugLog,
325
+ fetchImpl: certFetch,
300
326
  });
301
327
  const findingsBeforeFixList = scanState.sorted;
302
328
  const findingsBeforeFix = findingsBeforeFixList.length;
@@ -323,6 +349,7 @@ if (parsedArgs) {
323
349
  const auditResult = await audit(overrideCtx, { checkNetwork: !!options.checkNetwork });
324
350
  overrideFindings = auditResult.findings;
325
351
  }
352
+ let maintenanceFindings = [];
326
353
  // Emit cve.detected for each CVE finding
327
354
  for (const f of scanState.sorted) {
328
355
  auditLogHandle.emit({
@@ -368,6 +395,7 @@ if (parsedArgs) {
368
395
  options,
369
396
  projectPath,
370
397
  debugLog,
398
+ fetchImpl: certFetch,
371
399
  });
372
400
  }
373
401
  }
@@ -549,6 +577,19 @@ if (parsedArgs) {
549
577
  scanState.tableFindings = scanState.tableFindings.filter(f => filtered.newFindings.some(nf => nf.pkg.name === f.pkg.name && nf.pkg.version === f.pkg.version));
550
578
  suppressedCount = filtered.suppressedCount;
551
579
  }
580
+ // Maintenance risk findings are derived from CVE findings (via
581
+ // recommendedParentUpgrade), so they must be computed from the same
582
+ // baseline-filtered set everything below uses (JSON, rendering,
583
+ // --fail-on). Computing this earlier - before the baseline filter above -
584
+ // let a DM001 finding on an already-baselined CVE keep failing
585
+ // --fail-on forever, even as printFinalStatus reported a clean scan.
586
+ // This point is unreached in --ratchet mode (which always exits above
587
+ // via process.exit), so packument fetches never run wastefully there.
588
+ if (options.checkMaintenance) {
589
+ const directNames = readDirectDependencyNames(projectPath, !!options.prodOnly);
590
+ const directDependencies = scanState.allPackages.filter(p => directNames?.has(p.name));
591
+ maintenanceFindings = await detectDM001(scanState.sorted, directDependencies, !!options.offline || !!options.offlineDb);
592
+ }
552
593
  await writeOutputs(options, {
553
594
  sorted: scanState.sorted,
554
595
  allPackages: scanState.allPackages,
@@ -556,7 +597,9 @@ if (parsedArgs) {
556
597
  coverage: scanState.coverage,
557
598
  minSeverity: scanState.minSeverity,
558
599
  tableFindings: scanState.tableFindings,
600
+ completeness: scanState.completeness,
559
601
  overrideFindings,
602
+ maintenanceFindings,
560
603
  }, scanInput, projectPath);
561
604
  if (!(options.json || options.sarif || options.cdx) || options.verbose) {
562
605
  const offline = !!options.offline || !!options.offlineDb;
@@ -585,8 +628,11 @@ if (parsedArgs) {
585
628
  if (options.checkOverrides && overrideFindings.length > 0) {
586
629
  console.log("\n" + renderOverrideFindings(overrideFindings, { verbose: true, projectPath }));
587
630
  }
631
+ if (options.checkMaintenance && maintenanceFindings.length > 0) {
632
+ console.log("\n" + renderMaintenanceFindings(maintenanceFindings, { verbose: true }));
633
+ }
588
634
  printCoverage([...scanInput.notes, ...scanState.coverage]);
589
- printFinalStatus(scanState.sorted, overrideCount);
635
+ printFinalStatus(scanState.sorted, overrideCount, scanState.completeness);
590
636
  if (showOverrideHint)
591
637
  printOverrideHint();
592
638
  }
@@ -594,10 +640,18 @@ if (parsedArgs) {
594
640
  const compactPmLabel = scanState.suggestedFixCommands
595
641
  ? `${chalk.cyan(scanState.suggestedFixCommands.packageManager)} ${chalk.gray(`(${scanState.suggestedFixCommands.sourceLabel})`)}`
596
642
  : undefined;
597
- printCompactOutput(scanState.sorted, scanInput, { offline, all: !!options.all, packageManager: compactPmLabel });
643
+ printCompactOutput(scanState.sorted, scanInput, {
644
+ offline,
645
+ all: !!options.all,
646
+ packageManager: compactPmLabel,
647
+ completeness: scanState.completeness,
648
+ });
598
649
  if (options.checkOverrides) {
599
650
  console.log("\n" + renderOverrideFindings(overrideFindings, { verbose: false, projectPath }));
600
651
  }
652
+ if (options.checkMaintenance && maintenanceFindings.length > 0) {
653
+ console.log("\n" + renderMaintenanceFindings(maintenanceFindings, { verbose: false }));
654
+ }
601
655
  if (showOverrideHint)
602
656
  printOverrideHint();
603
657
  }
@@ -615,9 +669,13 @@ if (parsedArgs) {
615
669
  suggestedFixCommands: scanState.suggestedFixCommands,
616
670
  notes: [...scanInput.notes, ...scanState.coverage],
617
671
  warnings: scanInput.warnings,
672
+ skippedDependencies: scanInput.skippedDependencies,
618
673
  // undefined (not []) when override checking was not requested, so the HTML
619
674
  // report omits the Override hygiene panel entirely on a plain scan.
620
675
  overrideFindings: options.checkOverrides ? overrideFindings : undefined,
676
+ // Same undefined-vs-[] convention as overrideFindings above.
677
+ maintenanceFindings: options.checkMaintenance ? maintenanceFindings : undefined,
678
+ completeness: scanState.completeness,
621
679
  });
622
680
  const { reportPath } = await writeHtmlReport({
623
681
  outputDir,
@@ -646,7 +704,8 @@ if (parsedArgs) {
646
704
  // override findings, giving a false sense of protection. overrideFindings is empty
647
705
  // unless --check-overrides (and non-ratchet), so this is a no-op otherwise.
648
706
  const shouldFail = reachesFailOn(scanState.sorted, options.failOn) ||
649
- reachesFailOn(overrideFindings, options.failOn);
707
+ reachesFailOn(overrideFindings, options.failOn) ||
708
+ reachesFailOn(maintenanceFindings, options.failOn);
650
709
  // In fix mode, remaining transitive findings cannot be auto-fixed.
651
710
  // Exiting non-zero would prevent the Action PR step from running.
652
711
  const exitCode = shouldFail && !options.fix ? 1 : 0;
@@ -687,11 +746,11 @@ if (parsedArgs) {
687
746
  }
688
747
  async function scanProject(params) {
689
748
  const directDependencyNames = readDirectDependencyNames(params.projectPath, !!params.options.prodOnly);
690
- const findings = await scanPackages(params.scanInput.packages, params.batchSize, params.options, {
749
+ const { findings, completeness } = await scanPackages(params.scanInput.packages, params.batchSize, params.options, {
691
750
  directDependencyNames,
692
751
  scanSource: params.scanInput.source,
693
752
  scanFilePath: params.scanInput.filePath,
694
- }, params.debugLog);
753
+ }, params.debugLog, params.fetchImpl);
695
754
  if (params.options.usage) {
696
755
  logInfo(`Scanning project source for usage hints...`, params.options);
697
756
  const usageStartedAt = Date.now();
@@ -745,5 +804,6 @@ async function scanProject(params) {
745
804
  tableFindings,
746
805
  suggestedFixCommands,
747
806
  allPackages: params.scanInput.packages,
807
+ completeness,
748
808
  };
749
809
  }
@@ -0,0 +1,122 @@
1
+ import { fetchPackument } from "../remediation/npm-registry.js";
2
+ import { computeStaleness, scoreMaintenanceFinding } from "./score.js";
3
+ import { runWithConcurrency } from "../utils/array.js";
4
+ const SEVERITY_ORDER_MAP = { high: 0, medium: 1, low: 2 };
5
+ // Bounds concurrent packument fetches for the deprecated-only pass over direct
6
+ // dependencies so a large dependency tree does not fire hundreds of requests at once.
7
+ const DEPRECATED_CHECK_CONCURRENCY = 10;
8
+ function majorOf(version) {
9
+ return parseInt(version.split(".")[0] ?? "0", 10);
10
+ }
11
+ /**
12
+ * Looks up the deprecation message on a packument's `latest` dist-tag version, if any.
13
+ * Deprecation is checked on `latest` (package-level abandonment signal), not the
14
+ * version actually installed.
15
+ */
16
+ function deprecationMessageOf(packument) {
17
+ if (!packument) {
18
+ return "";
19
+ }
20
+ const latestVersion = packument["dist-tags"]?.latest ?? "";
21
+ if (!latestVersion) {
22
+ return "";
23
+ }
24
+ return packument.versions?.[latestVersion]?.deprecated ?? "";
25
+ }
26
+ /**
27
+ * Checks a single direct dependency (already known not to be a drag candidate) for
28
+ * npm-level deprecation and, if deprecated, builds a DM001 finding for it. Returns
29
+ * null when the dependency is not deprecated or the packument fetch fails.
30
+ */
31
+ async function checkDeprecatedOnly(dep) {
32
+ let packument;
33
+ try {
34
+ packument = await fetchPackument(dep.name);
35
+ }
36
+ catch {
37
+ return null;
38
+ }
39
+ const deprecatedMsg = deprecationMessageOf(packument);
40
+ if (!deprecatedMsg) {
41
+ return null;
42
+ }
43
+ const staleness = computeStaleness(packument, new Date());
44
+ const severity = scoreMaintenanceFinding({ drag: false, deprecated: true }).severity;
45
+ return {
46
+ ruleId: "DM001",
47
+ severity,
48
+ package: { name: dep.name, version: dep.version },
49
+ drag: undefined,
50
+ deprecated: { message: deprecatedMsg },
51
+ staleness: staleness ?? undefined,
52
+ message: `Deprecated: ${deprecatedMsg}`,
53
+ };
54
+ }
55
+ export async function detectDM001(findings, directDependencies, isOffline) {
56
+ // Step 1: Collect drag candidates (transitive findings requiring a major-version parent bump)
57
+ const candidates = new Map();
58
+ for (const finding of findings) {
59
+ if (finding.relationship !== "transitive" || finding.recommendedParentUpgrade == null)
60
+ continue;
61
+ const { package: parentName, currentVersion, targetVersion } = finding.recommendedParentUpgrade;
62
+ if (majorOf(targetVersion) === majorOf(currentVersion))
63
+ continue;
64
+ if (!candidates.has(parentName)) {
65
+ candidates.set(parentName, { parentVersion: currentVersion, dragSignals: [] });
66
+ }
67
+ candidates.get(parentName).dragSignals.push({
68
+ constrainedPackage: finding.pkg.name,
69
+ installedVersion: finding.pkg.version,
70
+ fixVersion: finding.firstFixedVersion ?? finding.recommendedParentUpgrade.targetVersion,
71
+ parentTargetVersion: finding.recommendedParentUpgrade.targetVersion,
72
+ cveId: finding.cveAliases[0] ?? finding.vulnerabilities[0]?.id ?? "",
73
+ });
74
+ }
75
+ // Step 2: Check deprecated status for each drag candidate (skip when offline)
76
+ const results = [];
77
+ for (const [parentName, candidate] of candidates) {
78
+ let deprecated;
79
+ let packument = null;
80
+ if (!isOffline) {
81
+ try {
82
+ packument = await fetchPackument(parentName);
83
+ const deprecatedMsg = deprecationMessageOf(packument);
84
+ if (deprecatedMsg) {
85
+ deprecated = { message: deprecatedMsg };
86
+ }
87
+ }
88
+ catch {
89
+ // Network error - emit drag finding without deprecated/staleness signal
90
+ packument = null;
91
+ }
92
+ }
93
+ const staleness = isOffline ? null : computeStaleness(packument, new Date());
94
+ const severity = scoreMaintenanceFinding({ drag: true, deprecated: !!deprecated }).severity;
95
+ const pkgList = candidate.dragSignals.map(d => d.constrainedPackage).join(", ");
96
+ const message = `Constrains ${pkgList} - blocks CVE fix requiring major upgrade`;
97
+ results.push({
98
+ ruleId: "DM001",
99
+ severity,
100
+ package: { name: parentName, version: candidate.parentVersion },
101
+ drag: candidate.dragSignals,
102
+ deprecated,
103
+ staleness: staleness ?? undefined,
104
+ message,
105
+ });
106
+ }
107
+ // Step 3: Deprecated-only pass over direct dependencies not already covered by
108
+ // drag (package-level abandonment, independent of any CVE-driven parent upgrade).
109
+ if (!isOffline) {
110
+ const uncoveredDeps = directDependencies.filter(dep => !candidates.has(dep.name));
111
+ const deprecatedOnlyFindings = await runWithConcurrency(uncoveredDeps, DEPRECATED_CHECK_CONCURRENCY, checkDeprecatedOnly);
112
+ for (const finding of deprecatedOnlyFindings) {
113
+ if (finding) {
114
+ results.push(finding);
115
+ }
116
+ }
117
+ }
118
+ return results.sort((a, b) => {
119
+ const sDiff = (SEVERITY_ORDER_MAP[a.severity] ?? 4) - (SEVERITY_ORDER_MAP[b.severity] ?? 4);
120
+ return sDiff !== 0 ? sDiff : a.package.name.localeCompare(b.package.name);
121
+ });
122
+ }
@@ -0,0 +1,51 @@
1
+ // Severity comes only from explicit maintainer signals: drag (a package holding a
2
+ // transitive dep below its CVE fix) and npm-deprecation. Release age is NOT a
3
+ // severity input - a stable, feature-complete package can be years old and fine;
4
+ // only an explicit signal reliably means "this will not get fixed". Staleness is
5
+ // surfaced as display context (see computeStaleness), never as a score.
6
+ export const DRAG_WEIGHT = 3;
7
+ export const DEPRECATED_WEIGHT = 2;
8
+ // A package is shown as stale (a "Last release: …" context line) only when its
9
+ // latest release is at least this old. This is a display threshold, not a
10
+ // severity threshold.
11
+ export const STALE_YEARS = 2;
12
+ const MS_PER_YEAR = 365.25 * 24 * 60 * 60 * 1000;
13
+ export function scoreMaintenanceFinding(signals) {
14
+ let score = 0;
15
+ if (signals.drag) {
16
+ score += DRAG_WEIGHT;
17
+ }
18
+ if (signals.deprecated) {
19
+ score += DEPRECATED_WEIGHT;
20
+ }
21
+ let severity;
22
+ if (score >= 3) {
23
+ severity = "high";
24
+ }
25
+ else if (score === 2) {
26
+ severity = "medium";
27
+ }
28
+ else {
29
+ severity = "low";
30
+ }
31
+ return { score, severity };
32
+ }
33
+ // Returns a staleness signal ONLY when the latest release is at least STALE_YEARS
34
+ // old - a fresh package produces no signal (and no "Last release" line). This is
35
+ // context to help judge abandonment, not a severity input.
36
+ export function computeStaleness(packument, now) {
37
+ const latest = packument?.["dist-tags"]?.latest;
38
+ const lastPublish = latest ? packument?.time?.[latest] : undefined;
39
+ if (!lastPublish) {
40
+ return null;
41
+ }
42
+ const published = new Date(lastPublish);
43
+ if (Number.isNaN(published.getTime())) {
44
+ return null;
45
+ }
46
+ const ageYears = Math.floor((now.getTime() - published.getTime()) / MS_PER_YEAR);
47
+ if (ageYears < STALE_YEARS) {
48
+ return null;
49
+ }
50
+ return { lastPublish, ageYears };
51
+ }
@@ -0,0 +1 @@
1
+ export {};