cra-audit 0.1.0

package/src/core/license-checker.js

@@ -0,0 +1,102 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { readJson } = require('../utils/fs');
+const { parseLockfile } = require('./lockfile-parser');
+
+/**
+ * Resolves and evaluates the license of every third-party component.
+ * CRA / TR-03183 require every component's license to be documented.
+ *
+ * @param {string} projectRoot
+ * @param {{ allow?: string[], deny?: string[] }} [policy]
+ */
+function checkLicenses(projectRoot, policy = {}) {
+  const parsed = parseLockfile(projectRoot);
+  if (!parsed.ok) {
+    return { ok: false, error: parsed.error, components: [], summary: emptySummary() };
+  }
+
+  const allow = normalizeList(policy.allow);
+  const deny = normalizeList(policy.deny);
+
+  const components = parsed.components.map((c) => {
+    const license = c.license || readLicenseFromDisk(projectRoot, c.path, c.name);
+    const normalized = license ? String(license) : null;
+    const status = classify(normalized, allow, deny);
+    return {
+      name: c.name,
+      version: c.version,
+      license: normalized,
+      status, // 'ok' | 'missing' | 'denied' | 'not-allowed'
+    };
+  });
+
+  const summary = {
+    total: components.length,
+    documented: components.filter((c) => c.license).length,
+    missing: components.filter((c) => c.status === 'missing'),
+    denied: components.filter((c) => c.status === 'denied'),
+    notAllowed: components.filter((c) => c.status === 'not-allowed'),
+  };
+
+  return { ok: true, components, summary };
+}
+
+/** Reads the `license` field from an installed package's package.json. */
+function readLicenseFromDisk(projectRoot, pkgPath, name) {
+  const candidates = [];
+  if (pkgPath) candidates.push(path.join(projectRoot, pkgPath, 'package.json'));
+  candidates.push(path.join(projectRoot, 'node_modules', name, 'package.json'));
+
+  for (const candidate of candidates) {
+    try {
+      if (!fs.existsSync(candidate)) continue;
+      const pkg = readJson(candidate);
+      if (!pkg) continue;
+      if (typeof pkg.license === 'string') return pkg.license;
+      if (pkg.license && pkg.license.type) return pkg.license.type;
+      if (Array.isArray(pkg.licenses) && pkg.licenses.length) {
+        return pkg.licenses.map((l) => (typeof l === 'string' ? l : l.type)).filter(Boolean).join(' OR ');
+      }
+    } catch {
+      // Ignore unreadable package and continue.
+    }
+  }
+  return null;
+}
+
+function classify(license, allow, deny) {
+  if (!license || /^(unknown|unlicensed|see license)/i.test(license)) {
+    return 'missing';
+  }
+  const ids = extractLicenseIds(license);
+  if (deny.length && ids.some((id) => deny.includes(id))) {
+    return 'denied';
+  }
+  if (allow.length && !ids.every((id) => allow.includes(id))) {
+    return 'not-allowed';
+  }
+  return 'ok';
+}
+
+/** Splits an SPDX expression into individual license identifiers (lowercased). */
+function extractLicenseIds(expression) {
+  return expression
+    .replace(/[()]/g, ' ')
+    .split(/\s+(?:AND|OR|WITH)\s+/i)
+    .map((s) => s.trim().toLowerCase())
+    .filter(Boolean);
+}
+
+function normalizeList(list) {
+  if (!Array.isArray(list)) return [];
+  return list.map((s) => String(s).trim().toLowerCase()).filter(Boolean);
+}
+
+function emptySummary() {
+  return { total: 0, documented: 0, missing: [], denied: [], notAllowed: [] };
+}
+
+module.exports = { checkLicenses };

package/src/core/lockfile-parser.js

@@ -0,0 +1,198 @@
+'use strict';
+
+const path = require('node:path');
+const { readJson, exists } = require('../utils/fs');
+
+/**
+ * Parses an npm lockfile (package-lock.json v2/v3 or npm-shrinkwrap.json)
+ * into a normalized list of components. CRA / TR-03183 require traceability
+ * of every direct and transitive dependency, including integrity hashes.
+ *
+ * @param {string} projectRoot
+ * @returns {{
+ *   ok: boolean,
+ *   lockfileName: string|null,
+ *   lockfileVersion: number|null,
+ *   root: { name: string, version: string },
+ *   components: Array<object>,
+ *   error?: string
+ * }}
+ */
+function parseLockfile(projectRoot) {
+  const candidates = ['package-lock.json', 'npm-shrinkwrap.json'];
+  let lockPath = null;
+  let lockfileName = null;
+
+  for (const candidate of candidates) {
+    const full = path.join(projectRoot, candidate);
+    if (exists(full)) {
+      lockPath = full;
+      lockfileName = candidate;
+      break;
+    }
+  }
+
+  const pkgPath = path.join(projectRoot, 'package.json');
+  const rootPkg = readJson(pkgPath) || {};
+  const root = {
+    name: rootPkg.name || path.basename(projectRoot),
+    version: rootPkg.version || '0.0.0',
+  };
+
+  if (!lockPath) {
+    return {
+      ok: false,
+      lockfileName: null,
+      lockfileVersion: null,
+      root,
+      components: [],
+      error:
+        'No se encontró package-lock.json ni npm-shrinkwrap.json. ' +
+        'El CRA exige trazabilidad determinista de dependencias: ejecuta `npm install` para generar el lockfile.',
+    };
+  }
+
+  const lock = readJson(lockPath);
+  const lockfileVersion = lock.lockfileVersion || 1;
+
+  let components;
+  if (lock.packages) {
+    components = parsePackagesField(lock.packages);
+  } else if (lock.dependencies) {
+    components = parseDependenciesField(lock.dependencies);
+  } else {
+    components = [];
+  }
+
+  return {
+    ok: true,
+    lockfileName,
+    lockfileVersion,
+    root,
+    components,
+  };
+}
+
+/** Lockfile v2/v3 store everything under the `packages` map keyed by path. */
+function parsePackagesField(packages) {
+  const components = [];
+
+  for (const [pkgPath, info] of Object.entries(packages)) {
+    // The root project is stored under the empty key.
+    if (pkgPath === '') continue;
+    if (info.link) continue; // local symlinked workspace, not a third-party artifact
+
+    const name = info.name || nameFromPath(pkgPath);
+    if (!name) continue;
+
+    components.push(normalizeComponent({
+      name,
+      version: info.version,
+      resolved: info.resolved,
+      integrity: info.integrity,
+      license: info.license,
+      dev: Boolean(info.dev),
+      optional: Boolean(info.optional),
+      path: pkgPath,
+    }));
+  }
+
+  return dedupe(components);
+}
+
+/** Lockfile v1 nests dependencies recursively under `dependencies`. */
+function parseDependenciesField(dependencies, acc = []) {
+  for (const [name, info] of Object.entries(dependencies)) {
+    acc.push(normalizeComponent({
+      name,
+      version: info.version,
+      resolved: info.resolved,
+      integrity: info.integrity,
+      license: info.license,
+      dev: Boolean(info.dev),
+      optional: Boolean(info.optional),
+      path: `node_modules/${name}`,
+    }));
+    if (info.dependencies) {
+      parseDependenciesField(info.dependencies, acc);
+    }
+  }
+  return dedupe(acc);
+}
+
+function nameFromPath(pkgPath) {
+  const idx = pkgPath.lastIndexOf('node_modules/');
+  if (idx === -1) return null;
+  return pkgPath.slice(idx + 'node_modules/'.length);
+}
+
+function normalizeComponent(raw) {
+  const { algorithm, hash } = parseIntegrity(raw.integrity);
+  return {
+    name: raw.name,
+    version: raw.version || null,
+    purl: buildPurl(raw.name, raw.version),
+    resolved: raw.resolved || null,
+    integrity: raw.integrity || null,
+    hashAlgorithm: algorithm,
+    hashValue: hash,
+    license: raw.license || null,
+    scope: raw.dev ? 'optional' : 'required',
+    dev: raw.dev,
+    optional: raw.optional,
+    path: raw.path,
+  };
+}
+
+/**
+ * Parses an npm Subresource Integrity string ("sha512-<base64>")
+ * into a CycloneDX-friendly { algorithm, hash } pair.
+ */
+function parseIntegrity(integrity) {
+  if (!integrity || typeof integrity !== 'string') {
+    return { algorithm: null, hash: null };
+  }
+  const [algo, b64] = integrity.split('-');
+  if (!algo || !b64) return { algorithm: null, hash: null };
+
+  const map = { sha512: 'SHA-512', sha384: 'SHA-384', sha256: 'SHA-256', sha1: 'SHA-1' };
+  const algorithm = map[algo.toLowerCase()] || null;
+  if (!algorithm) return { algorithm: null, hash: null };
+
+  let hex;
+  try {
+    hex = Buffer.from(b64, 'base64').toString('hex');
+  } catch {
+    hex = null;
+  }
+  return { algorithm, hash: hex };
+}
+
+/** Builds a Package URL (purl) per the npm purl-spec. */
+function buildPurl(name, version) {
+  if (!name) return null;
+  let purl = 'pkg:npm/';
+  if (name.startsWith('@')) {
+    const [scope, pkg] = name.split('/');
+    purl += `${encodeURIComponent(scope)}/${encodeURIComponent(pkg)}`;
+  } else {
+    purl += encodeURIComponent(name);
+  }
+  if (version) purl += `@${version}`;
+  return purl;
+}
+
+function dedupe(components) {
+  const seen = new Map();
+  for (const comp of components) {
+    const key = `${comp.name}@${comp.version}`;
+    if (!seen.has(key)) {
+      seen.set(key, comp);
+    }
+  }
+  return Array.from(seen.values()).sort((a, b) =>
+    a.name.localeCompare(b.name) || String(a.version).localeCompare(String(b.version))
+  );
+}
+
+module.exports = { parseLockfile, buildPurl, parseIntegrity };

