@ktpartners/dgs-platform 3.0.4 → 3.3.0

package/deliver-great-systems/bin/lib/package-adapters.cjs

@@ -0,0 +1,530 @@
+/**
+ * package-adapters.cjs -- Per-tool JSON->canonical-finding translation
+ *
+ * Six pure adapter functions -- one per scanner in the cascade -- translate
+ * pre-parsed tool JSON into the canonical finding shape consumed by the
+ * Phase 150 orchestrator (which assigns ids at merge time) and the Phase 152
+ * severity normaliser (which translates raw strings to canonical tiers).
+ *
+ * Adapters DO NOT:
+ *   - assign finding ids (orchestrator's job -- avoids collisions across tools)
+ *   - normalise severity (Phase 152 PKG-23)
+ *   - map licences to severity (Phase 153 PKG-34)
+ *   - throw (malformed entries are skipped silently)
+ *
+ * Adapters DO:
+ *   - stamp tool provenance (every finding carries `tool`)
+ *   - preserve raw severity strings
+ *   - extract CVSS score/vector when the tool emits them
+ *   - set dependency_chain + chain_available on every finding
+ *   - pick the lowest fix version when tool emits multiple
+ *   - honour ctx.manifest_path when populated, else normalise tool-emitted paths
+ *
+ * Exports (named): adapterSnyk, adapterOsv, adapterNpmAudit, adapterPipAudit,
+ *                  adapterGovulncheck, adapterBundlerAudit
+ *
+ * Covers roadmap requirements PKG-11, PKG-12, PKG-13, PKG-14, adapter half of PKG-31.
+ */
+'use strict';
+const path = require('path');
+
+// ─── Shared helpers ──────────────────────────────────────────────────────────
+
+/**
+ * Normalise a tool-emitted path into repo-relative POSIX form. Strips absolute
+ * prefixes matching ctx.cwd, converts backslashes, and trims leading "./".
+ * Returns null for empty/null input.
+ */
+function _normaliseManifestPath(raw, ctxCwd) {
+  if (!raw) return null;
+  let p = String(raw);
+  if (ctxCwd && path.isAbsolute(p) && p.startsWith(ctxCwd)) {
+    p = p.slice(ctxCwd.length);
+    if (p.startsWith(path.sep) || p.startsWith('/') || p.startsWith('\\')) {
+      p = p.slice(1);
+    }
+  }
+  p = p.split(path.sep).join('/').replace(/\\/g, '/');
+  if (p.startsWith('./')) p = p.slice(2);
+  return p;
+}
+
+/** Apply ctx.manifest_path when populated, else normalise tool-emitted path. */
+function _pickManifestPath(ctx, fromToolJson) {
+  if (ctx && ctx.manifest_path) return ctx.manifest_path;
+  return _normaliseManifestPath(fromToolJson, ctx && ctx.cwd);
+}
+
+/** Infer direct vs transitive from chain length. Null chain -> null. */
+function _inferDirectOrTransitive(chain) {
+  if (!chain || !Array.isArray(chain)) return null;
+  return chain.length <= 2 ? 'direct' : 'transitive';
+}
+
+/** Semver-naive compare: split on dots, compare numeric segments. */
+function _compareVersions(a, b) {
+  const aParts = String(a).split('.').map(s => {
+    const n = parseInt(s, 10);
+    return Number.isNaN(n) ? s : n;
+  });
+  const bParts = String(b).split('.').map(s => {
+    const n = parseInt(s, 10);
+    return Number.isNaN(n) ? s : n;
+  });
+  const len = Math.max(aParts.length, bParts.length);
+  for (let i = 0; i < len; i++) {
+    const ai = aParts[i];
+    const bi = bParts[i];
+    if (ai === undefined) return -1;
+    if (bi === undefined) return 1;
+    if (typeof ai === 'number' && typeof bi === 'number') {
+      if (ai !== bi) return ai - bi;
+    } else {
+      const as = String(ai);
+      const bs = String(bi);
+      if (as !== bs) return as < bs ? -1 : 1;
+    }
+  }
+  return 0;
+}
+
+/** Pick the lowest fix version from an array. Null/empty -> null. */
+function _pickLowestFix(versionArray) {
+  if (!Array.isArray(versionArray) || versionArray.length === 0) return null;
+  const sorted = versionArray.slice().sort(_compareVersions);
+  return sorted[0];
+}
+
+/**
+ * Parse a Snyk from-entry like "pkg@1.2.3" or "@babel/core@7.0.0" into
+ * { name, version }. Falls back to { name: raw, version: '' } on failure.
+ */
+function _parseSnykFromEntry(raw) {
+  if (typeof raw !== 'string') return { name: String(raw || ''), version: '' };
+  const atIdx = raw.lastIndexOf('@');
+  if (atIdx <= 0) return { name: raw, version: '' };
+  return { name: raw.slice(0, atIdx), version: raw.slice(atIdx + 1) };
+}
+
+/**
+ * Map a lockfile path to its adjacent manifest (e.g., package-lock.json ->
+ * package.json). Returns the original path if lockfile not recognised.
+ */
+function _manifestPathFromLockfile(lockPath) {
+  if (!lockPath) return lockPath;
+  const lockToManifest = {
+    'package-lock.json': 'package.json',
+    'yarn.lock': 'package.json',
+    'pnpm-lock.yaml': 'package.json',
+    'poetry.lock': 'pyproject.toml',
+    'Pipfile.lock': 'Pipfile',
+    'Gemfile.lock': 'Gemfile',
+    'go.sum': 'go.mod',
+  };
+  const base = lockPath.split('/').pop();
+  if (lockToManifest[base]) {
+    const dir = lockPath.slice(0, Math.max(0, lockPath.length - base.length));
+    return dir + lockToManifest[base];
+  }
+  return lockPath;
+}
+
+/** Extract fix_versions from OSV affected[].ranges[].events[].fixed. */
+function _extractOsvFixVersions(affected) {
+  const out = [];
+  if (!Array.isArray(affected)) return out;
+  for (const a of affected) {
+    if (!a || !Array.isArray(a.ranges)) continue;
+    for (const r of a.ranges) {
+      if (!r || !Array.isArray(r.events)) continue;
+      for (const e of r.events) {
+        if (e && e.fixed) out.push(e.fixed);
+      }
+    }
+  }
+  return out;
+}
+
+/** Find a CVE id in an aliases[] array (pattern CVE-YYYY-NNN). */
+function _findCveInAliases(aliases) {
+  if (!Array.isArray(aliases)) return null;
+  for (const a of aliases) {
+    if (typeof a === 'string' && /^CVE-\d{4}-\d+$/.test(a)) return a;
+  }
+  return null;
+}
+
+/** Extract CVE id from a URL containing a CVE-YYYY-NNN pattern. */
+function _findCveInUrl(url) {
+  if (typeof url !== 'string') return null;
+  const m = url.match(/CVE-\d{4}-\d+/);
+  return m ? m[0] : null;
+}
+
+// ─── adapterSnyk ─────────────────────────────────────────────────────────────
+
+/**
+ * Translate Snyk JSON output into canonical findings. Handles both single-
+ * project output (parsed.vulnerabilities + parsed.targetFile) and all-projects
+ * output (parsed.projects[] with per-project vulnerabilities/targetFile).
+ *
+ * @param {object} parsed
+ * @param {{ repo: string, ecosystem: string, cwd: string, manifest_path?: string|null }} ctx
+ * @returns {Array<object>}
+ */
+function adapterSnyk(parsed, ctx) {
+  if (!parsed || typeof parsed !== 'object') return [];
+  const out = [];
+
+  function emitOne(v, targetFile) {
+    if (!v || !v.packageName) return;
+    const from = Array.isArray(v.from) ? v.from : null;
+    const chain = from && from.length > 0 ? from.map(_parseSnykFromEntry) : null;
+    const fixVersion = Array.isArray(v.fixedIn) ? _pickLowestFix(v.fixedIn) : (v.fixedIn || null);
+    let remediation = null;
+    if (Array.isArray(v.upgradePath) && v.upgradePath.length > 0) {
+      const last = v.upgradePath[v.upgradePath.length - 1];
+      if (last && last !== false) remediation = `upgrade ${last}`;
+    }
+    if (!remediation && fixVersion) {
+      remediation = `upgrade to ${v.packageName}@${fixVersion}`;
+    }
+    out.push({
+      tool: 'snyk',
+      ecosystem: ctx.ecosystem,
+      repo: ctx.repo,
+      manifest_path: _pickManifestPath(ctx, targetFile),
+      package_name: v.packageName,
+      installed_version: v.version || '',
+      vulnerability: {
+        cve: (v.identifiers && Array.isArray(v.identifiers.CVE) && v.identifiers.CVE[0]) || null,
+        title: v.title || '',
+        description: v.description || null,
+        reference_url: v.url || null,
+      },
+      severity: v.severity == null ? null : v.severity,
+      cvss_score: typeof v.cvssScore === 'number' ? v.cvssScore : null,
+      cvss_vector: v.CVSSv3 || null,
+      direct_or_transitive: from && from.length ? (from.length <= 2 ? 'direct' : 'transitive') : null,
+      dependency_chain: chain,
+      chain_available: chain !== null,
+      fix_version: fixVersion,
+      remediation,
+      licence: v.license != null ? v.license : null,
+      id: null,
+    });
+  }
+
+  if (Array.isArray(parsed.projects)) {
+    for (const proj of parsed.projects) {
+      const tf = proj && proj.targetFile;
+      const vulns = Array.isArray(proj && proj.vulnerabilities) ? proj.vulnerabilities : [];
+      for (const v of vulns) emitOne(v, tf);
+    }
+  } else if (Array.isArray(parsed.vulnerabilities)) {
+    for (const v of parsed.vulnerabilities) emitOne(v, parsed.targetFile);
+  }
+
+  // Phase 153 PKG-32: surface .snyk-applied suppression count via ctx callback.
+  if (ctx && typeof ctx.recordSuppressions === 'function') {
+    let count = 0;
+    try {
+      const filtered = parsed && parsed.filtered;
+      if (filtered && Array.isArray(filtered.ignore)) count = filtered.ignore.length;
+    } catch { count = 0; }
+    ctx.recordSuppressions(count);
+  }
+
+  // Phase 153 PKG-30/34: surface licence roster via ctx callback.
+  if (ctx && typeof ctx.recordLicenceRoster === 'function') {
+    const roster = [];
+    try {
+      const deps = parsed && parsed.dependencyPackages;
+      if (deps && typeof deps === 'object' && !Array.isArray(deps)) {
+        for (const key of Object.keys(deps)) {
+          const dep = deps[key];
+          if (!dep || typeof dep !== 'object') continue;
+          let licenceValue = dep.license === undefined ? null : dep.license;
+          if (Array.isArray(licenceValue)) licenceValue = licenceValue.join(' OR ');
+          roster.push({
+            package_name: dep.name || key.split('@')[0] || 'unknown',
+            installed_version: dep.version || (key.split('@')[1] || 'unknown'),
+            licence: licenceValue,
+          });
+        }
+      }
+    } catch { /* roster stays empty */ }
+    ctx.recordLicenceRoster(roster);
+  }
+
+  return out;
+}
+
+// ─── adapterOsv ──────────────────────────────────────────────────────────────
+
+/**
+ * Translate OSV-Scanner JSON output into canonical findings.
+ *
+ * @param {object} parsed
+ * @param {{ repo, ecosystem, cwd, manifest_path? }} ctx
+ */
+function adapterOsv(parsed, ctx) {
+  if (!parsed || !Array.isArray(parsed.results) || parsed.results.length === 0) return [];
+  const out = [];
+  for (const result of parsed.results) {
+    if (!result) continue;
+    const sourcePath = result.source && result.source.path;
+    const manifestCandidate = _manifestPathFromLockfile(sourcePath);
+    const pkgs = Array.isArray(result.packages) ? result.packages : [];
+    for (const pkgEntry of pkgs) {
+      if (!pkgEntry || !pkgEntry.package) continue;
+      const pkgName = pkgEntry.package.name;
+      const pkgVersion = pkgEntry.package.version || '';
+      if (!pkgName) continue;
+      const vulns = Array.isArray(pkgEntry.vulnerabilities) ? pkgEntry.vulnerabilities : [];
+      for (const vuln of vulns) {
+        if (!vuln || !vuln.id) continue;
+        const cvssVector = (Array.isArray(vuln.severity) && vuln.severity[0] && vuln.severity[0].score) || null;
+        const fixVersion = _pickLowestFix(_extractOsvFixVersions(vuln.affected));
+        out.push({
+          tool: 'osv',
+          ecosystem: ctx.ecosystem,
+          repo: ctx.repo,
+          manifest_path: _pickManifestPath(ctx, manifestCandidate),
+          package_name: pkgName,
+          installed_version: pkgVersion,
+          vulnerability: {
+            cve: _findCveInAliases(vuln.aliases),
+            title: vuln.summary || '',
+            description: vuln.details || null,
+            reference_url: (Array.isArray(vuln.references) && vuln.references[0] && vuln.references[0].url) || null,
+          },
+          severity: (vuln.database_specific && vuln.database_specific.severity) || null,
+          cvss_score: null,
+          cvss_vector: cvssVector,
+          direct_or_transitive: null,
+          dependency_chain: null,
+          chain_available: false,
+          fix_version: fixVersion,
+          remediation: fixVersion ? `upgrade to ${pkgName}@${fixVersion}` : null,
+          id: null,
+        });
+      }
+    }
+  }
+  return out;
+}
+
+// ─── adapterNpmAudit ─────────────────────────────────────────────────────────
+
+/**
+ * Translate npm audit v10+ JSON output into canonical findings.
+ *
+ * @param {object} parsed
+ * @param {{ repo, ecosystem, cwd, manifest_path? }} ctx
+ */
+function adapterNpmAudit(parsed, ctx) {
+  if (!parsed || !parsed.vulnerabilities || typeof parsed.vulnerabilities !== 'object') return [];
+  const out = [];
+  for (const entry of Object.values(parsed.vulnerabilities)) {
+    if (!entry || !entry.name) continue;
+    const viaArr = Array.isArray(entry.via) ? entry.via : [];
+    const via0 = viaArr.length > 0 && typeof viaArr[0] === 'object' ? viaArr[0] : null;
+    const fixVersion = (entry.fixAvailable && entry.fixAvailable.version) || null;
+    const direct = entry.isDirect === true ? 'direct'
+      : entry.isDirect === false ? 'transitive' : null;
+    out.push({
+      tool: 'npm-audit',
+      ecosystem: ctx.ecosystem,
+      repo: ctx.repo,
+      manifest_path: _pickManifestPath(ctx, null),
+      package_name: entry.name,
+      installed_version: '',
+      vulnerability: {
+        cve: via0 ? _findCveInUrl(via0.url) : null,
+        title: (via0 && via0.title) || entry.name,
+        description: null,
+        reference_url: (via0 && via0.url) || null,
+      },
+      severity: entry.severity == null ? null : entry.severity,
+      cvss_score: via0 && via0.cvss && typeof via0.cvss.score === 'number' ? via0.cvss.score : null,
+      cvss_vector: via0 && via0.cvss && via0.cvss.vectorString ? via0.cvss.vectorString : null,
+      direct_or_transitive: direct,
+      dependency_chain: null,
+      chain_available: false,
+      fix_version: fixVersion,
+      remediation: fixVersion ? `npm install ${entry.name}@${fixVersion} --save` : null,
+      id: null,
+    });
+  }
+  return out;
+}
+
+// ─── adapterPipAudit ─────────────────────────────────────────────────────────
+
+/**
+ * Translate pip-audit v2.10+ JSON output into canonical findings.
+ *
+ * @param {object} parsed
+ * @param {{ repo, ecosystem, cwd, manifest_path? }} ctx
+ */
+function adapterPipAudit(parsed, ctx) {
+  if (!parsed || !Array.isArray(parsed.dependencies)) return [];
+  const out = [];
+  for (const dep of parsed.dependencies) {
+    if (!dep || !dep.name) continue;
+    const vulns = Array.isArray(dep.vulns) ? dep.vulns : [];
+    for (const vuln of vulns) {
+      if (!vuln || !vuln.id) continue;
+      const fixVersion = _pickLowestFix(vuln.fix_versions);
+      const descFirstLine = typeof vuln.description === 'string'
+        ? vuln.description.split('\n')[0]
+        : null;
+      out.push({
+        tool: 'pip-audit',
+        ecosystem: ctx.ecosystem,
+        repo: ctx.repo,
+        manifest_path: _pickManifestPath(ctx, null),
+        package_name: dep.name,
+        installed_version: dep.version || '',
+        vulnerability: {
+          cve: _findCveInAliases(vuln.aliases),
+          title: descFirstLine || vuln.id,
+          description: vuln.description || null,
+          reference_url: null,
+        },
+        severity: null,
+        cvss_score: null,
+        cvss_vector: null,
+        direct_or_transitive: null,
+        dependency_chain: null,
+        chain_available: false,
+        fix_version: fixVersion,
+        remediation: fixVersion ? `pip install ${dep.name}==${fixVersion}` : null,
+        id: null,
+      });
+    }
+  }
+  return out;
+}
+
+// ─── adapterGovulncheck ──────────────────────────────────────────────────────
+
+/**
+ * Translate govulncheck NDJSON output into canonical findings.
+ *
+ * Input is the raw NDJSON string (one JSON object per line). The adapter
+ * parses each line, indexes OSV entries by id, and emits one finding per
+ * `finding` message.
+ *
+ * @param {string} rawString
+ * @param {{ repo, ecosystem, cwd, manifest_path? }} ctx
+ */
+function adapterGovulncheck(rawString, ctx) {
+  if (typeof rawString !== 'string' || rawString.length === 0) return [];
+  const lines = rawString.split('\n');
+  const osvMap = Object.create(null);
+  const findings = [];
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    let parsedLine;
+    try {
+      parsedLine = JSON.parse(trimmed);
+    } catch {
+      continue;
+    }
+    const msg = parsedLine && parsedLine.message;
+    if (!msg || !msg.type) continue;
+    if (msg.type === 'osv' && msg.osv && msg.osv.id) {
+      osvMap[msg.osv.id] = msg.osv;
+    } else if (msg.type === 'finding' && msg.finding && msg.finding.osv) {
+      findings.push(msg.finding);
+    }
+  }
+  const ecosystem = (ctx && ctx.ecosystem) || 'go';
+  const out = [];
+  for (const finding of findings) {
+    const osv = osvMap[finding.osv] || null;
+    const trace = Array.isArray(finding.trace) ? finding.trace : null;
+    const chain = trace ? trace.map(t => ({ name: (t && t.module) || '', version: (t && t.version) || '' })) : null;
+    const pkgName = trace && trace.length > 0 ? (trace[0].module || null) : null;
+    const pkgVersion = trace && trace.length > 0 ? (trace[0].version || '') : '';
+    const fixVersion = finding.fixed_version || null;
+    out.push({
+      tool: 'govulncheck',
+      ecosystem,
+      repo: ctx && ctx.repo,
+      manifest_path: _pickManifestPath(ctx || {}, null),
+      package_name: pkgName,
+      installed_version: pkgVersion,
+      vulnerability: {
+        cve: osv ? _findCveInAliases(osv.aliases) : null,
+        title: (osv && osv.summary) || finding.osv,
+        description: (osv && osv.details) || null,
+        reference_url: (osv && Array.isArray(osv.references) && osv.references[0] && osv.references[0].url) || null,
+      },
+      severity: null,
+      cvss_score: null,
+      cvss_vector: null,
+      direct_or_transitive: _inferDirectOrTransitive(chain),
+      dependency_chain: chain,
+      chain_available: chain !== null,
+      fix_version: fixVersion,
+      remediation: fixVersion && pkgName ? `go get ${pkgName}@${fixVersion}` : null,
+      id: null,
+    });
+  }
+  return out;
+}
+
+// ─── adapterBundlerAudit ─────────────────────────────────────────────────────
+
+/**
+ * Translate bundler-audit --format json output into canonical findings.
+ *
+ * @param {object} parsed
+ * @param {{ repo, ecosystem, cwd, manifest_path? }} ctx
+ */
+function adapterBundlerAudit(parsed, ctx) {
+  if (!parsed || !Array.isArray(parsed.results)) return [];
+  const out = [];
+  const ecosystem = (ctx && ctx.ecosystem) || 'ruby';
+  for (const r of parsed.results) {
+    if (!r || !r.gem || !r.gem.name) continue;
+    const advisory = r.advisory || {};
+    out.push({
+      tool: 'bundler-audit',
+      ecosystem,
+      repo: ctx && ctx.repo,
+      manifest_path: _pickManifestPath(ctx || {}, null),
+      package_name: r.gem.name,
+      installed_version: r.gem.version || '',
+      vulnerability: {
+        cve: advisory.id || null,
+        title: advisory.title || '',
+        description: advisory.description || null,
+        reference_url: advisory.url || null,
+      },
+      severity: advisory.criticality == null ? null : advisory.criticality,
+      cvss_score: typeof advisory.cvss_v3 === 'number' ? advisory.cvss_v3 : null,
+      cvss_vector: null,
+      direct_or_transitive: null,
+      dependency_chain: null,
+      chain_available: false,
+      fix_version: null,
+      remediation: advisory.solution || null,
+      id: null,
+    });
+  }
+  return out;
+}
+
+module.exports = {
+  adapterSnyk,
+  adapterOsv,
+  adapterNpmAudit,
+  adapterPipAudit,
+  adapterGovulncheck,
+  adapterBundlerAudit,
+};