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

Datei	Zweck
content/incident-report.fr.md / content/incident-report.en.md	Vollständiger Bericht: Funktionsweise, Payload-Entschleierung, IOCs, Beseitigung
Scan-Miasma.ps1	Einheitlicher Scanner (lokal + remote), strukturiertes JSON + Pro-Repo-Markdown-Bericht — dieses verwenden
iocs.psd1	Gemeinsame Indikatoren (Hashes, Signaturen, bösartige Pakete, Konfigurationen), geladen vom Scanner — IOCs hier bearbeiten
Expand-MiasmaPayload.ps1	Statischer Entschleierer für setup.js — entfernt Packer/Zeichenkodierung → Caesar → AES-128-GCM und extrahiert die C2/IOCs (führt die Payload nie aus)
Invoke-MiasmaRotation.ps1	Checkliste für Schlüsselrotation — erkennt, welche Anmeldedaten hier erreichbar sind, und gibt die Widerrufsbefehle aus (schreibgeschützt; widerruft nichts)
scan-miasma.sh	Bash-Port des lokalen Scans für Linux/macOS (plattformübergreifende Teilmenge)
purge-history.sh	Bereinigt bösartige Dateien aus der gesamten Git-Historie (filter-repo → filter-branch) + Backup
setup-js.yar	YARA-Regeln für den Dropper + Launcher-Konfigurationen
.github/actions/miasma-guard/	Wiederverwendbare GitHub Actions Composite Action — verweigert den Build, wenn der Dropper/Launcher vorhanden ist
.claude/	Claude Code Hooks — Echtzeit-Schutz/Quarantäne + /miasma-scan-Befehl (siehe unten)

Voraussetzungen

Tool	Benötigt für	Erforderlich?
PowerShell 7+ (pwsh)	Scan-Miasma.ps1, Expand-MiasmaPayload.ps1, Invoke-MiasmaRotation.ps1	erforderlich (diese Tools)
bash + coreutils (sha256sum/shasum, awk, find)	scan-miasma.sh (Linux/macOS)	nur der Bash-Port
git	Lokale Repo-Historie-Prüfungen, purge-history.sh	erforderlich
GitHub CLI (gh, authentifiziert)	Scan-Miasma.ps1 -Mode Remote	nur Remote-Scan
npm	Remote npm audit (nur Lockfile)	optional (automatisch übersprungen, wenn nicht vorhanden)
git-filter-repo	Bevorzugte Historien-Umschreibung (fällt auf integriertes git filter-branch zurück)	optional
YARA (yara)	setup-js.yar-Scan	optional

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: