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

File	Descrizione
content/incident-report.fr.md / content/incident-report.en.md	Resoconto completo: come funziona, deoffuscamento del payload, IOC, eradicazione
Scan-Miasma.ps1	Scanner unificato (locale + remoto), report JSON strutturato + report Markdown per repository — usa questo
iocs.psd1	Indicatori condivisi (hash, firme, pacchetti dannosi, configurazioni) caricati dallo scanner — modifica gli IOC qui
Expand-MiasmaPayload.ps1	Deoffuscatore statico per setup.js — rimuove i layer packer/codici-char → Caesar → AES-128-GCM ed estrae C2/IOC (non esegue mai il payload)
Invoke-MiasmaRotation.ps1	Checklist di rotazione dei segreti — rileva quali credenziali sono raggiungibili da qui e stampa i comandi di revoca (sola lettura; non revoca nulla)
scan-miasma.sh	Porting Bash della scansione locale per Linux/macOS (sottoinsieme multipiattaforma)
purge-history.sh	Elimina i file dannosi da tutta la cronologia git (filter-repo → filter-branch) + backup
setup-js.yar	Regole YARA per il dropper + configurazioni del launcher
.github/actions/miasma-guard/	Azione composita GitHub Actions riutilizzabile — rifiuta la build se dropper/launcher è presente
.claude/	Hook Claude Code — protezione/quarantena in tempo reale + comando /miasma-scan (vedi sotto)

Prerequisiti

Tool	Serve per	Obbligatorio?
PowerShell 7+ (pwsh)	Scan-Miasma.ps1, Expand-MiasmaPayload.ps1, Invoke-MiasmaRotation.ps1	obbligatorio (questi strumenti)
bash + coreutils (sha256sum/shasum, awk, find)	scan-miasma.sh (Linux/macOS)	solo il porting bash
git	controlli della cronologia dei repository locali, purge-history.sh	obbligatorio
GitHub CLI (gh, autenticato)	Scan-Miasma.ps1 -Mode Remote	solo scansione remota
npm	npm audit remoto (solo lockfile)	facoltativo (saltato automaticamente se assente)
git-filter-repo	riscrittura cronologia preferita (ripiega su git filter-branch integrato)	facoltativo
YARA (yara)	scansione setup-js.yar	facoltativo

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:

Hook	Evento	Azione
Guard-Write.ps1	PreToolUse (Write/Edit/MultiEdit)	Blocca una scrittura che inietterebbe un IOC del worm (annulla la chiamata dello strumento)
Guard-Bash.ps1	PreToolUse (Bash)	Blocca l'esecuzione del worm — node .github/setup.js, bun/bunx, un installer bun.sh via pipe
Scan-Write.ps1	PostToolUse (Write/Edit/MultiEdit)	Avvisa e mette in quarantena un file infetto dopo che viene scritto
Session-Sweep.ps1	SessionStart	Scansione rapida del repository; segnala qualsiasi infezione preesistente nel contesto
/miasma-scan	comando	Wrapper on-demand attorno a Scan-Miasma.ps1