cra-audit 0.1.0

package/src/commands/sbom.js

@@ -0,0 +1,100 @@
+'use strict';
+
+const path = require('node:path');
+const { findProjectRoot, readJson, writeJson, exists } = require('../utils/fs');
+const { logger, color } = require('../utils/logger');
+const { generateSbom } = require('../core/sbom-generator');
+const { validateSbom } = require('../core/sbom-validator');
+
+/**
+ * `cra-audit sbom <generate|check>` and the `--sbom` shortcut.
+ *
+ * - generate: builds a CycloneDX/SPDX SBOM and prints it or writes it to disk.
+ * - check:    generates (or reads) an SBOM and validates the minimum elements
+ *             required by BSI TR-03183 §6.
+ */
+function sbomCommand(subcommand, flags) {
+  const projectRoot = findProjectRoot(flags.cwd || process.cwd());
+  if (!projectRoot) {
+    logger.error('No se encontró ningún package.json. Ejecuta el comando dentro de un proyecto npm.');
+    return 1;
+  }
+
+  const action = subcommand || 'generate';
+  const format = flags.format || 'cyclonedx';
+
+  if (action === 'check') {
+    return sbomCheck(projectRoot, format, flags);
+  }
+  if (action === 'generate') {
+    return sbomGenerate(projectRoot, format, flags);
+  }
+
+  logger.error(`Subcomando de SBOM desconocido: "${action}". Usa "generate" o "check".`);
+  return 1;
+}
+
+function sbomGenerate(projectRoot, format, flags) {
+  const result = generateSbom(projectRoot, { format });
+  if (!result.ok) {
+    logger.error(result.error);
+    return 1;
+  }
+
+  if (flags.output) {
+    const outPath = path.isAbsolute(flags.output) ? flags.output : path.join(projectRoot, flags.output);
+    writeJson(outPath, result.document);
+    logger.success(`SBOM (${result.format}) con ${result.componentCount} componentes escrito en: ${outPath}`);
+  } else {
+    process.stdout.write(JSON.stringify(result.document, null, 2) + '\n');
+  }
+  return 0;
+}
+
+function sbomCheck(projectRoot, format, flags) {
+  let document;
+
+  // If an SBOM file is provided, validate it directly; otherwise generate one.
+  if (flags.input) {
+    const inPath = path.isAbsolute(flags.input) ? flags.input : path.join(projectRoot, flags.input);
+    if (!exists(inPath)) {
+      logger.error(`No se encontró el SBOM indicado: ${flags.input}`);
+      return 1;
+    }
+    document = readJson(inPath);
+  } else {
+    const result = generateSbom(projectRoot, { format });
+    if (!result.ok) {
+      logger.error(result.error);
+      return 1;
+    }
+    document = result.document;
+  }
+
+  const validation = validateSbom(document);
+  if (!validation.ok) {
+    logger.error(validation.error);
+    return 1;
+  }
+
+  if (flags.json) {
+    process.stdout.write(JSON.stringify(validation, null, 2) + '\n');
+    return validation.valid ? 0 : 1;
+  }
+
+  logger.heading('Validación de SBOM · BSI TR-03183 §6 (elementos mínimos)');
+  logger.detail(`Formato detectado: ${validation.format} · Componentes: ${validation.stats.total}`);
+  for (const check of validation.checks) {
+    const mark = check.passed ? color.green('✔') : color.red('✖');
+    logger.log(`  ${mark} ${check.label}`);
+  }
+  logger.log('');
+  if (validation.valid) {
+    logger.success(color.bold('SBOM VÁLIDO — cumple los elementos mínimos exigidos por el CRA.'));
+    return 0;
+  }
+  logger.error(color.bold(`SBOM INVÁLIDO — ${validation.failedChecks.length} requisito(s) sin cumplir.`));
+  return 1;
+}
+
+module.exports = { sbomCommand };

package/src/commands/visualize.js

