Toolkit Miasma / Shai-Hulud

Herramientas de análisis de incidentes + detección/remediación para el gusano Miasma (una variante Mini Shai-Hulud) que inyecta cargas útiles de auto-ejecución en configuraciones de agentes de IA / IDE y repositorios npm/GitHub.

⚠️ Aviso legal — sin garantía. Este es un kit de herramientas defensivo comunitario proporcionado "tal cual", sin garantía de ningún tipo (consulte LICENSE). El escáner y las reglas YARA son de solo lectura, pero purge-history.sh reescribe el historial de git y los hooks de .claude/ mueven archivos a cuarentena — ambos pueden alterar un repositorio. Haga una copia de seguridad primero, revise qué hace cada herramienta y ejecútela bajo su propio riesgo. Un análisis limpio no es una garantía de seguridad: los indicadores evolucionan y aparecen nuevas variantes. Úselo en sistemas y cuentas que esté autorizado a inspeccionar. ¿Encontró una brecha o un error? Consulte SECURITY.md y CONTRIBUTING.md.

Contenido

Requisitos previos

Instale YARA (Windows): winget install VirusTotal.YARA — o choco install yara / scoop install yara. En Linux/macOS: apt install yara / brew install yara. Verifique con yara --version.

Uso rápido

Nota: -Mode Local escanea solo $env:USERPROFILE por defecto. Pase -CodeRoots para cubrir repositorios en otras ubicaciones, p. ej. -CodeRoots E:\Sources,D:\work.

# Escanea la máquina local + repositorios locales (+ CVE-2026-35603 ProgramData)
pwsh -File Scan-Miasma.ps1 -Mode Local
pwsh -File Scan-Miasma.ps1 -Mode Local -CodeRoots E:\Sources,D:\work

# Escanea repositorios remotos de GitHub (autentíquese primero en la cuenta objetivo para repositorios/secretos privados)
gh auth login
pwsh -File Scan-Miasma.ps1 -Mode Remote -Owners su-org,su-usuario -OutReport report.md

# Todo + JSON + informe Markdown
pwsh -File Scan-Miasma.ps1 -OutJson findings.json -OutReport report.md

Código de salida 1 si hay algún hallazgo INFECTADO (compatible con CI).

# Purga el historial de un repositorio infectado (revise PATHS en el script primero)
./purge-history.sh /ruta/al/repo
# luego, después de revisar la verificación:
git push origin --force --all && git push origin --force --tags

# Escaneo YARA
yara -r setup-js.yar /ruta/a/escanear

# Linux/macOS: escaneo local (puerto Bash — usa $HOME por defecto; pase raíces para ampliar)
./scan-miasma.sh
./scan-miasma.sh ~/src /opt/work

# Desofusca estáticamente un dropper capturado (solo lectura — nunca lo ejecuta)
pwsh -File Expand-MiasmaPayload.ps1 -Path .github/setup.js   # escribe capas + iocs.txt en <Path>.deob/
pwsh -File Expand-MiasmaPayload.ps1 -SelfTest                # verifica el motor de decodificación/descifrado

El desofuscador desempaqueta la oleada del empaquetador p,a,c,k,e,d, decodifica la oleada de códigos de caracteres, detecta automáticamente y revierte el desplazamiento César (anule con -Shift), luego descifra cada blob AES-128-GCM incrustado (_b bootstrap, _p ladrón) y escanea el código recuperado en busca de URLs, IPs y cuentas de drop muerto.

# Después de la erradicación: genera una lista de verificación priorizada de rotación de secretos (no revoca nada)
pwsh -File Invoke-MiasmaRotation.ps1                       # detecta credenciales accesibles aquí
pwsh -File Invoke-MiasmaRotation.ps1 -OutReport rotation.md

Guardia de CI (rechazar compilar si el dropper/lanzador está presente)

Use la acción compuesta incluida como primer paso de cualquier flujo de trabajo:

# En otro repositorio (fíjese a una etiqueta/SHA para seguridad de cadena de suministro):
- uses: actions/checkout@v4
- uses: jchable/miasma-toolkit/.github/actions/miasma-guard@main
  # with:
  #   full-scan: 'true'   # también ejecuta Scan-Miasma.ps1 -Mode Local (necesita pwsh)

Este kit ejecuta la misma guardia sobre sí mismo a través de .github/workflows/miasma-ci.yml (referenciando la acción por ruta relativa). La guardia es independiente de la oleada y está enfocada en los archivos de configuración del lanzador del gusano, por lo que nunca da falsos positivos en documentos que solo mencionan la cadena IOC.

Hooks de Claude Code (.claude/)

Protección en tiempo real para máquinas que ejecutan Claude Code en este repositorio. Los hooks reutilizan iocs.psd1 (sin indicadores duplicados) y están conectados en .claude/settings.json:

• La cuarentena es reversible: los archivos infectados se mueven a .miasma-quarantine/<marca de tiempo>/… (ignorados por git) y se registran en .miasma-quarantine/quarantine.log — restáurelos con Move-Item. No se elimina nada de forma permanente.
• Autoexclusión (Test-MiasmaExcluded en Miasma.Common.ps1): los propios archivos del kit contienen legítimamente cadenas IOC (iocs.psd1, Scan-Miasma.ps1, scan-miasma.sh, Expand-MiasmaPayload.ps1, Invoke-MiasmaRotation.ps1, purge-history.sh, setup-js.yar, content/, , , ) y nunca son bloqueados/puestos en cuarentena.

Modelo de gravedad (Scan-Miasma.ps1)

• INFECTADO — DROPPER, INJECT, FORGED, BADDEP, WORKFLOW, RUNNER, PAYLOAD, BUN-DROP, PROGRAMDATA
• REVISAR — NPM-AUDIT, SECRETS (inventario de rotación), SIGNATURE, PERSIST, PROGRAMDATA-CFG

Errores conocidos ya corregidos (tener en cuenta al rehacer)

• gh api <404> --jq vuelca el cuerpo del error a stdout → nunca confíe en la veracidad de la salida; verifique $LASTEXITCODE + valide el formato (tamaño numérico, nombre de rama exacto).
• GitHub mantiene una redirección master→main tras el cambio de nombre → branches/master devuelve 200; solo acepte una rama si el nombre devuelto == nombre solicitado.
• npm audit debe permanecer con --package-lock-only (sin npm install, sin ejecución de scripts).

TODO / pendientes de reelaboración

La lista original (puerto Bash, insignias de gravedad, desofuscación de oleadas de packer, ayuda de rotación) está completa. Ideas futuras:

1. scan-miasma.sh: añadir el modo remoto/GitHub (actualmente solo local).
2. Desofuscador: manejar ROT-4/ROT-9 multibyte y variantes que no sean AES-128-GCM si se observan.
3. Ayuda de rotación: modo --revoke opcional (restringido, con confirmación) para gh/npm/aws.

Referencias

• The bot that never was — icflorescu (dev.to)
• Miasma worm: AI coding agent config injection — safedep.io
• CVE-2026-35603: AI coding tools privilege escalation — Cymulate