cra-audit 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 cra-audit contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,248 @@
+# cra-audit
+
+> 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.
+
+```bash
+# Run ALL the law's checks (Vulnerabilities + Licenses + SBOM)
+npx cra-audit
+
+# Interactive visual report (HTML) with maintenance data
+npx cra-audit --visualize
+
+# Just the SBOM part
+npx cra-audit --sbom
+npx cra-audit sbom check
+```
+
+---
+
+## What it checks and why (mapping to the regulation)
+
+Under the hood, the package runs the checks derived from the CRA legal obligations and the TR-03183 technical guideline:
+
+### 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`. It verifies the **minimum elements** required by TR-03183 §6 for every component: name, version, unique identifier (`purl`), cryptographic integrity hash and license.
+
+> CRA Annex I · TR-03183 Part 2 — *"Transparency through SBOM"*.
+
+### 2. "Zero known vulnerabilities" audit
+
+Scans **direct and transitive** dependencies (from the lockfile) with `npm audit` and blocks the audit if there are exploitable vulnerabilities above the configured threshold.
+
+> CRA Art. 13 — *products must be placed on the market without known exploitable vulnerabilities*.
+
+### 3. Third-party component check
+
+Identifies every third-party open-source library present in the dependency tree and cross-references it against known security advisories, flagging vulnerable components and whether a fix is available.
+
+> CRA — special attention to third-party developed components.
+
+### 4. License and hash management
+
+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.
+
+### 5. Visualization (`--visualize`)
+
+Generates an **interactive, self-contained HTML report** (no external CDNs, works offline) that gathers, per package: SBOM, installed vs. latest published version, license, vulnerabilities and **maintenance signals** to assess how well each project is maintained:
+
+- Last npm publish and number of maintainers.
+- Associated repository.
+- (Optional, with `--github`) **last commit** date, number of **contributors** and **stars**.
+- **Deprecated** / **archived** indicators.
+- A **maintenance score** (0-100) with a label *well-maintained / moderate / at-risk*.
+
+The report includes summary cards, search, filters (vulnerable, outdated, license issues, at risk) and column sorting.
+
+---
+
+## Usage
+
+```bash
+# Full audit (default)
+npx cra-audit
+npx cra-audit audit
+
+# Visual report
+npx cra-audit --visualize            # shortcut
+npx cra-audit visualize              # long form
+npx cra-audit visualize --github     # adds last commit, contributors and stars
+npx cra-audit visualize --offline    # no network (skips maintenance metadata)
+npx cra-audit visualize --no-open -o report.html
+
+# SBOM
+npx cra-audit --sbom                          # = sbom check
+npx cra-audit sbom check
+npx cra-audit sbom generate -o sbom.cdx.json          # CycloneDX (default)
+npx cra-audit sbom generate --format spdx -o sbom.spdx.json
+npx cra-audit sbom check -i sbom.cdx.json             # validate an existing SBOM
+
+# Individual checks
+npx cra-audit vulnerabilities        # alias: vuln
+npx cra-audit licenses
+```
+
+### Global installation (optional)
+
+```bash
+npm install -g cra-audit
+cra-audit --help
+```
+
+---
+
+## Commands
+
+| Command | Description |
+| --- | --- |
+| `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 vulnerabilities` (alias `vuln`) | Vulnerability analysis only. |
+| `cra-audit licenses` | License analysis only. |
+| `cra-audit help` | Show help. |
+
+## Options
+
+| Option | Description |
+| --- | --- |
+| `--visualize`, `-V` | Shortcut to generate and open the interactive HTML report. |
+| `--github` | Enrich the visual report with GitHub data (last commit, contributors, stars). |
+| `--offline` | Do not query the network when visualizing (skips maintenance metadata). |
+| `--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`. |
+| `--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. |
+| `--json` | Machine-readable JSON output. |
+| `--output`, `-o <path>` | Write the result / SBOM / HTML to a file. |
+| `--input`, `-i <path>` | Existing SBOM to validate (for `sbom check`). |
+| `--config`, `-c <path>` | Path to the security policy. |
+| `--cwd <path>` | Project directory to audit. |
+| `--no-color` | Disable colors. |
+| `--version`, `-v` · `--help`, `-h` | Version / help. |
+
+### GitHub data and rate limits
+
+With `--github`, the tool queries the public GitHub API to fetch the last commit, contributors and stars. Unauthenticated, GitHub limits to **60 requests/hour**. For large projects, set a read-only token:
+
+```bash
+# PowerShell
+$env:GITHUB_TOKEN = "ghp_xxx"; npx cra-audit visualize --github
+# bash
+GITHUB_TOKEN=ghp_xxx npx cra-audit visualize --github
+```
+
+The token is only used to add the `Authorization` header on calls to `api.github.com`; it is not stored or sent anywhere else.
+
+---
+
+## The visual report in detail
+
+`cra-audit visualize` writes `cra-audit-report.html` (or the `-o` path) and opens it in the browser. The report is a **single HTML file** with all data embedded and the filtering/sorting logic in its own vanilla JavaScript (no third-party scripts), so it is safe to share and works offline.
+
+| Column | Meaning |
+| --- | --- |
+| Package | Component name (flags `deprecated` / `archived`). |
+| Version | Installed version + `up to date` / `→ latest` indicator. |
+| Latest | Latest version published on npm. |
+| License | Detected license (red badge if missing or denied). |
+| Vulnerability | Highest known severity (`clean` if none). |
+| Last activity | Last commit date (with `--github`) or last publish date. |
+| Maint. | Number of npm maintainers. |
+| Contrib. | Number of GitHub contributors (with `--github`). |
+| Maintenance | Score 0-100 based on recency, maintainers, contributors and status. |
+
+Summary cards: total components, vulnerable, license issues, outdated and at risk.
+
+---
+
+## Security policy
+
+Create a `.cra-audit.json` file at the project root to customize the rules (there is an example in `.cra-audit.example.json`):
+
+```json
+{
+  "failOn": "high",
+  "requireSbom": true,
+  "sbomFormat": "cyclonedx",
+  "productionOnly": false,
+  "vulnerabilities": {
+    "allowlist": []
+  },
+  "licenses": {
+    "allow": [],
+    "deny": ["GPL-3.0", "AGPL-3.0"],
+    "failOnMissing": true
+  }
+}
+```
+
+- `failOn`: minimum severity that blocks the audit.
+- `requireSbom`: require the SBOM to meet the TR-03183 minimum elements.
+- `sbomFormat`: `cyclonedx` or `spdx`.
+- `productionOnly`: audit production dependencies only.
+- `vulnerabilities.allowlist`: advisory/CVE identifiers accepted with documented justification.
+- `licenses.allow` / `licenses.deny`: allowed / denied lists (SPDX id).
+- `licenses.failOnMissing`: treat undocumented licenses as a failure.
+
+Command-line options take precedence over the policy file.
+
+---
+
+## Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| `0` | Audit passed (or report generated successfully). |
+| `1` | Audit failed or execution error. |
+
+Suitable for CI/CD: a non-`0` code blocks the pipeline.
+
+```yaml
+# Example in GitHub Actions
+- name: CRA compliance audit
+  run: npx cra-audit --fail-on high --production --json -o cra-report.json
+```
+
+---
+
+## Programmatic API
+
+```js
+const {
+  runAudit, loadPolicy, generateSbom, validateSbom,
+  scanVulnerabilities, checkLicenses, parseLockfile,
+  enrichComponents, buildHtml,
+} = require('cra-audit');
+
+const { policy, source } = loadPolicy(process.cwd());
+const report = runAudit(process.cwd(), policy, source);
+console.log(report.gate.passed ? 'OK' : 'FAILED');
+
+// Maintenance data + custom HTML report
+const { components } = parseLockfile(process.cwd());
+const signals = await enrichComponents(components, { network: true, github: true });
+```
+
+---
+
+## Requirements
+
+- Node.js >= 18 (uses native `fetch` and `node --test`).
+- `npm` available on the `PATH` (for `npm audit`).
+- A `package-lock.json` or `npm-shrinkwrap.json` present (run `npm install` if missing).
+
+## Legal notice
+
+`cra-audit` is a technical support tool. It helps verify controls associated with the CRA and TR-03183, but it **does not constitute legal advice** nor does it guarantee regulatory compliance on its own.
+
+## License
+
+MIT

package/bin/cra-audit.js

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+'use strict';
+
+const { main } = require('../src/cli');
+
+Promise.resolve()
+  .then(() => main(process.argv.slice(2)))
+  .then((exitCode) => {
+    process.exitCode = typeof exitCode === 'number' ? exitCode : 0;
+  })
+  .catch((err) => {
+    process.stderr.write(`\x1b[31m✖ Error inesperado: ${err && err.message ? err.message : err}\x1b[0m\n`);
+    if (process.env.CRA_AUDIT_DEBUG) {
+      process.stderr.write(String(err && err.stack) + '\n');
+    }
+    process.exitCode = 1;
+  });

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "cra-audit",
+  "version": "0.1.0",
+  "description": "Audits npm projects for compliance with the European Cyber Resilience Act (CRA, EU Regulation 2024/2847) and the BSI TR-03183 technical guideline: SBOM (CycloneDX/SPDX), known vulnerabilities, third-party components, and licenses.",
+  "author": "Miguel Gonzalez Herrera",
+  "keywords": [
+    "cra",
+    "cyber-resilience-act",
+    "tr-03183",
+    "bsi",
+    "sbom",
+    "cyclonedx",
+    "spdx",
+    "security",
+    "audit",
+    "compliance",
+    "vulnerabilities",
+    "licenses",
+    "supply-chain"
+  ],
+  "license": "MIT",
+  "type": "commonjs",
+  "bin": {
+    "cra-audit": "bin/cra-audit.js"
+  },
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "node bin/cra-audit.js",
+    "test": "node --test"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {},
+  "preferGlobal": true
+}

package/src/cli.js

@@ -0,0 +1,217 @@
+'use strict';
+
+const { logger, color } = require('./utils/logger');
+const { auditCommand } = require('./commands/audit');
+const { sbomCommand } = require('./commands/sbom');
+const { visualizeCommand } = require('./commands/visualize');
+
+const VERSION = require('../package.json').version;
+
+const FLAG_ALIASES = {
+  '-h': '--help',
+  '-v': '--version',
+  '-o': '--output',
+  '-i': '--input',
+  '-c': '--config',
+  '-V': '--visualize',
+};
+
+const BOOLEAN_FLAGS = new Set([
+  '--help', '--version', '--json', '--sbom', '--no-sbom',
+  '--production', '--prod', '--no-color',
+  '--visualize', '--offline', '--github', '--no-open',
+]);
+
+/**
+ * Entry point invoked from bin/cra-audit.js.
+ * @param {string[]} argv Arguments after `node script`.
+ * @returns {Promise<number>} exit code.
+ */
+async function main(argv) {
+  const { positionals, flags } = parseArgs(argv);
+
+  if (flags.noColor) logger.setColor(false);
+
+  if (flags.help) {
+    printHelp();
+    return 0;
+  }
+  if (flags.version) {
+    logger.log(VERSION);
+    return 0;
+  }
+
+  const command = positionals[0] || 'audit';
+
+  // `--visualize` is a shortcut for the visual HTML report.
+  if (flags.visualize && command === 'audit') {
+    return visualizeCommand(flags);
+  }
+  // `--sbom` is a shortcut for "sbom check" regardless of the (default) command.
+  if (flags.sbom && command === 'audit') {
+    return sbomCommand('check', flags);
+  }
+
+  switch (command) {
+    case 'audit':
+      return auditCommand(flags);
+
+    case 'visualize':
+    case 'view':
+    case 'report':
+      return visualizeCommand(flags);
+
+    case 'sbom':
+      // `cra-audit --sbom` is handled below; here we route the subcommand form.
+      return sbomCommand(positionals[1], flags);
+
+    case 'vulnerabilities':
+    case 'vuln':
+    case 'vulns':
+      return auditCommand(flags, 'vulnerabilities');
+
+    case 'licenses':
+    case 'license':
+      return auditCommand(flags, 'licenses');
+
+    case 'help':
+      printHelp();
+      return 0;
+
+    default:
+      logger.error(`Comando desconocido: "${command}".`);
+      logger.log(`Ejecuta ${color.cyan('cra-audit --help')} para ver los comandos disponibles.`);
+      return 1;
+  }
+}
+
+/**
+ * Minimal, dependency-free argument parser.
+ * Supports `--flag`, `--flag value`, `--flag=value`, short aliases and `--no-*`.
+ */
+function parseArgs(argv) {
+  const positionals = [];
+  const flags = {};
+
+  for (let i = 0; i < argv.length; i++) {
+    let arg = argv[i];
+
+    if (!arg.startsWith('-')) {
+      positionals.push(arg);
+      continue;
+    }
+
+    let value;
+    const eq = arg.indexOf('=');
+    if (eq !== -1) {
+      value = arg.slice(eq + 1);
+      arg = arg.slice(0, eq);
+    }
+
+    const canonical = FLAG_ALIASES[arg] || arg;
+
+    if (BOOLEAN_FLAGS.has(canonical)) {
+      setFlag(flags, canonical, true);
+      continue;
+    }
+
+    // Value flag: take inline `=value` or the next argument.
+    if (value === undefined) {
+      const next = argv[i + 1];
+      if (next !== undefined && !next.startsWith('-')) {
+        value = next;
+        i++;
+      } else {
+        value = true;
+      }
+    }
+    setFlag(flags, canonical, value);
+  }
+
+  return { positionals, flags };
+}
+
+function setFlag(flags, name, value) {
+  switch (name) {
+    case '--help': flags.help = value; break;
+    case '--version': flags.version = value; break;
+    case '--json': flags.json = value; break;
+    case '--sbom': flags.sbom = value; break;
+    case '--no-sbom': flags.noSbom = value; break;
+    case '--no-color': flags.noColor = value; break;
+    case '--visualize': flags.visualize = value; break;
+    case '--offline': flags.offline = value; break;
+    case '--github': flags.github = value; break;
+    case '--no-open': flags.noOpen = value; break;
+    case '--production':
+    case '--prod': flags.production = value; break;
+    case '--output': flags.output = value; break;
+    case '--input': flags.input = value; break;
+    case '--config': flags.config = value; break;
+    case '--format': flags.format = String(value).toLowerCase(); break;
+    case '--fail-on': flags.failOn = String(value).toLowerCase(); break;
+    case '--cwd': flags.cwd = value; break;
+    default:
+      // Unknown flag stored under its raw name for forward compatibility.
+      flags[name.replace(/^--/, '')] = value;
+  }
+}
+
+function printHelp() {
+  const c = color;
+  logger.log(`
+${c.bold('cra-audit')} — Auditoría de cumplimiento del Cyber Resilience Act (UE 2024/2847)
+            y la directriz técnica BSI TR-03183 para proyectos npm.
+
+${c.bold('USO')}
+  npx cra-audit [comando] [opciones]
+
+${c.bold('COMANDOS')}
+  ${c.cyan('audit')}                 Ejecuta TODAS las comprobaciones (vulnerabilidades + SBOM + licencias). Por defecto.
+  ${c.cyan('visualize')}             Genera un informe HTML interactivo (SBOM, licencias, versiones y mantenimiento).
+  ${c.cyan('sbom generate')}         Genera un SBOM (CycloneDX o SPDX) y lo imprime o guarda.
+  ${c.cyan('sbom check')}            Valida que el SBOM cumple los elementos mínimos de TR-03183.
+  ${c.cyan('vulnerabilities')}       Analiza solo vulnerabilidades conocidas (alias: vuln).
+  ${c.cyan('licenses')}              Analiza solo las licencias de las dependencias.
+  ${c.cyan('help')}                  Muestra esta ayuda.
+
+${c.bold('OPCIONES')}
+  ${c.cyan('--visualize, -V')}       Atajo para generar y abrir el informe HTML interactivo.
+  ${c.cyan('--github')}              Enriquece el informe visual con datos de GitHub (último commit, contribuidores, stars).
+  ${c.cyan('--offline')}             No consulta la red al visualizar (omite metadatos de mantenimiento).
+  ${c.cyan('--no-open')}             No abre el informe HTML en el navegador automáticamente.
+  ${c.cyan('--sbom')}                Atajo equivalente a "sbom check".
+  ${c.cyan('--format <fmt>')}        Formato del SBOM: cyclonedx (def.) | spdx.
+  ${c.cyan('--fail-on <sev>')}       Severidad mínima que hace fallar la auditoría: info|low|moderate|high|critical.
+  ${c.cyan('--production, --prod')}  Audita solo dependencias de producción (omite devDependencies).
+  ${c.cyan('--no-sbom')}             No exige SBOM en la auditoría completa.
+  ${c.cyan('--json')}                Salida en JSON legible por máquina.
+  ${c.cyan('--output, -o <ruta>')}   Escribe el resultado/SBOM/HTML en un archivo.
+  ${c.cyan('--input, -i <ruta>')}    SBOM existente a validar (para "sbom check").
+  ${c.cyan('--config, -c <ruta>')}   Ruta a la política de seguridad (.cra-audit.json).
+  ${c.cyan('--cwd <ruta>')}          Directorio del proyecto a auditar.
+  ${c.cyan('--no-color')}            Desactiva los colores.
+  ${c.cyan('--version, -v')}         Muestra la versión.
+  ${c.cyan('--help, -h')}            Muestra esta ayuda.
+
+${c.bold('EJEMPLOS')}
+  ${c.gray('# Auditoría completa de cumplimiento CRA')}
+  npx cra-audit
+
+  ${c.gray('# Informe visual interactivo (HTML) con datos de mantenimiento')}
+  npx cra-audit --visualize
+  npx cra-audit visualize --github
+
+  ${c.gray('# Solo la parte del SBOM')}
+  npx cra-audit --sbom
+  npx cra-audit sbom check
+
+  ${c.gray('# Generar un SBOM CycloneDX en disco')}
+  npx cra-audit sbom generate -o sbom.cdx.json
+
+  ${c.gray('# Fallar solo ante vulnerabilidades críticas, en CI')}
+  npx cra-audit --fail-on critical --production --json -o cra-report.json
+`);
+}
+
+module.exports = { main, parseArgs };

package/src/commands/audit.js

@@ -0,0 +1,62 @@
+'use strict';
+
+const { findProjectRoot } = require('../utils/fs');
+const { logger } = require('../utils/logger');
+const { loadPolicy } = require('../core/policy');
+const { runAudit } = require('../core/auditor');
+const { reportConsole } = require('../reporters/console');
+const { reportJson } = require('../reporters/json');
+
+/**
+ * `cra-audit [audit]` — runs the full compliance audit (vulnerabilities + SBOM
+ * + licenses) or a single section via `only`.
+ *
+ * @param {object} flags Parsed CLI flags.
+ * @param {'vulnerabilities'|'sbom'|'licenses'} [only]
+ * @returns {number} Process exit code.
+ */
+function auditCommand(flags, only) {
+  const projectRoot = resolveRoot(flags);
+  if (!projectRoot) return 1;
+
+  let policyResult;
+  try {
+    policyResult = loadPolicy(projectRoot, flags.config);
+  } catch (err) {
+    logger.error(err.message);
+    return 1;
+  }
+
+  const policy = applyFlagOverrides(policyResult.policy, flags);
+  const report = runAudit(projectRoot, policy, policyResult.source, { only });
+
+  if (flags.json) {
+    reportJson(report, { outputPath: flags.output });
+  } else {
+    reportConsole(report);
+  }
+
+  return report.gate.passed ? 0 : 1;
+}
+
+function resolveRoot(flags) {
+  const start = flags.cwd || process.cwd();
+  const root = findProjectRoot(start);
+  if (!root) {
+    logger.error('No se encontró ningún package.json. Ejecuta el comando dentro de un proyecto npm.');
+    return null;
+  }
+  return root;
+}
+
+/** CLI flags take precedence over the file-based policy. */
+function applyFlagOverrides(policy, flags) {
+  const merged = { ...policy };
+  if (flags.failOn) merged.failOn = flags.failOn;
+  if (flags.production) merged.productionOnly = true;
+  if (flags.format) merged.sbomFormat = flags.format;
+  if (flags.noSbom) merged.requireSbom = false;
+  return merged;
+}
+
+module.exports = { auditCommand };