Automatización de Verificaciones de Seguridad en Paquetes npm con npq

npq audita un paquete npm antes de instalarlo, mientras que npm audit solo reporta vulnerabilidades después de que el código ya ha sido escrito en node_modules. Ese orden es precisamente el punto central: para cuando se audita el árbol de dependencias, un script postinstall malicioso ya se ha ejecutado en tu máquina. npq desplaza la verificación hacia una etapa anterior — inspecciona los metadatos del paquete, su antigüedad, sus scripts y los CVEs conocidos en el momento de la solicitud de instalación, y luego pregunta si deseas continuar.

Esta guía integra npq en tu terminal y en un hook de pre-commit, de modo que la auditoría se ejecute en el momento en que incorporas dependencias — no solo cuando recuerdas ejecutarla manualmente.

npm install -g npq

La brecha que npq cubre

npq es un auditor de seguridad pre-instalación que ejecuta un conjunto de verificaciones — denominadas “marshalls” — contra los metadatos de un paquete antes de que npm descargue o ejecute ninguno de su código. Esto es la operación inversa de npm audit, que lee el árbol de dependencias instaladas y reporta CVEs a posteriori. La campaña Shai-Hulud de 2025 explotó scripts de ciclo de vida que se ejecutan durante la instalación, que es exactamente la ventana que npm audit no puede cubrir y que npq sí puede. La herramienta es de código abierto en lirantal/npq y fue desarrollada por Liran Tal.

Instalar npq y ejecutar una auditoría puntual

Instala npq de forma global y luego utiliza npq install en lugar de npm install para cualquier paquete que desees verificar previamente.

npm install -g npq
npq install express

El paquete npq en npm instala dos binarios: npq y npq-hero. El primero ejecuta una auditoría explícita; el segundo es un wrapper de npm de sustitución directa que se describe en la siguiente sección. Cuando ejecutas npq install express, npq obtiene los metadatos, ejecuta sus marshalls, imprime los hallazgos y — si algo es marcado como sospechoso — te solicita confirmación antes de delegar la operación a npm.

Un paquete marcado produce una salida similar a esta:

warning Package has install scripts (preinstall, postinstall)
warning Package is older than 22 days? no — published 1 day ago
? Would you like to continue installing package(s)? (Y/n)

El prompt es el punto de control. Nada se instala hasta que respondas, o hasta que expire el temporizador de auto-continuación de 15 segundos (activo solo cuando hay advertencias).

Crear un alias de npm apuntando a npq-hero y hacerlo persistente

Para auditar cada instalación de forma automática, crea un alias de npm apuntando a npq-hero y escríbelo en la configuración de tu shell. npq-hero es el wrapper diseñado para este propósito — pasa todos los subcomandos de npm (run, ci, publish, entre otros) sin modificaciones, interceptando únicamente las instalaciones para ejecutar la auditoría primero.

echo "alias npm='npq-hero'" >> ~/.zshrc   # o ~/.bashrc para bash
source ~/.zshrc

Con el alias configurado, npm install fastify pasa por los marshalls de npq antes de que npm descargue el tarball. Crea el alias de npm apuntando a npq-hero en lugar de a npq directamente — npq es el binario de auditoría, mientras que npq-hero es el wrapper completo compatible con npm, documentado en el README de npq. Crear un alias apuntando al binario npq directamente rompe los subcomandos que npq no implementa por sí mismo.

¿Qué verifica npq exactamente?

npq ejecuta un conjunto de verificaciones de seguridad, denominadas “marshalls”, que están documentadas en el README de npq. Se agrupan en cuatro categorías prácticas:

Agruparlos de esta manera refleja cómo se manifiesta un ataque en la práctica: un typosquat con un script postinstall y cero descargas activa múltiples marshalls simultáneamente. Cada verificación es una señal que debes evaluar, no un veredicto binario — npq expone los datos y te deja la decisión.

Deshabilitar la auto-continuación para una revisión explícita

Por defecto, el prompt interactivo de npq espera 15 segundos y luego continúa automáticamente la instalación cuando solo hay advertencias. Establece NPQ_DISABLE_AUTO_CONTINUE=true o pasa --disable-auto-continue para eliminar la cuenta regresiva y forzar una respuesta explícita (y/N) antes de que npq delegue a npm. Tanto el flag como la variable de entorno están documentados en el README de npq.

# Cualquiera de las dos formas funciona
NPQ_DISABLE_AUTO_CONTINUE=true npq install
npq install --disable-auto-continue

