Drasrax/npm-shai-hulud-scanner
GitHub: Drasrax/npm-shai-hulud-scanner
一款针对 npm/PyPI 生态系统的供应链安全扫描工具，专注于检测并隔离已知恶意软件包及其变种攻击。
Stars: 15 | Forks: 4
# NPM 供应链安全扫描器
用于检测 NPM 项目中供应链漏洞的安全工具包，旨在检测 2025-2026 年重大 npm 供应链攻击的模式：
- **CVE-2025-54313**（Scavenger 恶意软件 - 2025 年 7 月）
- **Shai-Hulud 蠕虫**（2025 年 9 月）和 **Shai-Hulud 2.0 "The Second Coming"**（2025 年 11 月）
- **Mini Shai-Hulud / TeamPCP 家族**（2026 年 4 月-6 月）：SAP CAP、Bitwarden CLI、TanStack（**CVE-2026-45321**）、AntV、Miasma (Red Hat)、Hades (PyPI)
## 目的
检测并通知 NPM（以及现在的 PyPI）依赖项中的安全漏洞，包括：
- **1340+ 个受损的软件包版本**（Shai-Hulud v1/v2 + CVE-2025-54313 + 2026 年 Mini Shai-Hulud 浪潮）
- **跨生态系统覆盖**：npm + PyPI（Hades 浪潮），并记录了波及 Maven 的情况
- 用于规避 EDR 的 Bun-runtime 加载器（`setup.mjs`, `execution.js`, `bw1.js`, `_index.js`，锁定 Bun v1.3.13）
- 通过 agent/IDE 配置文件实现恶意软件持久化（在 `npm uninstall` 后依然存活）
- OIDC / Trusted-Publishing 滥用以及 GitHub commit 锁定的 tarball 注入
- Shai-Hulud 2.0 Bun payloads（`setup_bun.js`, `bun_environment.js`）
- 域名抢注企图
- 注入的恶意代码（DLL/SO 文件、混淆脚本）
- 可疑的安装脚本
- 蠕虫式/传播行为
- C2 域名通信
- 云元数据端点 (IMDS) 访问
## 文件
- `npm-supply-chain-detector.py` - 主 Python 检测脚本
- `scan-npm-security.sh` - Bash 自动化与监控脚本
- `malicious-patterns.json` - 恶意模式数据库（生产环境）
- `shai-hulud-iocs.json` - 扩展 IOCs 数据库（740+ 个软件包 / 1340 个版本，29 个哈希值，C2 域名，2026 年 Mini Shai-Hulud + PyPI Hades 部分）
- `update-patterns.py` - 模式数据库生成器/更新器
## 安装
```
# 克隆或下载 scripts
chmod +x npm-supply-chain-detector.py scan-npm-security.sh
# 检查先决条件
./scan-npm-security.sh --help
```
### 前置条件
- Python 3.6+
- 已安装 npm/node
- 带有 package.json 的 NPM 项目
## 用法
### 简单扫描
```
# 扫描当前目录
python3 npm-supply-chain-detector.py
# 扫描特定项目
python3 npm-supply-chain-detector.py /path/to/project
# 生成详细报告
python3 npm-supply-chain-detector.py -v -o markdown -f report.md
```
### 自动化脚本
```
# 基本扫描
./scan-npm-security.sh
# 持续监控（每 5 分钟扫描一次）
./scan-npm-security.sh -c -i 300
# 深度扫描并保存
./scan-npm-security.sh -d -f security-report.md -o markdown /project
# 附带 webhook 通知（Slack、Discord 等）
./scan-npm-security.sh -w https://hooks.slack.com/services/XXX
# 隔离可疑 packages（移动到 .npm-quarantine/）
./scan-npm-security.sh --quarantine
# 如果是 false positive 则恢复被隔离的 packages
./.npm-quarantine/restore.sh
```
### 可用选项
#### Python 脚本 (`npm-supply-chain-detector.py`)
- `-o, --output`：输出格式（json, text, markdown）
- `-f, --file`：将报告保存到文件
- `-v, --verbose`：详细模式
- `--webhook`：用于通知的 Webhook URL
#### Bash 脚本 (`scan-npm-security.sh`)
- `-c, --continuous`：持续监控模式
- `-i, --interval`：扫描之间的间隔（秒）
- `-d, --deep`：深度扫描（包括 npm audit、过时的软件包）
- `--quarantine`：**将可疑软件包移动到隔离文件夹**
- `--update-patterns`：从文件更新模式
## 隔离功能
`--quarantine` 选项会自动隔离受损的软件包：
**工作原理：**
1. 扫描关键漏洞
2. 从扫描结果中识别受损的软件包
3. 将软件包从 `node_modules/` 移动到 `.npm-quarantine/packages/`
4. 创建包含元数据（版本、路径、时间戳）的 JSON 清单
5. 生成自动恢复脚本 `restore.sh`
**创建的目录结构：**
```
.npm-quarantine/
├── packages/ # Isolated packages
│ ├── package-name/
│ └── @scope_package-name/
├── logs/ # Scan logs
├── quarantine-manifest-*.json # Metadata
└── restore.sh # Restoration script
```
**恢复（如果是误报）：**
```
cd .npm-quarantine
./restore.sh # Interactive confirmation required
```
## 检测项
### 1. 已知的受损软件包（1340 个版本）
**CVE-2025-54313 (Scavenger - 2025 年 7 月)：**
- eslint-config-prettier (8.10.1, 9.1.1, 10.1.6, 10.1.7)
- eslint-plugin-prettier (4.2.2, 4.2.3)
- synckit (0.11.9)
- @pkgr/core (0.2.8)
- napi-postinstall (0.3.1)
- got-fetch (5.1.11, 5.1.12)
- is (3.3.1, 5.0.0)
- @crowdstrike/node-exporter (0.2.2)
- @crowdstrike/threat-center (1.205.2)
- tailwind-toucan-base (5.0.2)
- **Shai-Hulud 2.0 (Wiz, 2025 年 11 月 27 日)**：约 470 个软件包/版本（例如 `@asyncapi/*`, `@actbase/*`, `@accordproject/*`, `@antstackio/*` 等）——完整列表请参见 `shai-hulud-iocs.json`
**Shai-Hulud 蠕虫（2025 年 9 月）：**
- CrowdStrike 软件包 (@crowdstrike/*)
- @ctrl/tinycolor (4.1.1, 4.1.2)
- @nativescript-community/* 软件包
- @operato/* 软件包
- @things-factory/* 软件包
- 许多其他（参见 shai-hulud-iocs.json）
**Shai-Hulud 2.0（2025 年 11 月，Unit42 和 Wiz）**
- 新的 payloads：`setup_bun.js`, `bun_environment.js`
- bun_environment.js 哈希值：`62ee164b9b306250c1172583f138c9614139264f889fa99614903c12755468d0`, `f099c5d9ec417d4445a0328ac0ada9cde79fc37410914103ae9c609cbc0ee068`, `cbb9bc5a8496243e02f3cc080efbe3e4a1430ba0671f2e43a202bf45b05479cd`
- setup_bun.js 哈希值：`a3894003ad1d293ba96d77881ccd2071446dc3f65f434669b49b3da92421901a`
- GitHub 数据外泄：仓库描述 "Sha1-Hulud: The Second Coming"
- 可能的破坏性后备方案（`rm -rf ~` / `$HOME`）
**Mini Shai-Hulud / TeamPCP 家族（2026 年 4 月-6 月）**
威胁行为者 **TeamPCP（又名 UNC6780）** 开源了他们的 "Mini Shai-Hulud" 恶意软件，引发了一系列的攻击浪潮（和模仿者）。它们全都使用 **Bun loader**（规避 EDR），并通过在受害者自己的账号上创建的 GitHub dead-drop 仓库进行数据外泄：
| 浪潮 | 日期 | 生态系统 | 关键软件包 |
|------|------|-----------|--------------|
| Bitwarden CLI ("The Third Coming") | 2026-04-22 | npm | `@bitwarden/cli@2026.4.0`（通过 Checkmarx 泄露） |
| SAP CAP ("A Mini Shai-Hulud has Appeared") | 2026-04-29 | npm | `mbt`, `@cap-js/sqlite`, `@cap-js/postgres`, `@cap-js/db-service` |
| TanStack (**CVE-2026-45321**) | 2026-05-11 | npm + PyPI | 42 个 `@tanstack/*` 软件包，`@mistralai/mistralai`, `@uipath/cli`（OIDC/Trusted-Publishing 劫持，有效的 SLSA 来源） |
| AntV ("Here We Go Again") | 2026-05-19 | npm | `@antv/g2,g6,l7,s2`, `echarts-for-react`, `timeago.js`, `size-sensor`（受损的 `atool` 维护者账号） |
| Miasma ("The Spreading Blight") | 2026-06-01 | npm | `@redhat-cloud-services/*`（通过 GitHub Actions OIDC） |
| Hades ("The End for the Damned") | 2026-06-07 | **PyPI** | 19 个项目，通过 `*-setup.pth` 钩子 → Bun → `_index.js` |
涵盖的新型 TTP：**Bun v1.3.13 runtime**（规避）、**通过 agent/IDE 配置文件实现持久化**（`.claude`/`.vscode`/`.cursor`，在 `npm uninstall` 后存活）、**OIDC/Trusted-Publishing 滥用**、**"living-off-trusted-host" 数据外泄**（`api.anthropic.com/v1/api`, `filev2.getsession.org`），以及在 token 失效时触发的**破坏性擦除**。
### 2. 域名抢注检测
- Levenshtein 距离分析
- 常见替换（0→o, 1→i 等）
- 破折号/下划线变体
### 3. 恶意代码模式
- 凭据外泄（AWS, npm, SSH, GitHub tokens）
- 远程代码执行（curl|sh, eval）
- 混淆（base64, atob, XOR 加密）
- 与 C2 域名的可疑网络通信
- 自我传播（蠕虫模式，npm 发布）
- 云元数据端点 (IMDS) 访问
- **CVE-2025-54313 特定：**DLL/SO 加载，logDiskSpace 函数
### 4. 可疑的安装脚本
- 恶意的 preinstall/postinstall 钩子
- 脚本下载和执行
- npm token 操作
- **Windows DLL 执行**（rundll32, regsvr32）
- 恶意文件：node-gyp.dll, loader.dll, version.dll
### 5. 基于哈希的检测（29 种变体）
- **Shai-Hulud bundle.js**（7 个 SHA-256 哈希值）
- **Shai-Hulud 2.0 Bun payloads**：`bun_environment.js`（3 个哈希值），`setup_bun.js`（1 个哈希值）
- **CVE-2025-54313 Scavenger**（3 个 SHA-256 哈希值）
- node-gyp.dll: c68e42f416f482d43653f36cd14384270b54b68d6496a8e34ce887687de5b441
- Scavenger stage 2: 5bed39728e404838ecd679df65048abcb443f8c7a9484702a2ded60104b8c4a9
- install.js: 32d0dbdfef0e5520ba96a2673244267e204b94a49716ea13bf635fa9af6f66bf
### 6. C2 域名检测
- firebase.su (CVE-2025-54313)
- dieorsuffer.com (CVE-2025-54313)
- smartscreen-api.com (CVE-2025-54313)
- npnjs.com（域名抢注）
- webhook.site/bb8ca5f6-4175-45d2-b042-fc9ebb8170b7 (Shai-Hulud)
- t.m-kosche.com (Mini Shai-Hulud AntV C2)
- filev2.getsession.org, api.masscan.cloud, git-tanstack.com (TanStack 浪潮)
- audit.checkmarx.cx (Bitwarden 浪潮数据外泄)
- `api.anthropic.com/v1/api` — **仅路径**检测（主机是合法的，通过伪造路径滥用；从不直接屏蔽）
### 7. 完整性分析
- 通过 `npm audit` 验证
- 大型 JS 文件检测（>3MB）
- npm 域名验证
## 报告格式
### JSON
```
{
"scan_date": "2025-01-22T10:30:00",
"project_path": "/path/to/project",
"findings": [
{
"severity": "critical",
"message": "KNOWN COMPROMISED PACKAGE",
"location": "package.json",
"details": {...}
}
],
"statistics": {
"total_findings": 5,
"critical": 2,
"warning": 3
}
}
```
### Markdown
带有表格和结构化部分的格式化报告。
Text
用于 CI/CD 集成的纯文本报告。
## 通知
### Webhook 配置
可将关键发现发送至 Webhook：
```
./scan-npm-security.sh -w https://your-webhook-url
```
Payload 格式：
```
{
"text": "NPM Security Alert: X critical vulnerabilities",
"findings": [...]
}
```
## CI/CD 集成
### GitHub Actions
```
- name: NPM Security Scan
run: |
python3 npm-supply-chain-detector.py . -o json -f scan-results.json
if [ $? -ne 0 ]; then
echo "Critical vulnerabilities found!"
exit 1
fi
```
### GitLab CI
```
npm-security-scan:
script:
- python3 npm-supply-chain-detector.py
artifacts:
reports:
paths:
- security-reports/
```
### Jenkins
```
stage('Security Scan') {
sh './scan-npm-security.sh -o json -f report.json'
}
```
## 自定义配置
修改 `malicious-patterns.json` 以：
- 添加新的受损软件包
- 定义自定义模式
- 调整通知阈值
- 排除误报
## 持续监控
用于 24/7 监控：
```
# 使用 systemd
sudo tee /etc/systemd/system/npm-security-monitor.service << EOF
[Unit]
Description=NPM Security Monitor
After=network.target
[Service]
Type=simple
User=youruser
WorkingDirectory=/path/to/project
ExecStart=/path/to/scan-npm-security.sh -c -i 600 -w https://webhook.url
Restart=always
[Install]
WantedBy=multi-user.target
EOF
sudo systemctl enable npm-security-monitor
sudo systemctl start npm-security-monitor
```
## 发生检测时该怎么办？
1. **关键发现**：
- **使用隔离模式**：`./scan-npm-security.sh --quarantine`
- 立即隔离受损软件包
- 重新生成所有暴露的 tokens/secrets（npm, GitHub, AWS, SSH keys）
- 审查受影响系统的凭据暴露情况
- 检查名为 "Shai-Hulud" 的未授权 GitHub 仓库
- 审查云元数据端点 (IMDS) 访问日志
2. **CVE-2025-54313 特定项**：
- 检查恶意 DLL/SO 文件（node-gyp.dll, loader.dll 等）
- 扫描与 C2 域名的连接（firebase.su, dieorsuffer.com, smartscreen-api.com）
- Windows 系统：审查 rundll32/regsvr32 执行日志
3. **警告**：
- 调查可疑模式
- 在恢复前验证软件包合法性
- 更新到安全版本
- 审查软件包维护者更改
4. **事件处理后**：
- 替换为安全的软件包版本：`npm install @`
- 运行 `npm audit fix` 进行自动修复
- 依赖项审查和 lockfile 验证
- 设置持续监控（`-c -i 300`）
- 考虑仅在验证后从隔离区恢复
## 参考链接
- [CrowdStrike NPM 攻击 2025](https://socket.dev/blog/ongoing-supply-chain-attack-targets-crowdstrike-npm-packages)
- [CVE-2025-54313](https://nvd.nist.gov/vuln/detail/CVE-2025-54313)
- [CVE-2026-45321 (TanStack / Mini Shai-Hulud)](https://snyk.io/blog/tanstack-npm-packages-compromised/)
- [Mini Shai-Hulud SAP CAP (StepSecurity)](https://www.stepsecurity.io/blog/a-mini-shai-hulud-has-appeared)
- [Bitwarden CLI 劫持 (JFrog)](https://research.jfrog.com/post/bitwarden-cli-hijack/)
- [Shai-Hulud Miasma / Red Hat (Wiz)](https://www.wiz.io/blog/miasma-supply-chain-attack-targeting-redhat-npm-packages)
- [Shai-Hulud Hades PyPI 浪潮 (Socket)](https://socket.dev/blog/shai-hulud-descends-to-hades-miasma-pypi-wave)
- [AntV 生态系统受损 (Socket)](https://socket.dev/blog/antv-packages-compromised)
- [npm audit 文档](https://docs.npmjs.com/cli/v8/commands/npm-audit)
## 备注
- 跨 npm + PyPI 追踪 **1340 个受损软件包版本**（更新于 2026-06-08）
- 检测到 **29 个恶意软件文件哈希值**（Shai-Hulud v1/v2 + Scavenger + 2026 年 Mini Shai-Hulud 浪潮）
- 涵盖**多次攻击活动**：CVE-2025-54313、Shai-Hulud v1/v2 以及 2026 年 Mini Shai-Hulud / TeamPCP 家族（CVE-2026-45321）
- 扫描器旨在最大程度减少误报（已针对合法的 `.claude`/`.vscode` 配置、干净的 PyPI/npm 版本、真实的 Anthropic API 调用进行了验证）
- 模式基于观察到的真实攻击（2025 年 7 月 - 2026 年 6 月）
- 建议定期更新恶意模式
- 兼容所有标准 NPM 项目
- 隔离功能允许安全隔离并提供恢复选项
## 局限性
- 不能替代彻底的手动分析
- 可能无法检测到零日攻击
- 性能取决于项目大小
- 需要 node_modules 的读取权限
## 贡献
如需添加新模式或受损的软件包：
1. **更新模式文件：**
- 编辑 `update-patterns.py` 以添加新的软件包/模式
- 运行 `python3 update-patterns.py` 以重新生成 `shai-hulud-iocs.json`
- 或者手动编辑 `malicious-patterns.json` 以进行快速更新
2. **测试更改：**
python3 npm-supply-chain-detector.py -v test-project/
3. **更新文档：**
- 更新 `README.md` 中的统计数据
标签：Cilium, Homebrew安装, IP 地址批量处理, MITM代理, NPM, Python, StruQ, 威胁情报, 应用安全, 开发者工具, 文档安全, 无后门, 暗色界面, 网络信息收集, 逆向工具, 配置审计