PackageInferno

Logo de PackageInferno

Increíblemente simple, escáner de cadena de suministro npm que prioriza Docker. Un solo archivo compose ejecuta:

Enumerador → construye la cola de paquetes
Descargador → descarga los tarballs (y opcionalmente los sube a S3)
Analizador → análisis estático + YARA opcional
Postgres → base de datos local para hallazgos
Panel Streamlit → visualiza hallazgos en http://localhost:8501

Esta es la edición solo para contenedores. El proyecto se puede construir para escalar usando EC2, SQS y RDS. La mayor parte está configurada para ello en el conjunto de herramientas.

Lo que obtienes

Pipeline completo en Docker (sin instalaciones adicionales en el host más allá de Docker)
Reglas configurables mediante scan.yml (listas blancas, umbrales, YARA)
Esquema Postgres local + historial de escaneos (scan_runs) listo para usar
Cargas opcionales a S3 para tarballs y hallazgos (credenciales mediante ~/.aws)
Panel Streamlit: búsqueda, detalle y analíticas

Contenido

docker-compose.yml – servicios: db, enumerador, descargador, analizador, panel, init-db
enumerator/ – trabajador Node que construye la cola NDJSON
fetcher/ – trabajador Node que descarga tarballs (+ subida a S3 si está habilitado)
analyzer/ – analizador estático Python (+ YARA integrado opcional)
dashboard/ – aplicación Streamlit (puerto 8501)
infra/migrations.sql – esquema principal de la BD (paquetes, versiones, hallazgos, puntuaciones, índices)
infra/20251106_scan_runs.sql – tabla de historial de escaneos
scan.yml – configuración de análisis (reglas, puntuación, listas blancas, YARA)
scripts/run_pipeline.sh – ejecuta enumerar → descargar → analizar
scripts/init_db.sh – inicializa el esquema de la BD
scripts/test_setup.sh – validación automatizada de la instalación
SCANNING_GUIDE.md – estrategias de escaneo detalladas y ejemplos

Inicio rápido (local)

Requisitos: Docker Desktop (o motor) con Compose v2.

Instalación en una sola línea

curl -fsSL https://raw.githubusercontent.com/MHaggis/Package-Inferno/main/install.sh | bash

Esto clona el repositorio en ~/package-inferno y te da instrucciones para empezar.

Opción A: Usar imágenes preconstruidas (más rápido)

Descarga y ejecuta contenedores preconstruidos desde GitHub Container Registry:

# Clona el repositorio (para archivos de configuración y scripts)
git clone https://github.com/MHaggis/Package-Inferno.git
cd Package-Inferno

# Ejecuta con imágenes preconstruidas
docker compose -f docker-compose.ghcr.yml up -d db
./scripts/init_db.sh
SEEDS="lodash,express" docker compose -f docker-compose.ghcr.yml run --rm enumerator
docker compose -f docker-compose.ghcr.yml run --rm fetcher
docker compose -f docker-compose.ghcr.yml run --rm analyzer

Imágenes disponibles:

ghcr.io/mhaggis/package-inferno/enumerator:main
ghcr.io/mhaggis/package-inferno/fetcher:main
ghcr.io/mhaggis/package-inferno/analyzer:main

Opción B: Compilar desde el código fuente

Validación automatizada de la instalación

Ejecuta el script de prueba para validar tu instalación:

./scripts/test_setup.sh

Esto hará:

✓ Comprobar Docker y Docker Compose
✓ Iniciar e inicializar la base de datos
✓ Ejecutar un escaneo de prueba (2 paquetes)
✓ Verificar que los hallazgos se almacenan correctamente

Configuración manual

Inicia Postgres e inicializa el esquema:

docker compose up -d db
./scripts/init_db.sh

Ejecuta el pipeline:

./scripts/run_pipeline.sh

Inicia el panel:

docker compose up -d dashboard
# abre http://localhost:8501

