muad-dib v2.12.0

Instalación | Uso | Características | VS Code | CI/CD

Version française

¿Por qué MUAD'DIB?

Los ataques a la cadena de suministro de npm y PyPI están explotando. Shai-Hulud comprometió más de 25K repositorios en 2025. Las herramientas existentes detectan amenazas pero no ayudan a responder.

MUAD'DIB combina 22 escáneres paralelos (278 reglas de detección), un motor de desofuscación, análisis de flujo de datos entre módulos, puntuación compuesta (21 reglas compuestas) y un sandbox gVisor/Docker para detectar amenazas conocidas y patrones de comportamiento sospechosos en paquetes npm y PyPI. Existe un clasificador XGBoost en el código base, pero está actualmente inactivo (ver Evaluación).

Posicionamiento

MUAD'DIB es un escáner de cadena de suministro gratuito, abierto y totalmente auditable para npm y PyPI. Detecta amenazas conocidas (más de 225,000 IOCs), RCE en tiempo de instalación, flujos de robo de credenciales seguido de exfiltración, payloads ofuscados y otros patrones de comportamiento sospechosos — localmente, sin telemetría.

Está licenciado bajo AGPL-3.0; hay disponible una licencia comercial para organizaciones que necesiten integrarlo en un producto propietario o ejecutarlo como un servicio alojado cerrado (ver Licencia).

Deliberadamente no intenta hacerlo todo — ver Alcance para saber exactamente qué detecta y qué no.

Alcance

Detecta (npm y PyPI): paquetes maliciosos conocidos (coincidencia de IOC por nombre + SHA256), typosquats, RCE en tiempo de instalación (scripts de ciclo de vida preinstall/postinstall, curl | sh, tiempo de importación en Python, binding.gyp), lectura de credenciales seguida de exfiltración por red (intra- y entre archivos), payloads ofuscados / de alta entropía / stub-loader, droppers binarios (chmod +x + exec/spawn) y marcadores de evasión anti-análisis.

Fuera de alcance: ataques solo de navegador (DOM/window, sin API de Node.js), el contenido de binarios nativos / WASM (sin análisis binario), paquetes desconocidos de día cero (el feed de IOCs es reactivo) y ecosistemas que no sean npm/PyPI (RubyGems, Maven, Go). El fingerprinting anti-sandbox decidido y los payloads remotos de múltiples etapas son riesgos conocidos de falsos negativos. Detalle completo: Modelo de amenazas.

Sin telemetría. Tu código y los resultados de los escaneos nunca salen de tu máquina — MUAD'DIB solo descarga feeds de inteligencia de amenazas (muaddib update) y, para la puntuación, lee metadatos públicos del registro npm. Las alertas por webhook son opcionales.

Instalación

npm (recomendado)

npm install -g muaddib-scanner

Desde el código fuente

git clone https://github.com/DNSZLSK/muad-dib
cd muad-dib
npm install
npm link

Uso

Escaneo básico

muaddib scan .
muaddib scan /ruta/al/proyecto

Escanea tanto dependencias npm (package.json, node_modules) como Python (requirements.txt, setup.py, pyproject.toml).

Modo interactivo

muaddib

Instalación segura

muaddib install <paquete>
muaddib install lodash axios --save-dev
muaddib install paquete-sospechoso --force    # Forzar instalación a pesar de las amenazas

Escanea los paquetes en busca de amenazas ANTES de instalarlos. Bloquea paquetes maliciosos conocidos.

Puntuación de riesgo

Cada escaneo muestra una puntuación de riesgo de 0 a 100:

[SCORE] 58/100 [***********---------] HIGH

Modo explicación

muaddib scan . --explain

Muestra el ID de la regla, la técnica MITRE ATT&CK, las referencias y el playbook de respuesta para cada detección.

Exportación

muaddib scan . --json > resultados.json     # JSON
muaddib scan . --html reporte.html          # HTML
muaddib scan . --sarif resultados.sarif     # SARIF (GitHub Security)

