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

package/package.json

@@ -1,51 +1,35 @@
 {
   "name": "@theoptimalpartner/npm-security-kit",
-  "version": "1.0.1",
-  "description": "Portable security kit to protect Node.js/npm projects against malicious packages and vulnerabilities",
-  "main": "src/index.js",
+  "version": "2.0.0-beta.0",
+  "description": "Revisa el lockfile antes de npm ci: malware, vulnerabilidades, versión de Node, .npmrc, install scripts y Dockerfiles",
+  "type": "module",
   "bin": {
-    "npm-security-install": "bin/install.js",
-    "npm-security-check": "bin/check.js"
+    "npm-security-kit": "bin/npm-security-kit.js"
   },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
   "scripts": {
-    "test": "echo \"No tests specified - package verified with npm pack\"",
-    "prepare": "chmod +x bin/*.js"
+    "test": "node --test"
   },
   "keywords": [
     "security",
     "npm",
-    "malicious-packages",
     "supply-chain",
-    "vulnerability",
+    "malware",
     "audit",
-    "phishing",
-    "typosquatting",
-    "socket.dev",
-    "dependabot",
-    "github-actions"
+    "allowScripts",
+    "min-release-age"
   ],
-  "author": "The Optimal",
+  "author": "The Optimal Partner",
   "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://bitbucket.org/RoutingUC/npm-security-kit.git"
-  },
   "engines": {
-    "node": ">=14.0.0",
-    "npm": ">=6.0.0"
+    "node": ">=18.3"
   },
-  "files": [
-    "bin/",
-    "src/",
-    "template/",
-    "README.md",
-    "LICENSE",
-    "QUICK_START.md",
-    "EXAMPLES.md"
-  ],
-  "dependencies": {},
-  "devDependencies": {},
-  "peerDependencies": {},
   "publishConfig": {
     "access": "public"
   }

package/src/checks/dockerfile.js