package/src/core/policy.js

@@ -0,0 +1,76 @@
+'use strict';
+
+const path = require('node:path');
+const { readJson, exists } = require('../utils/fs');
+
+const CONFIG_FILENAMES = ['.cra-audit.json', 'cra-audit.config.json'];
+
+/**
+ * Default security policy aligned with CRA Article 13 ("no known exploitable
+ * vulnerabilities") and TR-03183 transparency requirements.
+ */
+const DEFAULT_POLICY = {
+  // Fail the audit when a vulnerability of this severity (or higher) is found.
+  failOn: 'high', // info | low | moderate | high | critical
+  // Require an SBOM that satisfies the minimum TR-03183 elements.
+  requireSbom: true,
+  sbomFormat: 'cyclonedx', // cyclonedx | spdx
+  // Audit only production dependencies (recommended for shipped products).
+  productionOnly: false,
+  vulnerabilities: {
+    // CVE/advisory ids explicitly accepted with documented justification.
+    allowlist: [],
+  },
+  licenses: {
+    // Empty allow = accept any license that is not denied.
+    allow: [],
+    deny: ['GPL-3.0', 'AGPL-3.0'],
+    // Treat undocumented licenses as a compliance failure.
+    failOnMissing: true,
+  },
+};
+
+/**
+ * Loads and merges the project security policy from disk over the defaults.
+ *
+ * @param {string} projectRoot
+ * @param {string} [explicitPath] Path provided via --config.
+ */
+function loadPolicy(projectRoot, explicitPath) {
+  let configPath = null;
+
+  if (explicitPath) {
+    configPath = path.isAbsolute(explicitPath)
+      ? explicitPath
+      : path.join(projectRoot, explicitPath);
+    if (!exists(configPath)) {
+      throw new Error(`No se encontró el archivo de configuración: ${explicitPath}`);
+    }
+  } else {
+    for (const name of CONFIG_FILENAMES) {
+      const candidate = path.join(projectRoot, name);
+      if (exists(candidate)) {
+        configPath = candidate;
+        break;
+      }
+    }
+  }
+
+  let userPolicy = {};
+  if (configPath) {
+    userPolicy = readJson(configPath) || {};
+  }
+
+  return { policy: mergePolicy(DEFAULT_POLICY, userPolicy), source: configPath };
+}
+
+function mergePolicy(base, override) {
+  return {
+    ...base,
+    ...override,
+    vulnerabilities: { ...base.vulnerabilities, ...(override.vulnerabilities || {}) },
+    licenses: { ...base.licenses, ...(override.licenses || {}) },
+  };
+}
+
+module.exports = { loadPolicy, DEFAULT_POLICY };