Esto convierte a npq en un paso de revisión deliberada — útil en tu terminal y dentro de un hook de commit de git, donde alguien está presente para responder al prompt. No es un modo de fallo no interactivo documentado: el prompt sigue esperando una respuesta, y npq no ofrece un flag que convierta cada paquete marcado en una salida automática con código de error.

Enrutar pnpm a través de npq

npq delega al gestor de paquetes especificado en NPQ_PKG_MGR, por lo que la misma capa de auditoría cubre pnpm. Establece la variable por comando para usos puntuales, o incorpórala en un alias de shell para el uso diario.

# Auditorías puntuales a través de pnpm
NPQ_PKG_MGR=pnpm npq install fastify

# Hacer que pnpm siempre pase por npq
alias pnpm="NPQ_PKG_MGR=pnpm npq-hero"
echo 'alias pnpm="NPQ_PKG_MGR=pnpm npq-hero"' >> ~/.zshrc

La variable NPQ_PKG_MGR, listada en el README de npq, le indica a npq-hero qué gestor de paquetes invocar una vez que la auditoría pasa. La forma con alias te ofrece la misma garantía para pnpm que el alias de npm te ofrece para npm: ninguna instalación procede hasta que los marshalls se hayan ejecutado.

Añadir un hook de pre-commit con husky

Detecta dependencias riesgosas antes de que sean confirmadas ejecutando npq desde un hook de pre-commit de husky. Esto audita las dependencias declaradas en package.json cada vez que realizas un commit, lo cual resulta especialmente valioso en commits que modifican los manifiestos de dependencias.

Instala husky e inicialízalo (sintaxis de husky v9):

npm install --save-dev husky
npx husky init

Luego escribe el hook en .husky/pre-commit:

# .husky/pre-commit
if git diff --cached --name-only | grep -qE 'package(-lock)?\.json'; then
  npx npq
fi

La verificación con git diff --cached limita la auditoría a los commits que realmente modifican package.json o package-lock.json, de modo que los commits no relacionados no incurran en el costo de la auditoría. El comando npx npq sin argumentos (sin el subcomando install) audita las dependencias declaradas en package.json y termina con código de error distinto de cero cuando se encuentran problemas. Dado que husky bloquea los commits cuando un hook termina con código de error distinto de cero, esto convierte al hook en una barrera estricta de pre-commit. El comando npx husky init y el formato de script simple en .husky/pre-commit corresponden a la convención de husky v9; la v8 usaba una sintaxis diferente con husky add, así que verifica la versión instalada antes de copiar fragmentos de versiones anteriores.

Limitaciones honestas: heurísticas, no pruebas

Los marshalls de npq son señales heurísticas, no prueba de malicia. Un paquete publicado ayer con cero descargas resulta sospechoso según las verificaciones de antigüedad y popularidad de npq — pero todo paquete legítimo nuevo comienza exactamente en ese estado. npq reduce el ruido a un conjunto de señales ponderadas y te deja la decisión; no puede, ni pretende, clasificar intenciones. Trata una instalación marcada como una invitación a revisar el paquete, no como una amenaza confirmada.

npq tampoco reemplaza a npm audit ni a Socket — los complementa. Las tres herramientas cubren ventanas diferentes:

npq captura señales previas a la instalación; npm audit detecta CVEs en paquetes ya presentes en disco; Socket añade monitoreo de comportamiento continuo de tu grafo de dependencias después del merge. Combinar la barrera de instalación de npq con --ignore-scripts como opción predeterminada (y herramientas como LavaMoat allow-scripts para las dependencias que genuinamente necesitan scripts de ciclo de vida) cierra la mayor parte de la superficie de ataque en tiempo de instalación.

Conclusión

Crear un alias de npm apuntando a npq-hero y bloquear los commits con un hook de husky coloca la misma auditoría pre-instalación delante de cada punto donde incorporas dependencias — tanto en el terminal local como en el momento del commit. Comienza con la instalación global y el alias de shell, y luego configura el hook de husky la próxima vez que toques tus manifiestos de dependencias. Los marshalls son heurísticas, así que lee lo que marcan — pero leer una advertencia es siempre mejor que descubrir un payload en postinstall después de que ya se ha ejecutado.

Preguntas Frecuentes

Understand every bug

Uncover frustrations, understand bugs and fix slowdowns like never before with OpenReplay — the open-source session replay tool for developers. Self-host it in minutes, and have complete control over your customer data. Check our GitHub repo and join the thousands of developers in our community.