muad-dib — Detección de amenazas en la cadena de suministro de npm/PyPI en tiempo real. Análisis de cadenas de comportamiento, escaneo de AST, fuentes de IOC y motor de puntuación compuesta. | Kitploit
<p align="center">
  <img src="https://assets.kitploit.com/production/public/readmes/10373/84132538a800a2879cff088259fe9e98e975a3fe37f8462fe731d6a06f82314a.png" alt="MUAD'DIB Logo" width="700">
</p>

<p align="center">
  <a href="https://www.npmjs.com/package/muaddib-scanner"><img src="https://img.shields.io/npm/v/muaddib-scanner" alt="npm version"></a>
  <a href="https://github.com/DNSZLSK/muad-dib/actions/workflows/scan.yml"><img src="https://github.com/DNSZLSK/muad-dib/actions/workflows/scan.yml/badge.svg" alt="CI"></a>
  <a href="https://codecov.io/gh/DNSZLSK/muad-dib"><img src="https://codecov.io/gh/DNSZLSK/muad-dib/branch/master/graph/badge.svg" alt="Coverage"></a>
  <a href="https://scorecard.dev/viewer/?uri=github.com/DNSZLSK/muad-dib"><img src="https://api.scorecard.dev/projects/github.com/DNSZLSK/muad-dib/badge" alt="OpenSSF Scorecard"></a>
  <img src="https://img.shields.io/badge/license-AGPL--3.0--only-blue" alt="License">
  <img src="https://img.shields.io/badge/node-%3E=18-brightgreen" alt="Node">
  <img src="https://img.shields.io/badge/IOCs-225,000+-red" alt="IOCs">
</p>

<p align="center">
  <a href="#installation">Instalación</a> |
  <a href="#usage">Uso</a> |
  <a href="#features">Características</a> |
  <a href="#vs-code">VS Code</a> |
  <a href="#cicd">CI/CD</a>
</p>

<p align="center">
  <a href="https://github.com/dnszlsk/muad-dib/blob/master/docs/README.fr.md">Version française</a>
</p>

---

## ¿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 **<!--stat:scanners-->22<!--/stat:scanners--> escáneres paralelos** (<!--stat:rulesTotal-->278<!--/stat:rulesTotal--> reglas de detección), un **motor de desofuscación**, **análisis de flujo de datos entre módulos**, **puntuación compuesta** (<!--stat:compound-->21<!--/stat:compound--> 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](#evaluation)).

---

## 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](#license)).

Deliberadamente no intenta hacerlo todo — ver [Alcance](#scope) 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](https://github.com/dnszlsk/muad-dib/blob/master/docs/threat-model.md).

**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)

```bash
npm install -g muaddib-scanner
```

### Desde el código fuente

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

---

## Uso

### Escaneo básico

```bash
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

```bash
muaddib
```

### Instalación segura

```bash
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

```bash
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

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

### Umbral de severidad

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

### Modo paranoico

```bash
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

