safe-npm

Un instalador de npm centrado en la seguridad que protege tus proyectos de paquetes recién comprometidos.

¿Por qué existe esto?

Los ataques a la cadena de suministro en paquetes npm son una amenaza creciente. Los atacantes a veces comprometen paquetes legítimos mediante:

• Robo de credenciales de mantenedores
• Publicación de actualizaciones maliciosas en paquetes populares
• Toma de control de paquetes abandonados

Estos ataques suelen ocurrir de repente: un paquete que ayer era seguro podría estar comprometido hoy. safe-npm te protege al instalar solo versiones de paquetes que han estado disponibles públicamente durante un tiempo mínimo (90 días por defecto). Esto le da tiempo a la comunidad de seguridad para descubrir e informar versiones maliciosas antes de que lleguen a tu proyecto.

Cómo funciona

Cuando ejecutas safe-npm install, este:

1. Lee tus dependencias de package.json o de los argumentos de línea de comandos
2. Consulta el registro npm para encontrar todas las versiones disponibles
3. Filtra las versiones publicadas más recientemente que tu umbral de antigüedad mínima
4. Selecciona la versión más reciente que cumpla tanto con tus requisitos semver como con los de antigüedad
5. Instala las versiones seguras usando npm

Por ejemplo, si especificas react@^18 y un [email protected] malicioso fue publicado ayer, safe-npm instalará la última versión que tenga al menos 90 días de antigüedad.

Instalación

Instalar desde npm (recomendado)

# Install globally
npm install -g @dendronhq/safe-npm

# Now you can use it anywhere
safe-npm install

Compilar desde el código fuente

# Clone and build
git clone <repository-url>
cd safe-npm
npm install
npm run build

# Link the binary globally
npm link

Uso básico

Instalar dependencias desde package.json

# Use the minimum age of 90 days (default)
safe-npm install

# Or specify your own minimum age
safe-npm install --min-age-days 120

Instalar paquetes específicos

# Install packages directly with version constraints
safe-npm install react@^18 lodash@^4.17.0

# These will be filtered to only use versions at least 90 days old
safe-npm install express --min-age-days 60

Ejecución en seco para ver qué se instalaría

# Preview which versions would be installed without actually installing
safe-npm install --dry-run

Opciones de configuración

--min-age-days <n>

Default: 90

El número mínimo de días que una versión de paquete debe haber estado publicada antes de poder instalarse.

Ejemplo: --min-age-days 120 requiere que los paquetes tengan al menos 4 meses de antigüedad.

Cuándo ajustarlo:

• Aumentar para máxima seguridad (ej., 180 días para sistemas críticos de producción)
• Disminuir si necesitas funciones más nuevas y aceptas un riesgo ligeramente mayor (ej., 30 días)

--ignore <pkg1,pkg2>

Una lista separada por comas de paquetes que omiten el requisito de antigüedad. Estos paquetes seguirán respetando los rangos semver pero ignorarán la antigüedad mínima.

Ejemplo: --ignore typescript,@types/node

Cuándo usarlo:

• Paquetes de rápida evolución en los que confíes (como TypeScript o herramientas de compilación)
• Paquetes internos de tu organización
• Paquetes donde necesitas las últimas funciones con urgencia

--strict

Salir con error si ALGUNA dependencia no se puede resolver a una versión que cumpla el requisito de antigüedad.

Ejemplo: safe-npm install --strict

Cuándo usarlo:

• Tuberías CI/CD donde quieres que las compilaciones fallen en lugar de omitir paquetes problemáticos
• Despliegues en producción donde necesitas certeza

--dev / --prod-only

Controla qué dependencias de package.json se procesan.

Ejemplos:

• safe-npm install --dev - Instalar solo devDependencies
• safe-npm install --prod-only - Instalar solo dependencias de producción

Cuándo usarlo:

• Instalar herramientas de desarrollo con requisitos más estrictos
• Compilaciones de producción donde quieres políticas de antigüedad diferentes para dependencias de desarrollo vs producción

--strategy <direct|overrides>

Default: direct

Cómo instala safe-npm las versiones resueltas:

direct - Instala directamente las versiones resueltas usando npm install package@version

• Simple y directo
• Bueno para instalaciones únicas o scripts

overrides - Escribe las versiones resueltas en el campo overrides de package.json, luego ejecuta npm install

• Impone versiones en todo tu árbol de dependencias (incluyendo dependencias transitivas)
• Nota: Esta funcionalidad está actualmente deshabilitada porque aún no funciona correctamente

--registry <url>

Default: https://registry.npmjs.org

Especifica un registro npm alternativo.

Ejemplo: --registry https://registry.company.com

Cuándo usarlo:

• Registros npm privados
• Espejos o cachés

--dry-run

Muestra lo que se instalaría sin realizar cambios.

Ejemplo: safe-npm install --dry-run

Cuándo usarlo:

• Probar tu configuración
• Entender qué versiones están disponibles
• Antes de hacer cambios en sistemas de producción

Flujos de trabajo comunes

Asegurar un nuevo proyecto

# Create a new project
mkdir my-project && cd my-project
npm init -y

# Install dependencies safely
safe-npm install express@^4 lodash

# This creates package-lock.json with versions at least 90 days old

Auditar un proyecto existente

# Check what versions would be installed with age requirements
safe-npm install --dry-run

# If you're happy, install them
safe-npm install

Integración con CI/CD

# In your CI pipeline, fail the build if any package can't meet age requirements
safe-npm install --strict --min-age-days 120

# Or allow newer packages for dev dependencies only
safe-npm install --prod-only --strict

Actualizaciones de emergencia

# Need to urgently update a specific package? Add it to ignore list
safe-npm install --ignore package-with-critical-fix

Pruebas

El proyecto incluye un conjunto de pruebas que puedes ejecutar:

npm test

Para pruebas automatizadas, puedes simular respuestas del registro usando fixtures:

export SAFE_NPM_FIXTURES=/path/to/fixtures.json
safe-npm install

El archivo fixtures debe contener JSON que refleje las respuestas del registro npm para cada paquete.

Cómo te protege esto

Escenario del mundo real:

1. Un paquete popular popular-lib es mantenido por un desarrollador de confianza
2. El atacante compromete las credenciales npm del mantenedor
3. El atacante publica [email protected] con malware
4. Los proyectos que usan ^5.0.0 instalarían inmediatamente la versión maliciosa
5. Con safe-npm, seguirías usando 4.9.0 (la última versión de hace más de 90 días)
6. Los investigadores de seguridad descubren el compromiso y lo reportan
7. La versión maliciosa se despublica
8. Nunca instalaste la versión comprometida

Limitaciones

• No protegerá contra paquetes que fueron maliciosos desde el inicio
• Retrasa el acceso a nuevas funciones y correcciones de errores legítimas
• Requiere confianza en que las versiones antiguas no tengan vulnerabilidades no descubiertas
• El filtrado basado en la antigüedad es una heurística, no una garantía

Filosofía

La seguridad se trata de compensaciones. safe-npm intercambia actualizaciones de última generación por protección contra compromisos repentinos de la cadena de suministro. Es una capa en una estrategia de defensa en profundidad que también debería incluir:

• Auditorías de seguridad periódicas (npm audit)
• Revisión de dependencias antes de añadir nuevos paquetes
• Monitoreo de avisos de seguridad
• Uso de archivos de bloqueo para garantizar compilaciones reproducibles
• Ejecución en entornos sandbox o contenedores

Requisitos

• Node.js 18 o superior
• npm (para la instalación subyacente)

Licencia

ISC