cve-lite-cli 1.36.1 → 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 (57) hide show
  1. package/README.md +25 -3
  2. package/dist/advisory/local-db.js +22 -3
  3. package/dist/audit-log/events.js +14 -0
  4. package/dist/cli/args.js +125 -102
  5. package/dist/cli/flags.js +39 -0
  6. package/dist/cli/help.js +8 -3
  7. package/dist/cli/overrides.js +25 -19
  8. package/dist/cli/validate.js +34 -9
  9. package/dist/index.js +6 -1
  10. package/dist/output/compact-truncation.js +35 -0
  11. package/dist/output/cyclonedx.js +6 -3
  12. package/dist/output/formatters.js +10 -2
  13. package/dist/output/html-reporter.js +31 -15
  14. package/dist/output/multi-folder-html-reporter.js +26 -7
  15. package/dist/output/output-dir.js +20 -0
  16. package/dist/output/override-findings-html.js +24 -3
  17. package/dist/output/override-findings-json.js +5 -2
  18. package/dist/output/override-findings-sarif.js +1 -0
  19. package/dist/output/override-findings-terminal.js +21 -1
  20. package/dist/output/printers.js +52 -25
  21. package/dist/output/sarif.js +63 -6
  22. package/dist/output/sbom-file.js +6 -4
  23. package/dist/output/scan-json.js +74 -0
  24. package/dist/output/skipped-override-rules.js +41 -0
  25. package/dist/output/spdx.js +2 -2
  26. package/dist/output/write-outputs.js +22 -32
  27. package/dist/overrides/admitted-scan.js +12 -1
  28. package/dist/overrides/api.js +75 -21
  29. package/dist/overrides/context-builder.js +17 -2
  30. package/dist/overrides/detectors/index.js +2 -0
  31. package/dist/overrides/detectors/oa008-materialized.js +74 -14
  32. package/dist/overrides/detectors/oa009-stale-floor.js +12 -15
  33. package/dist/overrides/detectors/oa010-vulnerable-floor.js +5 -1
  34. package/dist/overrides/detectors/oa011-exceeds-range.js +128 -0
  35. package/dist/overrides/detectors/pd001-override-only-phantom.js +5 -4
  36. package/dist/overrides/detectors/pd002-transitive-only-phantom.js +5 -4
  37. package/dist/overrides/detectors/phantom-utils.js +29 -0
  38. package/dist/overrides/parsing/registry.js +79 -10
  39. package/dist/remediation/fix-commands.js +89 -31
  40. package/dist/remediation/npm-registry.js +9 -1
  41. package/dist/remediation/parent-update-child-note.js +11 -0
  42. package/dist/scan/multi-folder-scan.js +68 -53
  43. package/dist/scan/override-audit.js +49 -0
  44. package/dist/scan/single-scan.js +115 -44
  45. package/dist/scanner.js +35 -11
  46. package/dist/skills/content.js +4 -2
  47. package/dist/usage/scanner.js +219 -28
  48. package/dist/utils/contextual-signals.js +193 -0
  49. package/dist/utils/create-pr.js +21 -2
  50. package/dist/utils/finding.js +5 -0
  51. package/dist/utils/fix-runner.js +15 -2
  52. package/dist/utils/package-json.js +66 -14
  53. package/dist/utils/severity.js +22 -0
  54. package/dist/utils/update-check.js +2 -1
  55. package/dist/utils/version.js +81 -86
  56. package/package.json +3 -1
  57. package/scripts/pr-scan-delta.mjs +7 -4
@@ -1,4 +1,5 @@
1
1
  import { relative } from "node:path";
2
+ import { groupSkippedByReason, skippedHeadline, skippedRuleCount } from "./skipped-override-rules.js";
2
3
  import { SEVERITY_ORDER } from "../utils/severity.js";
3
4
  import { OVERRIDES_COMMAND } from "../constants.js";
