@theoptimalpartner/npm-security-kit 1.0.2 → 2.0.0-beta.1

package/README.md

@@ -1,495 +1,196 @@
-# NPM Security Kit 🛡️
+# npm-security-kit
 
-**Protección instant contra paquetes maliciosos y vulnerabilidades**
+Reglas de seguridad de dependencias npm en un solo comando que corre en el pipeline **antes de `npm ci`**. No tiene
+dependencias: `npx` descarga un solo tarball y revisa el lockfile antes de que se ejecute un solo install script.
 
-Kit portable y reutilizable para proteger cualquier proyecto Node.js/npm contra:
-- ✅ 175+ paquetes maliciosos conocidos (campaña de phishing Oct 2025)
-- ✅ Vulnerabilidades en dependencias
-- ✅ Supply chain attacks
-- ✅ Typosquatting
-- ✅ Malware en dependencias transitivas
+## Qué revisa
 
----
+| Chequeo | Qué mira | Error (bloquea) | Aviso |
+|---|---|---|---|
+| `malware` | `npm audit` sobre **todo** el lockfile, incluidas las devDependencies | Cualquier advisory de malware (CWE-506), con cualquier severidad | — |
+| `vulnerabilities` | `npm audit --omit=dev` | Vulnerabilidades `critical` en producción | Resumen de las `high` |
+| `node-version` | `.nvmrc`, `.node-version`, `.tool-versions`, `engines.node`, `volta.node`, `FROM node:` y `image:` del pipeline | Línea de Node sin soporte o que no es LTS | Hay una LTS más nueva (mientras no tenga su primera release LTS, solo se informa), pocos días de soporte, parche de seguridad pendiente, versiones mayores distintas, nada fijado |
+| `npm-policy` | `.npmrc`, `engines.npm`, npm en uso, lockfile | Faltan `min-release-age`, `engine-strict` o `strict-allow-scripts`; npm < 11.17; no hay lockfile | Faltan `min-release-age-exclude[]`, `save-exact` o `audit-level`; lockfile < v3 |
+| `install-scripts` | Paquetes con install scripts del lockfile contra `allowScripts` | Alguno sin aprobar (con `strict-allow-scripts`) | Alguno sin aprobar con el override por variable de entorno |
+| `dockerfile` | `COPY` del `.npmrc` antes de `npm ci`, `.dockerignore` | Instala sin el `.npmrc` | Usa `npm install` en vez de `npm ci`; el `.dockerignore` deja fuera el lockfile |
 
-## 🚀 Instalación Rápida (2 minutos)
+Las versiones y fechas de Node se leen de nodejs.org en cada corrida: el kit no las trae fijas.
 
-### Opción 1: Instalación Automática (Recomendado)
+### El `.npmrc` que pide
 
