Miasma / Shai-Hulud toolkit

Incident analysis + detection/remediation tooling for the Miasma worm (a Mini Shai-Hulud variant) that injects auto-run payloads into AI-agent / IDE configs and npm/GitHub repos.

⚠️ Disclaimer — no warranty. This is a community defensive toolkit provided "as is", without warranty of any kind (see LICENSE). The scanner and YARA rules are read-only, but purge-history.sh rewrites git history and the .claude/ hooks move files to quarantine — both can alter a repository. Back up first, review what each tool does, and run it at your own risk. A clean scan is not a guarantee of safety: indicators evolve and new variants appear. Use on systems and accounts you are authorized to inspect. Found a gap or a bug? See SECURITY.md and CONTRIBUTING.md.

Contents

Prerequisites

Install YARA (Windows): winget install VirusTotal.YARA — or choco install yara / scoop install yara. On Linux/macOS: apt install yara / brew install yara. Verify with yara --version.

Quick usage

Note: -Mode Local defaults to scanning $env:USERPROFILE only. Pass -CodeRoots to cover repos elsewhere, e.g. -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

Exit code 1 if any INFECTED finding (CI-friendly).

# 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

The deobfuscator unpacks the p,a,c,k,e,d packer wave, decodes the char-code wave, auto-detects and reverses the Caesar shift (override with -Shift), then decrypts every embedded AES-128-GCM blob (_b bootstrapper, _p stealer) and scans the recovered code for URLs, IPs, and dead-drop accounts.

# 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

CI guard (refuse to build if the dropper/launcher is present)

Use the bundled composite action as the first step of any 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)

This toolkit runs the same guard on itself via .github/workflows/miasma-ci.yml (referencing the action by relative path). The guard is wave-agnostic and scoped to the worm's launcher config files, so it never false-positives on docs that merely mention the IOC string.

Claude Code hooks (.claude/)

Real-time protection for machines that run Claude Code in this repo. The hooks reuse iocs.psd1 (no duplicated indicators) and are wired in .claude/settings.json:

• Quarantine is reversible: infected files are moved to .miasma-quarantine/<timestamp>/… (git-ignored) and logged to .miasma-quarantine/quarantine.log — restore with Move-Item. Nothing is hard-deleted.
• Self-exclusion (Test-MiasmaExcluded in Miasma.Common.ps1): the toolkit's own files legitimately contain IOC strings (iocs.psd1, Scan-Miasma.ps1, scan-miasma.sh, Expand-MiasmaPayload.ps1, Invoke-MiasmaRotation.ps1, purge-history.sh, setup-js.yar, content/, , , ) and are never blocked/quarantined.

Severity model (Scan-Miasma.ps1)

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

Known bugs already fixed (keep in mind when reworking)

• gh api <404> --jq dumps the error body to stdout → never trust output truthiness; check $LASTEXITCODE + validate the format (numeric size, exact branch name).
• GitHub keeps a master→main redirect after rename → branches/master returns 200; only accept a branch if the returned name == requested name.
• npm audit must stay --package-lock-only (no npm install, no scripts executed).

TODO / rework backlog

The original backlog (bash port, severity badges, packer-wave deobfuscation, rotation helper) is done. Future ideas:

1. scan-miasma.sh: add the remote/GitHub mode (currently local-only).
2. Deobfuscator: handle ROT-4/ROT-9 multi-byte and non-AES-128-GCM variants if observed.
3. Rotation helper: optional --revoke mode (gated, with confirmation) for gh/npm/aws.

References

• 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