Umbral de severidad

muaddib scan . --fail-on critical  # Fallar solo en CRITICAL
muaddib scan . --fail-on high      # Fallar en HIGH y CRITICAL (por defecto)

Modo paranoico

muaddib scan . --paranoid

Detección ultraestricta con menor tolerancia. Detecta cualquier acceso a red, ejecución de subprocesos, evaluación dinámica de código y acceso a archivos sensibles.

Alertas por webhook

muaddib scan . --webhook "https://discord.com/api/webhooks/..."

Filtrado estricto (v2.1.2): alertas solo para coincidencias de IOC, amenazas confirmadas por sandbox o exfiltración de canary tokens. Triaje por prioridad (v2.10.21): P1 (rojo, IOC/sandbox/canary), P2 (naranja, puntuación alta/compuestos), P3 (amarillo, resto).

Detección de anomalías de comportamiento (v2.0)

muaddib scan . --temporal-full     # Las 4 características temporales
muaddib scan . --temporal          # Detección de scripts de ciclo de vida repentinos
muaddib scan . --temporal-ast      # Diferencia de AST entre versiones
muaddib scan . --temporal-publish  # Anomalía en la frecuencia de publicación
muaddib scan . --temporal-maintainer # Detección de cambios de mantenedor

Detecta ataques a la cadena de suministro antes de que aparezcan en las bases de datos de IOCs analizando los cambios entre versiones de paquetes. Ver Metodología de evaluación para más detalles.

Sandbox Docker

muaddib sandbox <nombre-del-paquete>
muaddib sandbox <nombre-del-paquete> --strict

Análisis dinámico en un contenedor Docker aislado: strace, tcpdump, diff del sistema de archivos, canary tokens, entorno consciente de CI y precarga con monkey-patching para detección de bombas de tiempo (múltiples ejecuciones en desplazamientos de [0h, 72h, 7d]).

Otros comandos

muaddib watch .                    # Monitoreo en tiempo real
muaddib daemon                     # Modo daemon (auto-escaneo de npm install)
muaddib update                     # Actualizar IOCs (rápido, ~5s)
muaddib scrape                     # Actualización completa de IOCs (~5min)
muaddib diff HEAD~1                # Comparar amenazas con el commit anterior
muaddib init-hooks                 # Hooks de pre-commit (husky/pre-commit/git)
muaddib scan . --breakdown         # Descomposición de puntuación explicable
muaddib replay                     # Validación de ground truth (90/94 TPR@3, v2.11.48)

Características

22 escáneres paralelos

278 reglas de detección

Todas las reglas (273 RULES + 5 PARANOID) están mapeadas a técnicas MITRE ATT&CK. Ver SECURITY.md para la referencia completa de reglas.

Campañas detectadas

VS Code

La extensión de VS Code escanea automáticamente tus proyectos npm.

code --install-extension dnszlsk.muaddib-vscode

• MUAD'DIB: Scan Project - Escanear todo el proyecto
• MUAD'DIB: Scan Current File - Escanear el archivo actual
• Configuración: muaddib.autoScan, muaddib.webhookUrl, muaddib.failLevel

Ver vscode-extension/README.md para la documentación completa.

CI/CD

GitHub Actions (Marketplace)

Mínimo (fallar la compilación en amenazas HIGH+, escaneo único):

name: Security Scan

on: [push, pull_request]

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: DNSZLSK/[email protected]   # fijar a una etiqueta publicada
        with:
          fail-on: 'high'

Con SARIF subido a la pestaña Security (requiere security-events: write; ejecuta una segunda pasada para emitir SARIF):

jobs:
  scan:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      security-events: write
    steps:
      - uses: actions/checkout@v4
      - uses: DNSZLSK/[email protected]
        with:
          path: '.'
          fail-on: 'high'
          sarif: 'results.sarif'

