Kit de ferramentas Miasma / Shai-Hulud

Ferramentas de análise de incidentes + detecção/remediação para o worm Miasma (uma variante Mini Shai-Hulud) que injeta payloads de execução automática em configurações de agentes de IA / IDEs e repositórios npm/GitHub.

⚠️ Aviso legal — sem garantia. Este é um kit de ferramentas defensivo da comunidade fornecido "como está", sem garantia de qualquer tipo (consulte LICENSE). O scanner e as regras YARA são somente leitura, mas o purge-history.sh reescreve o histórico do git e os hooks .claude/ movem arquivos para quarentena — ambos podem alterar um repositório. Faça backup primeiro, revise o que cada ferramenta faz e execute por sua conta e risco. Uma varredura limpa não é garantia de segurança: os indicadores evoluem e novas variantes surgem. Use apenas em sistemas e contas que você está autorizado a inspecionar. Encontrou uma lacuna ou um bug? Consulte SECURITY.md e CONTRIBUTING.md.

Conteúdo

Pré-requisitos

Instale o YARA (Windows): winget install VirusTotal.YARA — ou choco install yara / scoop install yara. No Linux/macOS: apt install yara / brew install yara. Verifique com yara --version.

Uso rápido

Observação: o -Mode Local por padrão varre apenas $env:USERPROFILE. Passe -CodeRoots para cobrir repositórios em outros locais, ex.: -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

Código de saída 1 se houver qualquer achado INFECTED (amigável para 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

O desofuscador desempacota a onda do empacotador p,a,c,k,e,d, decodifica a onda de códigos de caractere, detecta automaticamente e reverte o deslocamento Caesar (substitua com -Shift), depois descriptografa cada blob AES-128-GCM embutido (_b bootstrapper, _p stealer) e varre o código recuperado em busca de URLs, IPs e contas de 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

Proteção de CI (recusar a compilação se o dropper/launcher estiver presente)

Use a ação composta incluída como primeira etapa de qualquer 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)

Este kit executa a mesma proteção em si mesmo via .github/workflows/miasma-ci.yml (referenciando a ação por caminho relativo). A proteção é independente de variante e restrita aos arquivos de configuração do launcher do worm, portanto nunca gera falsos positivos em documentos que apenas mencionam a string de IOC.

Hooks do Claude Code (.claude/)

Proteção em tempo real para máquinas que executam o Claude Code neste repositório. Os hooks reutilizam iocs.psd1 (sem indicadores duplicados) e estão configurados em .claude/settings.json:

• A quarentena é reversível: os arquivos infectados são movidos para .miasma-quarantine/<timestamp>/… (ignorados pelo git) e registrados em .miasma-quarantine/quarantine.log — restaure com Move-Item. Nada é excluído permanentemente.
• Autoexclusão (Test-MiasmaExcluded em Miasma.Common.ps1): os próprios arquivos do kit contêm legitimamente strings de IOC (iocs.psd1, Scan-Miasma.ps1, scan-miasma.sh, Expand-MiasmaPayload.ps1, Invoke-MiasmaRotation.ps1, purge-history.sh, setup-js.yar, content/, , , ) e nunca são bloqueados/colocados em quarentena.

Modelo de severidade (Scan-Miasma.ps1)

• INFECTED — DROPPER, INJECT, FORGED, BADDEP, WORKFLOW, RUNNER, PAYLOAD, BUN-DROP, PROGRAMDATA
• REVIEW — NPM-AUDIT, SECRETS (inventário de rotação), SIGNATURE, PERSIST, PROGRAMDATA-CFG

Bugs conhecidos já corrigidos (tenha em mente ao retrabalhar)

• gh api <404> --jq despeja o corpo do erro no stdout → nunca confie na veracidade da saída; verifique $LASTEXITCODE + valide o formato (tamanho numérico, nome exato do branch).
• O GitHub mantém um redirecionamento master→main após a renomeação → branches/master retorna 200; aceite um branch somente se o nome retornado == nome solicitado.
• O npm audit deve permanecer com --package-lock-only (sem npm install, sem scripts executados).

TODO / backlog de retrabalho

O backlog original (porte em bash, selos de severidade, desofuscação da onda do empacotador, helper de rotação) está concluído. Ideias futuras:

1. scan-miasma.sh: adicionar o modo remoto/GitHub (atualmente apenas local).
2. Desofuscador: tratar variantes ROT-4/ROT-9 multibyte e não AES-128-GCM se forem observadas.
3. Helper de rotação: modo opcional --revoke (protegido, com confirmação) para gh/npm/aws.

Referências

• 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