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

INFECTED の検出があった場合、終了コードは 1 になります（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   # <Path>.deob/ にレイヤーと iocs.txt を書き出します
pwsh -File Expand-MiasmaPayload.ps1 -SelfTest                # デコード/復号エンジンを検証

難読化解除ツールは、p,a,c,k,e,d パッカーウェーブを展開し、文字コードウェーブをデコードし、シーザーシフトを自動検出して逆転します（-Shift で上書き可能）。次に、埋め込まれたすべてのAES-128-GCMブロブ（_b ブートストラッパー、_p スティーラー）を復号し、復元されたコードからURL、IP、デッドドロップアカウントをスキャンします。

# 駆除後：優先度付きの秘密鍵ローテーションチェックリストを生成します（何も取り消しません）
pwsh -File Invoke-MiasmaRotation.ps1                       # ここからアクセス可能な資格情報を検出
pwsh -File Invoke-MiasmaRotation.ps1 -OutReport rotation.md

CIガード（ドロッパー/ランチャーが存在する場合、ビルドを拒否）

バンドルされている複合アクションを、任意のワークフローの 最初のステップ として使用します。

# 別のリポジトリ内（サプライチェーンセキュリティのためタグ/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 を介して自身に対しても同じガードを実行します（アクションを相対パスで参照）。このガードはウェーブに依存せず、ワームのランチャー設定ファイルに限定されるため、IOC文字列を単に言及しているドキュメントに対して偽陽性を出すことはありません。

Claude Code フック（.claude/）

このリポジトリ内で Claude Code を実行するマシン向けのリアルタイム保護。フックは iocs.psd1 を再利用し（重複する指標なし）、.claude/settings.json で配線されています。

• 隔離は元に戻せます：感染ファイルは .miasma-quarantine/<timestamp>/…（git-ignored）に 移動 され、.miasma-quarantine/quarantine.log に記録されます — Move-Item で復元可能。恒久的な削除は行われません。
• 自己除外（Miasma.Common.ps1 の Test-MiasmaExcluded）：ツールキット自身のファイルには正当にIOC文字列が含まれています（iocs.psd1、Scan-Miasma.ps1、scan-miasma.sh、Expand-MiasmaPayload.ps1、Invoke-MiasmaRotation.ps1、purge-history.sh、setup-js.yar、content/、.claude/hooks|commands、、）。これらのファイルはブロック/隔離されません。

重大度モデル（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 は エラーボディを標準出力にダンプ する → 出力の真偽性を信頼しない；$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. ローテーションヘルパー：gh/npm/aws 向けのオプションの --revoke モード（ゲート付き、確認あり）。

参考文献

• 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