Entradas

Salidas (consumir en pasos posteriores mediante steps.<id>.outputs.*)

Hooks de pre-commit

muaddib init-hooks                        # Auto-detección (husky/pre-commit/git)
muaddib init-hooks --type husky           # Forzar husky
muaddib init-hooks --mode diff            # Solo bloquear amenazas NUEVAS

Con el framework pre-commit:

repos:
  - repo: https://github.com/DNSZLSK/muad-dib
    rev: v2.11.139
    hooks:
      - id: muaddib-scan

Evaluación

Última medición v2.11.48 (2026-05-26), solo reglas (el clasificador ML está inactivo — ver más abajo). Ground truth: 94 ataques reales dentro del alcance + 200 npm aleatorios + 124 PyPI + 107 adversariales/holdout.

Clasificador ML: inactivo. Un modelo XGBoost vive en src/ml/ pero nunca está conectado a muaddib scan, y se ejecuta SOLO-LOG en el monitor desde 2026-04-08 (el modelo entrenado colapsó, pendiente de reentrenamiento). Todos los números anteriores son solo de reglas.

Protocolo completo, historial por pista, la advertencia del límite de 35 de PyPI, la cobertura operativa (denominada GHSA) y la metodología de reentrenamiento del ML: Metodología de evaluación.

Contribuciones

Añadir IOCs

Edita los archivos YAML en iocs/:

- id: NEW-MALWARE-001
  name: "paquete-malicioso"
  version: "*"
  severity: critical
  confidence: high
  source: community
  description: "Descripción de la amenaza"
  references:
    - https://example.com/article
  mitre: T1195.002

Desarrollo

git clone https://github.com/DNSZLSK/muad-dib
cd muad-dib
npm install
npm test

Pruebas

• 4545 pruebas en 155 archivos de prueba modulares
• 56 pruebas de fuzzing - Entradas malformadas, ReDoS, unicode, binario
• Benchmark Datadog 17K - 14,587 muestras de malware confirmadas (dentro del alcance)
• Validación de ground truth - 96 ataques del mundo real (95.74% TPR@3, 88.30% TPR@20 — medición completa v2.11.48 en 94 dentro del alcance)
• Validación de falsos positivos (medición v2.11.48) - 1.10% FPR de reglas (6/545 escaneados), 2.50% en 200 aleatorios, 9.68% en 124/132 PyPI (primera medición honesta tras la corrección de descarga Track-D). El clasificador ML está actualmente inactivo — ver Métricas de evaluación → Clasificador ML.

Comunidad

• Discord: https://discord.gg/y8zxSmue

Documentación

• Blog - Artículos técnicos sobre detección de amenazas en la cadena de suministro
• Carnet de bord - Diario de desarrollo (en francés)
• Índice de documentación - Toda la documentación en un solo lugar
• Metodología de evaluación - Protocolo experimental, puntuaciones holdout
• Modelo de amenazas - Qué detecta y qué no detecta MUAD'DIB
• Política de seguridad - Referencia de reglas de detección (278 reglas)
• Auditoría de seguridad - Informe de validación de bypass
• Análisis de FP - Análisis histórico de falsos positivos

Licencia

MUAD'DIB está licenciado bajo la GNU Affero General Public License v3.0 only (AGPL-3.0-only) — ver LICENSE y NOTICE.

Eres libre de usar, estudiar, modificar y redistribuir — incluso a través de una red — siempre que las obras derivadas y las modificaciones desplegadas en red se publiquen bajo la misma licencia.

Licencia comercial: para integrar MUAD'DIB en un producto propietario / de código cerrado, o para ofrecerlo como un servicio alojado sin las obligaciones de divulgación de código fuente de AGPL, hay disponible una licencia comercial separada. Abre un issue o contacta al autor (DNSZLSK).

Copyright (C) 2026 DNSZLSK.

La especia debe fluir. Los gusanos deben morir.