package/src/core/sbom-generator.js

@@ -0,0 +1,146 @@
+'use strict';
+
+const crypto = require('node:crypto');
+const { parseLockfile } = require('./lockfile-parser');
+
+const TOOL_NAME = 'cra-audit';
+const TOOL_VERSION = require('../../package.json').version;
+
+/**
+ * Generates a Software Bill of Materials from the project lockfile.
+ * Supported formats: CycloneDX 1.5 (JSON) and SPDX 2.3 (JSON).
+ * Required by CRA Annex I and BSI TR-03183 Part 2.
+ */
+function generateSbom(projectRoot, { format = 'cyclonedx' } = {}) {
+  const parsed = parseLockfile(projectRoot);
+  if (!parsed.ok) {
+    return { ok: false, error: parsed.error };
+  }
+
+  const normalizedFormat = String(format).toLowerCase();
+  let document;
+  if (normalizedFormat === 'spdx') {
+    document = buildSpdx(parsed);
+  } else if (normalizedFormat === 'cyclonedx' || normalizedFormat === 'cdx') {
+    document = buildCycloneDx(parsed);
+  } else {
+    return { ok: false, error: `Formato de SBOM no soportado: "${format}". Usa "cyclonedx" o "spdx".` };
+  }
+
+  return {
+    ok: true,
+    format: normalizedFormat === 'spdx' ? 'spdx' : 'cyclonedx',
+    componentCount: parsed.components.length,
+    document,
+  };
+}
+
+function buildCycloneDx(parsed) {
+  const timestamp = new Date().toISOString();
+  const serialNumber = `urn:uuid:${crypto.randomUUID()}`;
+
+  const components = parsed.components.map((c) => {
+    const component = {
+      type: 'library',
+      'bom-ref': c.purl || `${c.name}@${c.version}`,
+      name: c.name,
+      version: c.version || undefined,
+      scope: c.scope,
+      purl: c.purl || undefined,
+    };
+    if (c.hashAlgorithm && c.hashValue) {
+      component.hashes = [{ alg: c.hashAlgorithm, content: c.hashValue }];
+    }
+    if (c.license) {
+      component.licenses = [normalizeCdxLicense(c.license)];
+    }
+    return component;
+  });
+
+  return {
+    bomFormat: 'CycloneDX',
+    specVersion: '1.5',
+    serialNumber,
+    version: 1,
+    metadata: {
+      timestamp,
+      tools: [{ vendor: 'cra-audit', name: TOOL_NAME, version: TOOL_VERSION }],
+      component: {
+        type: 'application',
+        'bom-ref': `pkg:npm/${parsed.root.name}@${parsed.root.version}`,
+        name: parsed.root.name,
+        version: parsed.root.version,
+      },
+    },
+    components,
+  };
+}
+
+function normalizeCdxLicense(license) {
+  if (typeof license === 'string') {
+    // Use SPDX expression when it contains operators, else a license id.
+    if (/\s(AND|OR|WITH)\s/i.test(license)) {
+      return { expression: license };
+    }
+    return { license: { id: license } };
+  }
+  return { license: { name: String(license) } };
+}
+
+function buildSpdx(parsed) {
+  const created = new Date().toISOString();
+  const docNamespace = `https://spdx.org/spdxdocs/${parsed.root.name}-${crypto.randomUUID()}`;
+
+  const packages = parsed.components.map((c, index) => {
+    const spdxId = `SPDXRef-Package-${index}`;
+    const pkg = {
+      name: c.name,
+      SPDXID: spdxId,
+      versionInfo: c.version || 'NOASSERTION',
+      downloadLocation: c.resolved || 'NOASSERTION',
+      filesAnalyzed: false,
+      licenseConcluded: c.license || 'NOASSERTION',
+      licenseDeclared: c.license || 'NOASSERTION',
+      copyrightText: 'NOASSERTION',
+      externalRefs: c.purl
+        ? [{
+            referenceCategory: 'PACKAGE-MANAGER',
+            referenceType: 'purl',
+            referenceLocator: c.purl,
+          }]
+        : undefined,
+    };
+    if (c.hashAlgorithm && c.hashValue) {
+      pkg.checksums = [{ algorithm: c.hashAlgorithm.replace('-', ''), checksumValue: c.hashValue }];
+    }
+    return pkg;
+  });
+
+  const rootSpdxId = 'SPDXRef-Package-root';
+  packages.unshift({
+    name: parsed.root.name,
+    SPDXID: rootSpdxId,
+    versionInfo: parsed.root.version,
+    downloadLocation: 'NOASSERTION',
+    filesAnalyzed: false,
+    licenseConcluded: 'NOASSERTION',
+    licenseDeclared: 'NOASSERTION',
+    copyrightText: 'NOASSERTION',
+  });
+
+  return {
+    spdxVersion: 'SPDX-2.3',
+    dataLicense: 'CC0-1.0',
+    SPDXID: 'SPDXRef-DOCUMENT',
+    name: `${parsed.root.name}@${parsed.root.version}`,
+    documentNamespace: docNamespace,
+    creationInfo: {
+      created,
+      creators: [`Tool: ${TOOL_NAME}-${TOOL_VERSION}`],
+    },
+    documentDescribes: [rootSpdxId],
+    packages,
+  };
+}
+
+module.exports = { generateSbom };

