cve-lite-cli 1.41.4 → 1.42.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 (73) hide show
  1. package/README.md +22 -19
  2. package/dist/advisory/detail-resolution.js +62 -0
  3. package/dist/advisory/local-db.js +90 -15
  4. package/dist/advisory/osv-advisory-source.js +113 -62
  5. package/dist/advisory/osv-sync.js +18 -16
  6. package/dist/advisory/sqlite.js +50 -0
  7. package/dist/audit-log/ndjson-writer.js +6 -3
  8. package/dist/audit-log/open-error.js +22 -0
  9. package/dist/cli/args.js +145 -87
  10. package/dist/cli/flags.js +2 -0
  11. package/dist/cli/help.js +6 -2
  12. package/dist/cli/overrides.js +5 -2
  13. package/dist/cli/validate.js +45 -5
  14. package/dist/constants.js +10 -0
  15. package/dist/index.js +15 -6
  16. package/dist/licenses/license-check.js +17 -4
  17. package/dist/osv/cache.js +7 -13
  18. package/dist/output/cyclonedx.js +57 -18
  19. package/dist/output/finding-display.js +8 -1
  20. package/dist/output/formatters.js +52 -11
  21. package/dist/output/html-reporter.js +40 -8
  22. package/dist/output/override-findings-terminal.js +21 -13
  23. package/dist/output/printers.js +185 -76
  24. package/dist/output/sarif.js +182 -16
  25. package/dist/output/spdx.js +15 -1
  26. package/dist/output/write-outputs.js +29 -20
  27. package/dist/overrides/context-builder.js +1 -7
  28. package/dist/overrides/detectors/oa005-nested-ineffective.js +6 -1
  29. package/dist/overrides/detectors/oa008-materialized.js +33 -10
  30. package/dist/overrides/detectors/oa009-stale-floor.js +2 -2
  31. package/dist/overrides/detectors/oa010-vulnerable-floor.js +19 -13
  32. package/dist/overrides/detectors/phantom-utils.js +2 -10
  33. package/dist/overrides/fixer.js +13 -2
  34. package/dist/overrides/index.js +1 -0
  35. package/dist/overrides/types.js +15 -1
  36. package/dist/parsers/bun-lock.js +6 -0
  37. package/dist/parsers/index.js +177 -40
  38. package/dist/parsers/multi-package.js +4 -0
  39. package/dist/parsers/package-lock.js +6 -2
  40. package/dist/parsers/pnpm-lock.js +4 -7
  41. package/dist/parsers/requirements-txt.js +185 -0
  42. package/dist/parsers/utils.js +11 -6
  43. package/dist/parsers/yarn-lock.js +1 -5
  44. package/dist/remediation/fix-commands.js +60 -36
  45. package/dist/remediation/parent-update-child-note.js +3 -2
  46. package/dist/scan/completeness.js +57 -4
  47. package/dist/scan/multi-folder-scan.js +27 -13
  48. package/dist/scan/single-scan.js +118 -37
  49. package/dist/scanner.js +59 -36
  50. package/dist/types.js +1 -1
  51. package/dist/usage/scanner.js +345 -45
  52. package/dist/utils/array.js +5 -0
  53. package/dist/utils/baseline.js +8 -2
  54. package/dist/utils/chalk.js +1 -3
  55. package/dist/utils/create-pr.js +2 -2
  56. package/dist/utils/debug-bundle.js +37 -22
  57. package/dist/utils/debug-project.js +6 -5
  58. package/dist/utils/debug-redaction.js +1 -1
  59. package/dist/utils/effective-options.js +5 -1
  60. package/dist/utils/finding.js +4 -0
  61. package/dist/utils/fix-runner.js +110 -36
  62. package/dist/utils/import-type-queries.js +5 -1
  63. package/dist/utils/install-command.js +6 -0
  64. package/dist/utils/malicious.js +11 -0
  65. package/dist/utils/package-identity.js +12 -2
  66. package/dist/utils/path-coverage.js +1 -5
  67. package/dist/utils/sanitize.js +59 -0
  68. package/dist/utils/sbom-format.js +17 -8
  69. package/dist/utils/severity.js +61 -7
  70. package/dist/utils/url.js +175 -0
  71. package/dist/utils/version.js +44 -0
  72. package/dist/utils/vuln.js +11 -14
  73. package/package.json +2 -4
package/dist/index.js CHANGED
@@ -5,7 +5,8 @@ import { existsSync } from "node:fs";
5
5
  import { parseArgs } from "./cli/args.js";
6
6
  import { printBanner, printHelp, printOverridesHelp } from "./cli/help.js";
7
7
  import { validateOptions } from "./cli/validate.js";
8
- import { DEFAULT_BATCH_SIZE, DEFAULT_SEARCH_DEPTH } from "./constants.js";
8
+ import { DEFAULT_BATCH_SIZE } from "./constants.js";
9
+ import { resolveSearchDepth } from "./utils/effective-options.js";
9
10
  import { chalk } from "./utils/chalk.js";
10
11
  import { createDebugLogger } from "./output/debug.js";
11
12
  import { getCliVersion } from "./utils/version-info.js";
@@ -17,7 +18,8 @@ import { installSkill } from "./skills/install.js";
17
18
  import { setupCaCert } from "./cli/config.js";
