muad-dib

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

Versión francesa

¿Por qué MUAD'DIB?

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

MUAD'DIB combina 22 escáneres en paralelo (277 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. En el código base existe un clasificador XGBoost, pero actualmente está inactivo (consulta 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 exfiltración tras robo de credenciales, payloads ofuscados y otros patrones de comportamiento sospechosos — localmente, sin telemetría.

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

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

Alcance

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

Fuera del 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 son npm/PyPI (RubyGems, Maven, Go). Un fingerprinting anti-sandbox determinado 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 de npm. Las alertas por webhook son opcionales (opt-in).

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 /path/to/project

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

Modo interactivo

muaddib

Instalación segura

muaddib install <package>
muaddib install lodash axios --save-dev
muaddib install suspicious-pkg --force    # Force install despite threats

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 manual de respuesta para cada detección.

Exportación

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

Umbral de severidad

muaddib scan . --fail-on critical  # Fail only on CRITICAL
muaddib scan . --fail-on high      # Fail on HIGH and CRITICAL (default)

Modo paranoico

muaddib scan . --paranoid

Detección ultraestricta con menor tolerancia. Detecta cualquier acceso a la 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 tokens canary. Triaje por prioridad (v2.10.21): P1 (rojo, IOC/sandbox/canary), P2 (naranja, puntuación alta/compuestos), P3 (amarillo, el resto).

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

muaddib scan . --temporal-full     # All 4 temporal features
muaddib scan . --temporal          # Sudden lifecycle script detection
muaddib scan . --temporal-ast      # AST diff between versions
muaddib scan . --temporal-publish  # Publish frequency anomaly
muaddib scan . --temporal-maintainer # Maintainer change detection

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

Sandbox Docker

muaddib sandbox <package-name>
muaddib sandbox <package-name> --strict

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

Otros comandos

muaddib watch .                    # Real-time monitoring
muaddib daemon                     # Daemon mode (auto-scan npm install)
muaddib update                     # Update IOCs (fast, ~5s)
muaddib scrape                     # Full IOC refresh (~5min)
muaddib diff HEAD~1                # Compare threats with previous commit
muaddib init-hooks                 # Pre-commit hooks (husky/pre-commit/git)
muaddib scan . --breakdown         # Explainable score decomposition
muaddib replay                     # Ground truth validation (90/94 TPR@3, v2.11.48)

Características

22 escáneres en paralelo

277 reglas de detección

Todas las reglas (272 REGLAS + 5 PARANOID) están mapeadas a técnicas de MITRE ATT&CK. Consulta 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

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

CI/CD

GitHub Actions (Marketplace)

name: Security Scan

on: [push, pull_request]

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

Hooks de pre-commit

muaddib init-hooks                        # Auto-detect (husky/pre-commit/git)
muaddib init-hooks --type husky           # Force husky
muaddib init-hooks --mode diff            # Only block NEW threats

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). Verdad fundamental: 94 ataques reales dentro del alcance + 200 npm aleatorios + 124 PyPI + 107 adversariales/holdout.

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

Protocolo completo, historial por pista, la advertencia del límite de 35 en PyPI, la cobertura operativa (denominada en 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: "malicious-package"
  version: "*"
  severity: critical
  confidence: high
  source: community
  description: "Threat description"
  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 152 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 verdad fundamental - 96 ataques del mundo real (95.74% TPR@3, 88.30% TPR@20 — medición completa v2.11.48 sobre 94 dentro del alcance)
• Validación de falsos positivos (medición v2.11.48) - 1.10% FPR de reglas (6/545 escaneados), 2.50% sobre 200 aleatorios, 9.68% sobre 124/132 PyPI (primera medición honesta tras la corrección de descarga del 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 (277 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 GNU Affero General Public License v3.0 only (AGPL-3.0-only) — consulta LICENSE y NOTICE.

Eres libre de usarlo, estudiarlo, modificarlo y redistribuirlo — 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, u ofrecerlo como un servicio alojado sin las obligaciones de divulgación del código fuente del AGPL, hay disponible una licencia comercial independiente. Abre un issue o ponte en contacto con el autor (DNSZLSK).

Copyright (C) 2026 DNSZLSK.

La especia debe fluir. Los gusanos deben morir.