sngular/shai-hulud-integrity-scanner
GitHub: sngular/shai-hulud-integrity-scanner
针对 Shai-Hulud 供应链攻击的 Node.js 项目完整性扫描器，通过多维度检测帮助识别受污染依赖和可疑代码模式。
Stars: 13 | Forks: 4
# Shai-Hulud 完整性扫描器
一个用于扫描 Node.js 项目的脚本，旨在发现与 Shai-Hulud 供应链攻击相关的已知漏洞和可疑模式。
## 功能
此扫描器对项目执行多向量检查，以发现：
* **受损的依赖项：** 将 `package.json` 与已知恶意软件包版本列表进行比对。
* **恶意文件：** 检查具有已知恶意软件签名（SHA256 哈希）的文件。
* **关联数据渗出：** 标记同时访问环境变量（`process.env`）并包含数据渗出 URL（`webhook.site`）的文件。
* **可疑代码：** 查找 `postinstall` 钩子、硬编码的密钥扫描工具（`trufflehog`）以及其他可疑模式。
* **高风险命名空间：** 如果项目使用了已知受损的 npm 组织（例如 `@ctrl`）中的软件包，则发出警告。
**重要：** 内容扫描有意忽略文档（`.md`）和 TypeScript 定义（`.d.ts`），以减少误报。
## 前置条件
该脚本需要 POSIX 环境（Linux、macOS 或带有 WSL2 的 Windows）以及以下工具：
* `git`
* `curl`
* `jq`
* `shasum`
## 如何使用
### 在 Linux/macOS/WSL 上运行
在你要分析的项目**内部**执行以下 curl 命令：
```
curl -s https://raw.githubusercontent.com/sngular/shai-hulud-integrity-scanner/refs/heads/main/scan-project.sh | bash /dev/stdin
```
或者本地运行：
1. 使脚本可执行：
chmod +x scan-project.sh
2. 针对特定项目路径运行它：
./scan-project.sh /path/to/project
当然。这是文档的关键部分，为工具的能力设定了明确的预期。它需要直接且毫不含糊。
这里是一个简洁的警告部分，你可以将其添加到内部的 `README.md` 中。
### 在带有 PowerShell 的 Windows 上运行
如果你在 Windows 上并且更喜欢使用扫描器的 PowerShell 版本（`scan-project.ps1`），请按照以下步骤操作：
1. **下载脚本**到你的项目目录（或你机器上的任何位置）：
Invoke-WebRequest -Uri "https://raw.githubusercontent.com/sngular/shai-hulud-integrity-scanner/refs/heads/main/scan-project.ps1" -OutFile "scan-project.ps1"
2. **打开 PowerShell**（为了完整的 UTF-8 和颜色支持，最好使用 PowerShell 7 / Windows Terminal）。
3. 如果需要，**允许脚本执行**（每个系统仅需一次）：
Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
4. **在你的项目文件夹内运行扫描器**：
.\scan-project.ps1
或者针对特定的项目路径运行：
.\scan-project.ps1 -Path "C:\path\to\project"
5. **退出代码：**
* **0：** 扫描完成，未发现问题。
* **1：** 脚本错误（例如，缺少必需的依赖项）。
* **2：** 扫描完成，发现了可操作的问题。
**提示：** 为了在 Windows 上获得最佳效果，请在 **Windows Terminal** 内的 **PowerShell 7+** 中运行脚本。
这确保了 UTF-8 字符和彩色输出能够正确渲染。
## ⚠️ 关于扫描准确性的重要说明
**当存在 lockfile 时，此扫描器提供最准确的结果。**
脚本按以下顺序自动检测并优先使用最可靠的依赖文件：
1. **`pnpm-lock.yaml`（最高准确度）：** 如果找到，并且安装了 `pnpm`，扫描器将分析完整的依赖树，包括所有**传递依赖**。
2. **`yarn.lock`（高准确度）：** 如果找到，并且安装了 `yarn`，扫描器将分析完整的依赖树，包括所有**传递依赖**。
3. **`package-lock.json`（高准确度）：** 如果找到，扫描器将解析 lockfile 以分析完整的依赖树，包括所有**传递依赖**。
4. **`package.json`（回退方案 - 低准确度）：** 如果未找到 lockfile，扫描器将回退到读取 `package.json`。在此模式下，它**只能**检测*直接*依赖项中的漏洞，对于隐藏在传递依赖项中的任何威胁将无法察觉。
#### 最佳实践
为了进行完整且可靠的安全审计，请务必在安装依赖项（例如 `npm install`、`yarn install` 或 `pnpm install`）**之后**运行扫描器，因为这可以保证存在 lockfile。
## 退出代码与示例输出
该脚本使用退出代码进行自动化：
* **0：** 扫描完成，未发现问题。
* **1：** 脚本错误（例如，缺少依赖项）。
* **2：** 扫描完成，发现了可操作的问题。
```
==============================================
SHAI-HULUD DETECTION REPORT
==============================================
🚨 HIGH RISK: Compromised Package Versions Detected
- Package: @ctrl/tinycolor@4.1.0
NOTE: These specific package versions are known to be compromised.
🚨 HIGH RISK: Environment Scanning with Exfiltration Detected
- File: src/services/telemetry-service.js
NOTE: These files access secrets AND contain data exfiltration patterns.
⚠️ MEDIUM RISK: Packages from Compromised Namespaces
- Warning: Contains packages from compromised namespace: @ctrl (Found in package.json)
NOTE: Review packages from these organizations carefully.
==============================================
🔍 SUMMARY:
High/Critical Risk Issues: 2
Medium Risk Issues: 1
Total Actionable Issues: 3
==============================================
```
标签：AI合规, DNS 反向解析, GNU通用公共许可证, Hook检测, IPv6, Libemu, Libemu, MITM代理, Node.js, NPM安全, POSIX, PowerShell, Shai-Hulud, 哈希校验, 完整性校验, 应用安全, 数据渗漏检测, 文档安全, 环境变量保护, 网络安全, 脚本工具, 隐私保护