Miasma / Shai-Hulud toolkit

Analisi degli incidenti + strumenti di rilevamento/risanamento per il worm Miasma (una variante Mini Shai-Hulud) che inietta payload ad avvio automatico nelle configurazioni di agenti AI / IDE e nei repository npm/GitHub.

⚠️ Disclaimer — nessuna garanzia. Questo è un toolkit difensivo comunitario fornito "così com'è", senza garanzie di alcun tipo (vedi LICENSE). Lo scanner e le regole YARA sono di sola lettura, ma purge-history.sh riscrive la cronologia git e gli hook .claude/ spostano i file in quarantena — entrambe le cose possono alterare un repository. Fai un backup prima, verifica cosa fa ogni strumento ed eseguilo a tuo rischio. Una scansione pulita non è una garanzia di sicurezza: gli indicatori evolvono e compaiono nuove varianti. Usalo su sistemi e account che sei autorizzato a ispezionare. Hai trovato una lacuna o un bug? Vedi SECURITY.md e CONTRIBUTING.md.

Contenuti

Prerequisiti

Installa YARA (Windows): winget install VirusTotal.YARA — oppure choco install yara / scoop install yara. Su Linux/macOS: apt install yara / brew install yara. Verifica con yara --version.

Utilizzo rapido

Nota: -Mode Local esegue la scansione solo di $env:USERPROFILE per impostazione predefinita. Passa -CodeRoots per coprire repository altrove, es. -CodeRoots E:\Sources,D:\work.

# Scan local machine + local repos (+ CVE-2026-35603 ProgramData)
pwsh -File Scan-Miasma.ps1 -Mode Local
pwsh -File Scan-Miasma.ps1 -Mode Local -CodeRoots E:\Sources,D:\work

# Scan remote GitHub repos (authenticate on the target account first for private repos/secrets)
gh auth login
pwsh -File Scan-Miasma.ps1 -Mode Remote -Owners your-org,your-user -OutReport report.md

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

Codice di uscita 1 se è presente un qualsiasi esito INFECTED (compatibile CI).

# Purge history of an infected repo (review PATHS in the script first)
./purge-history.sh /path/to/repo
# then, after reviewing the verification:
git push origin --force --all && git push origin --force --tags

# YARA scan
yara -r setup-js.yar /path/to/scan

# Linux/macOS: local scan (bash port — defaults to $HOME; pass roots to widen)
./scan-miasma.sh
./scan-miasma.sh ~/src /opt/work

# Statically deobfuscate a captured dropper (read-only — never runs it)
pwsh -File Expand-MiasmaPayload.ps1 -Path .github/setup.js   # writes layers + iocs.txt to <Path>.deob/
pwsh -File Expand-MiasmaPayload.ps1 -SelfTest                # verify the decode/decrypt engine

Il deoffuscatore decomprime il layer packer p,a,c,k,e,d, decodifica il layer a codici-char, rileva automaticamente e inverte lo scorrimento Caesar (sostituibile con -Shift), quindi decrittografa ogni blob AES-128-GCM incorporato (_b bootstrapper, _p stealer) ed esamina il codice recuperato alla ricerca di URL, IP e account dead-drop.

# After eradication: generate a prioritized secret-rotation checklist (revokes nothing)
pwsh -File Invoke-MiasmaRotation.ps1                       # detects creds reachable here
pwsh -File Invoke-MiasmaRotation.ps1 -OutReport rotation.md

Guardia CI (rifiuta la build se dropper/launcher è presente)

Usa l'azione composita inclusa come primo passo di qualsiasi workflow:

# In another repo (pin to a tag/SHA for supply-chain safety):
- uses: actions/checkout@v4
- uses: jchable/miasma-toolkit/.github/actions/miasma-guard@main
  # with:
  #   full-scan: 'true'   # also run Scan-Miasma.ps1 -Mode Local (needs pwsh)

Questo toolkit esegue la stessa guardia su sé stesso tramite .github/workflows/miasma-ci.yml (facendo riferimento all'azione tramite percorso relativo). La guardia è indipendente dalla variante ed è limitata ai file di configurazione del launcher del worm, quindi non produce falsi positivi sui documenti che menzionano soltanto la stringa IOC.

Hook Claude Code (.claude/)

Protezione in tempo reale per le macchine che eseguono Claude Code in questo repository. Gli hook riutilizzano iocs.psd1 (nessun indicatore duplicato) e sono collegati in .claude/settings.json:

• La quarantena è reversibile: i file infetti vengono spostati in .miasma-quarantine/<timestamp>/… (ignorati da git) e registrati in .miasma-quarantine/quarantine.log — ripristino con Move-Item. Nulla viene eliminato definitivamente.
• Auto-esclusione (Test-MiasmaExcluded in Miasma.Common.ps1): i file del toolkit stesso contengono legittimamente stringhe IOC (iocs.psd1, Scan-Miasma.ps1, scan-miasma.sh, Expand-MiasmaPayload.ps1, Invoke-MiasmaRotation.ps1, purge-history.sh, setup-js.yar, content/, , , ) e non vengono mai bloccati/messi in quarantena.

Modello di gravità (Scan-Miasma.ps1)

• INFECTED — DROPPER, INJECT, FORGED, BADDEP, WORKFLOW, RUNNER, PAYLOAD, BUN-DROP, PROGRAMDATA
• REVIEW — NPM-AUDIT, SECRETS (inventario di rotazione), SIGNATURE, PERSIST, PROGRAMDATA-CFG

Bug noti già corretti (da tenere presenti in caso di refactoring)

• gh api <404> --jq invia il corpo dell'errore su stdout → non fidarti mai della veridicità dell'output; controlla $LASTEXITCODE + valida il formato (dimensione numerica, nome esatto del branch).
• GitHub mantiene un redirect master→main dopo la rinomina → branches/master restituisce 200; accetta un branch solo se il nome restituito == nome richiesto.
• npm audit deve rimanere --package-lock-only (niente npm install, nessuno script eseguito).

TODO / backlog di rework

Il backlog originale (porting bash, badge di gravità, deoffuscamento del layer packer, helper di rotazione) è completato. Idee future:

1. scan-miasma.sh: aggiungere la modalità remota/GitHub (attualmente solo locale).
2. Deoffuscatore: gestire le varianti ROT-4/ROT-9 multibyte e non-AES-128-GCM se osservate.
3. Helper di rotazione: modalità --revoke opzionale (protetta, con conferma) per gh/npm/aws.

Riferimenti

• 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