package/src/core/sbom-validator.js

@@ -0,0 +1,124 @@
+'use strict';
+
+/**
+ * Validates an SBOM document against the minimum elements required by
+ * CRA Annex I (2)(1) and BSI TR-03183 Part 2. It auto-detects whether the
+ * document is CycloneDX or SPDX.
+ *
+ * Minimum required elements (TR-03183 §6 "minimum elements"):
+ *  - SBOM format declared (CycloneDX or SPDX)
+ *  - Author / creator of the SBOM
+ *  - Timestamp of creation
+ *  - For each component: name, version, supplier/author, unique identifier,
+ *    cryptographic hash, license and dependency relationship.
+ */
+function validateSbom(document) {
+  if (!document || typeof document !== 'object') {
+    return invalid('El SBOM no es un objeto JSON válido.');
+  }
+
+  if (document.bomFormat === 'CycloneDX' || document.specVersion) {
+    return validateCycloneDx(document);
+  }
+  if (document.spdxVersion || document.SPDXID === 'SPDXRef-DOCUMENT') {
+    return validateSpdx(document);
+  }
+
+  return invalid('Formato de SBOM no reconocido (no es CycloneDX ni SPDX).');
+}
+
+function validateCycloneDx(doc) {
+  const issues = [];
+  const checks = [];
+
+  pushCheck(checks, 'format', 'Formato declarado (CycloneDX)', doc.bomFormat === 'CycloneDX');
+  pushCheck(checks, 'specVersion', 'Versión de especificación presente', Boolean(doc.specVersion));
+  pushCheck(checks, 'serialNumber', 'Identificador único del documento (serialNumber)', Boolean(doc.serialNumber));
+  pushCheck(checks, 'timestamp', 'Marca temporal de creación', Boolean(doc.metadata && doc.metadata.timestamp));
+  pushCheck(checks, 'author', 'Autor / herramienta generadora declarada',
+    Boolean(doc.metadata && (doc.metadata.tools || doc.metadata.authors)));
+  pushCheck(checks, 'rootComponent', 'Componente raíz (producto) identificado',
+    Boolean(doc.metadata && doc.metadata.component && doc.metadata.component.name));
+
+  const components = Array.isArray(doc.components) ? doc.components : [];
+  pushCheck(checks, 'components', 'Contiene al menos un componente', components.length > 0);
+
+  const stats = { total: components.length, missingVersion: 0, missingHash: 0, missingLicense: 0, missingPurl: 0 };
+  for (const comp of components) {
+    const label = comp.name || comp['bom-ref'] || 'desconocido';
+    if (!comp.version) { stats.missingVersion++; issues.push(`Componente sin versión: ${label}`); }
+    if (!hasCdxHash(comp)) { stats.missingHash++; issues.push(`Componente sin hash criptográfico: ${label}`); }
+    if (!hasCdxLicense(comp)) { stats.missingLicense++; issues.push(`Componente sin licencia: ${label}`); }
+    if (!comp.purl && !comp['bom-ref']) { stats.missingPurl++; issues.push(`Componente sin identificador único (purl): ${label}`); }
+  }
+
+  pushCheck(checks, 'componentVersions', 'Todos los componentes tienen versión', stats.missingVersion === 0);
+  pushCheck(checks, 'componentHashes', 'Todos los componentes tienen hash criptográfico', stats.missingHash === 0);
+  pushCheck(checks, 'componentLicenses', 'Todos los componentes tienen licencia', stats.missingLicense === 0);
+  pushCheck(checks, 'componentIdentifiers', 'Todos los componentes tienen identificador único', stats.missingPurl === 0);
+
+  return summarize('cyclonedx', checks, issues, stats);
+}
+
+function validateSpdx(doc) {
+  const issues = [];
+  const checks = [];
+
+  pushCheck(checks, 'format', 'Formato declarado (SPDX)', Boolean(doc.spdxVersion));
+  pushCheck(checks, 'dataLicense', 'Licencia de los datos declarada', Boolean(doc.dataLicense));
+  pushCheck(checks, 'serialNumber', 'Namespace único del documento', Boolean(doc.documentNamespace));
+  pushCheck(checks, 'timestamp', 'Marca temporal de creación', Boolean(doc.creationInfo && doc.creationInfo.created));
+  pushCheck(checks, 'author', 'Autor / creador declarado',
+    Boolean(doc.creationInfo && Array.isArray(doc.creationInfo.creators) && doc.creationInfo.creators.length));
+
+  const packages = Array.isArray(doc.packages) ? doc.packages : [];
+  pushCheck(checks, 'components', 'Contiene al menos un paquete', packages.length > 0);
+
+  const stats = { total: packages.length, missingVersion: 0, missingHash: 0, missingLicense: 0, missingPurl: 0 };
+  for (const pkg of packages) {
+    const label = pkg.name || pkg.SPDXID || 'desconocido';
+    if (pkg.SPDXID === 'SPDXRef-Package-root') continue;
+    if (!pkg.versionInfo || pkg.versionInfo === 'NOASSERTION') { stats.missingVersion++; issues.push(`Paquete sin versión: ${label}`); }
+    if (!Array.isArray(pkg.checksums) || pkg.checksums.length === 0) { stats.missingHash++; issues.push(`Paquete sin checksum: ${label}`); }
+    if (!pkg.licenseConcluded || pkg.licenseConcluded === 'NOASSERTION') { stats.missingLicense++; issues.push(`Paquete sin licencia: ${label}`); }
+    if (!Array.isArray(pkg.externalRefs) || !pkg.externalRefs.some((r) => r.referenceType === 'purl')) { stats.missingPurl++; issues.push(`Paquete sin purl: ${label}`); }
+  }
+
+  pushCheck(checks, 'componentVersions', 'Todos los paquetes tienen versión', stats.missingVersion === 0);
+  pushCheck(checks, 'componentHashes', 'Todos los paquetes tienen checksum', stats.missingHash === 0);
+  pushCheck(checks, 'componentLicenses', 'Todos los paquetes tienen licencia', stats.missingLicense === 0);
+  pushCheck(checks, 'componentIdentifiers', 'Todos los paquetes tienen purl', stats.missingPurl === 0);
+
+  return summarize('spdx', checks, issues, stats);
+}
+
+function hasCdxHash(comp) {
+  return Array.isArray(comp.hashes) && comp.hashes.length > 0;
+}
+
+function hasCdxLicense(comp) {
+  return Array.isArray(comp.licenses) && comp.licenses.length > 0;
+}
+
+function pushCheck(checks, id, label, passed) {
+  checks.push({ id, label, passed: Boolean(passed) });
+}
+
+function summarize(format, checks, issues, stats) {
+  const failed = checks.filter((c) => !c.passed);
+  return {
+    ok: true,
+    format,
+    valid: failed.length === 0,
+    checks,
+    failedChecks: failed,
+    issues,
+    stats,
+  };
+}
+
+function invalid(message) {
+  return { ok: false, valid: false, error: message, checks: [], issues: [message] };
+}
+
+module.exports = { validateSbom };