用于 Miasma 蠕虫（Mini Shai-Hulud 变种）的应急分析与检测/修复工具，该蠕虫将自启动载荷注入 AI agent / IDE 配置以及 npm/GitHub 仓库。
⚠️ 免责声明——无担保。 这是一个社区防御工具包，按“现状”提供，不附带任何形式的担保（参见
LICENSE）。扫描器和 YARA 规则为只读，但purge-history.sh会重写 git 历史，.claude/中的钩子 将文件移至隔离区——两者都可能修改仓库。请先备份，了解每个工具的作用，并自行承担运行风险。 扫描结果为干净并不保证安全：指标会演变，新变种会出现。请仅在你获得授权检查的系统或账户上使用。发现漏洞或 Bug？请参见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 # 将层及 iocs.txt 写入 <Path>.deob/
pwsh -File Expand-MiasmaPayload.ps1 -SelfTest # 验证解码/解密引擎
去混淆器解包 p,a,c,k,e,d 打包器层，解码字符码层，自动检测并逆转凯撒移位（可通过 -Shift 覆盖），然后解密每个嵌入的 AES-128-GCM blob（_b 引导程序、_p 窃取程序），并在恢复的代码中扫描 URL、IP 和死信账户。
# 清除后：生成按优先级排列的密钥轮换清单（不撤销任何内容）
pwsh -File Invoke-MiasmaRotation.ps1 # 检测当前可访问的凭据
pwsh -File Invoke-MiasmaRotation.ps1 -OutReport rotation.md
将随附的复合操作用作任何工作流的第一步：
# 在另一个仓库中（为供应链安全固定标签/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/）为在此仓库中运行 Claude Code 的机器提供实时保护。这些钩子复用 iocs.psd1（无重复指标），并通过 .claude/settings.json 连接：
.miasma-quarantine/<timestamp>/…（已加入 gitignore）并记录到 .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、、），永远不会被拦截/隔离。DROPPER、INJECT、FORGED、BADDEP、WORKFLOW、RUNNER、PAYLOAD、BUN-DROP、PROGRAMDATANPM-AUDIT、SECRETS（轮换清单）、SIGNATURE、PERSIST、PROGRAMDATA-CFGgh api <404> --jq 将错误信息输出到标准输出 → 永远不要相信输出的真伪；检查 $LASTEXITCODE 并验证格式（数字大小、精确的分支名称）。master→main 重定向 → branches/master 返回 200；仅当返回的名称 == 请求的名称时才接受某个分支。--package-lock-only（不执行 npm install，不执行脚本）。原始待办事项（Bash 移植版、严重性徽章、打包器层去混淆、轮换辅助工具）已完成。未来的想法：
scan-miasma.sh：添加远程/GitHub 模式（当前仅支持本地）。--revoke 模式（带确认门控），适用于 gh/npm/aws。| 文件 | 说明 |
|---|
content/incident-report.fr.md / content/incident-report.en.md | 完整报告：工作原理、载荷去混淆、IOC、清除方案 |
Scan-Miasma.ps1 | 统一扫描器（本地+远程），输出结构化 JSON + 每个仓库的 Markdown 报告——请使用此工具 |
iocs.psd1 | 共享指标（哈希、签名、恶意包、配置），由扫描器加载——在此处编辑 IOC |
Expand-MiasmaPayload.ps1 | setup.js 的静态去混淆器——剥离打包器/字符码 → 凯撒密码 → AES-128-GCM，提取 C2/IOC（从不执行载荷） |
Invoke-MiasmaRotation.ps1 | 密钥轮换清单——检测当前可访问的凭据并打印撤销命令（只读，不执行任何撤销） |
scan-miasma.sh | Bash 移植版，用于 Linux/macOS 的本地扫描（跨平台子集） |
purge-history.sh | 从 所有 git 历史 中清除恶意文件（filter-repo → filter-branch）+ 备份 |
setup-js.yar | 用于投放器及启动器配置的 YARA 规则 |
.github/actions/miasma-guard/ | 可复用的 GitHub Actions 复合操作——若检测到投放器/启动器则拒绝构建 |
.claude/ | Claude Code 钩子——实时防护/隔离 + /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 扫描 | 可选 |
| 钩子 | 事件 | 行为 |
|---|
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 |
.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（只读）不同，这些钩子会修改目录树（隔离）。它们是可选的：Claude Code 首次加载 .claude/settings.json 时会提示用户批准钩子。