@theoptimalpartner/npm-security-kit 1.0.1 → 2.0.0-beta.0

package/src/checks/npm-policy.js

@@ -0,0 +1,121 @@
+// Que el repo tenga la configuración que hace cumplir la política: claves del .npmrc,
+// engines.npm, un npm que las entienda y un lockfile.
+import { lockfileName } from '../lib/audit.js';
+import { parseNpmrc, requiredSettings, settingProblem } from '../lib/npmrc.js';
+import { jsonKeyLine } from '../lib/json-lines.js';
+import { compareVersions, minVersion, parseVersion } from '../lib/semver.js';
+
+export const id = 'npm-policy';
+export const title = 'npm y .npmrc';
+
+const NPM10_WHY = 'npm 10 ignora min-release-age sin avisar y no aplica allowScripts';
+
+export async function run(ctx) {
+  const { policy } = ctx;
+  const findings = [];
+  const minNpm = policy.minNpmVersion;
+  const minNpmShort = minNpm.replace(/\.0$/, '');
+
+  // .npmrc del proyecto (el archivo, no la configuración efectiva)
+  const npmrcText = ctx.readFile('.npmrc');
+  const npmrc = parseNpmrc(npmrcText);
+  const errorKeys = new Set(policy.requiredNpmrc.error);
+  for (const setting of requiredSettings(policy)) {
+    const name = setting.array ? `${setting.key}[]` : setting.key;
+    const problem = settingProblem(setting, npmrc, policy);
+    if (!problem) continue;
+    const level = errorKeys.has(name) ? 'error' : 'warn';
+    const line = `${name}=${setting.value}`;
+    const entry = setting.array ? undefined : npmrc.get(setting.key);
+    const where = npmrcText === null ? ' (no hay .npmrc: crearlo o correr `npm-security-kit init`)' : '';
+    const why = {
+      'min-release-age': ' Sin esto, npm instala versiones recién publicadas.',
+      'min-release-age-exclude[]': ` Sin esto, los paquetes ${setting.value} también esperan ${policy.minReleaseAgeDays} días.`,
+      'engine-strict': ' Es lo que hace cumplir engines.npm.',
+      'strict-allow-scripts': ' Sin esto, npm ejecuta los install scripts no aprobados.',
+    }[name] ?? '';
+    findings.push({
+      level,
+      file: '.npmrc',
+      line: entry?.line,
+      message:
+        problem === 'missing'
+          ? `Falta \`${line}\` en el .npmrc${where}.${why}`
+          : `\`${setting.key}=${entry.value}\` no cumple la política: usar \`${line}\`.${why}`,
+      data: {
+        key: name,
+        expected: setting.value,
+        actual: entry?.value ?? null,
+        // Sin .npmrc, en texto van todas juntas.
+        ...(npmrcText === null && {
+          pin: line,
+          group: `No hay .npmrc (\`npm-security-kit init\` lo crea). Faltan las claves ${level === 'error' ? 'que exige la política' : 'recomendadas'}:`,
+        }),
+      },
+    });
+  }
+
+  // engines.npm
+  const pkgText = ctx.readFile('package.json');
+  if (pkgText === null) {
+    findings.push({ level: 'error', message: 'No hay package.json en el directorio revisado.' });
+  } else {
+    const pkg = JSON.parse(pkgText);
+    const range = pkg.engines?.npm;
+    const min = typeof range === 'string' ? minVersion(range) : null;
+    if (typeof range !== 'string') {
+      findings.push({
+        level: 'error',
+        file: 'package.json',
+        message: `Falta engines.npm: agregar "npm": ">=${minNpmShort}" en engines (${NPM10_WHY}).`,
+      });
+    } else if (!min || compareVersions(min, minNpm) < 0) {
+      findings.push({
+        level: 'error',
+        file: 'package.json',
+        line: jsonKeyLine(pkgText, ['engines', 'npm']),
+        message: `engines.npm "${range}" admite npm anteriores a ${minNpm} (${NPM10_WHY}). Cambiar a ">=${minNpmShort}".`,
+        data: { range, min },
+      });
+    }
+  }
+
+  // npm en uso
+  const npmVersion = await ctx.runNpm(['--version']);
+  const used = npmVersion.code === 0 ? npmVersion.stdout.trim() : null;
+  if (!used || !parseVersion(used)) {
+    findings.push({ level: 'warn', message: `No se pudo saber la versión de npm en uso (${(npmVersion.stderr || npmVersion.stdout).trim() || 'sin salida'}).` });
+  } else if (compareVersions(used, minNpm) < 0) {
+    findings.push({
+      level: 'error',
+      message: `npm ${used} en uso: hace falta npm >= ${minNpm} (${NPM10_WHY}). En el pipeline, usar la imagen de Node LTS recomendada; en local, \`npm install -g npm@11\`.`,
+      data: { npm: used },
+    });
+  }
+
+  // Lockfile
+  const lockfile = lockfileName(ctx);
+  if (!lockfile) {
+    const other = ['yarn.lock', 'pnpm-lock.yaml'].find((f) => ctx.exists(f));
+    findings.push({
+      level: 'error',
+      message: `No hay package-lock.json: sin lockfile no hay \`npm ci\` ni audit.${other ? ` (${other} no sirve: el kit revisa proyectos npm.)` : ' Generarlo con `npm install --package-lock-only`.'}`,
+    });
+  } else {
+    const lock = ctx.readJson(lockfile);
+    if (!lock.packages) {
+      findings.push({
+        level: 'error',
+        file: lockfile,
+        message: `lockfileVersion ${lock.lockfileVersion ?? '?'}: no trae \`packages\` (ni \`hasInstallScript\`), así que no se pueden revisar los install scripts. Regenerar con npm 11 (\`npm install --package-lock-only\`).`,
+      });
+    } else if (!(lock.lockfileVersion >= 3)) {
+      findings.push({
+        level: 'warn',
+        file: lockfile,
+        message: `lockfileVersion ${lock.lockfileVersion ?? '?'}: regenerar con npm 11 (\`npm install --package-lock-only\`).`,
+      });
+    }
+  }
+  return findings;
+}

