Miasma / Shai-Hulud Toolkit

Vorfallanalyse + Erkennungs-/Behebungswerkzeuge für den Miasma-Wurm (eine Mini Shai-Hulud-Variante), der Auto-Start-Payloads in AI-Agenten-/IDE-Konfigurationen und npm/GitHub-Repositories einschleust.

⚠️ Haftungsausschluss — keine Gewährleistung. Dieses Community-Abwehr-Toolkit wird "wie besehen" ohne jegliche Gewährleistung bereitgestellt (siehe LICENSE). Der Scanner und die YARA-Regeln sind schreibgeschützt, aber purge-history.sh überschreibt die Git-Historie und die .claude/-Hooks verschieben Dateien in Quarantäne – beide können ein Repository verändern. Erstellen Sie zuerst ein Backup, prüfen Sie, was jedes Tool tut, und führen Sie es auf eigenes Risiko aus. Ein sauberer Scan ist keine Garantie für Sicherheit: Indikatoren entwickeln sich weiter und neue Varianten tauchen auf. Verwenden Sie es nur auf Systemen und Konten, die Sie zu überprüfen berechtigt sind. Eine Lücke oder einen Fehler gefunden? Siehe SECURITY.md und CONTRIBUTING.md.

Inhalt

Voraussetzungen

YARA installieren (Windows): winget install VirusTotal.YARA — oder choco install yara / scoop install yara. Unter Linux/macOS: apt install yara / brew install yara. Mit yara --version überprüfen.

Schnelle Verwendung

Hinweis: -Mode Local scannt standardmäßig nur $env:USERPROFILE. Übergeben Sie -CodeRoots, um auch Repos an anderen Orten abzudecken, z.B. -CodeRoots E:\Sources,D:\work.

# Lokalen Rechner + lokale Repos scannen (inkl. CVE-2026-35603 ProgramData)
pwsh -File Scan-Miasma.ps1 -Mode Local
pwsh -File Scan-Miasma.ps1 -Mode Local -CodeRoots E:\Sources,D:\work

# Remote-GitHub-Repos scannen (für private Repos/Secrets zuerst auf dem Zielkonto authentifizieren)
gh auth login
pwsh -File Scan-Miasma.ps1 -Mode Remote -Owners your-org,your-user -OutReport report.md

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

Exit-Code 1 bei einem INFECTED-Befund (CI-kompatibel).

# Historie eines infizierten Repos bereinigen (zuerst die PATHS im Skript prüfen)
./purge-history.sh /path/to/repo
# dann nach Überprüfung:
git push origin --force --all && git push origin --force --tags

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

# Linux/macOS: Lokaler Scan (Bash-Port — standardmäßig $HOME; Wurzeln angeben, um zu erweitern)
./scan-miasma.sh
./scan-miasma.sh ~/src /opt/work

# Einen erfassten Dropper statisch entschleiern (schreibgeschützt — führt ihn nie aus)
pwsh -File Expand-MiasmaPayload.ps1 -Path .github/setup.js   # schreibt Ebenen + iocs.txt nach <Path>.deob/
pwsh -File Expand-MiasmaPayload.ps1 -SelfTest                # Dekodier-/Entschlüsselungs-Engine verifizieren

Der Entschleierer entpackt die p,a,c,k,e,d-Packerwelle, dekodiert die Zeichencode-Welle, erkennt automatisch und kehrt die Caesar-Verschiebung um (mit -Shift überschreibbar), entschlüsselt dann jeden eingebetteten AES-128-GCM-Blob (_b Bootstrapper, _p Stealer) und scannt den wiederhergestellten Code nach URLs, IPs und Dead-Drop-Konten.

# Nach der Beseitigung: eine priorisierte Checkliste für die Schlüsselrotation erstellen (widerruft nichts)
pwsh -File Invoke-MiasmaRotation.ps1                       # erkennt hier erreichbare Anmeldedaten
pwsh -File Invoke-MiasmaRotation.ps1 -OutReport rotation.md

CI-Guard (Build verweigern, wenn Dropper/Launcher vorhanden ist)

Verwenden Sie die gebündelte Composite-Action als ersten Schritt eines beliebigen Workflows:

# In einem anderen Repo (für Lieferkettensicherheit auf einen Tag/SHA pinnen):
- uses: actions/checkout@v4
- uses: jchable/miasma-toolkit/.github/actions/miasma-guard@main
  # with:
  #   full-scan: 'true'   # führt auch Scan-Miasma.ps1 -Mode Local aus (benötigt pwsh)

Dieses Toolkit führt denselben Guard auf sich selbst via .github/workflows/miasma-ci.yml aus (referenziert die Action per relativem Pfad). Der Guard ist wellenunabhängig und auf die Launcher-Konfigurationsdateien des Wurms beschränkt, sodass er nie falsch-positiv bei Dokumenten wird, die lediglich den IOC-String erwähnen.

Claude Code Hooks (.claude/)

Echtzeitschutz für Maschinen, die in diesem Repo Claude Code ausführen. Die Hooks verwenden iocs.psd1 wieder (keine doppelten Indikatoren) und sind in .claude/settings.json eingebunden:

• Quarantäne ist umkehrbar: infizierte Dateien werden verschoben nach .miasma-quarantine/<timestamp>/… (durch git ignoriert) und in .miasma-quarantine/quarantine.log protokolliert — mit Move-Item wiederherstellen. Nichts wird endgültig gelöscht.
• Selbstausschluss (Test-MiasmaExcluded in Miasma.Common.ps1): Die eigenen Dateien des Toolkits enthalten legitimerweise IOC-Strings (iocs.psd1, Scan-Miasma.ps1, scan-miasma.sh, Expand-MiasmaPayload.ps1, Invoke-MiasmaRotation.ps1, purge-history.sh, setup-js.yar, content/, , , ) und werden nie blockiert/quarantiniert.

Schweregradmodell (Scan-Miasma.ps1)

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

Bekannte, bereits behobene Fehler (bei Überarbeitungen beachten)

• gh api <404> --jq gibt den Fehlerkörper auf stdout aus → niemals auf die Wahrheit der Ausgabe verlassen; $LASTEXITCODE prüfen + Format validieren (numerische Größe, exakter Branchname).
• GitHub behält nach Umbenennung eine master→main-Weiterleitung → branches/master gibt 200 zurück; einen Branch nur akzeptieren, wenn der zurückgegebene Name == angefragter Name ist.
• npm audit muss --package-lock-only bleiben (kein npm install, keine Skriptausführung).

TODO / Überarbeitungs-Backlog

Das ursprüngliche Backlog (Bash-Port, Schweregrad-Badges, Packerwellen-Entschleierung, Rotationshilfe) ist erledigt. Zukünftige Ideen:

1. scan-miasma.sh: Remote-/GitHub-Modus hinzufügen (derzeit nur lokal).
2. Entschleierer: ROT-4/ROT-9-Multibyte- und Nicht-AES-128-GCM-Varianten behandeln, falls beobachtet.
3. Rotationshilfe: Optionaler --revoke-Modus (gesichert, mit Bestätigung) für gh/npm/aws.

Referenzen

• 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