@@ -0,0 +1,217 @@
+// La política npm también tiene que aplicar dentro del `docker build`: el .npmrc se copia antes de
+// `npm ci`, y se usa `npm ci` (reproducible) en vez de `npm install`.
+import { findDockerfiles, parseStages } from '../lib/dockerfile.js';
+
+export const id = 'dockerfile';
+export const title = 'Dockerfiles';
+
+// Subcomandos de npm que instalan desde el lockfile (o lo actualizan). `npm run`, `npm prune`,
+// `npm rebuild` no cuentan.
+const CI_SUBS = new Set(['ci', 'clean-install', 'ic', 'install-clean', 'isntall-clean', 'cit', 'install-ci-test', 'clean-install-test']);
+const INSTALL_SUBS = new Set([...CI_SUBS, 'install', 'i', 'in', 'ins', 'inst', 'insta', 'instal', 'isnt', 'isnta', 'isntal', 'isntall', 'add', 'it', 'install-test']);
+// Opciones de npm que llevan valor aparte (`npm --prefix app ci`).
+const VALUE_OPTS = new Set(['--prefix', '-C', '--workspace', '-w', '--cache', '--registry', '--userconfig', '--globalconfig', '--loglevel', '--location', '--tag']);
+
+// Los `npm <subcomando que instala>` de un RUN, en forma shell o exec (`["npm","ci"]`), con
+// `{ sub, global }`. Un `npm install -g …` instala una herramienta, no las dependencias del proyecto.
+export function npmInstalls(args) {
+  let command = args.replace(/^(--[\w-]+(=\S+)?\s+)+/, ''); // --mount, --network, …
+  if (command.trim().startsWith('[')) {
+    try {
+      command = JSON.parse(command).join(' ');
+    } catch {
+      // queda como texto
+    }
+  }
+  const tokens = command.replace(/["'`]/g, ' ').replace(/&&|\|\||[;|()]/g, ' ; ').split(/\s+/).filter(Boolean);
+  const found = [];
+  for (let i = 0; i < tokens.length; i++) {
+    if (tokens[i] !== 'npm' && !tokens[i].endsWith('/npm')) continue;
+    let j = i + 1;
+    let global = false;
+    while (j < tokens.length && tokens[j].startsWith('-')) {
+      if (/^(-g|--global|--location=global)$/.test(tokens[j])) global = true;
+      if (VALUE_OPTS.has(tokens[j])) j++;
+      j++;
+    }
+    const sub = tokens[j];
+    if (!INSTALL_SUBS.has(sub)) continue;
+    for (let k = j + 1; k < tokens.length && tokens[k] !== ';'; k++) {
+      if (/^(-g|--global|--location=global)$/.test(tokens[k])) global = true;
+    }
+    found.push({ sub, global, ci: CI_SUBS.has(sub) });
+  }
+  return found;
+}
+
+// `RUN --mount=type=bind,source=.npmrc,…` o un secret montado en la carpeta del proyecto.
+function mountsNpmrc(args) {
+  for (const m of args.matchAll(/--mount=(\S+)/g)) {
+    const opts = Object.fromEntries(m[1].split(',').map((kv) => kv.split('=')));
+    const type = opts.type ?? 'bind';
+    if (type === 'bind' && /(^|\/)\.npmrc$/.test(opts.source ?? opts.src ?? '')) return true;
+    const target = opts.target ?? opts.dst ?? opts.destination ?? '';
+    if (type === 'secret' && /(^|\/)\.npmrc$/.test(target) && !/^(\/root\/|~|\$HOME)/.test(target)) return true;
+  }
+  return false;
+}
+
+const FLAG = /^--[\w-]+(=\S*)?$/;
+
+const dirOf = (file) => (file.includes('/') ? file.slice(0, file.lastIndexOf('/')) : '');
+const join = (dir, name) => (dir ? `${dir}/${name}` : name);
+
+// Glob de Docker (filepath.Match más `**`) a regex sobre rutas relativas al contexto.
+function globToRegex(pattern) {
+  let re = '';
+  for (let i = 0; i < pattern.length; i++) {
+    const c = pattern[i];
+    if (c === '*' && pattern[i + 1] === '*') {
+      i++;
+      if (pattern[i + 1] === '/') {
+        i++;
+        re += '(?:.*/)?';
+      } else {
+        re += '.*';
+      }
+    } else if (c === '*') re += '[^/]*';
+    else if (c === '?') re += '[^/]';
+    else re += c.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+  }
+  return new RegExp(`^${re}(?:/.*)?$`);
+}
+
+// ¿El .dockerignore excluye `path`? Devuelve la regla que lo excluye (la última que coincide gana).
+export function dockerignoreExcludes(text, path) {
+  let hit = null;
+  (text ?? '').split(/\r?\n/).forEach((raw, i) => {
+    let pattern = raw.trim();
+    if (!pattern || pattern.startsWith('#')) return;
+    const negate = pattern.startsWith('!');
+    if (negate) pattern = pattern.slice(1).trim();
+    pattern = pattern.replace(/^\/+/, '').replace(/^\.\//, '');
+    if (!pattern || !globToRegex(pattern).test(path)) return;
+    hit = negate ? null : { pattern: raw.trim(), line: i + 1 };
+  });
+  return hit;
+}
+
+// Fuentes y destino de un COPY/ADD, sin flags. `null` si copia de otra etapa (`--from`).
+export function copyParts(args) {
+  let tokens;
+  const json = args.match(/^((?:--\S+\s+)*)(\[.*\])\s*$/);
+  if (json) {
+    try {
+      tokens = [...json[1].split(/\s+/).filter(Boolean), ...JSON.parse(json[2])];
+    } catch {
+      tokens = args.split(/\s+/);
+    }
+  } else {
+    tokens = args.split(/\s+/).filter(Boolean);
+  }
+  const from = tokens.find((t) => /^--from=/.test(t))?.slice('--from='.length).toLowerCase();
+  const paths = tokens.filter((t) => !FLAG.test(t));
+  if (paths.length < 2) return null;
+  return { from, flags: tokens.filter((t) => FLAG.test(t)), sources: paths.slice(0, -1), dest: paths.at(-1) };
+}
+
+const basename = (p) => p.replace(/\/+$/, '').split('/').pop();
+const WHOLE_CONTEXT = new Set(['.', './', '*']);
+const bringsNpmrc = (src) => WHOLE_CONTEXT.has(src) || globToRegex(basename(src)).test('.npmrc');
+const isManifest = (src) => /^(\.\/)?(package(-lock)?\.json|package\*\.json|npm-shrinkwrap\.json)$/.test(src);
+
+// El COPY que conviene corregir: el último anterior al RUN que trae el lockfile o package*.json.
+function suggestion(copies, runLine) {
+  const target = [...copies].reverse().find((c) => !c.parts.from && c.parts.sources.some(isManifest));
+  if (!target) return `agregar \`COPY .npmrc ./\` antes de la línea ${runLine}`;
+  const { flags, sources, dest } = target.parts;
+  const fixed = ['COPY', ...flags, ...sources, '.npmrc', dest].join(' ');
+  return `agregar .npmrc al COPY de la línea ${target.line} (\`${fixed}\`)`;
+}
+
+export async function run(ctx) {
+  const findings = [];
+  const reportedIgnores = new Set();
+  for (const file of findDockerfiles(ctx)) {
+    // Contexto de build: la carpeta del Dockerfile si tiene su propio .dockerignore o package.json;
+    // si no, la raíz del repo (como `docker build -f pipeline/Dockerfile .`).
+    const own = dirOf(file);
+    const context = own && (ctx.exists(join(own, '.dockerignore')) || ctx.exists(join(own, 'package.json'))) ? own : '';
+    const hasNpmrc = ctx.exists(join(context, '.npmrc'));
+    const ignoreFile = ctx.exists(`${file}.dockerignore`) ? `${file}.dockerignore` : join(context, '.dockerignore');
+    const ignoreText = ctx.readFile(ignoreFile);
+    const npmrcIgnored = hasNpmrc ? dockerignoreExcludes(ignoreText, '.npmrc') : null;
+    const lockIgnored = dockerignoreExcludes(ignoreText, 'package-lock.json');
+
+    let installs = false;
+    // Qué etapas ya tienen el .npmrc (por nombre e índice), para `FROM <etapa>` y `COPY --from`.
+    const withNpmrc = new Map();
+    const stages = parseStages(ctx.readFile(file) ?? '');
+    stages.forEach((stage, index) => {
+      const parent = stage.from.image.toLowerCase();
+      let brought = withNpmrc.get(parent) ?? false;
+      const copies = [];
+      let reported = false;
+      for (const ins of stage.instructions) {
+        if (ins.instruction === 'COPY' || ins.instruction === 'ADD') {
+          const parts = copyParts(ins.args);
+          if (!parts) continue;
+          copies.push({ line: ins.line, parts });
+          if (parts.from === undefined) {
+            if (parts.sources.some(bringsNpmrc)) brought = true;
+          } else if (parts.sources.some((src) => globToRegex(basename(src)).test('.npmrc'))) {
+            brought = true;
+          } else if (withNpmrc.get(parts.from) && parts.sources.some((src) => !/\.[\w-]+$/.test(basename(src)) || WHOLE_CONTEXT.has(src))) {
+            // Copia una carpeta entera de una etapa que tenía el .npmrc.
+            brought = true;
+          }
+          continue;
+        }
+        if (ins.instruction !== 'RUN') continue;
+        const local = npmInstalls(ins.args).filter((n) => !n.global);
+        if (!local.length) continue;
+        installs = true;
+        if (hasNpmrc && !brought && !mountsNpmrc(ins.args) && !reported) {
+          reported = true;
+          findings.push({
+            level: 'error',
+            file,
+            line: ins.line,
+            message: `Instala sin el .npmrc (strict-allow-scripts, min-release-age y engine-strict no aplican dentro de la imagen): ${suggestion(copies, ins.line)}.`,
+          });
+        }
+        for (const n of local.filter((x) => !x.ci)) {
+          findings.push({
+            level: 'warn',
+            file,
+            line: ins.line,
+            message: `Usa \`npm ${n.sub}\` en vez de \`npm ci\`: no es reproducible y puede cambiar versiones respecto del lockfile. Usar \`npm ci\`.`,
+          });
+        }
+      }
+      withNpmrc.set(String(index), brought);
+      if (stage.name) withNpmrc.set(stage.name, brought);
+    });
+
+    if (!installs || reportedIgnores.has(ignoreFile)) continue;
+    if (npmrcIgnored) {
+      reportedIgnores.add(ignoreFile);
+      findings.push({
+        level: 'error',
+        file: ignoreFile,
+        line: npmrcIgnored.line,
+        message: `\`${npmrcIgnored.pattern}\` excluye el .npmrc del contexto de build: el npm de la imagen no recibe la política. Agregar \`!.npmrc\` al final del .dockerignore.`,
+      });
+    }
+    if (lockIgnored) {
+      reportedIgnores.add(ignoreFile);
+      findings.push({
+        level: 'warn',
+        file: ignoreFile,
+        line: lockIgnored.line,
+        message: `\`${lockIgnored.pattern}\` excluye el package-lock.json del contexto de build: la imagen instala versiones que no son las del lockfile revisado. Quitar esa línea y usar \`npm ci\`.`,
+      });
+    }
+  }
+  return findings;
+}

package/src/checks/index.js

@@ -0,0 +1,10 @@
+// Lista ordenada de chequeos de `check`. Cada uno exporta `{ id, title, run(ctx) }` y `run`
+// devuelve hallazgos `{ level: 'error'|'warn'|'info', message, file?, line?, data? }`.
+import * as dockerfile from './dockerfile.js';
+import * as installScripts from './install-scripts.js';
+import * as malware from './malware.js';
+import * as nodeVersion from './node-version.js';
+import * as npmPolicy from './npm-policy.js';
+import * as vulnerabilities from './vulnerabilities.js';
+
+export const checks = [malware, vulnerabilities, nodeVersion, npmPolicy, installScripts, dockerfile];

package/src/checks/install-scripts.js

@@ -0,0 +1,77 @@
+// Install scripts sin aprobar, antes de `npm ci`: los paquetes del lockfile con
+// `hasInstallScript` contra allowScripts. Con strict-allow-scripts es error (npm ci va a fallar);
+// con el override `npm_config_strict_allow_scripts=false` es aviso y se deja constancia.
+import { loadAllowPolicy, verdict } from '../lib/allow-scripts.js';
+import { lockfileName } from '../lib/audit.js';
+import { jsonKeyLine } from '../lib/json-lines.js';
+import { installsOn, lockEntries } from '../lib/lockfile.js';
+import { parseNpmrc } from '../lib/npmrc.js';
+
+export const id = 'install-scripts';
+export const title = 'Install scripts (allowScripts)';
+
+export const OVERRIDE_ENV = 'npm_config_strict_allow_scripts';
+
+// Paquetes del lockfile con install scripts que npm ejecutaría en esta plataforma.
+export function packagesWithScripts(lock, platform) {
+  return [...lockEntries(lock)].filter(({ entry }) => entry.hasInstallScript && !entry.inBundle && installsOn(entry, platform));
+}
+
+export async function run(ctx) {
+  const lockfile = lockfileName(ctx);
+  if (!lockfile) return []; // lo informa npm-policy
+  const lock = ctx.readJson(lockfile);
+  const pkgText = ctx.readFile('package.json');
+  const pkg = pkgText === null ? {} : JSON.parse(pkgText);
+  const npmrcText = ctx.readFile('.npmrc');
+  const findings = [];
+
+  const policy = loadAllowPolicy(pkg, npmrcText);
+  for (const rule of policy.ignored) {
+    findings.push({
+      level: 'warn',
+      file: 'package.json',
+      line: jsonKeyLine(pkgText, ['allowScripts', rule.key]),
+      message: `allowScripts: npm ignora "${rule.key}" (${rule.ignored}): usar versiones exactas unidas por "||", o solo el nombre. Mientras tanto, ese paquete queda sin aprobar.`,
+    });
+  }
+
+  // Modo efectivo (incluye el override por variable de entorno) contra lo que dice el repo.
+  const effective = await ctx.runNpm(['config', 'get', 'strict-allow-scripts']);
+  const repoStrict = parseNpmrc(npmrcText).get('strict-allow-scripts')?.value === 'true';
+  const strict = effective.code === 0 ? effective.stdout.trim() === 'true' : repoStrict;
+  const overridden = repoStrict && !strict;
+
+  const pending = [];
+  const seen = new Set();
+  for (const dep of packagesWithScripts(lock, ctx)) {
+    if (verdict(policy.rules, dep) !== null) continue;
+    const label = `${dep.name}@${dep.version}`;
+    if (seen.has(label)) continue;
+    seen.add(label);
+    pending.push({ ...dep, label });
+  }
+
+  const effect = strict ? 'npm ci va a fallar' : 'se van a ejecutar en npm ci';
+  const group = `Install scripts sin aprobar en allowScripts: ${effect}. Revisarlos con \`npm ci --ignore-scripts\` y \`npm install-scripts ls\`, y después \`npm install-scripts approve <paquete>\` o \`npm install-scripts deny <paquete>\`.`;
+  for (const dep of pending) {
+    const os = dep.entry.optional && dep.entry.os ? ` (opcional, solo ${dep.entry.os.join('/')})` : '';
+    const how = `Revisarlo con \`npm ci --ignore-scripts\` y \`npm install-scripts ls\`, y después \`npm install-scripts approve ${dep.name}\` o \`npm install-scripts deny ${dep.name}\`.`;
+    findings.push({
+      level: strict ? 'error' : 'warn',
+      file: lockfile,
+      message: strict
+        ? `${dep.label}${os} tiene install scripts y no está aprobado en allowScripts: npm ci va a fallar. ${how}`
+        : `${dep.label}${os} tiene install scripts y no está aprobado en allowScripts: se va a ejecutar en npm ci. ${how}`,
+      data: { name: dep.name, version: dep.version, key: dep.key, pin: `${dep.label}${os}`, group },
+    });
+  }
+  if (overridden) {
+    findings.push({
+      level: 'warn',
+      message: `strict-allow-scripts desactivado por la variable de entorno \`${OVERRIDE_ENV}\`; los install scripts no aprobados se van a ejecutar.`,
+      data: { override: OVERRIDE_ENV },
+    });
+  }
+  return findings;
+}

package/src/checks/malware.js

@@ -0,0 +1,61 @@
+// Malware en todo el árbol (incluidas las devDependencies), con cualquier severidad.
+// GitHub publica malware como `high` (debug@4.4.2): un umbral de severidad lo deja pasar.
+import { AuditUnavailableError, advisoriesOf, advisoryKey, isMalware, lockfileName, runAudit, unavailableFinding } from '../lib/audit.js';
+
+export const id = 'malware';
+export const title = 'Malware (todo el árbol, cualquier severidad)';
+
+const INCIDENT =
+  'Si llegó a instalarse en alguna máquina o pipeline, tratarlo como incidente: rotar los tokens y secretos de ese entorno (npm, CI, nube).';
+
+function installed(lock, nodes) {
+  const found = [];
+  for (const node of nodes) {
+    const entry = lock?.packages?.[node];
+    if (!entry?.version) continue;
+    found.push({ node, version: entry.version, dev: Boolean(entry.dev || entry.devOptional) });
+  }
+  return found;
+}
+
+export async function run(ctx) {
+  const lockfile = lockfileName(ctx);
+  if (!lockfile) return []; // sin lockfile no hay audit; lo informa npm-policy
+  let report;
+  try {
+    report = await runAudit(ctx, ['--include=dev', '--include=optional', '--include=peer']);
+  } catch (error) {
+    if (error instanceof AuditUnavailableError) return [unavailableFinding(error)];
+    throw error;
+  }
+  const lock = ctx.readJson(lockfile);
+  const seen = new Set();
+  const findings = [];
+  for (const advisory of advisoriesOf(report)) {
+    if (!isMalware(advisory, ctx.policy) || seen.has(advisoryKey(advisory))) continue;
+    seen.add(advisoryKey(advisory));
+    const copies = installed(lock, advisory.nodes);
+    const versions = [...new Set(copies.map((c) => c.version))];
+    const label = versions.length ? versions.map((v) => `${advisory.name}@${v}`).join(', ') : `${advisory.name} (${advisory.range})`;
+    const dev = copies.length && copies.every((c) => c.dev) ? ' (devDependency)' : '';
+    findings.push({
+      level: 'error',
+      file: lockfile,
+      message:
+        `${label}${dev}: ${advisory.title}. Es malware aunque la severidad del advisory diga "${advisory.severity}". ` +
+        `Quitarlo o cambiar a una versión fuera del rango ${advisory.range}. ${INCIDENT}` +
+        (advisory.url ? ` ${advisory.url}` : ''),
+      data: {
+        name: advisory.name,
+        range: advisory.range,
+        title: advisory.title,
+        url: advisory.url,
+        severity: advisory.severity,
+        cwe: advisory.cwe,
+        nodes: advisory.nodes,
+        versions,
+      },
+    });
+  }
+  return findings;
+}

package/src/checks/node-version.js

@@ -0,0 +1,234 @@
+// Versión de Node: pasa cualquier LTS con soporte (Active o Maintenance); se avisa si hay una LTS
+// más nueva, si quedan pocos días de soporte o si hay parches de seguridad pendientes. Una línea
+// sin soporte o que no es LTS es error. Todo sale del calendario de nodejs.org.
+import { findDockerfiles, nodeImageTag, parseStages } from '../lib/dockerfile.js';
+import { jsonKeyLine } from '../lib/json-lines.js';
+import { loadCalendar } from '../lib/node-calendar.js';
+import { isRange, minVersion, parseVersion } from '../lib/semver.js';
+
+export const id = 'node-version';
+export const title = 'Versión de Node';
+
+const PIPELINE = 'bitbucket-pipelines.yml';
+// Tags de la imagen oficial que siguen a la última release de Node (la Current).
+const LATEST_TAGS = /^(latest|current|alpine|slim|bookworm|bullseye|buster|trixie|stretch|jessie|wheezy|windowsservercore|nanoserver)$/;
+
+// Dónde fija el proyecto la versión de Node: `{ file, line?, pin, spec, kind }`.
+export function findPins(ctx) {
+  const pins = [];
+  for (const file of ['.nvmrc', '.node-version']) {
+    const text = ctx.readFile(file);
+    if (text === null) continue;
+    const lines = text.split(/\r?\n/);
+    const idx = lines.findIndex((l) => l.replace(/#.*/, '').trim());
+    if (idx >= 0) {
+      const spec = lines[idx].replace(/#.*/, '').trim();
+      pins.push({ file, line: idx + 1, pin: spec, spec, kind: 'version-file' });
+    }
+  }
+  const tool = ctx.readFile('.tool-versions');
+  tool?.split(/\r?\n/).forEach((l, i) => {
+    const m = l.match(/^\s*(?:nodejs|node)\s+(\S+)/);
+    if (m) pins.push({ file: '.tool-versions', line: i + 1, pin: l.trim(), spec: m[1], kind: 'version-file' });
+  });
+
+  const pkgText = ctx.readFile('package.json');
+  if (pkgText !== null) {
+    const pkg = JSON.parse(pkgText);
+    if (typeof pkg.engines?.node === 'string') {
+      const line = jsonKeyLine(pkgText, ['engines', 'node']);
+      pins.push({ file: 'package.json', line, pin: `engines.node: ${pkg.engines.node}`, spec: pkg.engines.node, kind: 'engines' });
+    }
+    if (typeof pkg.volta?.node === 'string') {
+      const line = jsonKeyLine(pkgText, ['volta', 'node']);
+      pins.push({ file: 'package.json', line, pin: `volta.node: ${pkg.volta.node}`, spec: pkg.volta.node, kind: 'version-file' });
+    }
+  }
+
+  for (const file of findDockerfiles(ctx)) {
+    for (const stage of parseStages(ctx.readFile(file) ?? '')) {
+      const tag = nodeImageTag(stage.from.image);
+      if (tag !== null) pins.push({ file, line: stage.from.line, pin: stage.from.raw, spec: tag, kind: 'docker' });
+    }
+  }
+
+  const pipeline = ctx.readFile(PIPELINE);
+  if (pipeline !== null) {
+    for (const { image, line, raw } of pipelineImages(pipeline)) {
+      const tag = nodeImageTag(image);
+      pins.push({ file: PIPELINE, line, pin: raw, spec: tag ?? image, kind: tag === null ? 'other-image' : 'docker' });
+    }
+  }
+  return pins;
+}
+
+// `image: x`, `- image: x`, `image: &ancla x`, `image: *ancla`, `image: { name: x }` e `image:`
+// seguido de `name: x` en las líneas siguientes (con o sin comillas).
+export function pipelineImages(text) {
+  const out = [];
+  const lines = text.split(/\r?\n/);
+  const clean = (v) => v.replace(/\s+#.*$/, '').trim().replace(/^["']|["']$/g, '');
+  // Anclas YAML definidas en cualquier lugar: `&nombre valor`.
+  const anchors = new Map();
+  for (const l of lines) {
+    const m = l.match(/&([\w-]+)\s+([^\s{][^#]*?)\s*(?:#.*)?$/);
+    if (m) anchors.set(m[1], clean(m[2]));
+  }
+  const resolve = (value) => {
+    let v = value;
+    const alias = v.match(/^\*([\w-]+)$/);
+    if (alias) return anchors.get(alias[1]) ?? null;
+    v = v.replace(/^&[\w-]+\s*/, '');
+    const flow = v.match(/^\{(.*)\}$/);
+    if (flow) {
+      const name = flow[1].match(/(?:^|,)\s*name\s*:\s*([^,}]+)/);
+      return name ? clean(name[1]) : null;
+    }
+    return v ? clean(v) : null;
+  };
+  for (let i = 0; i < lines.length; i++) {
+    const m = lines[i].match(/^(\s*)(?:-\s+)?image:\s*(.*)$/);
+    if (!m) continue;
+    const value = clean(m[2]);
+    if (value && value.replace(/^&[\w-]+\s*$/, '')) {
+      const image = resolve(value);
+      if (image) out.push({ image, line: i + 1, raw: lines[i].trim() });
+      continue;
+    }
+    // Forma `image:` con `name:` en las líneas siguientes, más indentadas.
+    const indent = m[1].length;
+    for (let j = i + 1; j < lines.length; j++) {
+      if (!lines[j].trim() || /^\s*#/.test(lines[j])) continue;
+      const ind = lines[j].match(/^(\s*)/)[1].length;
+      if (ind <= indent) break;
+      const n = lines[j].match(/^\s*name:\s*(.+)$/);
+      if (n) {
+        const image = resolve(clean(n[1]));
+        if (image) out.push({ image, line: j + 1, raw: lines[j].trim() });
+        break;
+      }
+    }
+  }
+  return out;
+}
+
+// Qué línea de Node fija un pin: `{ major, exact?, range?, floating?, latest? }` o `{ note }`.
+export function resolvePin(pin, cal) {
+  if (pin.kind === 'other-image') return { otherImage: true };
+  let spec = pin.spec.trim();
+  if (pin.kind === 'docker') {
+    if (/^\d/.test(spec)) {
+      spec = spec.split('-')[0];
+    } else {
+      const head = spec.split('-')[0].toLowerCase();
+      if (head === 'lts') return { major: cal.latestLtsMajor, floating: `tag "${pin.spec}"` };
+      if (LATEST_TAGS.test(head)) return { major: cal.latestMajor, floating: `tag "${pin.spec}"`, latest: true };
+      const byCodename = cal.majorOfCodename(head);
+      if (byCodename !== null) return { major: byCodename, floating: `tag "${pin.spec}"` };
+      return { note: `no se entiende el tag "${pin.spec}"` };
+    }
+  }
+  const lts = spec.match(/^lts\/(\*|[a-z]+)$/i);
+  if (lts) {
+    if (lts[1] === '*') return { major: cal.latestLtsMajor, floating: `"${spec}"` };
+    const major = cal.majorOfCodename(lts[1]);
+    return major !== null ? { major, floating: `"${spec}"` } : { note: `codename desconocido: ${spec}` };
+  }
+  if (/^(node|stable|latest|current)$/i.test(spec)) return { major: cal.latestMajor, floating: `"${spec}"`, latest: true };
+  if (isRange(spec)) {
+    const min = minVersion(spec);
+    return min ? { major: parseVersion(min)[0], range: true } : { note: `no se entiende el rango "${spec}"` };
+  }
+  const v = parseVersion(spec);
+  if (!v) return { note: `no se entiende "${spec}"` };
+  const parts = spec.replace(/^v/, '').split('.').length;
+  return { major: v[0], exact: parts === 3 ? v.join('.') : undefined };
+}
+
+function evaluate(pin, r, cal, policy) {
+  const base = { file: pin.file, line: pin.line };
+  if (r.otherImage) {
+    return { ...base, level: 'info', message: `${pin.spec}: imagen sin Node fijado (la versión de Node la decide la imagen).`, data: { pin: pin.pin } };
+  }
+  if (r.note) return { ...base, level: 'warn', message: `${r.note}: no se puede saber qué versión de Node corre.`, data: { pin: pin.pin } };
+
+  const sch = cal.lines.get(r.major);
+  const prefix = `${r.range ? 'el rango admite desde ' : ''}v${r.major}${r.floating ? ` (${r.floating})` : ''}`;
+  const rec = cal.recommended;
+  const engineHint = pin.kind === 'engines' ? ` (en engines: ">=${parseVersion(rec)[0]}")` : '';
+  const data = { pin: pin.pin, major: r.major, phase: cal.phaseOf(r.major), recommended: rec };
+  if (!sch) return { ...base, level: 'warn', message: `${prefix}: no aparece en el calendario de Node.`, data };
+
+  const phase = cal.phaseOf(r.major);
+  if (phase === 'eol') {
+    return { ...base, level: 'error', message: `${prefix}: sin soporte desde ${sch.end}. Actualizar a ${rec}${engineHint}.`, data };
+  }
+  if (phase === 'not-lts') {
+    const why = sch.lts ? `todavía no es LTS (lo será el ${sch.lts})` : 'línea impar, nunca va a ser LTS';
+    return { ...base, level: 'error', message: `${prefix}: no es LTS, ${why}. Usar ${rec}${engineHint}.`, data };
+  }
+
+  const notes = [];
+  // Mientras la LTS nueva no tiene su primera release LTS nadie puede migrar: se informa sin avisar.
+  const infoNotes = [];
+  if (r.latest) notes.push(`El tag sigue a la última release de Node aunque no sea LTS: fijar una versión LTS (${rec}).`);
+  if (cal.newestLts > r.major) {
+    const n = cal.lines.get(cal.newestLts);
+    if (cal.newestLtsWithoutRelease) {
+      infoNotes.push(`Hay una LTS nueva (v${cal.newestLts}, desde ${n.lts}), aún sin release LTS: planificar la migración cuando salga.`);
+    } else {
+      notes.push(`Hay una LTS nueva (v${cal.newestLts}, desde ${n.lts}): planificar la migración.`);
+    }
+  }
+  const days = cal.daysUntilEnd(r.major);
+  if (days < policy.nodeEolWarnDays && !(cal.newestLts > r.major)) {
+    const next = cal.nextLtsAfter(r.major);
+    if (next) notes.push(`Planificar el paso a v${next}.`);
+  }
+  if (r.exact) {
+    const sec = cal.securityAfter(r.major, r.exact);
+    if (sec.length) notes.push(`Hay releases de seguridad posteriores a ${r.exact}: como mínimo ${sec[0].version.replace(/^v/, '')}.`);
+  }
+  const support = `con soporte hasta ${sch.end}${days < policy.nodeEolWarnDays ? ` (quedan ${days} días)` : ''}`;
+  if (!notes.length && !infoNotes.length && days >= policy.nodeEolWarnDays) {
+    return { ...base, level: 'info', message: `${prefix}: LTS más nueva, ${support}.`, data: { ...data, ok: true } };
+  }
+  const all = [...notes, ...infoNotes];
+  const detail = `LTS ${support}.${all.length ? ` ${all.join(' ')}` : ''}`;
+  const level = notes.length || days < policy.nodeEolWarnDays ? 'warn' : 'info';
+  // En texto, los pines de la misma línea con las mismas observaciones van juntos (rango o no).
+  return { ...base, level, message: `${prefix}: ${detail}`, data: { ...data, group: `v${r.major}: ${detail}` } };
+}
+
+export async function run(ctx) {
+  let cal;
+  try {
+    cal = await loadCalendar(ctx);
+  } catch (error) {
+    return [{ level: 'warn', message: `no se pudo leer el calendario de Node (${error.message}); se omite el chequeo.` }];
+  }
+  if (!cal.recommended) return [{ level: 'warn', message: 'el calendario de Node no trae releases LTS; se omite el chequeo.' }];
+
+  const pins = findPins(ctx);
+  const findings = [];
+  const majors = new Set();
+  let nodePins = 0;
+  for (const pin of pins) {
+    const r = resolvePin(pin, cal);
+    if (!r.otherImage) nodePins++;
+    if (r.major !== undefined && r.major !== null) majors.add(r.major);
+    findings.push(evaluate(pin, r, cal, ctx.policy));
+  }
+  if (!nodePins) {
+    const major = parseVersion(cal.recommended)[0];
+    findings.push({
+      level: 'warn',
+      message: `No se fija la versión de Node en ningún lado (.nvmrc, engines.node, Dockerfile, pipeline). Fijarla, por ejemplo: .nvmrc con ${cal.recommended} y engines.node ">=${major}".`,
+    });
+  }
+  if (majors.size > 1) {
+    const list = [...majors].sort((a, b) => a - b).map((m) => `v${m}`);
+    findings.push({ level: 'warn', message: `Versiones mayores distintas entre archivos: ${list.join(', ')}. Alinearlas en la misma LTS.`, data: { majors: [...majors].sort((a, b) => a - b) } });
+  }
+  return findings;
+}