package/src/checks/vulnerabilities.js

@@ -0,0 +1,79 @@
+// Vulnerabilidades (que no son malware) en dependencias de producción. Bloquea desde
+// `policy.vulnerabilityLevel`; las `high` van en un solo aviso de resumen.
+import {
+  AuditUnavailableError,
+  advisoriesOf,
+  advisoryKey,
+  isMalware,
+  lockfileName,
+  runAudit,
+  severityAtLeast,
+  unavailableFinding,
+} from '../lib/audit.js';
+
+export const id = 'vulnerabilities';
+export const title = 'Vulnerabilidades en producción';
+
+function fixText(fixAvailable) {
+  if (fixAvailable === true) return 'hay arreglo (npm audit fix)';
+  if (fixAvailable && typeof fixAvailable === 'object') {
+    const target = fixAvailable.name ? `${fixAvailable.name}@${fixAvailable.version}` : 'otra versión';
+    return fixAvailable.isSemVerMajor ? `hay arreglo con ${target}, pero requiere major` : `hay arreglo con ${target}`;
+  }
+  return 'sin arreglo publicado todavía';
+}
+
+export async function run(ctx) {
+  const lockfile = lockfileName(ctx);
+  if (!lockfile) return [];
+  let report;
+  try {
+    report = await runAudit(ctx, ['--omit=dev']);
+  } catch (error) {
+    if (error instanceof AuditUnavailableError) return [unavailableFinding(error)];
+    throw error;
+  }
+  const level = ctx.policy.vulnerabilityLevel;
+  // Advisories por paquete, sin el malware (lo cuenta el chequeo `malware`, sobre todo el árbol).
+  const byPackage = new Map();
+  const seen = new Set();
+  for (const advisory of advisoriesOf(report)) {
+    if (isMalware(advisory, ctx.policy) || seen.has(advisoryKey(advisory))) continue;
+    seen.add(advisoryKey(advisory));
+    if (!byPackage.has(advisory.name)) byPackage.set(advisory.name, []);
+    byPackage.get(advisory.name).push(advisory);
+  }
+  const findings = [];
+  const high = []; // paquetes cuya vulnerabilidad más grave es high (como cuenta npm audit)
+  for (const [name, advisories] of byPackage) {
+    const blocking = advisories.filter((a) => severityAtLeast(a.severity, level));
+    for (const advisory of blocking) {
+      findings.push({
+        level: 'error',
+        file: lockfile,
+        message:
+          `${advisory.name} (${advisory.range}): ${advisory.title} [${advisory.severity}]. ${fixText(advisory.fixAvailable)}.` +
+          (advisory.url ? ` ${advisory.url}` : ''),
+        data: {
+          name: advisory.name,
+          range: advisory.range,
+          title: advisory.title,
+          url: advisory.url,
+          severity: advisory.severity,
+          fixAvailable: advisory.fixAvailable,
+        },
+      });
+    }
+    if (!blocking.length && advisories.some((a) => a.severity === 'high')) high.push(name);
+  }
+  if (high.length) {
+    high.sort();
+    findings.push({
+      level: 'warn',
+      file: lockfile,
+      message: `${high.length} paquete(s) con vulnerabilidades high en producción (${high.join(', ')}). No bloquean; ver \`npm audit --omit=dev\` y planificar el arreglo.`,
+      data: { severity: 'high', count: high.length, packages: high },
+    });
+  }
+  return findings;
+}