Los hallazgos se guardan en ./out/findings/*.findings.json y en la tabla findings cuando la BD está habilitada.

Modos de escaneo

PackageInferno admite múltiples estrategias de escaneo según tus objetivos:

Modo	Caso de uso	Velocidad	Cobertura	Comando
Semillas específicas	Probar/investigar paquetes conocidos	Más rápida	Dirigida	`SEEDS="pkg1,pkg2"`
Lote pequeño	Validar configuración, escaneo de muestra	Rápida	10-100 paq.	`MAX_CHUNKS=2 CHUNK_LIMIT=10`
Registro completo	Auditoría integral de cadena de suministro	Horas-Días	2M+ paq.	`MAX_CHUNKS=0 CHUNK_LIMIT=100`
Feed de cambios	Monitorear nuevas versiones (incluido automáticamente)	Tiempo real	Actualizaciones recientes	Integrado

1. Escanear paquetes específicos (recomendado para pruebas)

Define los paquetes que deseas analizar:

# Comando único con semillas
export SEEDS="lodash,express,axios"
./scripts/run_pipeline.sh

# O desde un archivo
echo -e "react\nvue\nangular" > packages.txt
export SEEDS_FILE=packages.txt
./scripts/run_pipeline.sh

Cómo probé inicialmente: Usé SEEDS="is-odd,is-even" para validación rápida.

2. Escanear desde el registro npm (_all_docs)

Escanea paquetes paginados desde el registro de npm:

# Limpiar ejecuciones anteriores
rm -rf downloads/* out/*

# Escanear 2 páginas de 10 paquetes cada una (20 paquetes)
export MAX_CHUNKS=2        # Número de páginas
export CHUNK_LIMIT=10      # Paquetes por página
unset SEEDS                # Importante: deshabilitar modo de semillas

# Ejecutar pasos individuales para mejor visibilidad
docker compose run --rm enumerator  # Descubre y encola
docker compose run --rm fetcher     # Descarga tarballs
docker compose run --rm analyzer    # Escanea amenazas

Ejemplo de salida:

config: chunkLimit=10, maxChunks=2
checking recent changes feed...
changes feed: enqueued 2 new versions
enumerating via _all_docs (fresh scan)
page 1/2 count: 10
page 2/2 count: 10
done, enqueued 22 (22 new versions)

3. Monitoreo continuo (escaneo ilimitado)

Escanea todo el registro de npm:

export MAX_CHUNKS=0        # 0 = ilimitado
export CHUNK_LIMIT=100     # Lotes más grandes para eficiencia
./scripts/run_pipeline.sh

Advertencia: Esto se ejecutará durante horas/días y escaneará cientos de miles de paquetes. Monitorea el espacio en disco y el tamaño de la base de datos.

4. Reanudar escaneos interrumpidos

El enumerador guarda el estado en ./out/enumerator_state.json con la posición del cursor:

{
  "last_seq": "0",
  "last_startkey": "package-name",
  "last_run": "2025-11-23T19:24:49.123Z",
  "last_processed": 22,
  "last_new": 22
}

Simplemente vuelve a ejecutar el pipeline y se reanudará desde el último cursor:

./scripts/run_pipeline.sh  # Se reanuda automáticamente

Para forzar un escaneo nuevo:

rm -f out/enumerator_state.json
./scripts/run_pipeline.sh

Ejemplo de resultados de escaneo

De un escaneo de 2 páginas de 22 paquetes, esto es lo que detectó PackageInferno:

-- Paquetes más sospechosos por puntuación
SELECT p.name, s.score, s.label, COUNT(f.id) as findings 
FROM packages p 
JOIN versions v ON p.id = v.package_id 
JOIN scores s ON v.id = s.version_id 
LEFT JOIN findings f ON v.id = f.version_id 
GROUP BY p.name, s.score, s.label 
ORDER BY s.score DESC;

-- Resultados:
   name                | score | label      | findings
-----------------------+-------+------------+----------
 rendition             | 606   | malicious  | 153
 vs-deploy             | 454   | malicious  | 119
 --123hoodmane-pyodide | 213   | malicious  | 46

¿Qué hizo que rendition fuera tan sospechoso?

57 × url_outside_allowlist - Dominios no permitidos
46 × suspicious_pattern - Patrones de shell/eval
12 × advanced_obfuscation - Codificación hex, XOR, arreglos de cadenas
6 × big_base64_blob - Cargas útiles grandes codificadas en base64
18 × url_in_code - URLs incrustadas

Package-Inferno

Más Populares