jchable/miasma-toolkit
GitHub: jchable/miasma-toolkit
一套用于检测、分析和清除 Miasma 蠕虫感染的专项安全工具包，支持恶意 payload 反混淆、Git 历史清除与 CI/CD 持续防护。
Stars: 0 | Forks: 0
# Miasma / Shai-Hulud 工具包
[](LICENSE)
[](https://learn.microsoft.com/powershell/)
[](https://github.com/jchable/miasma-toolkit/actions/workflows/miasma-ci.yml)
用于 **Miasma** 蠕虫（一种 *Mini Shai-Hulud* 变体）的事件分析 + 检测/修复工具，该蠕虫会向 AI-agent / IDE 配置以及 npm/GitHub 仓库中注入自动运行的 payload。
## 目录
| 文件 | 用途 |
|---|---|
| `content/incident-report.fr.md` / `content/incident-report.en.md` | 完整报告：运行机制、payload 反混淆、IOC、根除方法 |
| **`Scan-Miasma.ps1`** | **统一扫描器**（本地 + 远程），结构化 JSON + 每个仓库的 Markdown 报告 — *推荐使用* |
| `iocs.psd1` | 扫描器加载的共享指标（哈希、签名、恶意包、配置） — *在此处编辑 IOC* |
| `Expand-MiasmaPayload.ps1` | 用于 `setup.js` 的**静态反混淆器** — 解包 packer/char-codes → Caesar → AES-128-GCM 并提取 C2/IOC（从不执行 payload） |
| `Invoke-MiasmaRotation.ps1` | **密钥轮换清单** — 检测在此处可访问哪些凭证并打印撤销命令（只读；不执行任何撤销操作） |
| `scan-miasma.sh` | 面向 Linux/macOS 的本地扫描 **Bash 移植版**（跨平台子集） |
| `purge-history.sh` | 从**所有 git 历史记录**中清除恶意文件（filter-repo → filter-branch）+ 备份 |
| `setup-js.yar` | 用于 dropper + launcher 配置的 YARA 规则 |
| `.github/actions/miasma-guard/` | 可复用的 **GitHub Actions 复合操作** — 如果存在 dropper/launcher 则拒绝构建 |
| `.claude/` | **Claude Code hooks** — 实时防护/隔离 + `/miasma-scan` 命令（见下文） |
## 前置条件
| 工具 | 用途 | 是否必需？ |
|---|---|---|
| **PowerShell 7+** (`pwsh`) | `Scan-Miasma.ps1`, `Expand-MiasmaPayload.ps1`, `Invoke-MiasmaRotation.ps1` | （这些工具）必需 |
| **bash + coreutils** (`sha256sum`/`shasum`, `awk`, `find`) | `scan-miasma.sh` (Linux/macOS) | 仅 bash 移植版需要 |
| **git** | 本地仓库历史检查, `purge-history.sh` | 必需 |
| **GitHub CLI** (`gh`, 已认证) | `Scan-Miasma.ps1 -Mode Remote` | 仅远程扫描需要 |
| **npm** | 远程 `npm audit` (仅限 lockfile) | 可选（如不存在则自动跳过） |
| **git-filter-repo** | 首选的历史重写工具（回退到内置的 `git filter-branch`） | 可选 |
| **YARA** (`yara`) | `setup-js.yar` 扫描 | 可选 |
安装 YARA (Windows): `winget install VirusTotal.YARA` — 或者使用 `choco install yara` / `scoop install yara`。
在 Linux/macOS 上: `apt install yara` / `brew install yara`。通过 `yara --version` 进行验证。
## 快速用法
```
# 扫描本地机器 + 本地 repos（+ CVE-2026-35603 ProgramData）
pwsh -File Scan-Miasma.ps1 -Mode Local
pwsh -File Scan-Miasma.ps1 -Mode Local -CodeRoots E:\Sources,D:\work
# 扫描远程 GitHub repos（对于私有 repos/secrets，需先在目标账户上进行身份验证）
gh auth login
pwsh -File Scan-Miasma.ps1 -Mode Remote -Owners your-org,your-user -OutReport report.md
# Everything + JSON + Markdown 报告
pwsh -File Scan-Miasma.ps1 -OutJson findings.json -OutReport report.md
```
如果发现任何 **INFECTED**（已感染）结果，退出码为 `1`（对 CI 友好）。
```
# 清除受感染 repo 的历史记录（请先检查脚本中的 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；传入 roots 以扩大范围）
./scan-miasma.sh
./scan-miasma.sh ~/src /opt/work
```
```
# 静态反混淆捕获的 dropper（只读 — 绝不运行它）
pwsh -File Expand-MiasmaPayload.ps1 -Path .github/setup.js # writes layers + iocs.txt to .deob/
pwsh -File Expand-MiasmaPayload.ps1 -SelfTest # verify the decode/decrypt engine
```
反混淆器会解开 `p,a,c,k,e,d` packer 波段，解码 char-code 波段，自动检测并逆转 Caesar 移位（可通过 `-Shift` 覆盖），然后解密每个内嵌的 AES-128-GCM blob（`_b` 引导程序，`_p` 窃取程序），并扫描恢复出的代码以查找 URL、IP 和 dead-drop 账户。
```
# 清除后：生成优先级的 secret-rotation 清单（不撤销任何内容）
pwsh -File Invoke-MiasmaRotation.ps1 # detects creds reachable here
pwsh -File Invoke-MiasmaRotation.ps1 -OutReport rotation.md
```
## CI 防护（如果存在 dropper/launcher 则拒绝构建）
将内置的复合操作作为任何工作流的**第一步**使用：
```
# 在另一个 repo 中（为供应链安全，请 pin 到 tag/SHA）：
- 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)
```
该工具包通过 [`.github/workflows/miasma-ci.yml`](.github/workflows/miasma-ci.yml)（通过相对路径引用该操作）对自身运行相同的防护。该防护与波段无关，且范围仅限于蠕虫的 launcher 配置文件，因此绝不会对仅仅提及 IOC 字符串的文档产生误报。
## Claude Code hooks（`.claude/`）
为在此仓库中运行 **Claude Code** 的机器提供实时保护。这些 hooks 复用 `iocs.psd1`（无重复的指标），并在 `.claude/settings.json` 中进行绑定：
| Hook | 事件 | 动作 |
|---|---|---|
| `Guard-Write.ps1` | `PreToolUse` (Write/Edit/MultiEdit) | **阻止**会注入蠕虫 IOC 的写入操作（取消工具调用） |
| `Guard-Bash.ps1` | `PreToolUse` (Bash) | **阻止**蠕虫*执行* — `node .github/setup.js`, `bun`/`bunx`, 管道传输的 `bun.sh` 安装程序 |
| `Scan-Write.ps1` | `PostToolUse` (Write/Edit/MultiEdit) | 受感染文件落地后**发出警报并隔离** |
| `Session-Sweep.ps1` | `SessionStart` | 快速仓库扫描；将任何预先存在的感染报告到上下文中 |
| `/miasma-scan` | 命令 | 围绕 `Scan-Miasma.ps1` 的按需封装 |
- **隔离是可逆的**：受感染的文件会被*移动*到 `.miasma-quarantine//…`
（被 git 忽略）并记录到 `.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`, `.github/actions/miasma-guard/`, `.github/workflows/`），且永远不会被阻止/隔离。
- **`Guard-Bash` 针对执行而非提及**：其模式（`iocs.psd1` → `CmdSigs`）锚定在命令位置，因此仅仅命名了 IOC 的分类排查命令（`grep "node .github/setup.js"`, `yara -r setup-js.yar`, `cat setup.js`）**不会**被阻止 —
只有实际运行 `node …/setup.js` / `bun` / `bun.sh` 安装管道的操作才会被阻止。注意：`bun`/`bunx`
调用会被彻底阻止（蠕虫的运行时）；如果你确实需要 Bun，可通过 `CmdSigs` 设置白名单。
- ⚠️ 与 `Scan-Miasma.ps1`（只读）不同，这些 hooks 会**修改目录树**（隔离）。它们是
可选的：Claude Code 在首次加载 `.claude/settings.json` 时会提示批准这些 hooks。
## 严重性模型 (Scan-Miasma.ps1)
- **INFECTED** — `DROPPER`, `INJECT`, `FORGED`, `BADDEP`, `WORKFLOW`, `RUNNER`, `PAYLOAD`, `BUN-DROP`, `PROGRAMDATA`
- **REVIEW** — `NPM-AUDIT`, `SECRETS` (轮换清单), `SIGNATURE`, `PERSIST`, `PROGRAMDATA-CFG`
## 已修复的已知 Bug（重构时请牢记）
- `gh api <404> --jq` **会将错误主体转储到 stdout** → 切勿相信输出的布尔真值；
请检查 `$LASTEXITCODE` 并验证格式（数字大小、确切的分支名称）。
- GitHub 在重命名后保留了 **`master`→`main` 重定向** → `branches/master` 返回 200；
仅当**返回的名称 == 请求的名称**时才接受该分支。
- npm audit 必须保持使用 **`--package-lock-only`**（不执行 `npm install`，不执行任何脚本）。
## 待办 / 重构积压
_最初的积压任务（bash 移植版、严重性徽章、packer-wave 反混淆、轮换助手）已
完成。未来的想法：_
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
标签：AI合规, AMSI绕过, DAST, DNS 反向解析, IPv6, IP 地址批量处理, Libemu, PowerShell, 威胁检测, 库, 应急响应, 应用安全, 恶意软件分析, 配置注入