-```bash
-# Desde la raíz de tu proyecto
-curl -sSL https://raw.githubusercontent.com/tu-org/npm-security-kit/main/install.sh | bash
-```
-
-O si tienes el kit localmente:
-
-```bash
-# Desde la raíz de tu proyecto
-bash /ruta/a/npm-security-kit/install.sh
-```
-
-### Opción 2: Instalación Manual (3 pasos)
+```ini
+# Dependencias externas: mínimo 7 días desde su publicación
+min-release-age=7
 
-```bash
-# 1. Copiar archivos de seguridad
-cp -r /ruta/a/npm-security-kit/template/.security .
-cp -r /ruta/a/npm-security-kit/template/scripts .
-cp -r /ruta/a/npm-security-kit/template/.github .
-
-# 2. Hacer scripts ejecutables
-chmod +x scripts/*.sh
-
-# 3. Agregar scripts a package.json
-# Ver sección "Scripts NPM" más abajo
-```
+# Paquetes internos: se pueden instalar inmediatamente
+min-release-age-exclude[]=@theoptimalpartner/*
 
----
+# Guardar versiones exactas
+save-exact=true
 
-## 📦 ¿Qué Incluye?
+# Validar engines (npm >= la versión mínima de la política)
+engine-strict=true
 
-### Archivos Instalados
+# Install scripts: solo corren los aprobados en allowScripts (package.json)
+strict-allow-scripts=true
 
-```
-tu-proyecto/
-├── .github/
-│   ├── workflows/
-│   │   └── security-audit.yml       # GitHub Actions automático
-│   └── dependabot.yml               # Actualizaciones automáticas
-├── .security/
-│   ├── malicious-packages-blacklist.json  # 175+ paquetes maliciosos
-│   └── config.json                  # Configuración personalizable
-├── scripts/
-│   ├── check-malicious-packages.sh  # Verificar paquetes maliciosos
-│   └── security-check.sh            # Auditoría completa
-└── SECURITY.md                      # Documentación
+# npm audit falla solo por vulnerabilidades críticas
+audit-level=critical
 ```
 
-### Scripts NPM Agregados
-
-```json
-{
-  "scripts": {
-    "security:check": "./scripts/security-check.sh",
-    "security:check-malicious": "./scripts/check-malicious-packages.sh",
-    "security:audit": "npm audit --audit-level=moderate",
-    "security:audit:fix": "npm audit fix",
-    "security:outdated": "npm outdated",
-    "security:licenses": "npm list --json | jq -r '.dependencies | to_entries[] | \"\\(.key): \\(.value.license)\"'",
-    "security:full": "npm run security:audit && npm run security:check"
-  }
-}
-```
+Además, `engines.npm` en `>=11.17`: npm 10 ignora `min-release-age` sin avisar y no aplica `allowScripts`.
 
----
+## Uso
 
-## 🎯 Uso Diario
+### En el pipeline
 
-### Antes de Instalar un Paquete
+Un step **antes de `npm ci`**, con la versión del kit fija y solo en los PR a ramas que despliegan (ejemplo de
+`bitbucket-pipelines.yml`, el pipeline que lee el chequeo de Node):
 
-```bash
-# Verificar si un paquete es seguro
-npm run security:check-malicious
+```yaml
+definitions:
+  steps:
+    - step: &test
+        name: Test (supply chain + build)
+        image: node:24.22.1
+        caches:
+          - npm
+        script:
+          # Antes de instalar: malware, vulnerabilidades, Node, .npmrc, install scripts, Dockerfiles
+          - npx --yes --min-release-age=0 @theoptimalpartner/npm-security-kit@2.0.0 check
+          - npm ci            # con strict-allow-scripts, los scripts no aprobados cortan acá
+          - npm audit signatures
+          - npm run build
 
-# Ver info del paquete
-npm info paquete-nombre
+pipelines:
+  pull-requests:
+    '**':
+      - step:
+          <<: *test
+          condition:
+            state: BITBUCKET_PR_DESTINATION_BRANCH == "develop" || BITBUCKET_PR_DESTINATION_BRANCH == "main"
 ```
 
-### Después de Instalar Dependencias
+- **Antes de `npm ci`:** `npm audit` funciona solo con el lockfile, así que el malware se detecta antes de que
+  corra su `postinstall`.
+- **Versión fija** (`@2.0.0`): subir la política en un repo es un cambio visible en su PR.
+- **`--min-release-age=0` solo para `npx`:** `npx` no aplica `min-release-age-exclude` (npm 11.19.1 lo aplica al
+  instalar, no al resolver el paquete de `npx`). Sin el flag, dentro de un repo con `min-release-age=7` una versión
+  nueva del kit no se puede usar hasta cumplir 7 días (`ETARGET … with a date before`). Afecta solo al kit: la
+  versión va fija y no tiene dependencias. El `npm ci` que sigue aplica los 7 días como siempre.
+- **`npm audit signatures`** va después de `npm ci` porque necesita `node_modules`.
+- Para guardar el resultado como artefacto: `npx --yes --min-release-age=0 @theoptimalpartner/npm-security-kit@2.0.0 check --json > npm-security-kit.json`.
 
-```bash
-# Verificación rápida
-npm run security:audit
-
-# Verificación completa (recomendado)
-npm run security:full
-```
+### Dockerfile
 
-### Antes de Deploy
+El `.npmrc` se copia con el lockfile, antes de `npm ci`. Si no, dentro de la imagen no aplican
+`strict-allow-scripts`, `min-release-age` ni `engine-strict`:
 
-```bash
-# Auditoría completa
-npm run security:full
-
-# Si hay problemas, auto-fix
-npm run security:audit:fix
+```dockerfile
+COPY package.json package-lock.json .npmrc ./
+RUN npm ci
 ```
 
----
-
-## ⚙️ Configuración
-
-### Personalizar para tu Proyecto
-
-Edita `.security/config.json`:
-
-```json
-{
-  "projectName": "mi-proyecto",
-  "projectType": "node",
-  "excludeDirs": ["node_modules", "dist", "build"],
-  "strictMode": true,
-  "notifications": {
-    "email": "security@tuempresa.com",
-    "slack": "https://hooks.slack.com/..."
-  }
-}
-```
-
-### Tipos de Proyecto Soportados
-
-- `node` - Proyectos Node.js backend
-- `react` - Aplicaciones React
-- `nextjs` - Aplicaciones Next.js
-- `vue` - Aplicaciones Vue.js
-- `express` - APIs Express
-- `serverless` - Funciones serverless
-- `library` - Librerías npm
-
----
+Si el `.dockerignore` excluye el `.npmrc` (por ejemplo con `.*`), agregar `!.npmrc` al final.
 
-## 🔒 Características
+### Adoptarlo en un repo: `init`
 
-### 1. Verificación de Paquetes Maliciosos
-
-**Blacklist de 175+ paquetes conocidos**:
-- Campaña de phishing Oct 2025
-- Patrones maliciosos (`redirect-*`)
-- Dominios de phishing
-- Cuentas npm comprometidas
+Una vez por repo, en una rama:
 
 ```bash
-npm run security:check-malicious
+npx --yes --min-release-age=0 @theoptimalpartner/npm-security-kit@2.0.0 init --dry-run
 ```
 
-### 2. Auditoría Automática
-
-**npm audit mejorado**:
-- Verifica vulnerabilidades conocidas
-- Auto-fix cuando es posible
-- Reportes detallados
-
 ```bash
-npm run security:audit
+npx --yes --min-release-age=0 @theoptimalpartner/npm-security-kit@2.0.0 init
 ```
 
-### 3. GitHub Actions
-
-**Verificación en cada PR/Push**:
-- ✅ npm audit
-- ✅ Paquetes maliciosos
-- ✅ Dependency review
-- ✅ License compliance
-- ✅ Secrets detection
+`init`:
 
-**Ejecución semanal automática** (Lunes 9am UTC)
+- agrega al `.npmrc` las claves de la política que faltan (con un comentario) y corrige las que tienen otro valor,
+  sin borrar ni reordenar nada;
+- completa `engines.npm` (`>=11.17`) y, solo si falta, `engines.node`;
+- **no aprueba install scripts**: lista los pendientes y los comandos para revisarlos;
+- **no edita** `bitbucket-pipelines.yml` ni los Dockerfiles: muestra el step y los `COPY` corregidos;
+- se puede correr de nuevo sin cambiar nada.
 
-### 4. Dependabot
+Después: revisar el diff, aprobar o negar los install scripts, aplicar el step y el Dockerfile, y correr `check`.
 
-**Actualizaciones automáticas**:
-- Security patches prioritarios
-- Agrupación inteligente
-- PRs con contexto
-
-### 5. Pre-commit Hooks (Opcional)
-
-Instalar con Husky:
+### En local
 
 ```bash
-npm install --save-dev husky
-npx husky init
-echo "npm run security:check-malicious" > .husky/pre-commit
-```
-
----
-
-## 📊 Ejemplos de Salida
-
-### ✅ Proyecto Limpio
-
+npx --yes --min-release-age=0 @theoptimalpartner/npm-security-kit@2.0.0 check
 ```
-========================================
-Malicious Package Detection
-========================================
-
-Loading blacklist...
-✓ Loaded 175 malicious packages
-  Source: Socket.dev - 175 Malicious npm Packages...
-  Last Updated: 2025-10-20
-
-Analyzing installed packages...
-  Total installed packages: 342
-
-Checking against blacklist...
-
-Checking against malicious patterns...
-
-========================================
-Results
-========================================
-✓ No malicious packages detected
-
-Summary:
-  - Checked: 342 packages
-  - Against: 175 known malicious packages
-  - Found: 0 threats
-```
-
-### ❌ Amenaza Detectada
-
-```
-========================================
-Results
-========================================
-✗ MALICIOUS PACKAGES FOUND!
-
-Summary:
-  - Direct matches: 1
-  - Pattern matches: 0
-  - Total threats: 1
-
-Malicious packages found:
-  - redirect-abc123 (direct match)
-
-IMMEDIATE ACTIONS REQUIRED:
-1. DO NOT use this application
-2. Uninstall malicious packages immediately
-3. Review application logs for suspicious activity
-4. Check for data exfiltration
-5. Report to security team
-```
-
----
-
-## 🔄 Actualización
-
-### Actualizar Blacklist
-
-```bash
-# Descargar última blacklist
-curl -o .security/malicious-packages-blacklist.json \
-  https://raw.githubusercontent.com/tu-org/npm-security-kit/main/blacklist.json
 
-# Verificar
-npm run security:check-malicious
-```
+No se instala como devDependency ni usa husky: el `.npmrc` protege el `npm install` local y el pipeline es el
+control que no se puede saltar.
 
-### Actualizar Scripts
+## Cómo leer la salida
 
-```bash
-# Re-ejecutar instalación (preserva config)
-bash /ruta/a/npm-security-kit/install.sh --update
-```
+Un bloque por chequeo. `✗` error, `⚠` aviso, `ℹ` información, con `archivo:línea` cuando aplica. Cada mensaje dice
+qué hacer. Cuando el mismo aviso aparece en varios archivos (por ejemplo, la misma versión de Node en `.nvmrc`,
+Dockerfile y pipeline) va una sola vez, con la lista de archivos.
 
----
+| Exit code | Significado |
+|---|---|
+| 0 | Sin errores (puede haber avisos) |
+| 1 | Hay al menos un error |
+| 2 | Uso incorrecto o fallo del kit |
 
-## 🎓 Mejores Prácticas
+`check --json` escribe solo JSON en stdout:
+`{ kitVersion, policy, results: [{ check, level, message, file?, line?, data? }], summary: { errors, warnings } }`.
 
-### 1. Verificar Antes de Instalar
+## Recetas
 
-```bash
-# ❌ NO HACER
-npm install paquete-random
-
-# ✅ HACER
-npm info paquete-random
-npm view paquete-random repository
-npm view paquete-random license
-npm install paquete-random
-npm run security:check-malicious
-```
+### `npm ci` falla con EUSAGE (lockfile incompleto)
 
-### 2. Mantener Dependencias Actualizadas
+Pasa con lockfiles generados con npm 10, a los que les faltan opcionales de plataforma. Regenerarlo con npm 11:
 
 ```bash
-# Ver paquetes desactualizados
-npm run security:outdated
-
-# Actualizar con cuidado
-npm update
-npm run security:full
+npm install --package-lock-only
 ```
 
-### 3. Revisar Dependabot PRs
-
-- ✅ Priorizar PRs de seguridad
-- ✅ Leer changelog antes de aprobar
-- ✅ Probar en staging primero
-
-### 4. Auditorías Regulares
-
-| Frecuencia | Acción | Comando |
-|------------|--------|---------|
-| **Diario** | Revisar Dependabot PRs | GitHub UI |
-| **Semanal** | GitHub Actions (automático) | - |
-| **Mensual** | Auditoría manual completa | `npm run security:full` |
-| **Trimestral** | Actualizar blacklist | Ver sección Actualización |
-
----
-
-## 🚨 Respuesta a Incidentes
-
-### Si se Detecta un Paquete Malicioso
-
-1. **DETENER** - No desplegar ni ejecutar
-2. **AISLAR** - Marcar entorno como comprometido
-3. **ANALIZAR**:
-   ```bash
-   npm run security:check-malicious
-   npm list | grep nombre-paquete
-   git log package-lock.json
-   ```
-4. **REMOVER**:
-   ```bash
-   npm uninstall nombre-paquete
-   npm audit
-   npm run security:full
-   ```
-5. **INVESTIGAR**:
-   - Revisar logs de aplicación
-   - Verificar conexiones de red
-   - Buscar data exfiltration
-6. **REPORTAR**:
-   - Equipo de seguridad interno
-   - npm security (security@npmjs.com)
-   - Socket.dev (https://socket.dev/report)
-
----
+### Parche urgente con menos de 7 días
 
-## 🔧 Troubleshooting
-
-### Error: "jq command not found"
-
-```bash
-# Ubuntu/Debian
-sudo apt-get install jq
-
-# macOS
-brew install jq
-
-# Windows (WSL)
-sudo apt-get install jq
-```
-
-### Error: "Permission denied" en scripts
+`min-release-age=7` no deja instalar versiones recién publicadas. Para un parche de seguridad que no puede esperar:
 
 ```bash
-chmod +x scripts/*.sh
+npm install paquete@x.y.z --min-release-age=0
 ```
 
-### GitHub Actions no ejecuta
+Dejar en la descripción del PR qué versión es, por qué no puede esperar (el advisory) y quién lo aprobó, y revisar que
+el lockfile solo cambió en ese paquete y sus dependencias.
 
-Verifica que `.github/workflows/security-audit.yml` esté commiteado:
+### Aprobar o negar install scripts
 
 ```bash
-git add .github/workflows/security-audit.yml
-git commit -m "chore: add security audit workflow"
-git push
+npm ci --ignore-scripts
+npm install-scripts ls
+npm install-scripts approve esbuild   # baja el binario de su plataforma: lo necesita
+npm install-scripts deny core-js      # solo imprime un mensaje: no hace falta
 ```
 
-### Dependabot no abre PRs
-
-Verifica en GitHub Settings > Security > Dependabot que esté habilitado.
-
----
-
-## 📚 Recursos
-
-### Documentación Adicional
-
-- **SECURITY_PROTOCOL.md** - Protocolo completo (en auth-service)
-- **SECURITY_AUDIT_REPORT.md** - Ejemplo de informe
-- **SECURITY_QUICK_GUIDE.md** - Guía rápida
-
-### Enlaces Útiles
+Se aprueba lo que necesita compilar o bajar binarios para funcionar, y se niega lo que es solo telemetría o
+publicidad. El kit no aprueba nada en automático. Queda en `allowScripts` del `package.json`. Reglas (las mismas de
+npm):
 
-- Socket.dev Blog: https://socket.dev/blog
-- npm Security: https://docs.npmjs.com/security
-- OWASP Dependency Check: https://owasp.org/www-community/Component_Analysis
-- Snyk Advisor: https://snyk.io/advisor
+- `"pkg": true|false` vale para cualquier versión; `"pkg@1.2.3"` solo para esa; `"pkg@1.2.3 || 1.2.4"` para una lista.
+- `false` le gana a `true`.
+- **npm ignora los rangos** (`pkg@^1`) y los dist-tags (`pkg@latest`): esa entrada no aprueba nada, y el kit lo avisa.
+- Las opcionales de otra plataforma (como `fsevents` en Linux) npm no las instala: en el pipeline no cuentan.
 
-### Reportar Vulnerabilidades
+### Desactivar `strict-allow-scripts` en un repo (override)
 
-- NPM Security: security@npmjs.com
-- Socket.dev: https://socket.dev/report
-- GitHub Security: https://github.com/security
+Si un repo no puede adoptar todavía la aprobación de install scripts, se define la variable de npm, que le gana al
+`.npmrc`:
 
----
+- en el pipeline: *Repository variable* `npm_config_strict_allow_scripts` = `false`;
+- en local: `npm_config_strict_allow_scripts=false npm ci`.
 
-## 🤝 Contribuir
+Con el override, npm ejecuta los scripts sin aprobar y el kit los informa como **aviso**, más un aviso de que el
+override está activo. Dentro del `docker build` la variable no llega sola: hay que pasarla como `ARG`.
 
-### Agregar Paquetes a la Blacklist
-
-1. Verificar en múltiples fuentes (Socket.dev, Snyk, GitHub)
-2. Editar `.security/malicious-packages-blacklist.json`
-3. Agregar evidencia y referencias
-4. Pull request con documentación
-
-### Mejorar Scripts
-
-1. Fork del repositorio
-2. Crear rama con feature
-3. Probar en múltiples proyectos
-4. PR con tests y documentación
-
----
-
-## 📄 Licencia
-
-MIT License - Úsalo libremente en proyectos comerciales y open source
-
----
-
-## ⭐ Proyectos Usando Este Kit
-
-- auth-service
-- jwt-auth-package
-- auth-react-client
-
-¿Usas este kit? Agrega tu proyecto aquí!
-
----
-
-## 🎯 Roadmap
-
-- [ ] npm package instalable (`npm install -D @tuorg/security-kit`)
-- [ ] Integración con más CI/CD (GitLab, Bitbucket, CircleCI)
-- [ ] Dashboard web de métricas
-- [ ] Integración con Slack/Discord
-- [ ] Soporte para Python/pip, Ruby/gems, etc.
-- [ ] Machine learning para detectar patrones
-
----
-
-## 📞 Soporte
-
-- **Issues**: GitHub Issues
-- **Discusiones**: GitHub Discussions
-- **Email**: security@tuempresa.com
-- **Slack**: #security channel
-
----
-
-**Versión**: 1.0.0
-**Última actualización**: 2025-10-20
-**Mantenedor**: Diego
-
----
-
-## 🚀 Quick Start
-
-```bash
-# 1. Clonar o descargar el kit
-git clone https://github.com/tu-org/npm-security-kit
-
-# 2. Ir a tu proyecto
-cd mi-proyecto
-
-# 3. Ejecutar instalación
-bash /ruta/a/npm-security-kit/install.sh
-
-# 4. Verificar
-npm run security:check-malicious
-
-# 5. ¡Listo! Tu proyecto está protegido
-```
+### El registro de npm no responde
 
-**¿Preguntas?** Lee la documentación completa o abre un issue.
+El chequeo de malware falla cerrado: `no se pudo consultar los advisories del registro (…); reintentar el step`.
+No es un hallazgo de seguridad; se reintenta el step. Si nodejs.org no responde, `node-version` avisa y se omite.

package/bin/npm-security-kit.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+import { main } from '../src/cli.js';
+
+main(process.argv.slice(2)).then(
+  (code) => {
+    process.exitCode = code;
+  },
+  (error) => {
+    process.stderr.write(`npm-security-kit: fallo interno: ${error?.stack ?? error}\n`);
+    process.exitCode = 2;
+  },
+);