package/src/cli.js

@@ -0,0 +1,117 @@
+// Parseo de argumentos y despacho de comandos. Devuelve el exit code:
+// 0 sin errores (puede haber avisos), 1 con al menos un error, 2 por uso incorrecto o fallo interno.
+import { existsSync, statSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { parseArgs } from 'node:util';
+import { checks } from './checks/index.js';
+import { createContext, parseDay } from './context.js';
+import { formatJson, formatText, useColor } from './report.js';
+import { runChecks } from './run.js';
+import { kitVersion } from './version.js';
+
+export const HELP = `npm-security-kit ${kitVersion}
+Reglas de seguridad de dependencias npm, revisadas antes de npm ci.
+
+Uso:
+  npm-security-kit check [dir] [--json] [--base <ref>]
+  npm-security-kit init [dir] [--dry-run]
+  npm-security-kit --version | --help
+
+Comandos:
+  check   Revisa el proyecto sin modificar nada. Va en el pipeline ANTES de npm ci.
+  init    Completa .npmrc y engines, lista los install scripts por aprobar y muestra
+          los cambios sugeridos para el pipeline y los Dockerfiles (no los edita).
+
+Opciones:
+  --json         Salida en JSON (solo check).
+  --base <ref>   Rama base para comparar el lockfile (por defecto, la rama destino del PR
+                 en Bitbucket: origin/$BITBUCKET_PR_DESTINATION_BRANCH).
+  --dry-run      init: muestra el diff sin escribir.
+  -h, --help     Esta ayuda.
+  -v, --version  Versión del kit.
+
+Exit codes: 0 sin errores (puede haber avisos), 1 hay errores, 2 uso incorrecto o fallo del kit.
+`;
+
+const OPTIONS = {
+  json: { type: 'boolean' },
+  base: { type: 'string' },
+  today: { type: 'string' }, // solo para tests; no aparece en --help
+  'dry-run': { type: 'boolean' },
+  help: { type: 'boolean', short: 'h' },
+  version: { type: 'boolean', short: 'v' },
+};
+
+class UsageError extends Error {}
+
+function parse(argv) {
+  let parsed;
+  try {
+    parsed = parseArgs({ args: argv, options: OPTIONS, allowPositionals: true, strict: true });
+  } catch (error) {
+    throw new UsageError(error.message);
+  }
+  const { values, positionals } = parsed;
+  if (values.help || values.version) return { values, command: null };
+  const [command, dir, ...rest] = positionals;
+  if (!command) throw new UsageError('falta el comando');
+  if (!['check', 'init'].includes(command)) throw new UsageError(`comando desconocido: ${command}`);
+  if (rest.length) throw new UsageError(`argumento de más: ${rest.join(' ')}`);
+  if (command !== 'check' && (values.json || values.base)) throw new UsageError(`--json y --base son opciones de check`);
+  if (command !== 'init' && values['dry-run']) throw new UsageError('--dry-run es una opción de init');
+  if (values.today !== undefined && !parseDay(values.today)) throw new UsageError(`--today espera YYYY-MM-DD: ${values.today}`);
+  return { values, command, dir };
+}
+
+export async function main(argv, io = {}) {
+  const {
+    stdout = process.stdout,
+    stderr = process.stderr,
+    env = process.env,
+    cwd = process.cwd(),
+    contextOptions = {},
+    checkList = checks,
+  } = io;
+  let args;
+  try {
+    args = parse(argv);
+  } catch (error) {
+    if (!(error instanceof UsageError)) throw error;
+    stderr.write(`npm-security-kit: ${error.message}\n\n${HELP}`);
+    return 2;
+  }
+  if (args.values.help) {
+    stdout.write(HELP);
+    return 0;
+  }
+  if (args.values.version) {
+    stdout.write(`${kitVersion}\n`);
+    return 0;
+  }
+
+  const dir = resolve(cwd, args.dir ?? '.');
+  if (!existsSync(dir) || !statSync(dir).isDirectory()) {
+    stderr.write(`npm-security-kit: no existe el directorio ${dir}\n`);
+    return 2;
+  }
+  const ctx = createContext({
+    dir,
+    env,
+    today: parseDay(args.values.today),
+    base: args.values.base,
+    ...contextOptions,
+  });
+
+  if (args.command === 'init') {
+    const { runInit } = await import('./init.js');
+    return runInit(ctx, { dryRun: Boolean(args.values['dry-run']), stdout, color: useColor(stdout, env) });
+  }
+
+  const { results, summary } = await runChecks(checkList, ctx);
+  if (args.values.json) {
+    stdout.write(formatJson({ kitVersion, policy: ctx.policy, results, summary }));
+  } else {
+    stdout.write(formatText({ kitVersion, dir, checks: checkList, results, summary }, { color: useColor(stdout, env) }));
+  }
+  return summary.errors ? 1 : 0;
+}

package/src/context.js

@@ -0,0 +1,147 @@
+// Arma el `ctx` que reciben los chequeos. Todo acceso a archivos, a npm, a git y a la red pasa
+// por acá, para que los tests puedan reemplazarlo sin red ni procesos.
+import { execFile } from 'node:child_process';
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { join, relative, sep } from 'node:path';
+import { policy as defaultPolicy } from './policy.js';
+import { kitVersion } from './version.js';
+
+export class NetworkError extends Error {
+  constructor(message, { url, status } = {}) {
+    super(message);
+    this.name = 'NetworkError';
+    this.url = url;
+    this.status = status;
+  }
+}
+
+// Directorios que no se recorren al buscar Dockerfiles.
+const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'coverage']);
+
+export const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+// Fecha `YYYY-MM-DD` a medianoche UTC. Sin argumento, hoy.
+export function parseDay(value) {
+  const text = value ?? new Date().toISOString().slice(0, 10);
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(text)) return null;
+  const date = new Date(`${text}T00:00:00Z`);
+  return Number.isNaN(date.getTime()) || date.toISOString().slice(0, 10) !== text ? null : date;
+}
+
+function runProcess(cmd, args, options) {
+  return new Promise((resolve) => {
+    execFile(cmd, args, { maxBuffer: 256 * 1024 * 1024, windowsHide: true, ...options }, (error, stdout, stderr) => {
+      if (error && typeof error.code !== 'number') {
+        // No se pudo ejecutar (por ejemplo, ENOENT): no hay exit code.
+        resolve({ code: -1, stdout: stdout ?? '', stderr: stderr || error.message });
+        return;
+      }
+      resolve({ code: error ? error.code : 0, stdout: stdout ?? '', stderr: stderr ?? '' });
+    });
+  });
+}
+
+export function createContext({
+  dir,
+  env = process.env,
+  today = parseDay(),
+  policy = defaultPolicy,
+  platform = process.platform,
+  arch = process.arch,
+  base,
+  fetchImpl = globalThis.fetch,
+  wait = sleep,
+} = {}) {
+  const abs = (file) => join(dir, file);
+
+  const readFile = (file) => {
+    try {
+      // Sin BOM: npm lo ignora y JSON.parse no.
+      return readFileSync(abs(file), 'utf8').replace(/^\uFEFF/, '');
+    } catch (error) {
+      if (error.code === 'ENOENT' || error.code === 'EISDIR') return null;
+      throw error;
+    }
+  };
+
+  const readJson = (file) => {
+    const text = readFile(file);
+    if (text === null) return null;
+    try {
+      return JSON.parse(text);
+    } catch (error) {
+      throw new Error(`${file} no es JSON válido (${error.message})`);
+    }
+  };
+
+  // Lista archivos (rutas relativas con `/`) hasta `maxDepth` niveles bajo `dir`.
+  const listFiles = (match, maxDepth = 3) => {
+    const out = [];
+    const walk = (current, depth) => {
+      let entries;
+      try {
+        entries = readdirSync(current);
+      } catch {
+        return;
+      }
+      for (const name of entries.sort()) {
+        const full = join(current, name);
+        let stats;
+        try {
+          stats = statSync(full);
+        } catch {
+          continue;
+        }
+        if (stats.isDirectory()) {
+          if (depth < maxDepth && !SKIP_DIRS.has(name)) walk(full, depth + 1);
+        } else if (match(name)) {
+          out.push(relative(dir, full).split(sep).join('/'));
+        }
+      }
+    };
+    walk(dir, 0);
+    return out;
+  };
+
+  const fetchJson = async (url, { retries = 2, timeoutMs = 15000 } = {}) => {
+    let lastError;
+    for (let attempt = 0; attempt <= retries; attempt++) {
+      if (attempt > 0) await wait(1000 * 2 ** (attempt - 1));
+      try {
+        const res = await fetchImpl(url, {
+          signal: AbortSignal.timeout(timeoutMs),
+          headers: { accept: 'application/json' },
+        });
+        if (res.status === 404) throw new NetworkError(`${url}: HTTP 404`, { url, status: 404 });
+        if (!res.ok) {
+          lastError = new NetworkError(`${url}: HTTP ${res.status}`, { url, status: res.status });
+          continue;
+        }
+        return await res.json();
+      } catch (error) {
+        if (error instanceof NetworkError && error.status === 404) throw error;
+        lastError = error instanceof NetworkError ? error : new NetworkError(`${url}: ${error.message}`, { url });
+      }
+    }
+    throw lastError;
+  };
+
+  return {
+    dir,
+    env,
+    today,
+    policy,
+    platform,
+    arch,
+    base,
+    kitVersion,
+    readFile,
+    readJson,
+    exists: (file) => existsSync(abs(file)),
+    listFiles,
+    runNpm: (args) => runProcess('npm', args, { cwd: dir, env, shell: process.platform === 'win32' }),
+    git: (args) => runProcess('git', args, { cwd: dir, env }),
+    fetchJson,
+    sleep: wait,
+  };
+}