installprobe

Investigación educativa de cadena de suministro: qué se ejecuta realmente en tu máquina cuando haces npm install — y hasta dónde podría llegar un paquete malicioso.

Todo gestor de paquetes ejecuta lifecycle scripts (preinstall, install, postinstall, …) con los privilegios del usuario instalador. Esa es la superficie de ataque de todo el ecosistema npm: al atacante solo le basta meter su paquete en tu árbol de dependencias, y el código corre en silencio en tu máquina — antes de que jamás mires el paquete.

installprobe demuestra la cadena completa de ataque en tres niveles. Por defecto no hace nada; cada comportamiento interesante está tras una variable de entorno explícita. El nivel destructivo ni siquiera viaja en el paquete npm.

⚠️ El demo destructivo (T2) es solo para una VM desechable. Nunca lo ejecutes en una máquina que te importe.

Español · English

Modelo de seguridad

| Nivel | Qué hace | Cómo se dispara | Dónde | |---|---|---|---| | T0 | Loguea cuándo corre cada lifecycle script y con qué privilegios | (siempre, durante la instalación) | npm + repo | | T1 | Simula reconocimiento: detecta presencia de credenciales (nombres de env vars, .npmrc, .env, claves SSH) y escribe un reporte local. Sin red, sin valores, nada sale de la máquina | MALPACK_PROBE=1 | npm + repo | | T2 | Simula el payload destructivo: borra exactamente un archivo — solo si MALPACK_ARM=1, la ruta pasa el allowlist de sandbox (marcador sandbox/vm o dir temporal) y resuelve vía realpath (escapes de symlink rechazados). MALPACK_DRYRUN=1 ensaya sin borrar | MALPACK_ARM=1 + MALPACK_TARGET=<ruta> | solo repo (nunca en el tarball npm) |

Pruébalo (T0 — completamente seguro)

mkdir demo && cd demo && npm init -y
npm install installprobe

Verás los lifecycle scripts dispararse durante la instalación:

> [email protected] preinstall
[installprobe] lifecycle "preinstall" — running with your privileges (win32/x64 ...)
> [email protected] postinstall
[installprobe] probe desactivado — el paquete no hace nada por defecto.

Después prueba la mitigación #1:

npm install --ignore-scripts installprobe   # nada corre

T1 — demo de reconocimiento

touch .npmrc && mkdir -p .ssh && touch .ssh/id_rsa   # archivos "víctima" falsos
MALPACK_PROBE=1 npm install installprobe
cat probe-report.json   # escrito en la raíz del proyecto

El reporte lista los nombres de env vars sensibles y la presencia de archivos de credenciales. Un atacante real correría este nivel incondicionalmente y exfiltraría el reporte — el gate es la única diferencia.

T2 — demo destructivo (SOLO VM, solo repo)

git clone https://github.com/darkm3tter/installprobe && cd installprobe
echo doomed > ~/vm-sandbox/important.txt                       # crea un archivo víctima
MALPACK_ARM=1 MALPACK_TARGET=~/vm-sandbox/important.txt MALPACK_DRYRUN=1 node scripts/wipe.js   # ensayo
MALPACK_ARM=1 MALPACK_TARGET=~/vm-sandbox/important.txt node scripts/wipe.js                    # el wipe
ls ~/vm-sandbox/important.txt   # no existe

Las rutas fuera del allowlist son rechazadas:

MALPACK_ARM=1 MALPACK_TARGET=/etc/passwd node scripts/wipe.js   # BLOQUEADO por el allowlist

Documentación

| Doc | Contenido | |---|---| | 01 — Superficie de ataque | Lifecycle scripts, vectores de entrega (typosquatting, dependency confusion, robo de cuentas, protestware), incidentes reales | | 02 — Impacto en el SO | ¿Hasta dónde llega? Windows (admin) y Linux, tablas de capacidades y límites honestos (kernel, Secure Boot, TPM, EDR) | | 03 — Detección y mitigación | --ignore-scripts, lockfiles, provenance, 2FA al publicar, EDR, respuesta a incidentes | | 04 — Plan de pruebas en VM | Laboratorio paso a paso T0→T2, qué observar, qué esperar |

Toda la documentación es bilingüe (EN/ES). Instrucciones completas del laboratorio en docs/04-plan-vm.es.md — toma snapshot de la VM primero.

Por qué existe

Los ataques a la cadena de suministro son la amenaza #1 real del ecosistema JS: event-stream (robo de bitcoins), ua-parser-js (criptominero), node-ipc (protestware que borraba archivos), colors/faker (destrucción de datos). Entender el mecanismo — scripts de instalación corriendo con tus privilegios — es la mejor defensa que existe. Los docs responden la pregunta de investigación con honestidad: un paquete puede hacer todo lo que puede hacer el usuario que lo instala, y las mitigaciones son operativas, no técnicas.

Verificación y transparencia

• El tarball npm contiene solo lifecycle.js, probe.js, READMEs y LICENSE — wipe.js queda excluido vía files y el CI lo verifica (npm pack --dry-run + grep)
• La lógica de gating está testeada: allowlist, escape por realpath de symlinks, regla de tmpdir, interruptor de armado (18 tests)
• Cero acceso de red en todo el paquete

Licencia

MIT — para educación e investigación defensiva de seguridad. Úsalo con responsabilidad, solo en sandboxes y VMs.