@@ -0,0 +1,188 @@
+'use strict';
+
+const path = require('node:path');
+const fs = require('node:fs');
+const { spawn } = require('node:child_process');
+const { findProjectRoot } = require('../utils/fs');
+const { logger, color } = require('../utils/logger');
+const { parseLockfile } = require('../core/lockfile-parser');
+const { scanVulnerabilities, SEVERITY_ORDER } = require('../core/vuln-scanner');
+const { checkLicenses } = require('../core/license-checker');
+const { enrichComponents } = require('../core/enrich');
+const { loadPolicy } = require('../core/policy');
+const { buildHtml } = require('../reporters/html');
+
+/**
+ * `cra-audit visualize` / `--visualize`
+ *
+ * Builds a single, self-contained HTML report that visualises the SBOM,
+ * licenses, versions, known vulnerabilities and maintenance signals
+ * (last publish/commit, maintainers, contributors, stars) per dependency.
+ *
+ * @param {object} flags
+ * @returns {Promise<number>} exit code
+ */
+async function visualizeCommand(flags) {
+  const projectRoot = findProjectRoot(flags.cwd || process.cwd());
+  if (!projectRoot) {
+    logger.error('No se encontró ningún package.json. Ejecuta el comando dentro de un proyecto npm.');
+    return 1;
+  }
+
+  const parsed = parseLockfile(projectRoot);
+  if (!parsed.ok) {
+    logger.error(parsed.error);
+    return 1;
+  }
+
+  let policy = {};
+  try {
+    policy = loadPolicy(projectRoot, flags.config).policy;
+  } catch {
+    policy = {};
+  }
+
+  logger.info(`Analizando ${parsed.components.length} componentes de ${parsed.root.name}@${parsed.root.version}…`);
+
+  // Vulnerabilities + licenses run locally (no network).
+  const vulns = scanVulnerabilities(projectRoot, { production: policy.productionOnly });
+  const licenses = checkLicenses(projectRoot, policy.licenses || {});
+
+  // Maintenance enrichment over the network (opt-out with --offline).
+  const network = !flags.offline;
+  const github = Boolean(flags.github);
+  if (network) {
+    logger.info(
+      `Consultando metadatos de mantenimiento (npm${github ? ' + GitHub' : ''})…` +
+      (github && !process.env.GITHUB_TOKEN ? color.gray(' (sin GITHUB_TOKEN: límite de 60 req/h)') : '')
+    );
+  } else {
+    logger.info('Modo offline: se omiten metadatos de mantenimiento.');
+  }
+
+  let lastPct = -1;
+  const enrichment = await enrichComponents(parsed.components, {
+    network,
+    github,
+    onProgress: (done, total) => {
+      const pct = Math.floor((done / total) * 100);
+      if (pct !== lastPct && pct % 20 === 0) {
+        logger.detail(`metadatos npm: ${pct}%`);
+        lastPct = pct;
+      }
+    },
+  });
+
+  const model = buildModel(parsed, vulns, licenses, enrichment);
+  const html = buildHtml(model);
+
+  const outPath = resolveOutputPath(projectRoot, flags.output);
+  fs.writeFileSync(outPath, html, 'utf8');
+  logger.success(`Informe visual escrito en: ${outPath}`);
+
+  if (!flags.noOpen) {
+    openInBrowser(outPath);
+    logger.detail('Abriendo en el navegador…');
+  } else {
+    logger.detail(`Ábrelo en tu navegador: file://${outPath.replace(/\\/g, '/')}`);
+  }
+
+  return 0;
+}
+
+/** Merges all data sources into the view model consumed by the HTML reporter. */
+function buildModel(parsed, vulns, licenses, enrichment) {
+  const vulnByName = new Map();
+  if (vulns.ok) {
+    for (const v of vulns.vulnerabilities) vulnByName.set(v.name, v);
+  }
+  const licByKey = new Map();
+  if (licenses.ok) {
+    for (const l of licenses.components) licByKey.set(`${l.name}@${l.version}`, l);
+  }
+
+  const components = parsed.components.map((c) => {
+    const key = `${c.name}@${c.version}`;
+    const vuln = vulnByName.get(c.name) || null;
+    const lic = licByKey.get(key) || null;
+    const enr = enrichment.get(key) || {};
+
+    return {
+      name: c.name,
+      version: c.version,
+      license: (lic && lic.license) || c.license || null,
+      licenseStatus: lic ? lic.status : (c.license ? 'ok' : 'missing'),
+      severity: vuln ? vuln.severity : 'none',
+      fixAvailable: vuln ? Boolean(vuln.fixAvailable) : false,
+      latest: enr.latest || null,
+      outdated: Boolean(enr.outdated),
+      lastPublish: enr.lastPublish || null,
+      lastCommit: enr.lastCommit || null,
+      maintainers: enr.maintainers == null ? null : enr.maintainers,
+      contributors: enr.contributors == null ? null : enr.contributors,
+      stars: enr.stars == null ? null : enr.stars,
+      deprecated: Boolean(enr.deprecated),
+      archived: Boolean(enr.archived),
+      repoUrl: enr.repoUrl || null,
+      maintenanceScore: enr.maintenanceScore == null ? null : enr.maintenanceScore,
+      maintenanceLabel: enr.maintenanceLabel || 'unknown',
+      hasHash: Boolean(c.hashValue),
+      purl: c.purl || null,
+    };
+  });
+
+  const summary = {
+    total: components.length,
+    vulnerable: components.filter((c) => c.severity !== 'none').length,
+    critical: components.filter((c) => c.severity === 'critical').length,
+    high: components.filter((c) => c.severity === 'high').length,
+    licenseIssues: components.filter((c) => !c.license || c.licenseStatus === 'denied' || c.licenseStatus === 'not-allowed').length,
+    outdated: components.filter((c) => c.outdated).length,
+    atRisk: components.filter((c) => c.maintenanceLabel === 'at-risk').length,
+  };
+
+  return {
+    project: parsed.root,
+    generatedAt: new Date().toISOString().replace('T', ' ').slice(0, 19) + ' UTC',
+    summary,
+    components: components.sort(byRisk),
+  };
+}
+
+function byRisk(a, b) {
+  const r = (SEVERITY_ORDER.indexOf(b.severity) - SEVERITY_ORDER.indexOf(a.severity));
+  if (r !== 0) return r;
+  return a.name.localeCompare(b.name);
+}
+
+function resolveOutputPath(projectRoot, output) {
+  if (output) {
+    return path.isAbsolute(output) ? output : path.join(projectRoot, output);
+  }
+  return path.join(projectRoot, 'cra-audit-report.html');
+}
+
+/** Opens a file with the OS default handler, best-effort. */
+function openInBrowser(filePath) {
+  try {
+    let cmd;
+    let args;
+    if (process.platform === 'win32') {
+      cmd = 'cmd';
+      args = ['/c', 'start', '', filePath];
+    } else if (process.platform === 'darwin') {
+      cmd = 'open';
+      args = [filePath];
+    } else {
+      cmd = 'xdg-open';
+      args = [filePath];
+    }
+    const child = spawn(cmd, args, { stdio: 'ignore', detached: true });
+    child.on('error', () => {});
+    child.unref();
+  } catch {
+    // Ignore: the path was already printed for manual opening.
+  }
+}
+
+module.exports = { visualizeCommand };