4
5
  function esc(s) {
@@ -8,7 +9,27 @@ function esc(s) {
8
9
  .replace(/>/g, ">")
9
10
  .replace(/"/g, """);
10
11
  }
11
- export function renderOverrideFindingsHtml(findings, projectPath) {
12
+ /**
13
+ * The rules that could not run, rendered inside the panel. Without this the panel can say
14
+ * "No override hygiene findings" while a rule never ran, which is the same false all-clear
15
+ * the terminal output had (#1222). Reasons embed upstream error text, so they are escaped.
16
+ */
17
+ function skippedNoticeHtml(skipped) {
18
+ if (!skipped || skipped.length === 0)
19
+ return "";
20
+ const items = groupSkippedByReason(skipped)
21
+ .map(({ reason, ruleIds }) => ` <li><code>${esc(ruleIds.join(", "))}</code> - ${esc(reason)}</li>`)
22
+ .join("\n");
23
+ return `
24
+ <div class="override-skipped">
25
+ <p><strong>\u26a0 ${esc(skippedHeadline(skippedRuleCount(skipped)))}</strong></p>
26
+ <ul>
27
+ ${items}
28
+ </ul>
29
+ </div>
30
+ `;
31
+ }
32
+ export function renderOverrideFindingsHtml(findings, projectPath, skipped) {
12
33
  // undefined = override hygiene was never requested -> render nothing, so a plain
13
34
  // `cve-lite .` report shows no Override hygiene panel at all. An empty array =
14
35
  // it ran and found nothing -> render the "no findings" reassurance.
@@ -20,7 +41,7 @@ export function renderOverrideFindingsHtml(findings, projectPath) {
20
41
  <section class="override-hygiene">
21
42
  <h2>Override hygiene</h2>
22
43
  <p>No override hygiene findings.</p>
23
- </section>
44
+ ${skippedNoticeHtml(skipped)}</section>
24
45
  `;
25
46
  }
26
47
  const sorted = [...findings].sort((a, b) => SEVERITY_ORDER.indexOf(a.severity) - SEVERITY_ORDER.indexOf(b.severity));
@@ -55,6 +76,6 @@ export function renderOverrideFindingsHtml(findings, projectPath) {
55
76
  ${rows.join("\n")}
56
77
  </tbody>
57
78
  </table>
58
- </section>
79
+ ${skippedNoticeHtml(skipped)}</section>
59
80
  `;
60
81
  }
@@ -1,3 +1,6 @@
1
- export function overrideFindingsToJson(findings) {
2
- return { overrideFindings: [...findings] };
1
+ export function overrideFindingsToJson(findings, skipped) {
2
+ return {
3
+ overrideFindings: [...findings],
4
+ ...(skipped ? { skippedOverrideRules: [...skipped] } : {}),
5
+ };
3
6
  }
@@ -12,6 +12,7 @@ const OA_RULES = [
12
12
  { id: "OA008", name: "MaterializedVulnerable", shortDescription: "Vulnerable copy still on disk", helpUri: "https://github.com/OWASP/cve-lite-cli/blob/main/docs/rules/OA008.md" },
13
13
  { id: "OA009", name: "StaleFloor", shortDescription: "Override floor already met by all parent declarations", helpUri: "https://github.com/OWASP/cve-lite-cli/blob/main/docs/rules/OA009.md" },
14
14
  { id: "OA010", name: "VulnerableFloor", shortDescription: "Override floor admits a known-vulnerable version", helpUri: "https://github.com/OWASP/cve-lite-cli/blob/main/docs/rules/OA010.md" },
15
+ { id: "OA011", name: "OverReachingFloor", shortDescription: "Override floor exceeds every declaring package's range", helpUri: "https://github.com/OWASP/cve-lite-cli/blob/main/docs/rules/OA011.md" },
15
16
  { id: "PD001", name: "OverrideOnlyPhantom", shortDescription: "Package imported in source but only present via override pin - declare it as a dependency", helpUri: "https://github.com/OWASP/cve-lite-cli/blob/main/docs/rules/PD001.md" },
16
17
  { id: "PD002", name: "TransitiveOnlyPhantom", shortDescription: "Package imported in source but only present as a transitive dependency - declare it explicitly", helpUri: "https://github.com/OWASP/cve-lite-cli/blob/main/docs/rules/PD002.md" },
17
18
  ];
@@ -1,4 +1,5 @@
1
1
  import { relative } from "node:path";
2
+ import { groupSkippedByReason, skippedHeadline, skippedRuleCount } from "./skipped-override-rules.js";
2
3
  import { chalk, stripAnsi } from "../utils/chalk.js";
3
4
  import { formatSeverityLabel, SEVERITY_ORDER } from "../utils/severity.js";
4
5
  import { pluralize } from "../utils/string.js";
@@ -18,7 +19,12 @@ export function renderOverrideFindings(findings, options) {
18
19
  }
19
20
  lines.push("");
20
21
  if (findings.length === 0) {
21
- lines.push(chalk.greenBright("✔ No override hygiene issues found."));
22
+ // Qualified when rules were skipped. An unqualified tick is the line a skimming reader
23
+ // takes away, and this whole feature exists because a clean bill of health from an
24
+ // incomplete audit is worse than no audit.
25
+ lines.push(chalk.greenBright(options?.rulesSkipped
26
+ ? "✔ No override hygiene issues found in the rules that ran."
27
+ : "✔ No override hygiene issues found."));
22
28
  return lines.join("\n");
23
29
  }
24
30
  const grouped = new Map();
@@ -122,3 +128,17 @@ function wrapText(text, width) {
122
128
  lines.push(remaining);
123
129
  return lines.length > 0 ? lines : [text];
124
130
  }
131
+ /**
132
+ * Renders the rules that could not run. Printed whether or not there are findings,
133
+ * because the case this exists for is a scan that reports nothing: a clean bill of
134
+ * health from an audit that skipped a rule is worse than no audit at all (#1222).
135
+ */
136
+ export function renderSkippedOverrideRules(skipped) {
137
+ if (skipped.length === 0)
138
+ return "";
139
+ const lines = [chalk.yellow(`\u26a0 ${skippedHeadline(skippedRuleCount(skipped))}`)];
140
+ for (const { reason, ruleIds } of groupSkippedByReason(skipped)) {
141
+ lines.push(` ${ruleIds.join(", ")} - ${reason}`);
142
+ }
143
+ return lines.join("\n");
144
+ }
@@ -1,5 +1,6 @@
1
1
  import { chalk, stripAnsi } from "../utils/chalk.js";
2
- import { buildSuggestedFixCommandPlan, findFixTargetForFinding, UNVERIFIED_PARENT_UPGRADE_NOTE } from "../remediation/fix-commands.js";
2
+ import { buildSuggestedFixCommandPlan, planVersionForFinding, UNVERIFIED_PARENT_UPGRADE_NOTE } from "../remediation/fix-commands.js";
3
+ import { formatParentUpdateChildNote } from "../remediation/parent-update-child-note.js";
3
4
  import { isBreakingUpgrade } from "../utils/version.js";
4
5
  import { getPrimaryParent } from "../utils/finding.js";
5
6
  import { countUniqueAdvisories, countProdFindings, formatRelationshipLabel, formatRelLabel, formatRootDependencySummary, formatFixCommandWithPublishDates, formatCooldownWarning, } from "./formatters.js";
@@ -8,7 +9,9 @@ import { severityOrder } from "../constants.js";
8
9
  import { pluralize } from "../utils/string.js";
9
10
  import { hasMaliciousAdvisory } from "../utils/vuln.js";
10
11
  import { selectFindingsForCompact } from "./finding-display.js";
12
+ import { COMPACT_COMMAND_GROUP_LIMIT, COMPACT_FINDING_BLOCK_LIMIT, formatCompactCommandGroupTruncationNotice, formatCompactFindingTruncationNotice, } from "./compact-truncation.js";
11
13
  import { computePrioritySignal, PRIORITY_SIGNAL_LABELS, PRIORITY_SIGNAL_TABLE_LABELS, PRIORITY_SIGNAL_DESCRIPTIONS } from "../utils/priority-signal.js";
14
+ import { computeContextualSignals, formatContextualSignalValues, formatContextualSignalsLine } from "../utils/contextual-signals.js";
12
15
  import { renderLicenseFindings } from "./license-terminal.js";
13
16
  import { getCompletenessImpact } from "../scan/completeness.js";
14
17
  import { MAL_PRIVATE_REGISTRY_COMPACT_MESSAGE, MAL_PRIVATE_REGISTRY_LEGEND_MESSAGE, MAL_GIT_SOURCE_PINNED_MESSAGE, MAL_GIT_SOURCE_FLOATING_MESSAGE, MAL_GIT_SOURCE_COMPACT_MESSAGE, MAL_GIT_SOURCE_LEGEND_MESSAGE, MAL_GIT_SOURCE_PINNED_DISPLAY, MAL_GIT_SOURCE_FLOATING_DISPLAY, OVERRIDES_COMMAND, } from "../constants.js";
@@ -227,6 +230,8 @@ const TABLE_COLUMNS = [
227
230
  cell: row => {
228
231
  if (!row.usage)
229
232
  return { value: "n/a", decorated: chalk.gray("n/a") };
233
+ if (row.usage.imported === null)
234
+ return { value: "unknown", decorated: chalk.gray("unknown") };
230
235
  const value = row.usage.imported ? `${row.usage.files.length} file(s)` : "unused";
231
236
  return { value, decorated: row.usage.imported ? chalk.red(value) : chalk.green(value) };
232
237
  },
@@ -279,11 +284,6 @@ const TABLE_COLUMNS = [
279
284
  decorated: formatPrioritySignal(row.signal ?? null),
280
285
  }),
281
286
  },
282
- {
283
- name: "ids",
284
- header: "IDs",
285
- cell: row => ({ value: row.ids ? formatAdvisoryIdFoothold(row.ids) : "-" }),
286
- },
287
287
  {
288
288
  name: "context",
289
289
  header: "Context",
@@ -303,7 +303,7 @@ const TABLE_COLUMNS = [
303
303
  const FINDINGS_TABLE_COLUMNS = [
304
304
  "package", "version", "severity", "type", "root", "usage",
305
305
  "advisory", "target", "scanned", "stillVulnerable", "breaking",
306
- "epss", "epssPriority", "ids",
306
+ "epss", "epssPriority",
307
307
  ];
308
308
  // Both remediation tables draw the same columns. A direct upgrade and a parent
309
309
  // upgrade are different rows, but showing them in differently shaped tables made
@@ -381,15 +381,16 @@ function findingToTableRow(finding, plan, skippedKeys) {
381
381
  // Prefer the version the fix plan will actually install. A package that is both
382
382
  // a direct finding and the parent of other findings needs a higher version than
383
383
  // its own advisory requires, and showing the lower one here contradicted the fix
384
- // command sitting a few lines above.
385
- const planTarget = plan ? findFixTargetForFinding(plan, finding)?.targetVersion : undefined;
384
+ // command sitting a few lines above. For parent-update this is the child's
385
+ // destination, not the parent's unchanged version stored on targetVersion.
386
+ const planTarget = plan ? planVersionForFinding(plan, finding) : undefined;
386
387
  const ownFixVersion = finding.validatedFirstFixedVersion ?? finding.firstFixedVersion;
387
388
  const fixVersion = planTarget ?? ownFixVersion ?? null;
388
389
  return {
389
390
  package: finding.pkg.name,
390
391
  version: finding.pkg.version,
391
392
  severity: finding.severity,
392
- relationship: formatRelLabel(finding).replace(" · dev", "\n· dev"),
393
+ relationship: formatRelLabel(finding),
393
394
  root: shortenRootSummary(formatRootDependencySummary(finding)),
394
395
  usage: finding.usage ?? null,
395
396
  advisoryVersion: finding.firstFixedVersion ?? null,
@@ -405,7 +406,6 @@ function findingToTableRow(finding, plan, skippedKeys) {
405
406
  signal: finding.epssScores && finding.epssScores.length > 0
406
407
  ? computePrioritySignal(finding.severity, finding.epssScores)
407
408
  : null,
408
- ids: finding.vulnerabilities.map(v => v.id),
409
409
  };
410
410
  }
411
411
  function formatTargetDisplay(finding, fixVersion, isSkipped) {
@@ -422,6 +422,18 @@ function formatTargetDisplay(finding, fixVersion, isSkipped) {
422
422
  return chalk.yellow("⚠ Malicious");
423
423
  return chalk.yellow("⚠ no fix");
424
424
  }
425
+ function fixTargetContext(target) {
426
+ const childNote = formatParentUpdateChildNote(target);
427
+ const reason = target.reason ?? target.adjustmentNote ?? null;
428
+ if (childNote && reason) {
429
+ if (target.childPackage && target.childTargetVersion
430
+ && reason.includes(`${target.childPackage}@${target.childTargetVersion}`)) {
431
+ return reason;
432
+ }
433
+ return `${childNote}. ${reason}`;
434
+ }
435
+ return childNote ?? reason;
436
+ }
425
437
  function fixTargetToTableRow(target, context) {
426
438
  return {
427
439
  package: target.package,
@@ -440,8 +452,7 @@ function fixTargetToTableRow(target, context) {
440
452
  breaking: !!target.currentVersion && isBreakingUpgrade(target.currentVersion, target.targetVersion),
441
453
  epss: context?.epss ?? null,
442
454
  signal: context?.prioritySignal ?? null,
443
- ids: context?.ids,
444
- context: target.reason ?? target.adjustmentNote ?? null,
455
+ context: fixTargetContext(target),
445
456
  };
446
457
  }
447
458
  /** The bold summary row under a fix table: only the validation counts carry values. */
@@ -469,6 +480,15 @@ export function printTable(findings, threshold, skippedKeys, plan) {
469
480
  console.log(chalk.gray("Use --all to show every finding."));
470
481
  }
471
482
  printColumnTable(columns, rows, columnWidths(columns, rows));
483
+ if (findings.length > 0) {
484
+ console.log("");
485
+ console.log(chalk.bold("Prioritization signals (heuristic)"));
486
+ console.log(chalk.gray("Triage hints only — not exploitability or runtime reachability proofs."));
487
+ for (const finding of findings) {
488
+ const values = formatContextualSignalValues(computeContextualSignals(finding));
489
+ console.log(chalk.gray(` ${finding.pkg.name}@${finding.pkg.version} ${values}`));
490
+ }
491
+ }
472
492
  const maliciousFindings = findings.filter(f => hasMaliciousAdvisory(f.vulnerabilities));
473
493
  if (maliciousFindings.length > 0) {
474
494
  console.log("");
@@ -570,13 +590,6 @@ export function printOverrideHint() {
570
590
  // --json, --sarif and the HTML report, where it is not competing for terminal
571
591
  // width and each ID is a link. Joined into the table it ran to 628 characters on
572
592
  // a real project, and truncated it left a single usable ID followed by a stump.
573
- function formatAdvisoryIdFoothold(ids) {
574
- if (ids.length === 0)
575
- return "-";
576
- if (ids.length === 1)
577
- return ids[0];
578
- return `${ids[0]} ${chalk.gray(`+${ids.length - 1}`)}`;
579
- }
580
593
  function renderRow(cells, widths) {
581
594
  const columnLines = cells.map(cell => String(cell).split("\n"));
582
595
  const height = Math.max(1, ...columnLines.map(lines => lines.length));
@@ -665,7 +678,7 @@ export function printCompactOutput(findings, scanInput, options) {
665
678
  console.log("────────────────────────────────\n");
666
679
  // Reuse shared display selection logic so compact mode does not silently
667
680
  // drop direct unknown-severity findings.
668
- const urgentFindings = selectFindingsForCompact(findings, { urgentLimit: 3 });
681
+ const urgentFindings = selectFindingsForCompact(findings, { urgentLimit: COMPACT_FINDING_BLOCK_LIMIT });
669
682
  for (const finding of urgentFindings) {
670
683
  const sevLabel = finding.severity.toUpperCase().padEnd(8);
671
684
  const typeLabel = finding.relationship === "direct"
@@ -675,7 +688,10 @@ export function printCompactOutput(findings, scanInput, options) {
675
688
  : "Unknown dependency";
676
689
  let usageContext = "";
677
690
  if (finding.usage) {
678
- if (finding.usage.imported) {
691
+ if (finding.usage.imported === null) {
692
+ usageContext = chalk.gray(` (import status unknown - usage scan hit the file cap)`);
693
+ }
694
+ else if (finding.usage.imported) {
679
695
  usageContext = chalk.red(` (imported in ${finding.usage.files.length} ${pluralize(finding.usage.files.length, "file")})`);
680
696
  }
681
697
  else {
@@ -684,6 +700,7 @@ export function printCompactOutput(findings, scanInput, options) {
684
700
  }
685
701
  console.log(`${formatSeverityLabel(sevLabel)} ${chalk.whiteBright(finding.pkg.name)}@${finding.pkg.version}`);
686
702
  console.log(` ${typeLabel}${usageContext}`);
703
+ console.log(` ${chalk.gray(formatContextualSignalsLine(computeContextualSignals(finding)))}`);
687
704
  if (finding.epssScores && finding.epssScores.length > 0) {
688
705
  const best = finding.epssScores.slice().sort((a, b) => b.percentile - a.percentile)[0];
689
706
  const pct = (best.epss * 100).toFixed(1);
@@ -746,6 +763,11 @@ export function printCompactOutput(findings, scanInput, options) {
746
763
  }
747
764
  console.log("");
748
765
  }
766
+ const findingTruncationNotice = formatCompactFindingTruncationNotice(urgentFindings.length, findings.length);
767
+ if (findingTruncationNotice && !options?.all) {
768
+ console.log(chalk.gray(findingTruncationNotice));
769
+ console.log("");
770
+ }
749
771
  const plan = scanInput ? buildSuggestedFixCommandPlan(findings, scanInput, options) : null;
750
772
  if (plan) {
751
773
  if (plan?.sections.length) {
@@ -759,7 +781,8 @@ export function printCompactOutput(findings, scanInput, options) {
759
781
  console.log(chalk.gray(`Validation: scanned ${compactValidationSummary.checked} package ${pluralize(compactValidationSummary.checked, "version")}; ${compactValidationSummary.vulnerable} ${pluralize(compactValidationSummary.vulnerable, "is", "are")} still known vulnerable.`));
760
782
  }
761
783
  console.log("");
762
- for (const section of plan.sections.slice(0, 3)) {
784
+ const shownSections = plan.sections.slice(0, COMPACT_COMMAND_GROUP_LIMIT);
785
+ for (const section of shownSections) {
763
786
  console.log(`${section.title}`);
764
787
  for (const target of section.targets) {
765
788
  if (section.kind === "direct-adjusted" && target.adjustmentNote) {
@@ -770,6 +793,11 @@ export function printCompactOutput(findings, scanInput, options) {
770
793
  console.log(renderCommandCallout(section.command, section.targets));
771
794
  console.log("");
772
795
  }
796
+ const commandGroupTruncationNotice = formatCompactCommandGroupTruncationNotice(plan.sections.slice(COMPACT_COMMAND_GROUP_LIMIT));
797
+ if (commandGroupTruncationNotice) {
798
+ console.log(chalk.gray(commandGroupTruncationNotice));
799
+ console.log("");
800
+ }
773
801
  }
774
802
  }
775
803
  if (options?.licenseFindings) {
@@ -967,7 +995,7 @@ function buildFixRowContexts(findings) {
967
995
  }
968
996
  const contexts = new Map();
969
997
  for (const [name, group] of byPackage) {
970
- // The package's own finding describes Type, Root and IDs; fall back to the
998
+ // The package's own finding describes Type and Root; fall back to the
971
999
  // first of the group when the package only appears as somebody else's parent.
972
1000
  const own = group.find(f => f.relationship === "direct") ?? group[0];
973
1001
  const worst = group.reduce((a, b) => (severityOrder[b.severity] > severityOrder[a.severity] ? b : a));
@@ -988,7 +1016,6 @@ function buildFixRowContexts(findings) {
988
1016
  root: shortenRootSummary(formatRootDependencySummary(own)),
989
1017
  epss: bestEpss,
990
1018
  prioritySignal: bestSignal,
991
- ids: own.vulnerabilities.map(v => v.id),
992
1019
  advisoryVersion: own.firstFixedVersion ?? null,
993
1020
  scanned: own.validatedTargetScannedVersions ?? null,
994
1021
  stillVulnerable: own.validatedTargetKnownVulnerableVersions ?? null,
@@ -5,6 +5,7 @@ import { getRecommendedAction, formatCooldownWarning } from "./formatters.js";
5
5
  import { getCliVersion } from "../utils/version-info.js";
6
6
  import { severityToSarifLevel } from "../utils/severity.js";
7
7
  import { sarifFingerprintHash } from "../utils/sarif.js";
8
+ import { displayOutputPath } from "./output-dir.js";
8
9
  import { buildOverrideSarifComponent, buildOverrideSarifResults } from "./override-findings-sarif.js";
9
10
  import { buildMaintenanceSarifComponent, buildMaintenanceSarifResults } from "./maintenance-findings-sarif.js";
10
11
  import { buildLicenseSarifComponent, buildLicenseSarifResults } from "./license-findings-sarif.js";
@@ -78,7 +79,24 @@ export function deriveLockfileUri(scanInput) {
78
79
  return path.basename(scanInput.filePath);
79
80
  return LOCKFILE_NAMES[scanInput.source] ?? "lockfile";
80
81
  }
81
- export function buildSarifOutput(findings, lockfileUri, version, plan, overrideFindings, maintenanceFindings, licenseFindings) {
82
+ function dedupeSkipped(skipped) {
83
+ const seen = new Set();
84
+ const out = [];
85
+ for (const entry of skipped) {
86
+ const key = `${entry.ruleId}\u0000${entry.reason}`;
87
+ if (seen.has(key))
88
+ continue;
89
+ seen.add(key);
90
+ out.push(entry);
91
+ }
92
+ return out;
93
+ }
94
+ export function buildSarifOutput(findings, lockfileUri, version, plan, overrideFindings, maintenanceFindings, licenseFindings,
95
+ // NOTE: this parameter list is too long and wants an options object, tracked as #1244.
96
+ // Kept positional here so #1222 does not also rewrite every call site. It is why the
97
+ // new parameter sits last in both functions even though `writeSarifReport` already has
98
+ // a defaulted `outputDir` ahead of it.
99
+ overrideSkipped) {
82
100
  const ruleMap = new Map();
83
101
  const ruleIndexMap = new Map();
84
102
  const results = [];
@@ -88,7 +106,8 @@ export function buildSarifOutput(findings, lockfileUri, version, plan, overrideF
88
106
  // If the recommended fix for this finding lands on a version inside the
89
107
  // project's configured release cooldown, surface that on the result so it
90
108
  // reaches Code Scanning (message text for humans, property for tooling).
91
- const cooldown = plan ? findFixTargetForFinding(plan, finding)?.cooldownWarning ?? null : null;
109
+ const planTarget = plan ? findFixTargetForFinding(plan, finding) : null;
110
+ const cooldown = planTarget?.cooldownWarning ?? null;
92
111
  const location = {
93
112
  physicalLocation: {
94
113
  artifactLocation: { uri: lockfileUri, uriBaseId: "%SRCROOT%" },
@@ -133,6 +152,10 @@ export function buildSarifOutput(findings, lockfileUri, version, plan, overrideF
133
152
  if (finding.validatedTargetKnownVulnerableVersions != null) {
134
153
  resultProperties.versionsStillVulnerable = finding.validatedTargetKnownVulnerableVersions;
135
154
  }
155
+ if (planTarget?.childPackage)
156
+ resultProperties.childPackage = planTarget.childPackage;
157
+ if (planTarget?.childTargetVersion)
158
+ resultProperties.childTargetVersion = planTarget.childTargetVersion;
136
159
  results.push({
137
160
  ruleId,
138
161
  ruleIndex: ruleIndexMap.get(ruleId),
@@ -170,6 +193,9 @@ export function buildSarifOutput(findings, lockfileUri, version, plan, overrideF
170
193
  ? buildLicenseSarifResults(licenseFindings, lockfileUri, licenseExtensionIndex)
171
194
  : []),
172
195
  ];
196
+ // One entry per (rule, reason), de-duplicated so the driver's notification
197
+ // descriptors and the invocation's notifications cannot disagree.
198
+ const skippedNotifications = dedupeSkipped(overrideSkipped ?? []);
173
199
  return {
174
200
  $schema: SARIF_SCHEMA,
175
201
  version: "2.1.0",
@@ -181,10 +207,41 @@ export function buildSarifOutput(findings, lockfileUri, version, plan, overrideF
181
207
  version,
182
208
  informationUri: "https://owasp.org/cve-lite-cli/",
183
209
  rules: Array.from(ruleMap.values()),
210
+ // Deduped by rule id, separately from the notification list. The notifications
211
+ // are per (rule, reason) and one rule can be skipped for two reasons, but
212
+ // reportingDescriptor.id must be unique within its array.
213
+ ...(skippedNotifications.length > 0
214
+ ? {
215
+ notifications: [...new Set(skippedNotifications.map((n) => n.ruleId))].map((id) => ({
216
+ id,
217
+ shortDescription: { text: `${id} did not run during this scan` },
218
+ })),
219
+ }
220
+ : {}),
184
221
  },
185
222
  ...(extensions.length > 0 ? { extensions } : {}),
186
223
  },
187
224
  results: allResults,
225
+ // SARIF 2.1.0 §3.20.21: a rule that could not run belongs in
226
+ // toolExecutionNotifications rather than being silently omitted, so a machine
227
+ // reading this file can tell an incomplete audit from a clean one.
228
+ //
229
+ // Emitted only when there is something to report, so a plain scan's SARIF is
230
+ // unchanged by #1222. Each descriptor is declared on the driver above.
231
+ ...(skippedNotifications.length > 0
232
+ ? {
233
+ invocations: [
234
+ {
235
+ executionSuccessful: true,
236
+ toolExecutionNotifications: skippedNotifications.map((entry) => ({
237
+ level: "warning",
238
+ message: { text: `${entry.ruleId} did not run: ${entry.reason}` },
239
+ descriptor: { id: entry.ruleId },
240
+ })),
241
+ },
242
+ ],
243
+ }
244
+ : {}),
188
245
  artifacts: [
189
246
  { location: { uri: lockfileUri, uriBaseId: "%SRCROOT%" } },
190
247
  ],
@@ -192,11 +249,11 @@ export function buildSarifOutput(findings, lockfileUri, version, plan, overrideF
192
249
  ],
193
250
  };
194
251
  }
195
- export function writeSarifReport(findings, lockfileUri, plan, overrideFindings, maintenanceFindings, licenseFindings) {
252
+ export function writeSarifReport(findings, lockfileUri, plan, overrideFindings, maintenanceFindings, licenseFindings, outputDir = process.cwd(), overrideSkipped) {
196
253
  const ts = new Date().toISOString().replace(/[:.]/g, "-").slice(0, 19);
197
254
  const filename = `cve-lite-scan-${ts}.sarif`;
198
- const outputPath = path.join(process.cwd(), filename);
199
- const sarif = buildSarifOutput(findings, lockfileUri, getCliVersion(), plan, overrideFindings, maintenanceFindings, licenseFindings);
255
+ const outputPath = path.join(outputDir, filename);
256
+ const sarif = buildSarifOutput(findings, lockfileUri, getCliVersion(), plan, overrideFindings, maintenanceFindings, licenseFindings, overrideSkipped);
200
257
  try {
201
258
  fs.writeFileSync(outputPath, JSON.stringify(sarif, null, 2));
202
259
  }
@@ -207,5 +264,5 @@ export function writeSarifReport(findings, lockfileUri, plan, overrideFindings,
207
264
  catch { /* best-effort cleanup */ }
208
265
  throw new Error(`Failed to write SARIF report to ${outputPath}: ${err instanceof Error ? err.message : String(err)}`, { cause: err });
209
266
  }
210
- return filename;
267
+ return displayOutputPath(outputPath);
211
268
  }
@@ -1,14 +1,16 @@
1
1
  import fs from "node:fs";
2
2
  import path from "node:path";
3
+ import { displayOutputPath } from "./output-dir.js";
3
4
  /**
4
- * Writes an SBOM document to a timestamped file in the working directory.
5
+ * Writes an SBOM document to a timestamped file in the output directory,
6
+ * which defaults to the working directory.
5
7
  *
6
8
  * A partial file left behind by a failed write would look like a valid SBOM to
7
9
  * whatever consumes it next, so the partial output is removed before the error
8
10
  * propagates.
9
11
  */
10
- export function writeSbomFile(filename, document, label) {
11
- const outputPath = path.join(process.cwd(), filename);
12
+ export function writeSbomFile(filename, document, label, outputDir = process.cwd()) {
13
+ const outputPath = path.join(outputDir, filename);
12
14
  try {
13
15
  fs.writeFileSync(outputPath, JSON.stringify(document, null, 2));
14
16
  }
@@ -19,7 +21,7 @@ export function writeSbomFile(filename, document, label) {
19
21
  catch { /* best-effort cleanup */ }
20
22
  throw new Error(`Failed to write ${label} to ${outputPath}: ${err instanceof Error ? err.message : String(err)}`, { cause: err });
21
23
  }
22
- return filename;
24
+ return displayOutputPath(outputPath);
23
25
  }
24
26
  /** Filesystem-safe UTC stamp shared by every SBOM filename. */
25
27
  export function sbomTimestamp() {
@@ -0,0 +1,74 @@
1
+ import { serializeFinding } from "./formatters.js";
2
+ import { overrideFindingsToJson } from "./override-findings-json.js";
3
+ import { maintenanceFindingsToJson } from "./maintenance-findings-json.js";
4
+ import { serializeLicenseFindings } from "./license-findings-json.js";
5
+ import { aggregateMultiFolderCompleteness } from "../scan/completeness.js";
6
+ /**
7
+ * Single-folder `--json` payload. HTML `report.json` reuses this so both
8
+ * artifacts share one schema.
9
+ */
10
+ export function buildScanJson(input) {
11
+ const payload = {
12
+ projectPath: input.projectPath,
13
+ mode: input.scanInput.mode,
14
+ source: input.scanInput.source,
15
+ packageCount: input.scanInput.packages.length,
16
+ findingCount: input.findings.length,
17
+ status: (input.completeness.complete ? "ok" : "partial"),
18
+ complete: input.completeness.complete,
19
+ diagnostics: input.completeness.diagnostics,
20
+ suggestedFixCommands: input.suggestedFixCommands,
21
+ notes: [...input.scanInput.notes, ...input.coverage],
22
+ warnings: input.scanInput.warnings,
23
+ skippedDependencies: input.scanInput.skippedDependencies,
24
+ findings: input.findings.map(finding => serializeFinding(finding, input.suggestedFixCommands)),
25
+ };
26
+ const overridePayload = overrideFindingsToJson(input.overrideFindings ?? [], input.overrideSkipped);
27
+ const maintenancePayload = maintenanceFindingsToJson(input.maintenanceFindings ?? []);
28
+ const licensePayload = input.licenseFindings && input.licenseFindings.length > 0
29
+ ? {
30
+ licenseFindings: serializeLicenseFindings(input.licenseFindings),
31
+ ...(input.licenseLimitedToDirectOnly ? { licenseLimitedToDirectOnly: true } : {}),
32
+ }
33
+ : {};
34
+ return { ...payload, ...overridePayload, ...maintenancePayload, ...licensePayload };
35
+ }
36
+ /**
37
+ * Multi-folder `--json` payload. HTML `report.json` reuses this so both
38
+ * artifacts share one schema.
39
+ */
40
+ export function buildMultiFolderScanJson(params) {
41
+ const aggregatedCompleteness = aggregateMultiFolderCompleteness(params.results);
42
+ const findings = params.results.flatMap(r => r.sorted.map(f => ({ ...serializeFinding(f, r.suggestedFixCommands), subfolder: r.subfolder })));
43
+ return {
44
+ multiFolder: true,
45
+ projectPath: params.projectPath,
46
+ folders: params.results.map(r => r.subfolder),
47
+ findingCount: findings.length,
48
+ status: aggregatedCompleteness.complete ? "ok" : "partial",
49
+ complete: aggregatedCompleteness.complete,
50
+ diagnostics: aggregatedCompleteness.diagnostics,
51
+ warnings: params.results.flatMap(r => r.scanInput.warnings),
52
+ findings,
53
+ ...(params.includeOverrides
54
+ ? {
55
+ overrideFindings: params.results.flatMap(r => r.overrideFindings.map(f => ({ ...f, subfolder: r.subfolder }))),
56
+ // CI and the GitHub App read this file, so a skipped rule has to reach it. Tagged
57
+ // per folder the same way findings are, since one folder can skip a rule while
58
+ // another runs it.
59
+ skippedOverrideRules: params.results.flatMap(r => (r.overrideSkipped ?? []).map(sk => ({ ...sk, subfolder: r.subfolder }))),
60
+ }
61
+ : {}),
62
+ ...(params.includeMaintenance
63
+ ? {
64
+ maintenanceFindings: params.results.flatMap(r => r.maintenanceFindings.map(f => ({ ...f, subfolder: r.subfolder }))),
65
+ }
66
+ : {}),
67
+ ...(params.includeLicenses
68
+ ? {
69
+ licenseFindings: params.results.flatMap(r => r.licenseFindings.map(f => ({ ...f, subfolder: r.subfolder }))),
70
+ }
71
+ : {}),
72
+ scannedAt: new Date().toISOString(),
73
+ };
74
+ }
@@ -0,0 +1,41 @@
1
+ // Shared shape for reporting override rules that could not run. The terminal renderer
2
+ // and the HTML report both need the same grouping and the same sentence, and when this
3
+ // lived in both files they had already drifted to two different pluralisations.
4
+ import { pluralize } from "../utils/string.js";
5
+ /** Distinct rules skipped. Not the entry count: one rule can be recorded more than
6
+ * once with different reasons. */
7
+ export function skippedRuleCount(skipped) {
8
+ return new Set(skipped.map((entry) => entry.ruleId)).size;
9
+ }
10
+ /** The sentence both surfaces lead with, kept in one place so they cannot diverge. */
11
+ export function skippedHeadline(ruleCount) {
12
+ return `${ruleCount} override ${pluralize(ruleCount, "rule")} did not run, so this is not a complete override audit:`;
13
+ }
14
+ /**
15
+ * The reason text for a total registry failure. Shared because OA007 and OA010 record it
16
+ * from two different modules, and the sentence plus its pluralisation had already been
17
+ * written out twice, which is the same drift this module exists to stop.
18
+ */
19
+ export function registryFailureReason(count, noun) {
20
+ return `registry lookups failed for all ${count} ${noun} ${pluralize(count, "package")}`;
21
+ }
22
+ /**
23
+ * Rule ids grouped by the reason they were skipped, de-duplicated and sorted.
24
+ *
25
+ * Grouped by reason rather than keyed on specific rule ids, so it covers the lockfile
26
+ * and node_modules skips recorded in context-builder as well as the network-backed ones
27
+ * recorded in audit().
28
+ */
29
+ export function groupSkippedByReason(skipped) {
30
+ const byReason = new Map();
31
+ for (const entry of skipped) {
32
+ const ids = byReason.get(entry.reason) ?? [];
33
+ if (!ids.includes(entry.ruleId))
34
+ ids.push(entry.ruleId);
35
+ byReason.set(entry.reason, ids);
36
+ }
37
+ return [...byReason.entries()].map(([reason, ruleIds]) => ({
38
+ reason,
39
+ ruleIds: [...ruleIds].sort(),
40
+ }));
41
+ }
@@ -286,8 +286,8 @@ export function buildSpdxDocument(allPackages, findings, projectMeta, version, p
286
286
  relationships,
287
287
  };
288
288
  }
289
- export function writeSpdxReport(allPackages, findings, plan, projectMeta, options = {}) {
289
+ export function writeSpdxReport(allPackages, findings, plan, projectMeta, options = {}, outputDir) {
290
290
  const filename = `cve-lite-scan-${sbomTimestamp()}.spdx.json`;
291
291
  const doc = buildSpdxDocument(allPackages, findings, projectMeta, getCliVersion(), plan, options);
292
- return writeSbomFile(filename, doc, "SPDX SBOM");
292
+ return writeSbomFile(filename, doc, "SPDX SBOM", outputDir);
293
293
  }