```bash
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)

```bash
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](https://github.com/dnszlsk/muad-dib/blob/master/docs/EVALUATION_METHODOLOGY.md) para más detalles.

### Sandbox Docker

```bash
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

```bash
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

### <!--stat:scanners-->22<!--/stat:scanners--> escáneres paralelos

| Escáner | Detección |
|---------|-----------|
| Análisis AST (acorn) | eval, Function, robo de credenciales, droppers binarios, hooks de prototipo |
| Coincidencia de patrones | Comandos de shell, reverse shells, interruptor de hombre muerto |
| Análisis de flujo de datos | Lectura de credenciales + envío por red (intra-archivo y entre archivos) |
| Detección de ofuscación | Patrones de ofuscación JS (omitir .min.js) |
| Preprocesamiento de desofuscación | Concatenación de cadenas, charcode, base64, array hexadecimal, propagación de constantes |
| Flujo de datos entre módulos | Propagación de taint entre archivos (cadenas de 3 saltos, métodos de clase) |
| Coherencia de intención | Emparejamiento fuente-sumidero intra-archivo (credencial + eval/red) |
| Typosquatting | npm + PyPI (distancia de Levenshtein) |
| Escáner Python | requirements.txt, setup.py, pyproject.toml, más de 14K IOCs de PyPI |
| Entropía de Shannon | Cadenas de alta entropía (5.5 bits + mínimo 50 caracteres) |
| Escáner de config de IA | Inyección en .cursorrules, CLAUDE.md, copilot-instructions.md |
| Paquete/Dependencias | Scripts de ciclo de vida, coincidencia de IOCs (más de 225K paquetes) |
| GitHub Actions | Detección de backdoor Shai-Hulud |
| Escáner de hashes | Hashes de archivos maliciosos conocidos |
| Cadenas IOC (intel-triage P1.1) | Coincidencia de cadenas estilo YARA (Axios 2026, TeamPCP, GlassWorm, CanisterSprawl) |
| AST anti-forense (intel-triage P1.2) | Compuesto de bucle XOR + auto-eliminación + escritura señuelo (autodelete csec) |
| Paquete stub (intel-triage P1.3) | Archivo principal diminuto + URL de dependencia externa + hook de ciclo de vida (cadena ltidi) |
| Escáner de monorepos | Detección de Lerna/pnpm-workspace/turbo (auditoría Sprint 1, corrección MR-C2) |
| Diff de dependencias confiables (opt-in) | Diff contra tarballs de dependencias confiables del registro (v2.10.x) |
| Código fuente Python (PYSRC) | Patrones de RCE en tiempo de importación/instalación en `__init__.py` / `setup.py` (v2.11.41 — cierra la brecha TrapDoor de PyPI) |
| AST Python (PYAST) | AST de Tree-sitter-Python con detectores conscientes de taint (v2.11.42+) |
| Inyección anti-escáner (ASI) | Texto de inyección de prompts en comentarios/cadenas que coacciona a un revisor de código LLM a dar un veredicto limpio o a omitir un payload ofuscado (ASI-001..004, campaña Hades 2026-06) |

### <!--stat:rulesTotal-->278<!--/stat:rulesTotal--> reglas de detección

Todas las reglas (<!--stat:rulesCore-->273<!--/stat:rulesCore--> RULES + <!--stat:rulesParanoid-->5<!--/stat:rulesParanoid--> PARANOID) están mapeadas a técnicas MITRE ATT&CK. Ver [SECURITY.md](https://github.com/dnszlsk/muad-dib/blob/master/SECURITY.md#detection-rules) para la referencia completa de reglas.

### Campañas detectadas

| Campaña | Estado |
|----------|--------|
| GlassWorm (2026, más de 433 paquetes) | Detectada |
| Shai-Hulud v1/v2/v3 (2025) | Detectada |
| event-stream (2018) | Detectada |
| eslint-scope (2018) | Detectada |
| Protestware (node-ipc, colors, faker) | Detectado |
| Typosquats (crossenv, mongose, babelcli) | Detectados |

---

## VS Code

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

```bash
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](https://github.com/dnszlsk/muad-dib/blob/master/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):

```yaml
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):

```yaml
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**

| Entrada | Descripción | Por defecto |
|-------|-------------|---------|
| `path` | Ruta a escanear | `.` |
| `fail-on` | Severidad mínima para fallar (`critical`/`high`/`medium`/`low`/`none`) | `high` |
| `sarif` | Ruta del archivo de salida SARIF — configurar también para subir a la pestaña Security | |
| `paranoid` | Detección ultraestricta (mayor FPR) | `false` |
| `version` | Versión npm de `muaddib-scanner` a instalar | `latest` |

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

| Salida | Descripción |
|--------|-------------|
| `risk-score` | Puntuación de riesgo 0–100 |
| `risk-level` | `SAFE` / `LOW` / `MEDIUM` / `HIGH` / `CRITICAL` |
| `threats-count` | Total de amenazas detectadas |
| `critical-count` / `high-count` | Amenazas por severidad |
| `exit-code` | `0` = pasó la puerta de `fail-on`, distinto de cero en caso contrario |
| `sarif-file` | Ruta del archivo SARIF (vacío si `sarif` no está configurado) |

### Hooks de pre-commit

```bash
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:
```yaml
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.

| Métrica | Resultado |
|--------|--------|
| Tasa de detección (TPR@3) | **95.74%** (90/94) |
| Tasa de alertas (TPR@20) | **88.30%** (83/94) |
| FPR — npm curado (548) | **1.10%** (6/545) |
| FPR — npm aleatorio (200) | **2.50%** (5/200) |
| FPR — PyPI (132) | **9.68%** (12/124) |
| ADR — adversarial + holdout | **96.26%** (103/107) |
| TPR salvaje (Datadog 17K) | **92.8%** (13,538/14,587) |

**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](https://github.com/dnszlsk/muad-dib/blob/master/docs/EVALUATION_METHODOLOGY.md).

---

## Contribuciones

### Añadir IOCs

Edita los archivos YAML en `iocs/`:

```yaml
- 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

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

### Pruebas

- **<!--stat:tests-->4545<!--/stat:tests--> pruebas** en <!--stat:testFiles-->155<!--/stat:testFiles--> 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](https://dnszlsk.github.io/muad-dib/blog/) - Artículos técnicos sobre detección de amenazas en la cadena de suministro
- [Carnet de bord](https://github.com/dnszlsk/muad-dib/blob/master/docs/CARNET_DE_BORD_MUADDIB.md) - Diario de desarrollo (en francés)
- [Índice de documentación](https://github.com/dnszlsk/muad-dib/blob/master/docs/INDEX.md) - Toda la documentación en un solo lugar
- [Metodología de evaluación](https://github.com/dnszlsk/muad-dib/blob/master/docs/EVALUATION_METHODOLOGY.md) - Protocolo experimental, puntuaciones holdout
- [Modelo de amenazas](https://github.com/dnszlsk/muad-dib/blob/master/docs/threat-model.md) - Qué detecta y qué no detecta MUAD'DIB
- [Política de seguridad](https://github.com/dnszlsk/muad-dib/blob/master/SECURITY.md) - Referencia de reglas de detección (<!--stat:rulesTotal-->278<!--/stat:rulesTotal--> reglas)
- [Auditoría de seguridad](https://github.com/dnszlsk/muad-dib/blob/master/docs/SECURITY_AUDIT.md) - Informe de validación de bypass
- [Análisis de FP](https://github.com/dnszlsk/muad-dib/blob/master/docs/EVALUATION.md) - 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](https://github.com/dnszlsk/muad-dib/blob/master/LICENSE) y [NOTICE](https://github.com/dnszlsk/muad-dib/blob/master/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](https://github.com/DNSZLSK)).

Copyright (C) 2026 DNSZLSK.

---

<p align="center">
  <strong>La especia debe fluir. Los gusanos deben morir.</strong>
</p>
Más Populares

muad-dib