package/src/core/auditor.js

@@ -0,0 +1,128 @@
+'use strict';
+
+const { scanVulnerabilities, SEVERITY_ORDER } = require('./vuln-scanner');
+const { generateSbom } = require('./sbom-generator');
+const { validateSbom } = require('./sbom-validator');
+const { checkLicenses } = require('./license-checker');
+
+/**
+ * @typedef {object} AuditResult
+ * @property {object} project
+ * @property {string|null} policySource
+ * @property {object} sections
+ * @property {{ passed: boolean, reasons: Array<{label:string, passed:boolean}> }} gate
+ */
+
+/**
+ * Runs the full CRA audit: vulnerabilities + SBOM + licenses, then evaluates
+ * the result against the configured security policy.
+ *
+ * @param {string} projectRoot
+ * @param {object} policy
+ * @param {string|null} policySource
+ * @param {{ only?: 'vulnerabilities'|'sbom'|'licenses' }} [options]
+ * @returns {AuditResult}
+ */
+function runAudit(projectRoot, policy, policySource, options = {}) {
+  const { only } = options;
+  const sections = {};
+  const reasons = [];
+
+  // --- 1. Vulnerabilities -------------------------------------------------
+  if (!only || only === 'vulnerabilities') {
+    const vulns = scanVulnerabilities(projectRoot, { production: policy.productionOnly });
+    sections.vulnerabilities = vulns;
+
+    if (!vulns.ok) {
+      reasons.push({ label: `No se pudieron analizar vulnerabilidades: ${vulns.error}`, passed: false });
+    } else {
+      const blocking = countBlocking(vulns, policy);
+      reasons.push({
+        label: blocking === 0
+          ? `Sin vulnerabilidades de severidad >= ${policy.failOn}`
+          : `${blocking} vulnerabilidad(es) de severidad >= ${policy.failOn}`,
+        passed: blocking === 0,
+      });
+    }
+  }
+
+  // --- 2. SBOM ------------------------------------------------------------
+  if (!only || only === 'sbom') {
+    const sbom = generateSbom(projectRoot, { format: policy.sbomFormat });
+    if (sbom.ok) {
+      sbom.validation = validateSbom(sbom.document);
+    }
+    sections.sbom = sbom;
+
+    if (policy.requireSbom) {
+      if (!sbom.ok) {
+        reasons.push({ label: `No se pudo generar el SBOM: ${sbom.error}`, passed: false });
+      } else {
+        reasons.push({
+          label: sbom.validation.valid
+            ? 'SBOM válido según los elementos mínimos de TR-03183'
+            : 'SBOM incompleto respecto a TR-03183',
+          passed: sbom.validation.valid,
+        });
+      }
+    }
+  }
+
+  // --- 3. Licenses --------------------------------------------------------
+  if (!only || only === 'licenses') {
+    const licenses = checkLicenses(projectRoot, policy.licenses);
+    sections.licenses = licenses;
+
+    if (!licenses.ok) {
+      reasons.push({ label: `No se pudieron analizar licencias: ${licenses.error}`, passed: false });
+    } else {
+      const s = licenses.summary;
+      const missingFails = policy.licenses.failOnMissing && s.missing.length > 0;
+      const licensesPassed = s.denied.length === 0 && s.notAllowed.length === 0 && !missingFails;
+      reasons.push({
+        label: licensesPassed
+          ? 'Licencias documentadas y conformes con la política'
+          : 'Problemas de licencias detectados (prohibidas, no permitidas o sin documentar)',
+        passed: licensesPassed,
+      });
+    }
+  }
+
+  return {
+    project: getProject(projectRoot, sections),
+    policySource,
+    generatedAt: new Date().toISOString(),
+    sections,
+    gate: { passed: reasons.every((r) => r.passed), reasons },
+  };
+}
+
+function countBlocking(vulns, policy) {
+  const threshold = SEVERITY_ORDER.indexOf(policy.failOn);
+  if (threshold === -1) return 0;
+  const allowlist = new Set((policy.vulnerabilities && policy.vulnerabilities.allowlist) || []);
+
+  let count = 0;
+  for (const vuln of vulns.vulnerabilities) {
+    if (SEVERITY_ORDER.indexOf(vuln.severity) < threshold) continue;
+    const isAllowlisted = vuln.sources.some(
+      (src) => src.url && [...allowlist].some((id) => src.url.includes(id))
+    ) || allowlist.has(vuln.name);
+    if (!isAllowlisted) count++;
+  }
+  return count;
+}
+
+function getProject(projectRoot, sections) {
+  // Derive project identity from any section that parsed the lockfile/root.
+  if (sections.sbom && sections.sbom.ok && sections.sbom.document) {
+    const comp = sections.sbom.document.metadata && sections.sbom.document.metadata.component;
+    if (comp) return { name: comp.name, version: comp.version };
+  }
+  const path = require('node:path');
+  const { readJson } = require('../utils/fs');
+  const pkg = readJson(path.join(projectRoot, 'package.json')) || {};
+  return { name: pkg.name || path.basename(projectRoot), version: pkg.version || '0.0.0' };
+}
+
+module.exports = { runAudit };

