cra-audit 1.0.0 → 1.1.0

package/README.md

@@ -1,5 +1,7 @@
 # cra-audit
 
+[![npm](https://img.shields.io/npm/v/cra-audit)](https://www.npmjs.com/package/cra-audit) [![CI](https://github.com/migohe14/cra-audit/actions/workflows/ci.yml/badge.svg)](https://github.com/migohe14/cra-audit/actions/workflows/ci.yml) [![license](https://img.shields.io/npm/l/cra-audit)](LICENSE)
+
 > Compliance audit for the **Cyber Resilience Act** (Regulation EU 2024/2847) and the **BSI TR-03183** technical guideline, for npm projects.
 
 `cra-audit` audits the installed dependencies of an npm project and checks the key requirements that the CRA imposes on "products with digital elements". It runs directly with `npx`, **without installation**, and has **no production dependencies** to minimize its own supply-chain surface.
@@ -24,7 +26,24 @@ Under the hood, the package runs the checks derived from the CRA legal obligatio
 
 ### 1. Automatic SBOM validation
 
-Generates and validates a **Software Bill of Materials (SBOM)** in a machine-readable format —**CycloneDX 1.5** or **SPDX 2.3**— from the `package-lock.json` / `npm-shrinkwrap.json`, `yarn.lock` or `pnpm-lock.yaml`. It verifies the **minimum elements** required by TR-03183 §6 for every component: name, version, unique identifier (`purl`), cryptographic integrity hash and license.
+Generates and validates a **Software Bill of Materials (SBOM)** in a machine-readable format —**CycloneDX 1.6** (default) or **SPDX 2.3**— from the `package-lock.json` / `npm-shrinkwrap.json`, `yarn.lock` or `pnpm-lock.yaml`, following the field mapping of **BSI TR-03183-2 v2.1.0**:
+
+| TR-03183-2 data field | Where it comes from | CycloneDX 1.6 field |
+| --- | --- | --- |
+| Creator of the SBOM (email or URL) | `--creator`, `sbomCreator` policy, or the project's `author` / `homepage` / `repository` | `metadata.manufacturer` |
+| Timestamp | generation time (UTC) | `metadata.timestamp` |
+| Component creator (email or URL) | installed `package.json`: `author`, `maintainers`, `homepage`, `repository` | `components[].manufacturer` |
+| Name, version, purl | lockfile | `name`, `version`, `purl` |
+| Filename | tarball name (`left-pad-1.3.0.tgz`) | property `bsi:component:filename` |
+| SHA-512 of the deployable component | lockfile `integrity` | `externalReferences[distribution].hashes` |
+| Executable / archive / structured | npm tarball: `non-executable`, `archive`, `structured` | properties `bsi:component:*` |
+| Dependencies + completeness | lockfile dependency graph (npm v1–v3, Yarn classic/Berry, pnpm v5–v9) | `dependencies`, `compositions[].aggregate` |
+| Distribution / original licences | lockfile or installed `package.json` | `licenses[]` with `acknowledgement` `concluded` / `declared` |
+| Source code URI | `repository` | `externalReferences[source-distribution]` |
+
+`sbom check` verifies every one of those fields for every component. Licenses (for Yarn/pnpm) and component creators are read from `node_modules`, so **run it after installing dependencies** (e.g. after `npm ci` in CI).
+
+Known limits: Yarn Berry lockfiles only store Yarn's own cache checksum, not the npm tarball SHA-512, so Berry projects fail the hash check. TR-03183-2 v2.1 requires **SPDX ≥ 3.0.1**; the SPDX output is still 2.3, so use CycloneDX for a conforming SBOM.
 
 > CRA Annex I · TR-03183 Part 2 — *"Transparency through SBOM"*.
 
@@ -44,7 +63,7 @@ Identifies every third-party open-source library present in the dependency tree
 
 Verifies that **all** dependencies have their license documented and compliant with the policy (allowlist / denylist), and that they carry unique identifiers (`purl`) and integrity hashes (SHA-512/384/256) as recommended by TR-03183.
 
-> TR-03183 §6 — license governance and hash integrity.
+> TR-03183-2 §5.2 — license governance and hash integrity.
 
 ### 5. Visualization (`--visualize`)
 
@@ -102,7 +121,7 @@ cra-audit --help
 | `cra-audit` / `cra-audit audit` | Full CRA compliance audit (vulnerabilities + SBOM + licenses). **Default.** |
 | `cra-audit visualize` (aliases `view`, `report`) | Interactive HTML report with SBOM, licenses, versions and maintenance. |
 | `cra-audit sbom generate` | Generate an SBOM (CycloneDX/SPDX). |
-| `cra-audit sbom check` | Validate the SBOM against the TR-03183 minimum elements. |
+| `cra-audit sbom check` | Validate the SBOM against the TR-03183-2 v2.1 data fields. |
 | `cra-audit vulnerabilities` (alias `vuln`) | Vulnerability analysis only. |
 | `cra-audit licenses` | License analysis only. |
 | `cra-audit help` | Show help. |
@@ -117,6 +136,7 @@ cra-audit --help
 | `--no-open` | Do not open the HTML report in the browser automatically. |
 | `--sbom` | Shortcut equivalent to `sbom check`. |
 | `--format <fmt>` | SBOM format: `cyclonedx` (default) or `spdx`. |
+| `--creator <contact>` | Email or URL of the SBOM creator (TR-03183-2 §5.2.1). Defaults to the project's `package.json` `author` / `homepage` / `repository`. |
 | `--fail-on <sev>` | Minimum severity that fails the audit: `info`, `low`, `moderate`, `high`, `critical`. |
 | `--production`, `--prod` | Audit production dependencies only. |
 | `--no-sbom` | Do not require an SBOM in the full audit. |
@@ -172,6 +192,7 @@ Create a `.cra-audit.json` file at the project root to customize the rules (ther
   "failOn": "high",
   "requireSbom": true,
   "sbomFormat": "cyclonedx",
+  "sbomCreator": "security@example.com",
   "productionOnly": false,
   "vulnerabilities": {
     "allowlist": []
@@ -185,8 +206,9 @@ Create a `.cra-audit.json` file at the project root to customize the rules (ther
 ```
 
 - `failOn`: minimum severity that blocks the audit.
-- `requireSbom`: require the SBOM to meet the TR-03183 minimum elements.
+- `requireSbom`: require the SBOM to meet the TR-03183-2 required data fields.
 - `sbomFormat`: `cyclonedx` or `spdx`.
+- `sbomCreator`: email or URL of the entity that creates the SBOM (usually the manufacturer).
 - `productionOnly`: audit production dependencies only.
 - `vulnerabilities.allowlist`: advisory/CVE identifiers accepted with documented justification.
 - `licenses.allow` / `licenses.deny`: allowed / denied lists (SPDX id).

package/package.json

@@ -1,7 +1,16 @@
 {
   "name": "cra-audit",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Audits npm, yarn, and pnpm projects for compliance with the European Cyber Resilience Act (CRA, EU Regulation 2024/2847) and BSI TR-03183: SBOM (CycloneDX/SPDX), known vulnerabilities, third-party components, and licenses.",
+  "homepage": "https://github.com/migohe14/cra-audit#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/migohe14/cra-audit.git"
+  },
+  "bugs": {
+    "url": "https://github.com/migohe14/cra-audit/issues"
+  },
+  "author": "Miguel Gonzalez (https://github.com/migohe14)",
   "keywords": [
     "cra",
     "cyber-resilience-act",
@@ -15,7 +24,11 @@
     "compliance",
     "vulnerabilities",
     "licenses",
-    "supply-chain"
+    "supply-chain",
+    "yarn",
+    "pnpm",
+    "eu",
+    "sbom-validation"
   ],
   "license": "MIT",
   "type": "commonjs",

package/src/cli.js

@@ -151,6 +151,7 @@ function setFlag(flags, name, value) {
     case '--format': flags.format = String(value).toLowerCase(); break;
     case '--fail-on': flags.failOn = String(value).toLowerCase(); break;
     case '--cwd': flags.cwd = value; break;
+    case '--creator': flags.creator = value; break;
     default:
       // Unknown flag stored under its raw name for forward compatibility.
       flags[name.replace(/^--/, '')] = value;
@@ -170,7 +171,7 @@ ${c.bold('COMMANDS')}
   ${c.cyan('audit')}                 Run ALL the checks (vulnerabilities + SBOM + licenses). Default.
   ${c.cyan('visualize')}             Generate an interactive HTML report (SBOM, licenses, versions and maintenance).
   ${c.cyan('sbom generate')}         Generate an SBOM (CycloneDX or SPDX) and print or save it.
-  ${c.cyan('sbom check')}            Validate that the SBOM meets the TR-03183 minimum elements.
+  ${c.cyan('sbom check')}            Validate the SBOM against the TR-03183-2 v2.1 data fields.
   ${c.cyan('vulnerabilities')}       Analyze known vulnerabilities only (alias: vuln).
   ${c.cyan('licenses')}              Analyze dependency licenses only.
   ${c.cyan('help')}                  Show this help.
@@ -182,6 +183,7 @@ ${c.bold('OPTIONS')}
   ${c.cyan('--no-open')}             Do not open the HTML report in the browser automatically.
   ${c.cyan('--sbom')}                Shortcut equivalent to "sbom check".
   ${c.cyan('--format <fmt>')}        SBOM format: cyclonedx (default) | spdx.
+  ${c.cyan('--creator <contact>')}   Email or URL of the SBOM creator (default: package.json author/homepage).
   ${c.cyan('--fail-on <sev>')}       Minimum severity that fails the audit: info|low|moderate|high|critical.
   ${c.cyan('--production, --prod')}  Audit production dependencies only (skips devDependencies).
   ${c.cyan('--no-sbom')}             Do not require an SBOM in the full audit.

package/src/commands/sbom.js

@@ -5,13 +5,14 @@ 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');
+const { loadPolicy } = require('../core/policy');
 
 /**
  * `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.
+ * - check:    generates (or reads) an SBOM and validates the data fields
+ *             required by BSI TR-03183-2 v2.1.0 §5.2.
  */
 function sbomCommand(subcommand, flags) {
   const projectRoot = findProjectRoot(flags.cwd || process.cwd());
@@ -35,7 +36,7 @@ function sbomCommand(subcommand, flags) {
 }
 
 function sbomGenerate(projectRoot, format, flags) {
-  const result = generateSbom(projectRoot, { format });
+  const result = generateSbom(projectRoot, { format, creator: sbomCreator(projectRoot, flags) });
   if (!result.ok) {
     logger.error(result.error);
     return 1;
@@ -63,7 +64,7 @@ function sbomCheck(projectRoot, format, flags) {
     }
     document = readJson(inPath);
   } else {
-    const result = generateSbom(projectRoot, { format });
+    const result = generateSbom(projectRoot, { format, creator: sbomCreator(projectRoot, flags) });
     if (!result.ok) {
       logger.error(result.error);
       return 1;
@@ -82,7 +83,7 @@ function sbomCheck(projectRoot, format, flags) {
     return validation.valid ? 0 : 1;
   }
 
-  logger.heading('SBOM validation · BSI TR-03183 §6 (minimum elements)');
+  logger.heading('SBOM validation · BSI TR-03183-2 v2.1.0 (required data fields)');
   logger.detail(`Detected format: ${validation.format} · Components: ${validation.stats.total}`);
   for (const check of validation.checks) {
     const mark = check.passed ? color.green('✔') : color.red('✖');
@@ -90,11 +91,21 @@ function sbomCheck(projectRoot, format, flags) {
   }
   logger.log('');
   if (validation.valid) {
-    logger.success(color.bold('SBOM VALID — meets the minimum elements required by the CRA.'));
+    logger.success(color.bold('SBOM VALID — meets the TR-03183-2 data fields required by the CRA.'));
     return 0;
   }
   logger.error(color.bold(`SBOM INVALID — ${validation.failedChecks.length} requirement(s) not met.`));
   return 1;
 }
 
+/** SBOM creator from --creator, else from the project policy (`sbomCreator`). */
+function sbomCreator(projectRoot, flags) {
+  if (typeof flags.creator === 'string') return flags.creator;
+  try {
+    return loadPolicy(projectRoot, flags.config).policy.sbomCreator;
+  } catch {
+    return undefined; // A broken policy file must not block SBOM generation.
+  }
+}
+
 module.exports = { sbomCommand };

package/src/core/auditor.js

@@ -48,7 +48,7 @@ function runAudit(projectRoot, policy, policySource, options = {}) {
 
   // --- 2. SBOM ------------------------------------------------------------
   if (!only || only === 'sbom') {
-    const sbom = generateSbom(projectRoot, { format: policy.sbomFormat });
+    const sbom = generateSbom(projectRoot, { format: policy.sbomFormat, creator: policy.sbomCreator });
     if (sbom.ok) {
       sbom.validation = validateSbom(sbom.document);
     }
@@ -60,7 +60,7 @@ function runAudit(projectRoot, policy, policySource, options = {}) {
       } else {
         reasons.push({
           label: sbom.validation.valid
-            ? 'SBOM valid against the TR-03183 minimum elements'
+            ? 'SBOM valid against the TR-03183-2 required data fields'
             : 'SBOM incomplete with respect to TR-03183',
           passed: sbom.validation.valid,
         });

package/src/core/installed-metadata.js

@@ -0,0 +1,179 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { readJson } = require('../utils/fs');
+
+/**
+ * Reads the package.json of an installed component from node_modules.
+ * Lockfiles do not carry every field TR-03183 asks for (Yarn and pnpm have no
+ * licenses, none of them have the component creator), so the installed
+ * manifest is the best offline source for them.
+ *
+ * Looks in the npm path recorded in the lockfile, the hoisted location and
+ * pnpm's virtual store. Returns null when the package is not installed or the
+ * installed version differs from the locked one.
+ *
+ * @param {string} projectRoot
+ * @param {{ name: string, version: string|null, path?: string }} component
+ * @returns {object|null}
+ */
+function readInstalledManifest(projectRoot, component) {
+  const { name, version } = component;
+  const candidates = [];
+  if (component.path) candidates.push(path.join(projectRoot, component.path, 'package.json'));
+  candidates.push(path.join(projectRoot, 'node_modules', name, 'package.json'));
+  if (version) {
+    const storeName = `${name.replace('/', '+')}@${version}`;
+    candidates.push(path.join(projectRoot, 'node_modules', '.pnpm', storeName, 'node_modules', name, 'package.json'));
+  }
+
+  for (const candidate of candidates) {
+    const pkg = readManifest(candidate);
+    if (!pkg) continue;
+    if (version && pkg.version && pkg.version !== version) continue;
+    return pkg;
+  }
+
+  // Yarn records no install paths, so non-hoisted duplicates live somewhere
+  // under a nested node_modules: fall back to an index of the whole tree.
+  const nested = installedIndex(projectRoot).get(`${name}@${version}`);
+  return nested ? readManifest(nested) : null;
+}
+
+function readManifest(file) {
+  try {
+    return readJson(file);
+  } catch {
+    return null; // Unreadable manifest: treat as not installed.
+  }
+}
+
+const indexCache = new Map();
+
+/**
+ * Maps `name@version` to the package.json path of every package installed
+ * under `<projectRoot>/node_modules`, including nested node_modules folders.
+ * pnpm's `.pnpm` store is skipped: it is looked up directly by name.
+ */
+function installedIndex(projectRoot) {
+  if (indexCache.has(projectRoot)) return indexCache.get(projectRoot);
+  const index = new Map();
+
+  const visitModules = (dir) => {
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (!entry.isDirectory() || entry.name.startsWith('.')) continue;
+      const full = path.join(dir, entry.name);
+      if (entry.name.startsWith('@')) {
+        let scoped = [];
+        try {
+          scoped = fs.readdirSync(full, { withFileTypes: true });
+        } catch {
+          // Unreadable scope folder: skip it.
+        }
+        for (const s of scoped) if (s.isDirectory()) visitPackage(path.join(full, s.name));
+      } else {
+        visitPackage(full);
+      }
+    }
+  };
+
+  const visitPackage = (dir) => {
+    const manifestPath = path.join(dir, 'package.json');
+    const pkg = readManifest(manifestPath);
+    if (pkg && pkg.name && pkg.version) {
+      const key = `${pkg.name}@${pkg.version}`;
+      if (!index.has(key)) index.set(key, manifestPath);
+    }
+    visitModules(path.join(dir, 'node_modules'));
+  };
+
+  visitModules(path.join(projectRoot, 'node_modules'));
+  indexCache.set(projectRoot, index);
+  return index;
+}
+
+/** Extracts the declared license (SPDX id or expression) from a manifest. */
+function licenseFromManifest(pkg) {
+  if (!pkg) return null;
+  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 ') || null;
+  }
+  return null;
+}
+
+/**
+ * Derives the creator contact TR-03183 requires (§5.2.1 / §5.2.2): an email
+ * address, or a URL when no email is available. Uses `author`, then the first
+ * maintainer/contributor with an email, then `homepage` and `repository`.
+ *
+ * @returns {{ name: string|null, email: string|null, url: string|null }|null}
+ */
+function creatorFromManifest(pkg) {
+  if (!pkg) return null;
+
+  const author = parsePerson(pkg.author);
+  const people = [author, ...toArray(pkg.maintainers).map(parsePerson), ...toArray(pkg.contributors).map(parsePerson)]
+    .filter(Boolean);
+  const withEmail = people.find((p) => p.email);
+  const name = (author && author.name) || (withEmail && withEmail.name) || null;
+
+  if (withEmail) return { name, email: withEmail.email, url: null };
+
+  const url = (author && author.url) || httpUrl(pkg.homepage) || repositoryUrl(pkg.repository);
+  if (url) return { name, email: null, url };
+  return null;
+}
+
+/** Normalizes `repository` (string or object) into a browsable https URL. */
+function repositoryUrl(repository) {
+  if (!repository) return null;
+  let url = typeof repository === 'string' ? repository : repository.url;
+  if (!url || typeof url !== 'string') return null;
+
+  // Shorthands: "user/repo", "github:user/repo", "gitlab:user/repo".
+  const shorthand = url.match(/^(?:(github|gitlab|bitbucket):)?([\w.-]+\/[\w.-]+)$/);
+  if (shorthand) {
+    const host = { github: 'github.com', gitlab: 'gitlab.com', bitbucket: 'bitbucket.org' }[shorthand[1] || 'github'];
+    return `https://${host}/${shorthand[2]}`;
+  }
+
+  url = url
+    .replace(/^git\+/, '')
+    .replace(/^git:\/\//, 'https://')
+    .replace(/^ssh:\/\/git@/, 'https://')
+    .replace(/^git@([^:]+):/, 'https://$1/')
+    .replace(/\.git$/, '');
+  return httpUrl(url);
+}
+
+/** Parses npm "person" fields: "Name <email> (url)" or { name, email, url }. */
+function parsePerson(person) {
+  if (!person) return null;
+  if (typeof person === 'object') {
+    return { name: person.name || null, email: person.email || null, url: httpUrl(person.url) };
+  }
+  const str = String(person);
+  const email = (str.match(/<([^>]+)>/) || [])[1] || null;
+  const url = (str.match(/\(([^)]+)\)/) || [])[1] || null;
+  const name = str.replace(/<[^>]*>/, '').replace(/\([^)]*\)/, '').trim() || null;
+  return { name, email, url: httpUrl(url) };
+}
+
+function httpUrl(value) {
+  return typeof value === 'string' && /^https?:\/\//i.test(value) ? value : null;
+}
+
+function toArray(value) {
+  return Array.isArray(value) ? value : [];
+}
+
+module.exports = { readInstalledManifest, licenseFromManifest, creatorFromManifest, repositoryUrl };

package/src/core/license-checker.js

@@ -1,9 +1,7 @@
 'use strict';
 
-const fs = require('node:fs');
-const path = require('node:path');
-const { readJson } = require('../utils/fs');
 const { parseLockfile } = require('./lockfile-parser');
+const { readInstalledManifest, licenseFromManifest } = require('./installed-metadata');
 
 /**
  * Resolves and evaluates the license of every third-party component.
@@ -22,7 +20,7 @@ function checkLicenses(projectRoot, policy = {}) {
   const deny = normalizeList(policy.deny);
 
   const components = parsed.components.map((c) => {
-    const license = c.license || readLicenseFromDisk(projectRoot, c.path, c.name);
+    const license = c.license || licenseFromManifest(readInstalledManifest(projectRoot, c));
     const normalized = license ? String(license) : null;
     const status = classify(normalized, allow, deny);
     return {
@@ -44,29 +42,6 @@ function checkLicenses(projectRoot, policy = {}) {
   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';