18
19
  import { handleConfigCommand } from "./cli/config-command.js";
19
20
  import { createAuditLog } from "./audit-log/index.js";
20
- import { hasRootLockfile, findNestedLockfiles } from "./parsers/multi-package.js";
21
+ import { formatAuditLogOpenError } from "./audit-log/open-error.js";
22
+ import { isMultiFolderScan } from "./parsers/multi-package.js";
21
23
  import { handleMultiFolderScan } from "./scan/multi-folder-scan.js";
22
24
  import { handleSingleFolderScan } from "./scan/single-scan.js";
23
25
  let parsedArgs = null;
@@ -62,12 +64,20 @@ if (parsedArgs) {
62
64
  process.exit(EXIT_ERROR);
63
65
  }
64
66
  const batchSize = Number(options.batchSize || DEFAULT_BATCH_SIZE);
65
- const searchDepth = Math.max(0, Number(options.searchDepth || DEFAULT_SEARCH_DEPTH));
67
+ const searchDepth = resolveSearchDepth(options);
66
68
  const debugSession = createDebugLogger(!!options.debug);
67
69
  const debugLog = debugSession.log;
68
70
  let scanJsonPath;
69
71
  const scanStartedAt = Date.now();
70
- const auditLogHandle = createAuditLog(options.auditLog ?? process.env.CVE_LITE_AUDIT_LOG);
72
+ const auditLogPath = options.auditLog ?? process.env.CVE_LITE_AUDIT_LOG;
73
+ let auditLogHandle;
74
+ try {
75
+ auditLogHandle = createAuditLog(auditLogPath);
76
+ }
77
+ catch (error) {
78
+ console.error(chalk.red(formatAuditLogOpenError(auditLogPath, options.auditLog !== undefined, error)));
79
+ process.exit(1);
80
+ }
71
81
  async function main() {
72
82
  printBanner(options);
73
83
  debugSession.announcePath();
@@ -126,8 +136,7 @@ if (parsedArgs) {
126
136
  }
127
137
  // Multi-folder mode: if no root lockfile and 2+ nested lockfiles exist,
128
138
  // route to dedicated multi-folder handler instead of single-lockfile scan
129
- const nestedLockfiles = findNestedLockfiles(projectPath, searchDepth);
130
- if (!hasRootLockfile(projectPath) && nestedLockfiles.length >= 2) {
139
+ if (!options.python && isMultiFolderScan(projectPath, searchDepth)) {
131
140
  const exitCode = await handleMultiFolderScan({
132
141
  projectRoot: projectPath,
133
142
  batchSize,
@@ -25,6 +25,13 @@ const COPYLEFT_SPDX = new Set([
25
25
  "LGPL-3.0",
26
26
  "LGPL-3.0-ONLY",
27
27
  "LGPL-3.0-OR-LATER",
28
+ "EUPL-1.1",
29
+ "EUPL-1.2",
30
+ "OSL-3.0",
31
+ "CDDL-1.0",
32
+ "CPL-1.0",
33
+ "EPL-1.0",
34
+ "EPL-2.0",
28
35
  ]);
29
36
  const LICENSE_CHECK_CONCURRENCY = 10;
30
37
  /**
@@ -69,13 +76,14 @@ function lcFinding(ruleId, name, version, license, relationship) {
69
76
  /**
70
77
  * Scans an npm lockfile v2/v3 packages map for copyleft (LC001) and unknown
71
78
  * (LC002) licenses. Reads the license field directly from the lockfile - no
72
- * network calls, works offline.
79
+ * network calls, works offline. With prodOnly, skip entries marked dev just
80
+ * like the npm vulnerability inventory parser.
73
81
  *
74
82
  * The root entry (empty-string key) is always skipped. A package is "direct"
75
83
  * when its bare name appears in the root entry's dependencies,
76
84
  * devDependencies, or optionalDependencies.
77
85
  */
78
- export function detectNpmLicenses(rawPackages) {
86
+ export function detectNpmLicenses(rawPackages, prodOnly = false) {
79
87
  const directNames = new Set();
80
88
  const root = (rawPackages[""] ?? {});
81
89
  for (const section of ["dependencies", "devDependencies", "optionalDependencies"]) {
@@ -88,6 +96,8 @@ export function detectNpmLicenses(rawPackages) {
88
96
  if (!pkgPath || !pkgPath.includes("node_modules/"))
89
97
  continue;
90
98
  const typedMeta = meta;
99
+ if (prodOnly && typedMeta?.["dev"])
100
+ continue;
91
101
  const name = pkgPath.slice(pkgPath.lastIndexOf("node_modules/") + "node_modules/".length);
92
102
  const version = typedMeta?.["version"];
93
103
  if (!name || !version)
@@ -108,7 +118,10 @@ export function detectNpmLicenses(rawPackages) {
108
118
  async function checkPackumentLicense(dep) {
109
119
  try {
110
120
  const packument = await fetchPackument(dep.name);
111
- const license = packument?.license ?? null;
121
+ const rawLicense = packument?.versions?.[dep.version]?.license;
122
+ const license = typeof rawLicense === "string"
123
+ ? rawLicense
124
+ : typeof rawLicense?.type === "string" ? rawLicense.type : null;
112
125
  if (isUnknownLicense(license)) {
113
126
  return lcFinding("LC002", dep.name, dep.version, null, "direct");
114
127
  }
@@ -126,7 +139,7 @@ export async function detectLicenseIssues(opts) {
126
139
  if (isNpm && lockfilePath) {
127
140
  const raw = JSON.parse(readFileSync(lockfilePath, "utf8"));
128
141
  const rawPackages = (raw?.["packages"] ?? {});
129
- return { findings: detectNpmLicenses(rawPackages), limitedToDirectOnly: false };
142
+ return { findings: detectNpmLicenses(rawPackages, opts.prodOnly), limitedToDirectOnly: false };
130
143
  }
131
144
  if (isOffline) {
132
145
  return { findings: [], limitedToDirectOnly: true };
package/dist/osv/cache.js CHANGED
@@ -3,12 +3,12 @@ import path from "node:path";
3
3
  import os from "node:os";
4
4
  import { CACHE_TTL_MS } from "../constants.js";
5
5
  function createEmptyCache() {
6
- return { version: 6, createdAt: new Date().toISOString(), entries: {}, queryEntries: {}, npmVersionEntries: {}, npmAdvisoryEntries: {} };
6
+ return { version: 7, createdAt: new Date().toISOString(), entries: {}, queryEntries: {}, npmVersionEntries: {}, npmAdvisoryEntries: {} };
7
7
  }
8
8
  // v4 stores detail records as { vuln, cachedAt }. v1-v3 stored the OsvVuln (or
9
9
  // null for a known-empty lookup) directly, with no timestamp. Legacy records are
10
10
  // wrapped with an epoch-0 cachedAt so they read as stale and get refreshed on the
11
- // next scan, matching how the queryEntries v2->v3 migration backdates its records.
11
+ // next scan. Pre-pagination query entries are discarded separately below.
12
12
  function wrapLegacyDetailEntries(raw) {
13
13
  const epoch = new Date(0).toISOString();
14
14
  const entries = {};
@@ -61,16 +61,10 @@ export function loadCache(cacheDirOverride, debugLog) {
61
61
  // Detail records: v4 onward already carry { vuln, cachedAt }; v1-v3 stored the record
62
62
  // directly and are wrapped (and backdated) so the TTL applies uniformly.
63
63
  const entries = version >= 4 ? readDetailEntries(rawEntries) : wrapLegacyDetailEntries(rawEntries);
64
- // Query records: v2 stored string[]; v3 onward store { vulnIds, cachedAt }; v1/unknown had none.
64
+ // Before v7, a query entry may contain only the first page. Discard those
65
+ // matches even when fresh, while retaining detail and npm registry caches.
65
66
  const queryEntries = {};
66
- if (version === 2) {
67
- const rawQuery = parsed.queryEntries;
68
- const epoch = new Date(0).toISOString();
69
- for (const [key, vulnIds] of Object.entries(rawQuery ?? {})) {
70
- queryEntries[key] = { vulnIds: Array.isArray(vulnIds) ? vulnIds : [], cachedAt: epoch };
71
- }
72
- }
73
- else if (version >= 3) {
67
+ if (version >= 7) {
74
68
  const rawQuery = parsed.queryEntries;
75
69
  for (const [key, value] of Object.entries(rawQuery ?? {})) {
76
70
  if (value && typeof value === "object" && "vulnIds" in value && "cachedAt" in value) {
@@ -103,7 +97,7 @@ export function loadCache(cacheDirOverride, debugLog) {
103
97
  }
104
98
  }
105
99
  const loaded = {
106
- version: 6,
100
+ version: 7,
107
101
  createdAt: String(parsed.createdAt ?? new Date().toISOString()),
108
102
  entries,
109
103
  queryEntries,
@@ -114,7 +108,7 @@ export function loadCache(cacheDirOverride, debugLog) {
114
108
  path: filePath,
115
109
  queryEntries: Object.keys(loaded.queryEntries).length,
116
110
  detailEntries: Object.keys(loaded.entries).length,
117
- ...(version === 6 ? {} : { migratedFrom: version || "unknown" }),
111
+ ...(version === 7 ? {} : { migratedFrom: version || "unknown" }),
118
112
  });
119
113
  return loaded;
120
114
  }
@@ -1,4 +1,7 @@
1
1
  import { randomUUID } from "node:crypto";
2
+ import { severityOrder } from "../constants.js";
3
+ import { collapseAliasedDuplicates, extractCveAliases } from "../utils/vuln.js";
4
+ import { inferSeverity } from "../osv/severity.js";
2
5
  import { findFixTargetForFinding, findSuggestedCommandForFinding } from "../remediation/fix-commands.js";
3
6
  import { getRecommendedAction } from "./formatters.js";
4
7
  import { getCliVersion } from "../utils/version-info.js";
@@ -6,7 +9,7 @@ import { buildPurl, purlForSbom, sbomComponentRef } from "../utils/purl.js";
6
9
  import { registryPackageName } from "../utils/package-identity.js";
7
10
  import { sbomTimestamp, writeSbomFile } from "./sbom-file.js";
8
11
  export { buildPurl };
9
- export function buildCycloneDxBom(allPackages, findings, projectMeta, version, plan = null) {
12
+ export function buildCycloneDxBom(allPackages, findings, projectMeta, version, plan = null, options = {}) {
10
13
  const components = [];
11
14
  for (const pkg of allPackages) {
12
15
  const purl = purlForSbom(pkg);
@@ -23,30 +26,46 @@ export function buildCycloneDxBom(allPackages, findings, projectMeta, version, p
23
26
  : {}),
24
27
  });
25
28
  }
26
- // Deduplicate vulnerabilities by CVE ID - one entry per CVE with multiple affects
29
+ // Choose identifiers per advisory so an unrelated CVE never hides a record
30
+ // without one. Recommendations still use the package's validated fix target.
27
31
  const vulnMap = new Map();
28
32
  for (const finding of findings) {
29
- const cveIds = finding.cveAliases.length > 0
30
- ? finding.cveAliases
31
- : finding.vulnerabilities.map(v => v.id);
32
33
  const purl = purlForSbom(finding.pkg);
33
34
  if (!purl)
34
35
  continue;
35
- for (const cveId of cveIds) {
36
- const existing = vulnMap.get(cveId);
37
- if (existing) {
38
- existing.affects.push({ ref: sbomComponentRef(finding.pkg, purl) });
39
- }
40
- else {
41
- // severity from first finding wins when the same CVE affects multiple packages
42
- vulnMap.set(cveId, { finding, affects: [{ ref: sbomComponentRef(finding.pkg, purl) }] });
36
+ const ref = sbomComponentRef(finding.pkg, purl);
37
+ for (const advisory of collapseAliasedDuplicates(finding.vulnerabilities)) {
38
+ const advisoryId = typeof advisory.id === "string" ? advisory.id : undefined;
39
+ const cveIds = [...new Set([
40
+ ...(advisoryId?.startsWith("CVE-") ? [advisoryId] : []),
41
+ ...extractCveAliases([advisory]),
42
+ ])];
43
+ const ids = cveIds.length > 0 ? cveIds : advisoryId ? [advisoryId] : [];
44
+ const severity = inferSeverity(advisory);
45
+ const advisoryFinding = {
46
+ ...finding, vulnerabilities: [advisory], cveAliases: cveIds, severity,
47
+ };
48
+ for (const id of ids) {
49
+ const existing = vulnMap.get(id);
50
+ if (existing) {
51
+ if (!existing.affects.some(affect => affect.ref === ref))
52
+ existing.affects.push({ ref });
53
+ // Keep the highest known rating without changing the finding used for remediation.
54
+ if (severity !== "unknown" &&
55
+ (existing.severity === "unknown" || severityOrder[severity] > severityOrder[existing.severity])) {
56
+ existing.severity = severity;
57
+ }
58
+ }
59
+ else {
60
+ vulnMap.set(id, { finding: advisoryFinding, severity, affects: [{ ref }] });
61
+ }
43
62
  }
44
63
  }
45
64
  }
46
65
  const vulnerabilities = [];
47
- for (const [cveId, { finding, affects }] of vulnMap) {
66
+ for (const [cveId, { finding, severity, affects }] of vulnMap) {
48
67
  const runnableFixCommand = plan ? findSuggestedCommandForFinding(plan, finding) : null;
49
- const recommendation = runnableFixCommand ?? getRecommendedAction(finding);
68
+ const recommendation = (runnableFixCommand ?? getRecommendedAction(finding, plan?.packageManager)) ?? undefined;
50
69
  const properties = [];
51
70
  const addProperty = (name, value) => {
52
71
  if (value === null || value === undefined)
@@ -67,12 +86,31 @@ export function buildCycloneDxBom(allPackages, findings, projectMeta, version, p
67
86
  name: "OSV",
68
87
  url: `https://osv.dev/vulnerability/${cveId}`,
69
88
  },
70
- ratings: [{ severity: finding.severity, method: "other" }],
89
+ ratings: [{ severity, method: "other" }],
71
90
  affects,
72
91
  recommendation,
73
92
  ...(properties.length > 0 ? { properties } : {}),
74
93
  });
75
94
  }
95
+ const metadataProperties = [];
96
+ if (options.advisoryMetadata) {
97
+ metadataProperties.push({
98
+ name: "cve-lite:advisory-db:offline",
99
+ value: options.advisoryMetadata.offline ? "true" : "false",
100
+ });
101
+ if (options.advisoryMetadata.syncTimestamp) {
102
+ metadataProperties.push({
103
+ name: "cve-lite:advisory-db:sync-timestamp",
104
+ value: options.advisoryMetadata.syncTimestamp,
105
+ });
106
+ }
107
+ if (options.advisoryMetadata.sourceUrl) {
108
+ metadataProperties.push({
109
+ name: "cve-lite:advisory-db:source-url",
110
+ value: options.advisoryMetadata.sourceUrl,
111
+ });
112
+ }
113
+ }
76
114
  const metadata = {
77
115
  timestamp: new Date().toISOString(),
78
116
  tools: {
@@ -85,6 +123,7 @@ export function buildCycloneDxBom(allPackages, findings, projectMeta, version, p
85
123
  },
86
124
  ],
87
125
  },
126
+ ...(metadataProperties.length > 0 ? { properties: metadataProperties } : {}),
88
127
  };
89
128
  if (projectMeta && projectMeta.name) {
90
129
  const metaComponent = {
@@ -106,8 +145,8 @@ export function buildCycloneDxBom(allPackages, findings, projectMeta, version, p
106
145
  vulnerabilities,
107
146
  };
108
147
  }
109
- export function writeCycloneDxReport(allPackages, findings, plan, projectMeta, outputDir, filename) {
148
+ export function writeCycloneDxReport(allPackages, findings, plan, projectMeta, outputDir, filename, options = {}) {
110
149
  const finalFilename = filename ?? `cve-lite-scan-${sbomTimestamp()}.cdx.json`;
111
- const bom = buildCycloneDxBom(allPackages, findings, projectMeta, getCliVersion(), plan);
150
+ const bom = buildCycloneDxBom(allPackages, findings, projectMeta, getCliVersion(), plan, options);
112
151
  return writeSbomFile(finalFilename, bom, "CycloneDX report", outputDir);
113
152
  }
@@ -10,7 +10,14 @@ export function selectFindingsForCompact(findings, options) {
10
10
  .filter(finding => finding.severity === "critical" || finding.severity === "high")
11
11
  .slice(0, urgentLimit);
12
12
  const unknownDirect = findings.filter(finding => finding.severity === "unknown" && finding.relationship === "direct");
13
- return mergeUniqueFindings(urgent, unknownDirect);
13
+ const selected = mergeUniqueFindings(urgent, unknownDirect);
14
+ if (selected.length > 0) {
15
+ return selected;
16
+ }
17
+ // Fallback: when no critical/high or direct unknown findings exist, show up to urgentLimit
18
+ // top findings so compact output does not announce "Vulnerabilities found" and show 0 findings.
19
+ const fallback = findings.filter(finding => finding.severity !== "unknown" || finding.relationship === "direct");
20
+ return fallback.slice(0, urgentLimit);
14
21
  }
15
22
  function mergeUniqueFindings(primary, extra) {
16
23
  const result = [...primary];
@@ -1,8 +1,10 @@
1
1
  import { findFixTargetForFinding, findSuggestedCommandForFinding, formatParentUpgradeBlockedReason } from "../remediation/fix-commands.js";
2
2
  import { chalk } from "../utils/chalk.js";
3
+ import { FLAG_ALLOW_EMPTY } from "../cli/flags.js";
3
4
  import { severityOrder, MAL_PRIVATE_REGISTRY_MESSAGE, MAL_GIT_SOURCE_PINNED_MESSAGE, MAL_GIT_SOURCE_FLOATING_MESSAGE, } from "../constants.js";
4
5
  import { loadCache } from "../osv/cache.js";
5
6
  import { inferSeverity } from "../osv/severity.js";
7
+ import { isPep440Ecosystem } from "../utils/version.js";
6
8
  import { getPrimaryParent, getRootDependencies, isUnconfirmedFix } from "../utils/finding.js";
7
9
  import { calculatePathCoverage, formatDependencyPath } from "../utils/path-coverage.js";
8
10
  import { pluralize, isOutputStdout } from "../utils/string.js";
@@ -10,8 +12,12 @@ import { npmLsCommand, UNSAFE_LS_INSTRUCTION } from "../utils/shell-quote.js";
10
12
  import { hasMaliciousAdvisory } from "../utils/vuln.js";
11
13
  import { computePrioritySignal } from "../utils/priority-signal.js";
12
14
  import { computeContextualSignals } from "../utils/contextual-signals.js";
15
+ import { sanitizeOutputString } from "../utils/sanitize.js";
16
+ export { sanitizeOutputString };
13
17
  export function formatPackageName(pkg) {
14
- return pkg.registryName && pkg.registryName !== pkg.name ? `${pkg.name} (${pkg.registryName})` : pkg.name;
18
+ const name = sanitizeOutputString(pkg.name);
19
+ const regName = pkg.registryName ? sanitizeOutputString(pkg.registryName) : undefined;
20
+ return regName && regName !== name ? `${name} (${regName})` : name;
15
21
  }
16
22
  export function formatRelationshipLabel(value) {
17
23
  if (value.startsWith("direct"))
@@ -30,9 +36,10 @@ export function formatRootDependencySummary(finding) {
30
36
  const roots = getRootDependencies(finding);
31
37
  if (roots.length === 0)
32
38
  return "-";
39
+ const first = sanitizeOutputString(roots[0]);
33
40
  if (roots.length === 1)
34
- return roots[0];
35
- return `${roots[0]} +${roots.length - 1}`;
41
+ return first;
42
+ return `${first} +${roots.length - 1}`;
36
43
  }
37
44
  export function formatAdvisorySourceLine(sourceLabel) {
38
45
  const match = sourceLabel.match(/^(.*) \((.*)\)$/);
@@ -62,7 +69,13 @@ function transitiveRiskMessage(packageName, complete) {
62
69
  function unreadablePyPiBoundaryAction(packageName) {
63
70
  return `The advisory data for ${packageName} has an unreadable PyPI boundary, so the fix is inconclusive.`;
64
71
  }
65
- export function getRecommendedAction(finding) {
72
+ /**
73
+ * Human-readable fix guidance for one finding. `packageManager` is the one the
74
+ * scanned lockfile implies (the fix-command plan's), so the within-range refresh
75
+ * hint names `pnpm install`, `yarn install` or `bun install` instead of always
76
+ * `npm install`. Without a plan (no lockfile) it falls back to npm.
77
+ */
78
+ export function getRecommendedAction(finding, packageManager = "npm") {
66
79
  if (isMaliciousAdvisory(finding)) {
67
80
  if (finding.maliciousUnverifiable) {
68
81
  return MAL_PRIVATE_REGISTRY_MESSAGE;
@@ -79,6 +92,12 @@ export function getRecommendedAction(finding) {
79
92
  // may itself be vulnerable), and the validated target is what the fix
80
93
  // command actually uses.
81
94
  const directTarget = finding.validatedFirstFixedVersion ?? finding.firstFixedVersion;
95
+ if (isPep440Ecosystem(finding.pkg.ecosystem)) {
96
+ if (directTarget) {
97
+ return null;
98
+ }
99
+ return `No known fix exists for ${finding.pkg.name}. Consider replacing it with an actively maintained alternative.`;
100
+ }
82
101
  if (isUnconfirmedFix(finding)) {
83
102
  return `Verify a safe version of ${finding.pkg.name} before upgrading.`;
84
103
  }
@@ -92,7 +111,7 @@ export function getRecommendedAction(finding) {
92
111
  return formatParentUpgradeBlockedReason(finding);
93
112
  }
94
113
  if (finding.recommendedNpmTransitiveRemediation?.kind === "update-parent-within-range") {
95
- return `${finding.recommendedNpmTransitiveRemediation.package} already permits ${finding.pkg.name}@${finding.recommendedNpmTransitiveRemediation.targetChildVersion} - run \`npm install\` to pick it up.`;
114
+ return `${finding.recommendedNpmTransitiveRemediation.package} already permits ${finding.pkg.name}@${finding.recommendedNpmTransitiveRemediation.targetChildVersion} - run \`${packageManager} install\` to pick it up.`;
96
115
  }
97
116
  if (finding.recommendedNpmTransitiveRemediation?.kind === "upgrade-parent-to-version" &&
98
117
  finding.recommendedNpmTransitiveRemediation.targetVersion) {
@@ -205,6 +224,12 @@ export function summarizeNextAction(finding) {
205
224
  if (finding.advisoryBoundaryUnreadable) {
206
225
  return unreadablePyPiBoundaryAction(finding.pkg.name);
207
226
  }
227
+ if (isPep440Ecosystem(finding.pkg.ecosystem)) {
228
+ if (directTarget) {
229
+ return "";
230
+ }
231
+ return `No known fix exists for ${finding.pkg.name}. Consider replacing it with an actively maintained alternative.`;
232
+ }
208
233
  if (isUnconfirmedFix(finding)) {
209
234
  return `Verify a safe version of ${finding.pkg.name} before upgrading.`;
210
235
  }
@@ -239,7 +264,7 @@ export function summarizeNextAction(finding) {
239
264
  return `Inspect the parent dependency chain for ${finding.pkg.name} and choose the safest available upgrade.`;
240
265
  }
241
266
  export function formatFixVersionPublishDate(iso) {
242
- return iso.slice(0, 10);
267
+ return sanitizeOutputString(iso).slice(0, 10);
243
268
  }
244
269
  export function formatCooldownWarning(warning) {
245
270
  return `Published ${formatFixVersionPublishDate(warning.publishedAt)}, newer than your configured ${warning.windowLabel} release cooldown (${warning.sourceFile}); your package manager would hold this version - validate before overriding.`;
@@ -248,11 +273,15 @@ export function formatFixCommandPublishSuffix(targets) {
248
273
  const dated = targets.filter(target => target.kind === "direct" && target.fixVersionPublishedAt);
249
274
  if (dated.length === 0)
250
275
  return "";
276
+ let suffix;
251
277
  if (dated.length === 1) {
252
- return ` (published ${formatFixVersionPublishDate(dated[0].fixVersionPublishedAt)})`;
278
+ suffix = ` (published ${formatFixVersionPublishDate(dated[0].fixVersionPublishedAt)})`;
253
279
  }
254
- const parts = dated.map(target => `${target.package} published ${formatFixVersionPublishDate(target.fixVersionPublishedAt)}`);
255
- return ` (${parts.join(", ")})`;
280
+ else {
281
+ const parts = dated.map(target => `${target.package} published ${formatFixVersionPublishDate(target.fixVersionPublishedAt)}`);
282
+ suffix = ` (${parts.join(", ")})`;
283
+ }
284
+ return sanitizeOutputString(suffix);
256
285
  }
257
286
  export function formatFixCommandWithPublishDates(command, targets) {
258
287
  const suffix = formatFixCommandPublishSuffix(targets);
@@ -273,7 +302,7 @@ export function serializeFinding(finding, plan) {
273
302
  cooldownWarning: plan ? (findFixTargetForFinding(plan, finding)?.cooldownWarning ?? null) : null,
274
303
  validatedTargetScannedVersions: finding.validatedTargetScannedVersions ?? null,
275
304
  validatedTargetKnownVulnerableVersions: finding.validatedTargetKnownVulnerableVersions ?? null,
276
- recommendedAction: getRecommendedAction(finding),
305
+ recommendedAction: getRecommendedAction(finding, plan?.packageManager),
277
306
  runnableFixCommand: plan ? findSuggestedCommandForFinding(plan, finding) : null,
278
307
  primaryParent: getPrimaryParent(finding),
279
308
  rootDependencies: getRootDependencies(finding),
@@ -324,7 +353,19 @@ export function logInfo(message, options) {
324
353
  export function logWarn(message, options) {
325
354
  if (options?.json || isOutputStdout(options?.output))
326
355
  return;
327
- console.log(chalk.yellow(message));
356
+ console.log(chalk.yellow(sanitizeOutputString(message)));
357
+ }
358
+ /** Explains an empty scan, with the opt-out when it fails; JSON modes get it on stderr, since logWarn stays quiet there. */
359
+ export function logEmptyScan(message, exitCode, options) {
360
+ const text = exitCode === 0
361
+ ? message
362
+ : `${message} Exiting with code ${exitCode}; pass ${FLAG_ALLOW_EMPTY} to treat an empty scan as a pass.`;
363
+ if (options.json || isOutputStdout(options.output)) {
364
+ if (exitCode !== 0)
365
+ console.error(text);
366
+ return;
367
+ }
368
+ logWarn(text, options);
328
369
  }
329
370
  export function sortFindingsForOutput(findings) {
330
371
  return [...findings].sort((a, b) => {
@@ -4,7 +4,7 @@ import { randomUUID } from "node:crypto";
4
4
  import { spawn } from "node:child_process";
5
5
  import { serializeFinding, summarizeNextAction, summarizeRisk, formatCooldownWarning } from "./formatters.js";
6
6
  import { loadLogoDataUri } from "./logos.js";
7
- import { isBreakingUpgrade } from "../utils/version.js";
7
+ import { isBreakingUpgrade, isPep440Ecosystem } from "../utils/version.js";
8
8
  import { pluralize } from "../utils/string.js";
9
9
  import { npmLsCommand, UNSAFE_LS_INSTRUCTION } from "../utils/shell-quote.js";
10
10
  import { MAL_GIT_SOURCE_PINNED_DISPLAY, MAL_GIT_SOURCE_FLOATING_DISPLAY, severityOrder } from "../constants.js";
@@ -20,6 +20,7 @@ import { isUnconfirmedFix } from "../utils/finding.js";
20
20
  export function serializeHtmlFinding(finding, plan) {
21
21
  return {
22
22
  ...serializeFinding(finding, plan),
23
+ ecosystem: finding.pkg.ecosystem,
23
24
  riskSummary: summarizeRisk(finding),
24
25
  nextAction: summarizeNextAction(finding),
25
26
  };
@@ -596,13 +597,22 @@ function renderPriorityColumnHtml(priority) {
596
597
  const cssClass = priority.replace(/_/g, "-");
597
598
  return `<span class="priority-badge ${escapeHtml(cssClass)}">${escapeHtml(label)}</span>`;
598
599
  }
599
- export function renderDependencyPathChain(path, fallbackPkg) {
600
+ function packageRegistryUrl(name, ecosystem) {
601
+ return isPep440Ecosystem(ecosystem)
602
+ ? `https://pypi.org/project/${encodeURIComponent(name)}/`
603
+ : `https://www.npmjs.com/package/${encodeURIComponent(name)}`;
604
+ }
605
+ export function renderDependencyPathChain(path, fallbackPkg, ecosystem) {
600
606
  if (path.length === 0) {
601
607
  return fallbackPkg ? `<span class="dep-node">${escapeHtml(fallbackPkg)}</span>` : "";
602
608
  }
603
609
  return path.map((node, i, arr) => {
604
610
  const isLast = i === arr.length - 1;
605
- return `<span class="dep-step"><a href="https://www.npmjs.com/package/${encodeURIComponent(node)}" target="_blank" rel="noopener noreferrer" class="dep-node${isLast ? " vulnerable" : ""}">${escapeHtml(node)}</a>${isLast ? "" : '<span class="dep-arrow">→</span>'}</span>`;
611
+ if (node === "project") {
612
+ return `<span class="dep-step"><span class="dep-node${isLast ? " vulnerable" : ""}">${escapeHtml(node)}</span>${isLast ? "" : '<span class="dep-arrow">→</span>'}</span>`;
613
+ }
614
+ const url = packageRegistryUrl(node, ecosystem);
615
+ return `<span class="dep-step"><a href="${url}" target="_blank" rel="noopener noreferrer" class="dep-node${isLast ? " vulnerable" : ""}">${escapeHtml(node)}</a>${isLast ? "" : '<span class="dep-arrow">→</span>'}</span>`;
606
616
  }).join("");
607
617
  }
608
618
  export const MAX_PATHS_PER_PACKAGE = 5;
@@ -613,7 +623,7 @@ export function renderDependencyPathsHtml(finding) {
613
623
  : pluralize(Math.max(1, count), "Dependency path", "Known dependency paths");
614
624
  const paths = count > 0 ? finding.dependencyPaths : [[]];
615
625
  const html = paths
616
- .map(path => `<div class="dep-path">${renderDependencyPathChain(path, finding.package)}</div>`)
626
+ .map(path => `<div class="dep-path">${renderDependencyPathChain(path, finding.package, finding.ecosystem)}</div>`)
617
627
  .join("\n ");
618
628
  return { heading, html };
619
629
  }
@@ -624,7 +634,8 @@ export function renderFindingRow(finding, idx, skippedKeys) {
624
634
  const isMalicious = hasMaliciousAdvisory(finding.vulnerabilities);
625
635
  const isSkipped = skippedKeys?.has(`${finding.package}@${finding.version}`);
626
636
  const unconfirmed = isUnconfirmedFix(finding);
627
- const fixVersion = finding.validatedFirstFixedVersion ?? finding.firstFixedVersion;
637
+ const isPython = isPep440Ecosystem(finding.ecosystem);
638
+ const fixVersion = isPython ? null : (finding.validatedFirstFixedVersion ?? finding.firstFixedVersion);
628
639
  const fixHtml = (isSkipped || unconfirmed) && fixVersion
629
640
  ? `<span class="fix-hint hint-only" title="Advisory hint only: a safe fix has not been confirmed.">${escapeHtml(fixVersion)} ⊘</span>`
630
641
  : fixVersion
@@ -639,7 +650,9 @@ export function renderFindingRow(finding, idx, skippedKeys) {
639
650
  ? `<span class="fix-hint none" title="Malicious code advisory: remove this package">⚠ Malicious</span>`
640
651
  : finding.advisoryBoundaryUnreadable
641
652
  ? `<span class="fix-hint none" title="The advisory data has an unreadable PyPI boundary, so the fix is inconclusive.">unreadable advisory data</span>`
642
- : `<span class="fix-hint none" title="No known fix: consider replacing this package">⚠ No fix</span>`;
653
+ : isPython && (finding.validatedFirstFixedVersion ?? finding.firstFixedVersion)
654
+ ? `<span class="root-dep-none">-</span>`
655
+ : `<span class="fix-hint none" title="No known fix: consider replacing this package">⚠ No fix</span>`;
643
656
  const depPaths = renderDependencyPathsHtml(finding);
644
657
  const description = finding.vulnerabilities[0]?.summary ?? "";
645
658
  const runnable = finding.runnableFixCommand ?? null;
@@ -673,9 +686,10 @@ export function renderFindingRow(finding, idx, skippedKeys) {
673
686
  const publishedHtml = finding.fixVersionPublishedAt
674
687
  ? `<span class="published-date">${escapeHtml(finding.fixVersionPublishedAt.slice(0, 10))}</span>`
675
688
  : `<span class="root-dep-none">-</span>`;
689
+ const pkgUrl = packageRegistryUrl(finding.package, finding.ecosystem);
676
690
  return `<tr id="row-${idx}" data-skipped="${isSkipped ? '1' : '0'}" onclick="toggleRow(${idx})">
677
691
  <td><span class="expand-icon" id="icon-${idx}">▶</span></td>
678
- <td><div class="pkg-name"><a href="https://www.npmjs.com/package/${encodeURIComponent(finding.package)}" target="_blank" rel="noopener noreferrer">${escapeHtml(finding.package)}</a></div><div class="pkg-version">${escapeHtml(finding.version)}</div></td>
692
+ <td><div class="pkg-name"><a href="${pkgUrl}" target="_blank" rel="noopener noreferrer">${escapeHtml(finding.package)}</a></div><div class="pkg-version">${escapeHtml(finding.version)}</div></td>
679
693
  <td><span class="sev-badge ${escapeHtml(finding.severity)}">${escapeHtml(finding.severity)}</span></td>
680
694
  <td>${renderRelBadge(finding)}</td>
681
695
  <td>${rootDepsHtml}</td>
@@ -744,8 +758,10 @@ function renderTransitiveContextCol(finding) {
744
758
  </div>`;
745
759
  }
746
760
  export function renderCompletenessBanner(completeness) {
747
- if (completeness == null || completeness.complete)
761
+ if (completeness == null)
748
762
  return "";
763
+ if (completeness.complete)
764
+ return renderFreshnessNotice(completeness.diagnostics);
749
765
  const { hasDetectionGap, hasRemediationGap } = getCompletenessImpact(completeness);
750
766
  let bannerText;
751
767
  if (hasDetectionGap && hasRemediationGap) {
@@ -770,6 +786,22 @@ export function renderCompletenessBanner(completeness) {
770
786
  </div>
771
787
  </div>`;
772
788
  }
789
+ // A complete scan can still have used cached advisory details. That is not a
790
+ // gap, so it gets its own note rather than the incomplete-scan banner.
791
+ function renderFreshnessNotice(diagnostics) {
792
+ const freshness = diagnostics.filter(d => d.impact === "freshness");
793
+ if (freshness.length === 0)
794
+ return "";
795
+ const rows = freshness.map(d => `<li class="diag-item ${escapeHtml(d.severity)} ${escapeHtml(d.impact)}">${escapeHtml(d.message)}</li>`).join("\n");
796
+ return `<div class="completeness-banner">
797
+ <div class="completeness-banner-icon">ⓘ</div>
798
+ <div class="completeness-banner-body">
799
+ <strong>Some advisory details came from the local cache</strong>
800
+ <p>The scan is complete, but these lookups used earlier cached copies of the advisory details:</p>
801
+ <ul>${rows}</ul>
802
+ </div>
803
+ </div>`;
804
+ }
773
805
  function renderNotices(notes, warnings) {
774
806
  if (notes.length === 0 && warnings.length === 0)
775
807
  return "";