package/src/core/enrich.js

@@ -0,0 +1,220 @@
+'use strict';
+
+const { fetchJson, mapLimit } = require('../utils/http');
+
+const NPM_REGISTRY = 'https://registry.npmjs.org';
+const GITHUB_API = 'https://api.github.com';
+const DAY = 24 * 60 * 60 * 1000;
+
+/**
+ * Enriches lockfile components with maintenance signals so the visual report
+ * can show how well each third-party dependency is maintained:
+ *   - latest published version (and whether the installed one is outdated)
+ *   - last publish date
+ *   - number of maintainers
+ *   - repository URL
+ *   - deprecation status
+ *   - (optional) GitHub last commit date, contributors and stars
+ *
+ * Network failures degrade gracefully: missing data is simply left null.
+ *
+ * @param {Array<object>} components Normalized components from the lockfile.
+ * @param {{
+ *   network?: boolean,
+ *   github?: boolean,
+ *   concurrency?: number,
+ *   timeout?: number,
+ *   token?: string|null,
+ *   onProgress?: (done: number, total: number) => void,
+ * }} [options]
+ * @returns {Promise<Map<string, object>>} keyed by `name@version`.
+ */
+async function enrichComponents(components, options = {}) {
+  const {
+    network = true,
+    github = false,
+    concurrency = 8,
+    timeout = 8000,
+    token = process.env.GITHUB_TOKEN || null,
+    onProgress,
+  } = options;
+
+  const result = new Map();
+  if (!network) return result;
+
+  // Deduplicate by package name to avoid redundant registry calls.
+  const uniqueNames = [...new Set(components.map((c) => c.name))];
+  let done = 0;
+
+  const npmData = await mapLimit(uniqueNames, async (name) => {
+    const meta = await fetchNpmMeta(name, timeout);
+    done++;
+    if (onProgress) onProgress(done, uniqueNames.length);
+    return [name, meta];
+  }, concurrency);
+
+  const npmByName = new Map(npmData);
+
+  // Optional GitHub enrichment, deduplicated by repository.
+  const ghByRepo = new Map();
+  if (github) {
+    const repos = new Set();
+    for (const meta of npmByName.values()) {
+      if (meta && meta.repo) repos.add(`${meta.repo.owner}/${meta.repo.name}`);
+    }
+    const ghData = await mapLimit([...repos], async (slug) => {
+      const [owner, name] = slug.split('/');
+      const info = await fetchGithubRepo(owner, name, timeout, token);
+      return [slug, info];
+    }, Math.min(concurrency, 4));
+    for (const [slug, info] of ghData) ghByRepo.set(slug, info);
+  }
+
+  for (const comp of components) {
+    const npm = npmByName.get(comp.name) || null;
+    let gh = null;
+    if (npm && npm.repo) {
+      gh = ghByRepo.get(`${npm.repo.owner}/${npm.repo.name}`) || null;
+    }
+    result.set(`${comp.name}@${comp.version}`, buildSignals(comp, npm, gh));
+  }
+
+  return result;
+}
+
+async function fetchNpmMeta(name, timeout) {
+  const encoded = name.replace('/', '%2f');
+  const res = await fetchJson(`${NPM_REGISTRY}/${encoded}`, { timeout });
+  if (!res || !res.ok || !res.json) return null;
+
+  const doc = res.json;
+  const latest = doc['dist-tags'] && doc['dist-tags'].latest;
+  const time = doc.time || {};
+  const lastPublish = time.modified || (latest && time[latest]) || null;
+  const maintainers = Array.isArray(doc.maintainers) ? doc.maintainers.length : null;
+  const repo = parseRepoUrl(doc.repository);
+  const latestVersionDoc = (doc.versions && latest && doc.versions[latest]) || {};
+  const deprecated = Boolean(latestVersionDoc.deprecated || doc.deprecated);
+
+  return {
+    latest: latest || null,
+    lastPublish,
+    maintainers,
+    repo,
+    deprecated,
+    homepage: doc.homepage || null,
+  };
+}
+
+async function fetchGithubRepo(owner, name, timeout, token) {
+  const headers = { 'User-Agent': 'cra-audit', Accept: 'application/vnd.github+json' };
+  if (token) headers.Authorization = `Bearer ${token}`;
+
+  const repoRes = await fetchJson(`${GITHUB_API}/repos/${owner}/${name}`, { timeout, headers });
+  if (!repoRes || !repoRes.ok || !repoRes.json) return null;
+
+  const repo = repoRes.json;
+  let contributors = null;
+  // Contributor count is read from the Link header of a 1-per-page request.
+  const contribRes = await fetchJson(
+    `${GITHUB_API}/repos/${owner}/${name}/contributors?per_page=1&anon=1`,
+    { timeout, headers }
+  );
+  if (contribRes && contribRes.ok) {
+    contributors = contributorsFromLink(contribRes.headers.get('link'));
+    if (contributors === null && Array.isArray(contribRes.json)) {
+      contributors = contribRes.json.length;
+    }
+  }
+
+  return {
+    lastCommit: repo.pushed_at || null,
+    stars: typeof repo.stargazers_count === 'number' ? repo.stargazers_count : null,
+    openIssues: typeof repo.open_issues_count === 'number' ? repo.open_issues_count : null,
+    archived: Boolean(repo.archived),
+    contributors,
+    url: repo.html_url || null,
+  };
+}
+
+/** Parses the `rel="last"` page number out of a GitHub Link header. */
+function contributorsFromLink(link) {
+  if (!link) return null;
+  const match = link.match(/[?&]page=(\d+)>;\s*rel="last"/);
+  return match ? Number(match[1]) : null;
+}
+
+/** Extracts { owner, name } from a package.json repository field. */
+function parseRepoUrl(repository) {
+  if (!repository) return null;
+  const url = typeof repository === 'string' ? repository : repository.url;
+  if (!url || typeof url !== 'string') return null;
+
+  const match = url.match(/github\.com[/:]([^/]+)\/([^/.#?]+)/i);
+  if (!match) return null;
+  return { owner: match[1], name: match[2].replace(/\.git$/, '') };
+}
+
+/**
+ * Computes a coarse maintenance label/score from the gathered signals.
+ * Score 0-100; label: well-maintained | moderate | at-risk | unknown.
+ */
+function buildSignals(comp, npm, gh) {
+  const signals = {
+    name: comp.name,
+    version: comp.version,
+    license: comp.license || null,
+    latest: npm ? npm.latest : null,
+    outdated: Boolean(npm && npm.latest && comp.version && npm.latest !== comp.version),
+    lastPublish: npm ? npm.lastPublish : null,
+    maintainers: npm ? npm.maintainers : null,
+    deprecated: npm ? npm.deprecated : false,
+    repoUrl: npm && npm.repo ? `https://github.com/${npm.repo.owner}/${npm.repo.name}` : (gh && gh.url) || null,
+    lastCommit: gh ? gh.lastCommit : null,
+    contributors: gh ? gh.contributors : null,
+    stars: gh ? gh.stars : null,
+    archived: gh ? gh.archived : false,
+  };
+
+  const { score, label } = scoreMaintenance(signals);
+  signals.maintenanceScore = score;
+  signals.maintenanceLabel = label;
+  return signals;
+}
+
+function scoreMaintenance(s) {
+  // No data available at all.
+  if (!s.lastPublish && !s.lastCommit && s.maintainers === null) {
+    return { score: null, label: 'unknown' };
+  }
+
+  let score = 50;
+  const recencyDate = s.lastCommit || s.lastPublish;
+  if (recencyDate) {
+    const ageDays = (Date.now() - new Date(recencyDate).getTime()) / DAY;
+    if (ageDays <= 180) score += 30;
+    else if (ageDays <= 365) score += 15;
+    else if (ageDays <= 730) score -= 5;
+    else score -= 25;
+  }
+
+  if (s.maintainers !== null) {
+    if (s.maintainers >= 3) score += 10;
+    else if (s.maintainers === 1) score -= 5;
+  }
+  if (s.contributors !== null) {
+    if (s.contributors >= 20) score += 10;
+    else if (s.contributors >= 5) score += 5;
+    else if (s.contributors <= 1) score -= 5;
+  }
+  if (s.deprecated) score -= 40;
+  if (s.archived) score -= 30;
+
+  score = Math.max(0, Math.min(100, Math.round(score)));
+  let label = 'moderate';
+  if (s.deprecated || s.archived || score < 40) label = 'at-risk';
+  else if (score >= 70) label = 'well-maintained';
+  return { score, label };
+}
+
+module.exports = { enrichComponents };