Kit Miasma / Shai-Hulud

Outils d'analyse d'incident + détection/remédiation pour le ver Miasma (une variante Mini Shai-Hulud) qui injecte des charges utiles de démarrage automatique dans les configurations AI-agent / IDE et dans les dépôts npm/GitHub.

⚠️ Avertissement — aucune garantie. Il s'agit d'une boîte à outils défensive communautaire fournie « en l'état », sans garantie d'aucune sorte (voir LICENSE). Le scanner et les règles YARA sont en lecture seule, mais purge-history.sh réécrit l'historique git et les hooks .claude/ déplacent les fichiers en quarantaine — les deux peuvent modifier un dépôt. Sauvegardez d'abord, examinez ce que fait chaque outil et exécutez-le à vos propres risques. Un scan propre n'est pas une garantie de sécurité : les indicateurs évoluent et de nouveaux variants apparaissent. Utilisation sur des systèmes et des comptes que vous êtes autorisé à inspecter. Vous avez trouvé une lacune ou un bug ? Voir SECURITY.md et CONTRIBUTING.md.

Contenu

Prérequis

Installer YARA (Windows) : winget install VirusTotal.YARA — ou choco install yara / scoop install yara. Sur Linux/macOS : apt install yara / brew install yara. Vérifier avec yara --version.

Utilisation rapide

Remarque : -Mode Local scanne par défaut uniquement $env:USERPROFILE. Passez -CodeRoots pour couvrir les dépôts ailleurs, par ex. -CodeRoots E:\Sources,D:\work.

# Scanner la machine locale + les dépôts locaux (+ CVE-2026-35603 ProgramData)
pwsh -File Scan-Miasma.ps1 -Mode Local
pwsh -File Scan-Miasma.ps1 -Mode Local -CodeRoots E:\Sources,D:\work

# Scanner les dépôts GitHub distants (authentifiez-vous d'abord sur le compte cible pour les dépôts privés/secrets)
gh auth login
pwsh -File Scan-Miasma.ps1 -Mode Remote -Owners votre-org,votre-utilisateur -OutReport report.md

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

Code de sortie 1 si une découverte INFECTED (compatible CI).

# Purger l'historique d'un dépôt infecté (vérifiez d'abord PATHS dans le script)
./purge-history.sh /chemin/vers/depot
# puis, après avoir vérifié :
git push origin --force --all && git push origin --force --tags

# Scan YARA
yara -r setup-js.yar /chemin/vers/scan

# Linux/macOS : scan local (port bash — par défaut $HOME ; passez des racines pour élargir)
./scan-miasma.sh
./scan-miasma.sh ~/src /opt/work

# Désobfuscation statique d'un dropper capturé (lecture seule — ne l'exécute jamais)
pwsh -File Expand-MiasmaPayload.ps1 -Path .github/setup.js   # écrit layers + iocs.txt dans <Path>.deob/
pwsh -File Expand-MiasmaPayload.ps1 -SelfTest                # vérifier le moteur de décodage/déchiffrement

Le désobfuscateur déballe la vague p,a,c,k,e,d du packer, décode la vague de codes de caractères, détecte automatiquement et inverse le décalage Caesar (remplacer avec -Shift), puis déchiffre chaque blob AES-128-GCM intégré (_b bootstrap, _p voleur) et scanne le code récupéré pour les URL, IP et comptes de dépôt mort.

# Après éradication : générer une liste de vérification priorisée de rotation des secrets (ne révoque rien)
pwsh -File Invoke-MiasmaRotation.ps1                       # détecte les identifiants accessibles ici
pwsh -File Invoke-MiasmaRotation.ps1 -OutReport rotation.md

Garde CI (refuser de construire si le dropper/lanceur est présent)

Utilisez l'action composite fournie comme première étape de tout workflow :

# Dans un autre dépôt (épinglez sur un tag/SHA pour la sécurité de la chaîne d'approvisionnement) :
- uses: actions/checkout@v4
- uses: jchable/miasma-toolkit/.github/actions/miasma-guard@main
  # with:
  #   full-scan: 'true'   # exécute aussi Scan-Miasma.ps1 -Mode Local (nécessite pwsh)

Cette boîte à outils exécute la même garde sur elle-même via .github/workflows/miasma-ci.yml (en référence à l'action par chemin relatif). La garde est indépendante de la vague et limitée aux fichiers de configuration du lanceur du ver, donc ne produit jamais de faux positifs sur des documents qui mentionnent simplement la chaîne IOC.

Hooks Claude Code (.claude/)

Protection en temps réel pour les machines qui exécutent Claude Code dans ce dépôt. Les hooks réutilisent iocs.psd1 (pas d'indicateurs dupliqués) et sont câblés dans .claude/settings.json :

• La quarantaine est réversible : les fichiers infectés sont déplacés vers .miasma-quarantine/<timestamp>/… (ignorés par git) et journalisés dans .miasma-quarantine/quarantine.log — restaurez avec Move-Item. Rien n'est supprimé définitivement.
• Auto-exclusion (Test-MiasmaExcluded dans Miasma.Common.ps1) : les fichiers propres de la boîte à outils contiennent légitimement des chaînes IOC (iocs.psd1, Scan-Miasma.ps1, scan-miasma.sh, Expand-MiasmaPayload.ps1, Invoke-MiasmaRotation.ps1, purge-history.sh, setup-js.yar, content/, , , ) et ne sont jamais bloqués/mis en quarantaine.

Modèle de sévérité (Scan-Miasma.ps1)

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

Bugs connus déjà corrigés (à garder à l'esprit lors des refontes)

• gh api <404> --jq envoie le corps de l'erreur sur stdout → ne jamais se fier à la véracité de la sortie ; vérifier $LASTEXITCODE + valider le format (taille numérique, nom de branche exact).
• GitHub conserve une redirection master→main après le renommage → branches/master retourne 200 ; n'accepter une branche que si le nom retourné == nom demandé.
• npm audit doit rester --package-lock-only (pas de npm install, pas de scripts exécutés).

TODO / réserve de refonte

La réserve initiale (port bash, badges de sévérité, désobfuscation de vague de packer, assistant de rotation) est terminée. Idées futures :

1. scan-miasma.sh : ajouter le mode distant/GitHub (actuellement local uniquement).
2. Désobfuscateur : gérer les variantes ROT-4/ROT-9 multi-octets et non AES-128-GCM si observées.
3. Assistant de rotation : mode --revoke optionnel (protégé, avec confirmation) pour gh/npm/aws.

Références

• 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