Miasma / Shai-Hulud инструментарий

Инструменты анализа инцидентов, обнаружения и устранения для червя Miasma (варианта Mini Shai-Hulud), который внедряет автозапускаемые полезные нагрузки в конфигурации AI-агентов/IDE и репозитории npm/GitHub.

⚠️ Отказ от ответственности — без гарантии. Это общественный оборонительный инструментарий, предоставляемый «как есть», без каких-либо гарантий (см. LICENSE). Сканер и YARA-правила работают только на чтение, но purge-history.sh переписывает историю git, а хуки .claude/ перемещают файлы в карантин — оба могут изменить репозиторий. Сначала сделайте резервную копию, изучите, что делает каждый инструмент, и используйте на свой страх и риск. Чистое сканирование не является гарантией безопасности: индикаторы эволюционируют, и появляются новые варианты. Используйте на системах и аккаунтах, к которым у вас есть разрешение на проверку. Нашли пробел или ошибку? См. SECURITY.md и CONTRIBUTING.md.

Содержание

Предварительные требования

Установка YARA (Windows): winget install VirusTotal.YARA — или choco install yara / scoop install yara. На Linux/macOS: apt install yara / brew install yara. Проверьте: yara --version.

Быстрое использование

Примечание: -Mode Local по умолчанию сканирует только $env:USERPROFILE. Укажите -CodeRoots для охвата репозиториев в других местах, например -CodeRoots E:\Sources,D:\work.

# Сканирование локальной машины + локальных репозиториев (+ CVE-2026-35603 ProgramData)
pwsh -File Scan-Miasma.ps1 -Mode Local
pwsh -File Scan-Miasma.ps1 -Mode Local -CodeRoots E:\Sources,D:\work

# Сканирование удалённых репозиториев GitHub (сначала аутентифицируйтесь в целевом аккаунте для приватных репозиториев/секретов)
gh auth login
pwsh -File Scan-Miasma.ps1 -Mode Remote -Owners your-org,your-user -OutReport report.md

# Всё вместе + JSON + Markdown отчёт
pwsh -File Scan-Miasma.ps1 -OutJson findings.json -OutReport report.md

Код выхода 1, если есть INFECTED находка (для CI).

# Очистка истории заражённого репозитория (предварительно просмотрите PATHS в скрипте)
./purge-history.sh /path/to/repo
# затем, после проверки:
git push origin --force --all && git push origin --force --tags

# YARA-сканирование
yara -r setup-js.yar /path/to/scan

# Linux/macOS: локальное сканирование (bash-порт — по умолчанию $HOME; укажите пути для расширения)
./scan-miasma.sh
./scan-miasma.sh ~/src /opt/work

# Статическая деобфускация захваченного дроппера (только чтение — никогда не запускается)
pwsh -File Expand-MiasmaPayload.ps1 -Path .github/setup.js   # записывает слои + iocs.txt в <Path>.deob/
pwsh -File Expand-MiasmaPayload.ps1 -SelfTest                # проверка движка декодирования/дешифрования

Деобфускатор распаковывает волну упаковщика p,a,c,k,e,d, декодирует волну char-кода, автоматически определяет и обращает сдвиг Цезаря (переопределить через -Shift), затем дешифрует каждый встроенный AES-128-GCM блок (_b загрузчик, _p стилер) и сканирует восстановленный код на наличие URL, IP-адресов и аккаунтов для dead-drop.

# После устранения: создание приоритетного чеклиста смены секретов (ничего не отзывает)
pwsh -File Invoke-MiasmaRotation.ps1                       # определяет доступные отсюда учётные данные
pwsh -File Invoke-MiasmaRotation.ps1 -OutReport rotation.md

CI-защита (отказ от сборки, если присутствует дроппер/загрузчик)

Используйте встроенное composite action как первый шаг любого рабочего процесса:

# В другом репозитории (для безопасности цепочки поставок зафиксируйте тег/SHA):
- uses: actions/checkout@v4
- uses: jchable/miasma-toolkit/.github/actions/miasma-guard@main
  # with:
  #   full-scan: 'true'   # также запускает Scan-Miasma.ps1 -Mode Local (требуется pwsh)

Этот инструментарий запускает ту же защиту на себе через .github/workflows/miasma-ci.yml (ссылаясь на action по относительному пути). Защита не зависит от варианта червя и нацелена на файлы конфигурации его загрузчика, поэтому никогда не даёт ложных срабатываний на документах, которые просто упоминают строку IOC.

Хуки Claude Code (.claude/)

Защита в реальном времени для машин, на которых запущен Claude Code в этом репозитории. Хуки используют iocs.psd1 (без дублирования индикаторов) и подключены в .claude/settings.json:

• Карантин обратим: заражённые файлы перемещаются в .miasma-quarantine/<timestamp>/… (игнорируется git) и логируются в .miasma-quarantine/quarantine.log — восстановите через Move-Item. Ничего не удаляется безвозвратно.
• Самоисключение (Test-MiasmaExcluded в Miasma.Common.ps1): собственные файлы инструментария легитимно содержат строки IOC (iocs.psd1, Scan-Miasma.ps1, scan-miasma.sh, Expand-MiasmaPayload.ps1, Invoke-MiasmaRotation.ps1, purge-history.sh, setup-js.yar, content/, , , ) и никогда не блокируются/не помещаются в карантин.

Модель серьёзности (Scan-Miasma.ps1)

• INFECTED — DROPPER, INJECT, FORGED, BADDEP, WORKFLOW, RUNNER, PAYLOAD, BUN-DROP, PROGRAMDATA
• REVIEW — NPM-AUDIT, SECRETS (инвентаризация ротации), SIGNATURE, PERSIST, PROGRAMDATA-CFG

Известные ошибки, уже исправленные (имейте в виду при доработке)

• gh api <404> --jq выводит тело ошибки в stdout → никогда не доверяйте правдивости вывода; проверяйте $LASTEXITCODE + проверяйте формат (числовой размер, точное имя ветки).
• GitHub сохраняет редирект master→main после переименования → branches/master возвращает 200; принимайте ветку только если возвращённое имя == запрошенное имя.
• npm audit должен оставаться с флагом --package-lock-only (без npm install, без выполнения скриптов).

TODO / очередь доработок

Исходный бэклог (bash-порт, значки серьёзности, деобфускация упаковщика, помощник ротации) готов. Будущие идеи:

1. scan-miasma.sh: добавить удалённый/GitHub режим (сейчас только локальный).
2. Деобфускатор: обрабатывать ROT-4/ROT-9 многобайтовые и не-AES-128-GCM варианты, если будут обнаружены.
3. Помощник ротации: опциональный режим --revoke (с подтверждением) для gh/npm/aws.

Ссылки

• 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