Security-Phoenix-demo/Shai-Hulud-Sha1-Hulud-V2-npm-compromise-scanner
GitHub: Security-Phoenix-demo/Shai-Hulud-Sha1-Hulud-V2-npm-compromise-scanner
针对 2025 年 NPM 供应链攻击，提供覆盖 690 个已知受损包的检测与修复能力。
Stars: 11 | Forks: 2
# NPM 包妥协检测工具与 Phoenix 安全集成 - 2025
## ⚡ 快速开始（30 秒）
### **📊 快速结果指南：**
- **0 个发现** = ✅ **非常棒！** 您的项目是安全的（就像 Optimizely、Facebook、Google 的仓库一样）
- **1+ 个发现** = 🚨 **需要立即行动！** 检测到受妥协的包，请按照下面的修复步骤操作
**🚨 安全紧急情况？请立即运行以下命令：**
```
# 1. 使脚本可执行
chmod +x *.sh *.py
# 2. 最快：使用 Phoenix + Light Scan 增强安全检查
./enhanced-quick-check-with-phoenix.sh . --enable-phoenix --light-scan
# 3. 或传统快速检查
./local-security-check.sh .
# 4. 如果发现受损包，获取包含所有库的详细报告
python3 enhanced_npm_compromise_detector_phoenix.py . --full-tree --enable-phoenix --detail-log --output emergency-report.txt
```
### **⚡ 企业快速启动（批量扫描）**
**一次性扫描多个仓库：**
```
# 1. 创建仓库列表
cat > my_repos.txt << EOF
https://github.com/your-org/frontend
https://github.com/your-org/backend
https://github.com/your-org/mobile-app
EOF
# 2. 设置 GitHub 令牌以获得最佳性能（可选但推荐）
export GITHUB_TOKEN=your_github_token_here
# 3. 轻量扫描所有仓库（速度快 10 倍！）并清理
python3 enhanced_npm_compromise_detector_phoenix.py --repo-list my_repos.txt --light-scan --enable-phoenix --organize-folders --delete-local-files --detail-log --output batch-security-report.txt
# 4. 或使用集成脚本
./enhanced-quick-check-with-phoenix.sh my_repos.txt --enable-phoenix --light-scan --repo-list
```
### **🐙 GitHub 自动仓库发现（`--pull-all`）**
**自动扫描您有访问权限的所有仓库：**
```
# 1. 设置您的 GitHub 个人访问令牌
export GITHUB_TOKEN=ghp_your_personal_access_token_here
# 2. 自动发现并扫描所有可访问的仓库
python3 enhanced_npm_compromise_detector_phoenix.py \
--pull-all \
--organize-folders \
--output github-all-repos-scan.txt
# 3. 配合 Phoenix 集成和完整树分析
python3 enhanced_npm_compromise_detector_phoenix.py \
--pull-all \
--full-tree \
--enable-phoenix \
--organize-folders \
--output github-comprehensive-audit.txt
# 4. 调试模式快速扫描（查看正在发现的内容）
python3 enhanced_npm_compromise_detector_phoenix.py \
--pull-all \
--debug \
--organize-folders \
--output github-debug-scan.txt
```
**`--pull-all` 的作用：**
- 🔍 **自动发现** 所有通过您的 GitHub 凭据可访问的仓库
- 📦 **克隆** 每个仓库到本地
- 🔎 **递归扫描** 所有目录，查找 `package.json`、`package-lock.json` 和 `yarn.lock`
- 🚀 **完美适用于** 组织范围的安全审计和持续监控
- ✅ **适用于** 公有和私有仓库
**GitHub 令牌设置：**
在以下位置创建个人访问令牌：https://github.com/settings/tokens
所需权限范围：
- `repo`（对私有仓库的完全控制）
- `read:org`（读取组织和团队成员关系）
然后设置它：
```
# Linux/macOS
export GITHUB_TOKEN="ghp_your_token_here"
# Windows PowerShell
$env:GITHUB_TOKEN="ghp_your_token_here"
```
### **🎯 每个工具的作用**
| 工具 | 用途 | 速度 | 使用场景 |
|------|------|------|----------|
| `./enhanced-quick-check-with-phoenix.sh` | **🔗 集成扫描器 + Phoenix API** | ⚡ 快速 | 企业安全、自动化报告 |
| `./enhanced-quick-check-with-phoenix.sh --light-scan` | **🪶 轻量批量扫描器** | ⚡⚡ 非常快 | **企业批量扫描** |
| `./local-security-check.sh` | 输出美观的快速扫描器 | ⚡ 快速 | 日常检查、CI/CD |
| `./quick-check-compromised-packages-2025.sh` | **核心检测引擎** | ⚡ 快速 | 直接使用、自动化 |
| `enhanced_npm_compromise_detector_phoenix.py --light-scan` | **🪶 轻量 Phoenix 扫描器** | ⚡⚡ 非常快 | **批量仓库扫描，零存储** |
| `enhanced_npm_compromise_detector_phoenix.py --detail-log` | **📋 详细库报告** | ⚡ 快速 | **完整库可见性** |
| `enhanced_npm_compromise_detector_phoenix.py --delete-local-files` | **🗑️ 自动清理扫描器** | ⚡ 快速 | **CI/CD、清洁环境** |
| `enhanced_npm_compromise_detector_phoenix.py` | **🔗 Phoenix 集成分析** | 🐌 详尽 | 企业安全审计、资产清单 |
| `npm_package_compromise_detector_2025.py` | **全面分析** | 🐌 详尽 | 安全审计、报告 |
### **📊 理解扫描结果**
#### ✅ **干净项目（退出代码 0）- 好消息！**
```
$ ./local-security-check.sh .
✅ SCAN COMPLETE: No compromised packages detected
Files scanned: 3
Total packages scanned: 45
Clean packages found: 45
Total findings: 0
```
**这意味着：**
- ✅ **您的项目是安全的** - 未发现受妥协的包
- ✅ **所有依赖项都干净且安全**
- ✅ **无需立即采取行动** - 可以安全继续开发
- 📊 **示例**：Optimizely、Facebook Create React App、Vue.js 核心、微软 TypeScript 通常显示 0 个发现（它们是安全的！）
**为什么某些项目显示 0 个发现：**
- 它们使用 **主流、可信的包**（lodash、react、express）
- 它们 **避免实验性/小众包**，这些包更容易被妥协
- 它们有 **良好的安全实践** 和依赖管理
- 它们 **定期更新依赖项** 以避免已知漏洞版本
#### 🚨 **受妥协项目（退出代码 1）- 需要立即行动！**
```
$ ./local-security-check.sh .
🚨 CRITICAL: Compromised packages detected!
Files scanned: 2
Total packages scanned: 23
Clean packages found: 18
Total findings: 5
IMMEDIATE ACTIONS REQUIRED:
1. Stop all running applications immediately
2. Clear npm cache: npm cache clean --force
3. Remove node_modules: rm -rf node_modules
4. Remove lock files: rm package-lock.json yarn.lock
5. Update to safe versions and reinstall
```
**这意味着：**
- ❌ **检测到安全风险** - 发现了受妥协的包
- 🚨 **需要立即采取行动** - 请遵循下面的修复步骤
- 📊 **混合结果**：部分包干净（18 个），部分受妥协（5 个）
#### 🔍 **理解“0 个发现”结果**
**“0 个发现”是极好的消息，意味着：**
1. **✅ 依赖项安全**：您的项目只使用干净、未受妥协的包
2. **✅ 良好的安全态势**：供应链中没有已知漏洞
3. **✅ 可安全部署**：没有来自 NPM 包妥协的安全风险
4. **✅ 维护良好的项目**：依赖项来自受信任的来源
**现实中的干净项目示例：**
- **Optimizely 仓库**：0 个发现 ✅（专业、安全的依赖项）
- **Facebook Create React App**：0 个发现 ✅（经过充分审查的依赖项）
- **Vue.js 核心**：0 个发现 ✅（少量、受信任的依赖项）
- **微软 TypeScript**：0 个发现 ✅（企业级安全）
**为什么某些项目显示 0 个发现：**
- 它们使用 **主流、可信的包**（lodash、react、express）
- 它们 **避免实验性/小众包**，其中妥协经常发生
- 它们有 **良好的安全实践** 和依赖管理
- 它们 **定期更新依赖项** 以避免已知漏洞版本
## 🔗 Phoenix 安全集成（新功能！）
### **企业资产与漏洞管理**
增强的工具现在与 **Phoenix Security** 平台集成，自动：
- **🏗️ 为每个 package.json/package-lock.json 文件创建 BUILD 资产**
- **🔍 生成带有适当风险评分（1.0-10.0）的安全发现**
- **🔗 自动从文件路径检测 Git 仓库并链接**
- **📊 在 Phoenix 安全仪表板中集中安全数据**
### **快速 Phoenix 设置**
```
# 1. 创建 Phoenix API 配置模板
python3 enhanced_npm_compromise_detector_phoenix.py --create-config
# 2. 编辑 .config 并填入您的 Phoenix API 凭据
cp .config.example .config
# ⚠️ 重要：编辑 .config 文件并替换：
# - your_phoenix_client_id_here → 您的实际 Phoenix 客户端 ID
# - your_phoenix_client_secret_here → 您的实际 Phoenix 客户端密钥
# - your-phoenix-domain.com → 您的实际 Phoenix 域
# 3. 使用 Phoenix 集成运行
./enhanced-quick-check-with-phoenix.sh . --enable-phoenix
```
### **Phoenix 风险评分**
| 发现类型 | 风险评分 | 描述 |
|----------|----------|------|
| **受妥协的包** | 10.0（严重） | 检测到已知受妥协的版本 |
| **潜在受妥协** | 8.0（高） | 包名在妥协列表中 |
| **安全版本** | 1.0（信息） | 被监控包的安全版本 |
| **干净库** | 1.0（信息） | 未受 Shai Halud 影响的干净库 |
### **🆕 导入所有库（`--import-all`）**
默认情况下，Phoenix 发现仅针对受妥协或监控的包创建。使用 `--import-all` 为 **所有** 库创建发现，包括干净的库：
```
# 导入所有库（包括干净库，生成 CVSS 1.0 漏洞）
python3 enhanced_npm_compromise_detector_phoenix.py . --enable-phoenix --import-all
# 完整安全态势（包含所有库）
python3 enhanced_npm_compromise_detector_phoenix.py \
--repo-list repos.txt \
--light-scan \
--enable-phoenix \
--import-all \
--output complete-posture.txt
```
**`--import-all` 的好处：**
- ✅ **完整的资产清单**：每个库都有一个 Phoenix 发现
- ✅ **安全态势可见性**：查看所有依赖项，而不仅仅是受妥协的
- ✅ **合规准备就绪**：完整的库文档用于审计
- ✅ **干净库跟踪**：跟踪“库 XYZ 版本 Z 未受 Shai Halud 影响”
**干净库发现示例：**
- **名称**：“NPM 包安全性：express”
- **描述**：“库 express 版本 4.18.2 未受 Shai Halud 影响”
- **风险评分**：1.0（CVSS 1）
- **标签**：“shai-hulud-clean-library”
### **🏷️ 自定义标签配置**
为 Phoenix 发现和资产添加自定义标签以更好地组织：
#### **命令行标签：**
```
# 添加自定义漏洞标签
python3 enhanced_npm_compromise_detector_phoenix.py . \
--enable-phoenix \
--tag_vuln="security-audit,compliance-scan,Q4-2025"
# 添加自定义资产标签
python3 enhanced_npm_compromise_detector_phoenix.py . \
--enable-phoenix \
--tag_asset="frontend-project,production-ready,team-alpha"
# 合并两种标签类型
python3 enhanced_npm_compromise_detector_phoenix.py . \
--enable-phoenix \
--import-all \
--tag_vuln="security-audit,shai-halud-scan" \
--tag_asset="npm-project,dependency-inventory" \
--output tagged-security-scan.txt
```
#### **配置文件标签：**
在 `.config` 文件中添加标签以保持一致的标记：
```
[phoenix]
client_id = your_phoenix_client_id_here
client_secret = your_phoenix_client_secret_here
api_base_url = https://api.securityphoenix.cloud
assessment_name = NPM Compromise Detection - Shai Halud
import_type = new
# 针对漏洞和资产的附加标签（逗号分隔）
additional_vuln_tags = custom-scan,security-audit,Q4-2025
additional_asset_tags = npm-project,dependency-scan,team-alpha
# 用于增强 API 速率限制的 GitHub 令牌
github_token = your_github_token_here
```
**标签用例：**
- **团队组织**：`team-frontend,team-backend,team-mobile`
- **环境跟踪**：`production,staging,development`
- **合规性**：`sox-compliance,gdpr-audit,security-review`
- **基于时间**：`Q1-2025,monthly-scan,pre-deployment`
- **项目**：`critical-app,internal-tool,public-facing`
### **📊 增强的回退报告**
在使用轻量扫描模式时，扫描器提供有关 GitHub 访问方法的详细报告：
```
GITHUB ACCESS SUMMARY:
----------------------
API failures: 3 repositories
Fallback successes: 2 repositories
Complete failures: 1 repositories
REPOSITORIES ACCESSED VIA FALLBACK (Direct Raw GitHub):
1. react-sdk
URL: https://github.com/optimizely/react-sdk
Files found: 2
Access method: direct_raw_github
Status: ✅ Fallback successful
REPOSITORIES WITH API FAILURES:
1. react-sdk
URL: https://github.com/optimizely/react-sdk
Reason: github_api_failed
Status: ✅ Recovered via direct raw access
REPOSITORIES COMPLETELY INACCESSIBLE:
1. android-sdk
URL: https://github.com/optimizely/android-sdk
Reason: all_methods_failed
Status: ❌ All access methods failed
```
**报告类别：**
- **✅ 回退成功**：通过直接原始访问恢复仓库
- **⚠️ API 失败**：GitHub API 失败但回退有效的仓库
- **❌ 完全失败**：所有方法都无法访问的仓库（通常没有 NPM 文件）
### **仓库 URL 检测**
该工具自动从文件路径检测仓库 URL：
- **GitHub 模式**：`/Documents/GitHub/repo-name/` → `https://github.com/org/repo-name`
- **Git 远程**：从 `.git` 目录读取 `git remote get-url origin`
- **手动覆盖**：使用 `--repo-url` 参数
### **批量仓库处理**
```
# 创建仓库列表
cat > repos.txt << EOF
https://github.com/securityphoenix/SP-MVP1-Frontend
https://github.com/Security-Phoenix-demo/Shai-Halud-tinycolour-compromise-verifier
EOF
# 处理多个仓库（完整扫描）
python3 enhanced_npm_compromise_detector_phoenix.py --repo-list repos.txt --enable-phoenix
# 🪶 轻量扫描模式（速度快 10 倍 - 仅限 NPM 文件！）
python3 enhanced_npm_compromise_detector_phoenix.py --repo-list repos.txt --enable-phoenix --light-scan
```
### **🌐 拉取所有仓库模式（`--pull-all`）（新功能！）**
自动发现并扫描您的 GitHub 凭据可访问的所有仓库：
```
# 1. 在 .config 文件中配置 GitHub 令牌
[github]
token = ghp_your_github_token_here
# 2. 拉取并扫描所有可访问的仓库
python3 enhanced_npm_compromise_detector_phoenix.py . --pull-all
# 3. 配合 Phoenix 集成和清理
python3 enhanced_npm_compromise_detector_phoenix.py . \
--pull-all \
--enable-phoenix \
--organize-folders \
--delete-local-files
```
**特性：**
- 🔍 **自动发现**：从 GitHub API 获取所有者、协作者、组织成员的所有仓库
- 📦 **自动克隆**：将每个仓库克隆到有组织的文件夹中
- 🔄 **递归扫描**：扫描所有子目录中的包文件
- 🏢 **企业就绪**：完美用于组织范围的安全审计
- 🔐 **访问控制感知**：仅扫描凭据可访问的仓库
**用例：**
- 组织范围的安全审计
- 个人项目清单扫描
- 自动化合规检查
- 持续安全监控
📖 **[完整的 --pull-all 指南](PULL_ALL_FEATURE_GUIDE.md)**
### **🪶 轻量扫描模式（新功能！）**
非常适合快速扫描数百个仓库：
- ⚡ **快 10 倍**：仅通过 GitHub API 下载 NPM 文件
- 💾 **零存储**：无需克隆仓库
- 🔄 **批量优化**：高效扫描整个组织
- 🛡️ **自动回退**：从 API 故障中恢复，使用 GitHub 原始直接访问
```
# 为更高速率限制设置 GitHub 令牌（推荐）
export GITHUB_TOKEN=your_github_token_here
# 轻量扫描仓库列表
python3 enhanced_npm_compromise_detector_phoenix.py --repo-list repos.txt --light-scan --enable-phoenix
```
#### **🔄 智能回退系统**
当 GitHub API 访问失败（无效令牌、速率限制等）时，扫描器自动：
1. **GitHub API 搜索** → 尝试经过身份验证/未经过身份验证的 API 访问
2. **GitHub API 回退** → 尝试直接 GitHub API 文件访问
3. **直接原始访问** → 使用 `raw.githubusercontent.com` 访问公共仓库
4. **完整文档** → 在扫描结果中准确报告发生的情况
**回退流程示例：**
```
🔄 GitHub API failed completely, trying direct raw access...
🔄 Fallback: Trying direct raw GitHub access for optimizely/react-sdk
✅ Direct access found: package.json
✅ Direct access found: yarn.lock
✅ Fallback successful: Found 2 NPM file(s) via direct access
```
**回退的好处：**
- ✅ **零空文件**：不再有 JSON 解析错误
- ✅ **最大覆盖范围**：恢复原本会失败的仓库
- ✅ **详细报告**：显示哪些仓库使用了回退方法
- ✅ **公共仓库支持**：适用于任何公共 GitHub 仓库
- ✅ **自动恢复**：无需手动干预
### **🆕 2025 年新增强功能**
#### **📋 详细日志模式（`--detail-log`）**
显示所有库而不截断，以获得完整可见性：
```
# 显示每个库（不显示“……还有 50 个”消息）
python3 enhanced_npm_compromise_detector_phoenix.py --folders my_projects --detail-log
# 带完整库列表的企业审计
python3 enhanced_npm_compromise_detector_phoenix.py --repo-list enterprise_repos.txt --detail-log --output complete-audit.txt
```
**好处：**
- ✅ **完整可见性**：查看每个扫描的库
- ✅ **无截断**：没有“… 和 X 个更多库”的消息
- ✅ **审计就绪**：完美用于合规性和安全审计
- ✅ **仓库上下文**：每个库显示仓库、构建文件和本地路径
#### **🗑️ 自动清理模式（`--delete-local-files`）**
扫描后自动清理克隆的仓库：
```
# 扫描并清理 - 适合 CI/CD
python3 enhanced_npm_compromise_detector_phoenix.py --repo-list repos.txt --organize-folders --delete-local-files
# 带清理的企业批量扫描
python3 enhanced_npm_compromise_detector_phoenix.py \
--repo-list large_org_repos.txt \
--light-scan \
--organize-folders \
--delete-local-files \
--enable-phoenix
```
**好处：**
- ✅ **清洁环境**：不留下克隆的仓库
- ✅ **CI/CD 就绪**：完美用于自动化管道
- ✅ **磁盘管理**：防止磁盘空间积累
- ✅ **安全清理**：仅删除本次扫描克隆的仓库
#### **🔄 组合使用**
将这两个功能结合使用以获得终极扫描体验：
```
# 带清理的完整企业安全审计
python3 enhanced_npm_compromise_detector_phoenix.py \
--repo-list organization_repos.txt \
--light-scan \
--organize-folders \
--delete-local-files \
--detail-log \
--enable-phoenix \
--output comprehensive-security-audit.txt
```
### **🗂️ 有组织的文件夹结构**
适用于系统化的安全监控和审计跟踪：
```
# 按日期组织 GitHub 拉取请求和结果
python3 enhanced_npm_compromise_detector_phoenix.py \
--repo-list repos.txt \
--light-scan \
--organize-folders \
--enable-phoenix \
--output security_audit.txt
```
**创建有组织的结构：**
```
github-pull/20250917/ # Downloaded NPM files by repository
├── repo1/package.json
├── repo2/package-lock.json
└── repo3/yarn.lock
result/20250917/ # All reports and results
├── security_audit.txt
└── phoenix_import.log
```
📖 **[完整的 Phoenix 集成指南](PHOENIX_INTEGRATION_GUIDE.md)**
## 🆕 近期更新（2025 年 11 月）
### **🚨 第四波更新 - 2025 年 11 月 25 日**
**大规模安全警报**：482 个额外的包已确认被妥协！
- 📊 **数据库里程碑**：所有潜在受妥协的包现已确认
- **690 个总确认包**（原为 208 个，+482 个包）
- **0 个潜在受妥协**（所有 400 个已移至确认 + 82 个新包）
- **37 个组织受影响**（原为 29 个，+8 个新组织）
- 🏢 **新受重大影响的主要组织：**
- `@asyncapi/*` - 37 个包（异步 API 生成器、解析器、模板）
- `@posthog/*` - 56 个包（PostHog 分析、插件、集成）
- `@postman/*` - 19 个包（Postman MCP、二进制文件、工具）
- `@ensdomains/*` - 47 个包（ENS 合约、解析器、工具）
- `@voiceflow/*` - 43 个包（Voiceflow SDK、类型、配置）
- 加上来自各种维护者的 250 多个独立包
- ⚠️ **关键影响领域：**
- API 开发工具（@asyncapi、@postman）
- 分析和跟踪（@posthog）
- 区块链/Web3 基础设施（@ensdomains、crypto-addr-codec）
- 对话式 AI 平台（@voiceflow、dialogflow-es）
- React Native 移动开发（@actbase、@strapbuild）
- DevOps 和测试工具
### **之前的更新：**
- 🌐 **`--pull-all` 模式**：自动发现并扫描所有可访问的仓库
- 📦 **10 个 Zapier 包**：已确认具体受妥协版本
- 🧪 **测试变体套件**：针对移动、后端和前端专注的测试套件
### **完整的更新历史：**
- ✅ **690 个确认受妥协包**（2025 年 11 月 25 日 - 第四波）
- ✅ **37 个组织受影响**（8 个新组织）
- ✅ **100% 确认率**（所有潜在受妥协包现已确认）
## 概览
This repository contains comprehensive security tools to detect **690 confirmed compromised NPM packages** from the 2025 supply chain attack affecting multiple organizations including `@ctrl/*`, `@nativescript-community/*`, `@art-ws/*`, `@crowdstrike/*`, `@operato/*`, `@teselagen/*`, `@things-factory/*`, `@zapier/*`, `@asyncapi/*`, `@posthog/*`, `@postman/*`, `@ensdomains/*`, `@voiceflow/*`, and many others.
## ⚠️ 严重安全警报
**IMMEDIATE ACTION REQUIRED** if any of these packages are detected in your project:
### 🚨 **690 个已确认受损包（包含特定版本）**
**⚠️ CRITICAL ORGANIZATIONS AFFECTED (37 Organizations):**
- **@ctrl** - 15+ packages compromised
- **@nativescript-community** - 25+ packages compromised
- **@art-ws** - 15+ packages compromised
- **@crowdstrike** - 10+ packages compromised
- **@operato** - 15+ packages compromised
- **@teselagen** - 10+ packages compromised
- **@things-factory** - 8+ packages compromised
- **@nstudio** - 8+ packages compromised
- **@zap** - 10+ packages compromised
- **@asyncapi** - 37+ packages compromised (**4TH WAVE!**)
- **@posthog** - 56+ packages compromised (**4TH WAVE!**)
- **@postman** - 19+ packages compromised (**4TH WAVE!**)
- **@ensdomains** - 47+ packages compromised (**4TH WAVE!**)
- **@voiceflow** - 43+ packages compromised (**4TH WAVE!**)
- Plus 250+ individual packages from various maintainers
#### **关键受损包（样本，共 690 个）：**
**Original Wave:**
- `@ctrl/tinycolor@4.1.1, 4.1.2`
- `@ahmedhfarag/ngx-perfect-scrollbar@20.0.20`
- `@art-ws/common@2.0.28`
- `@crowdstrike/commitlint@8.1.1, 8.1.2`
- `@operato/board@9.0.36-9.0.46` (multiple versions)
- `@nativescript-community/text@1.6.9-1.6.13` (multiple versions)
**3rd Wave (Zapier):**
- `@zapier/zapier-sdk@0.15.5-0.15.7` (multiple versions)
- `zapier-platform-core@18.0.2-18.0.4` (multiple versions)
- `@zapier/mcp-integration@3.0.1-3.0.3` (multiple versions)
**4TH WAVE (482 packages - Nov 25, 2025):**
- `@asyncapi/*` - 37 packages (all versions affected)
- `@posthog/*` - 56 packages (all versions affected)
- `@postman/*` - 19 packages (all versions affected)
- `@ensdomains/*` - 47 packages (all versions affected)
- `@voiceflow/*` - 43 packages (all versions affected)
- `posthog-js`, `posthog-node`, `posthog-react-native` (all versions)
- `ethereum-ens`, `crypto-addr-codec` (all versions)
- Plus 250+ individual packages
## 🚨 紧急响应（如果发现受损包）
**If the scan detects compromised packages, follow these steps immediately:**
```
# 1. 立即停止应用程序
pkill -f node
# 2. 清理环境
npm cache clean --force
rm -rf node_modules
rm -f package-lock.json yarn.lock
# 3. 获取详细分析
python3 npm_package_compromise_detector_2025.py . --full-tree --output emergency-report.txt
# 4. 查看 emergency-report.txt 获取安全版本
# 5. 使用报告中的安全版本更新 package.json
# 6. 重新安装依赖项
npm install
# 7. 验证修复
./local-security-check.sh .
```
## 🛠️ 检测工具
### 1. **本地安全检查（推荐）**
```
# 最佳选项：结合 Shell 和 Python 分析，输出干净结果
./local-security-check.sh . # Check current directory
./local-security-check.sh /path/to/project # Check specific project
```
**Features:**
- ⚡ Fast execution with comprehensive coverage
- 🎨 Clean, readable output format
- 🔄 Runs both shell and Python scanners
- 📊 Clear summary with next steps
### 2. **快速 Shell 脚本（直接核心扫描器）**
```
# 直接访问核心检测引擎
./quick-check-compromised-packages-2025.sh . # Check current directory
./quick-check-compromised-packages-2025.sh /path/to/project # Check specific project
```
**Features:**
- ⚡ Fastest scanning of package.json and lock files
- 🎨 Color-coded output for easy identification
- 🗂️ NPM cache checking
- 📊 Summary report with actionable recommendations
### 3. **综合 Python 扫描器（详细分析）**
```
# 无需额外依赖 - 使用标准库
# 基本扫描
python3 npm_package_compromise_detector_2025.py .
# 完整依赖树分析（安全审计推荐）
python3 npm_package_compromise_detector_2025.py . --full-tree
# 保存带时间戳的详细报告
python3 npm_package_compromise_detector_2025.py . --full-tree \
--output "security-report-$(date +%Y%m%d-%H%M).txt"
# 静默模式（仅关键/高严重性发现）
python3 npm_package_compromise_detector_2025.py . --quiet
# 自定义配置文件
python3 npm_package_compromise_detector_2025.py . --config custom-packages.json
```
**Advanced Features:**
- 🌳 Full dependency tree traversal (requires npm install first)
- 📋 Detailed package analysis and reporting
- 🔍 Source code scanning for malicious patterns
- 📊 Comprehensive statistics and safe version recommendations
- 🧬 Crypto-related keyword detection
- 🌐 Malicious URL detection
### 4. **通用工作流**
```
# 日常开发检查
./local-security-check.sh .
# 部署前安全审计
python3 npm_package_compromise_detector_2025.py . --full-tree --output pre-deploy-security.txt
# 多项目扫描
for project in ~/projects/*/; do
echo "Scanning $project"
./local-security-check.sh "$project"
done
# CI/CD 集成
./local-security-check.sh . || exit 1 # Fail build if compromised
```
## 📁 仓库结构
```
├── local-security-check.sh # ⭐ Recommended: Clean runner script
├── quick-check-compromised-packages-2025.sh # Fast shell script checker
├── npm_package_compromise_detector_2025.py # Comprehensive Python scanner
├── compromised_packages_2025.json # Package compromise database
├── install-and-run.sh # One-liner installation script
├── test_sample/ # Test data for validation
│ ├── package.json # Sample with compromised packages
│ └── suspicious_code.js # Sample with malicious patterns
├── test_deep_dependencies/ # Deep dependency tree testing
│ ├── package.json # Complex dependency structure
│ └── package-lock.json # Lock file with nested compromised packages
├── test_comprehensive_scan/ # Comprehensive risk scoring test
│ ├── package.json # Test all severity levels and duplicates
│ └── README.md # Test documentation
├── test_variations/ # Focused test suites (NEW!)
│ ├── mobile-focused/ # Mobile development packages
│ ├── backend-api-focused/ # Backend/API packages
│ ├── frontend-web-focused/ # Frontend/web packages
│ └── README.md # Variations documentation
├── test_zapier_confirmed/ # Zapier confirmed compromises (NEW!)
│ └── package.json # All 10 Zapier packages with versions
├── .github/workflows/ # GitHub Actions integration
│ └── npm-security-scan.yml # CI/CD workflow template
├── QUICK_START.md # Comprehensive usage guide
├── COMMAND_REFERENCE.md # Quick reference card
├── requirements.txt # Python dependencies (optional)
└── README.md # This documentation
```
## 🚨 即时响应操作
If compromised packages are detected:
### 1. **立即停止**
```
# 终止所有正在运行的 Node.js 进程
pkill -f node
pkill -f npm
```
### 2. **清理环境**
```
# 清除 npm 缓存
npm cache clean --force
# 移除 node_modules 和锁定文件
rm -rf node_modules
rm -f package-lock.json yarn.lock
```
### 3. **更新包版本**
**🎯 Automatic Safe Version Detection**: The Python scanner generates safe version recommendations automatically. For manual updates, here are key examples:
```
{
"overrides": {
"@ctrl/tinycolor": "4.1.0",
"@ahmedhfarag/ngx-perfect-scrollbar": "20.0.19",
"@art-ws/common": "2.0.27",
"@crowdstrike/commitlint": "8.1.0",
"@nativescript-community/text": "1.6.8",
"@zapier/zapier-sdk": "0.15.4",
"zapier-platform-core": "18.0.1",
"zapier-platform-cli": "18.0.1",
"zapier-platform-schema": "18.0.1",
"@zapier/mcp-integration": "3.0.0",
"@zapier/secret-scrubber": "1.1.2",
"angulartics2": "14.1.0",
"ngx-color": "10.0.0",
"ngx-toastr": "19.0.0",
"ts-gaussian": "3.0.4",
"encounter-playground": "0.0.1"
}
}
```
```
### 4. **重新安装并审计**
```bash
# 重新安装依赖项
npm install
# 运行安全审计
npm audit
npm audit fix
# 验证无受损包残留
./quick-check-compromised-packages-2025.sh .
```
### 5. **安全评估**
- Review application logs for suspicious network activity
- Check for unauthorized file modifications
- Monitor for unusual CPU/memory usage
- Scan for crypto wallet compromise if browser-based application
- Review recent deployments and rollback if necessary
## 🔧 配置
### 自定义包数据库
You can modify `compromised_packages_2025.json` to add new compromised packages or update versions:
```
{
"compromised_packages": {
"package-name": {
"compromised_versions": ["1.0.0", "1.0.1"],
"safe_version": "0.9.9"
}
},
"potentially_compromised_packages": [
"suspicious-package-name"
]
}
```
### Python 脚本选项
```
# 自定义配置文件
python3 npm_package_compromise_detector_2025.py --config custom_packages.json
# 跳过递归目录扫描
python3 npm_package_compromise_detector_2025.py --no-recursive
# 启用完整依赖树分析
python3 npm_package_compromise_detector_2025.py --full-tree
```
## 🧪 测试与验证
### **快速测试（30 秒）**
```
# 使用干净项目测试
mkdir clean_test && echo '{"name":"test","version":"1.0.0","dependencies":{"lodash":"^4.17.21"}}' > clean_test/package.json
./local-security-check.sh clean_test
# 预期：✅ 未检测到受损包
# 使用受损包测试
./local-security-check.sh test_sample
# 预期：🚨 检测到多个受损包
```
### **综合测试**
```
# 使用示例数据测试 Shell 脚本
./quick-check-compromised-packages-2025.sh test_sample
# 使用详细输出测试 Python 脚本
python3 npm_package_compromise_detector_2025.py test_sample --output test_results.txt
# 测试深度依赖分析（首次需运行 npm install）
cd test_deep_dependencies && npm install && cd ..
python3 npm_package_compromise_detector_2025.py test_deep_dependencies --full-tree
```
### **预期结果：**
- **test_sample**: Should detect 5+ compromised packages and malicious patterns from 690 total monitored packages
- **test_deep_dependencies**: Should detect compromised packages in nested dependencies
- **test_variations**: Three focused test suites (mobile, backend, frontend) with 4th wave packages
- **test_zapier_confirmed**: Tests 10 Zapier packages with specific versions
- **clean_test**: Should show clean results with exit code 0
- **Coverage**: Scanner monitors **690 confirmed compromised packages** across **37 major organizations**
### **🤔 故障排查：“为何未发现任何问题？”**
#### **✅ 这通常是好消息！**
If you're scanning repositories like:
- **Optimizely**: `python3 enhanced_npm_compromise_detector_phoenix.py --repo-list optimizely_repos.txt --light-scan`
- **Facebook/Meta projects**: `--repo-list facebook_repos.txt`
- **Google/Angular projects**: `--repo-list google_repos.txt`
- **Microsoft projects**: `--repo-list microsoft_repos.txt`
**Expected Result: 0 findings ✅**
**Why?** These organizations:
- Use **enterprise-grade security practices**
- Have **dedicated security teams** reviewing dependencies
- Use **mainstream, well-vetted packages** (React, Express, TypeScript, etc.)
- **Avoid niche/experimental packages** where compromises typically occur
- **Regularly audit and update** their dependencies
#### **🔍 如何验证扫描器是否正常工作：**
```
# 1. 使用已知受损包测试（应显示发现）
python3 enhanced_npm_compromise_detector_phoenix.py --folders test_compromised_packages
# 预期：17 个严重 + 6 个信息发现
# 2. 使用干净企业仓库测试（应显示 0 个发现）
echo "https://github.com/optimizely/react-sdk" > clean_test.txt
python3 enhanced_npm_compromise_detector_phoenix.py --repo-list clean_test.txt --light-scan
# 预期：0 个发现（正确！）
# 3. 检查扫描器数据库是否已加载
python3 -c "import json; data=json.load(open('compromised_packages_2025.json')); print(f'Monitoring {len(data[\"compromised_packages\"])} confirmed packages')"
# 预期：监控 690 个已确认包
```
#### **📊 “0 个发现”表示：**
| Scenario | Findings | Meaning | Action |
|----------|----------|---------|--------|
| **Enterprise repos** (Optimizely, Facebook) | 0 | ✅ **Secure & Professional** | Continue development |
| **Your production app** | 0 | ✅ **Good security posture** | Continue monitoring |
| **Test files** (`test_compromised_packages`) | 17+ | ❌ **Contains test compromised packages** | Expected for testing |
| **Legacy/experimental project** | 0 | ✅ **Either clean OR uses packages we don't monitor** | Review manually if concerned |
#### **🚨 何时应关注“0 个发现”：**
**Only worry if:**
- You **expect** compromised packages (testing with `test_sample/`)
- Scanner shows `Files scanned: 0` (indicates scanning issue)
- You're using packages from the affected organizations (`@ctrl/*`, `@operato/*`, etc.) but getting 0 findings
**Debug steps:**
```
# 检查是否找到文件
python3 enhanced_npm_compromise_detector_phoenix.py your_project --debug
# 查看提示：“已扫描文件：X”，其中 X > 0
# 检查特定包
python3 -c "
import json
data = json.load(open('compromised_packages_2025.json'))
pkg = '@ctrl/tinycolor' # Replace with your package
if pkg in data['compromised_packages']:
print(f'✅ {pkg} is monitored')
print(f'Compromised versions: {data[\"compromised_packages\"][pkg][\"compromised_versions\"]}')
else:
print(f'❌ {pkg} is not in our database')
"
```
#### **🔧 GitHub API 故障排查**
**Common Issues and Solutions:**
| Issue | Symptoms | Solution |
|-------|----------|----------|
| **Invalid GitHub Token** | `Bad credentials (401)` | Generate new token at https://github.com/settings/tokens |
| **Rate Limit Exceeded** | `API rate limit exceeded` | Wait or use valid token for higher limits |
| **Empty Downloaded Files** | `JSON parsing errors` | ✅ **Auto-fixed by fallback system** |
| **Private Repository** | `Not Found (404)` | Ensure token has `repo` permission |
**Fallback System Handles:**
- ✅ Invalid/expired GitHub tokens
-✅ API rate limit exceeded
- ✅ Authentication failures
- ✅ Empty file downloads
- ✅ Network timeouts
**When Fallback Won't Work:**
- ❌ Private repositories (requires valid token)
- ❌ Repositories with no NPM files
- ❌ Repositories that don't exist
### **性能基准：**
- Shell script: ~1-2 seconds for typical projects
- Python basic scan: ~3-5 seconds for typical projects
- Python full-tree: ~10-30 seconds (requires npm install first)
## 📊 示例输出
### Shell 脚本输出：
```
🚨 CRITICAL: Compromised package detected: @ctrl/tinycolor@4.1.2 in dependencies
🚨 CRITICAL: Compromised package detected: angulartics2@14.1.2 in dependencies
❌ Found 5 compromised package(s) in package.json
Status: ❌ COMPROMISED PACKAGES DETECTED
```
### Python 脚本输出：
```
[CRITICAL] Compromised package detected: @ctrl/tinycolor@4.1.2
[HIGH] Malicious URL detected: npmjs.help
[MEDIUM] Crypto-related keywords detected: wallet, privatekey, crypto
[MEDIUM] Suspicious code patterns detected: 5 patterns
COMPROMISED PACKAGES FOUND: 5
POTENTIALLY COMPROMISED FOUND: 0
```
## 🔗 参考
- **Attack Vector**: Supply chain compromise targeting popular packages
- **Impact**: Potential malicious code injection, data exfiltration, crypto wallet stealing
- **Severity**: CRITICAL
- **Date**: September 2025
## 🤝 贡献
To add new compromised packages or improve detection:
1. Update `compromised_packages_2025.json` with new package data
2. Test with sample projects
3. Update documentation
4. Submit pull request with detailed description
## ⚖️ 许可证
This security tool is provided as-is for protection against supply chain attacks. Use responsibly and ensure you have proper authorization before scanning systems.
## 🆘 支持
For urgent security incidents or questions:
- Create an issue in this repository
- Include scan results and affected package information
- Mark as urgent for critical security issues
## 📚 快速参考
### **🚀 最常用命令**
```
# 每日快速检查
./local-security-check.sh .
# 部署前附带完整库详情
python3 enhanced_npm_compromise_detector_phoenix.py . --full-tree --detail-log --output pre-deploy-report.txt
# 安全警报后的紧急扫描
python3 enhanced_npm_compromise_detector_phoenix.py . --full-tree --detail-log --output emergency-$(date +%Y%m%d).txt
# 带清理的企业仓库批量扫描
python3 enhanced_npm_compromise_detector_phoenix.py --repo-list enterprise_repos.txt --light-scan --organize-folders --delete-local-files --enable-phoenix
# 包含干净库的所有功能完整审计
python3 enhanced_npm_compromise_detector_phoenix.py --repo-list repos.txt --light-scan --organize-folders --delete-local-files --detail-log --enable-phoenix --import-all --output complete-audit.txt
# 带自定义标签和自动回退的企业扫描
python3 enhanced_npm_compromise_detector_phoenix.py --repo-list repos.txt --light-scan --enable-phoenix --import-all --tag_vuln="Q4-audit,compliance" --tag_asset="production,critical" --output enterprise-scan.txt
# 自动回退处理 GitHub API 故障（无需配置）
python3 enhanced_npm_compromise_detector_phoenix.py --repo-list public_repos.txt --light-scan --import-all
# 扫描所有可访问仓库（自动发现模式 - 新增！）
python3 enhanced_npm_compromise_detector_phoenix.py . --pull-all --enable-phoenix --organize-folders --delete-local-files
```
### **📊 退出代码参考**
- `0` = ✅ Clean (no compromised packages)
- `1` = 🚨 Compromised packages detected (IMMEDIATE ACTION REQUIRED)
- `2` = ⚠️ Script error (check dependencies, file paths, permissions)
### **🚨 紧急检查清单**
If you see compromised packages:
1. ⏹️ **STOP** - Don't ignore this
2. 🔍 **ANALYZE** - Run: `python3 npm_package_compromise_detector_2025.py . --full-tree --output emergency.txt`
3. 🧹 **CLEAN** - `npm cache clean --force && rm -rf node_modules`
4. 📋 **REVIEW** - Check `emergency.txt` for safe versions
5. 🔄 **UPDATE** - Modify package.json with safe versions
6. 🔧 **REINSTALL** - `npm install`
7. ✅ **VERIFY** - `./local-security-check.sh .`
### **💡 专业提示**
- Run `./local-security-check.sh .` every morning
- Add to your git pre-commit hooks
- Use `--full-tree` for comprehensive audits
- Save reports with timestamps for tracking
- Integrate into CI/CD for automated protection
### **🏢 企业规模示例**
**Scan entire organization (hundreds of repositories):**
```
# 1. 从 GitHub API 生成仓库列表
curl -H "Authorization: token $GITHUB_TOKEN" \
"https://api.github.com/orgs/your-org/repos?per_page=100&type=all" | \
jq -r '.[].clone_url' > org_repos.txt
# 2. 使用 Phoenix 集成轻量扫描所有仓库
python3 enhanced_npm_compromise_detector_phoenix.py \
--repo-list org_repos.txt \
--light-scan \
--enable-phoenix \
--output "org_security_scan_$(date +%Y%m%d).txt"
# 3. 或使用集成脚本完成完整工作流
./enhanced-quick-check-with-phoenix.sh org_repos.txt \
--repo-list --light-scan --enable-phoenix
```
**CI/CD Pipeline Integration:**
```
# .github/workflows/npm-security-light-scan.yml
name: NPM Security Light Scan
on:
schedule:
- cron: '0 2 * * *' # Daily at 2 AM
workflow_dispatch:
jobs:
security-scan:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Light Scan NPM Security
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
# ⚠️ Replace with your actual Phoenix Security credentials
PHOENIX_CLIENT_ID: ${{ secrets.PHOENIX_CLIENT_ID }}
PHOENIX_CLIENT_SECRET: ${{ secrets.PHOENIX_CLIENT_SECRET }}
PHOENIX_API_URL: ${{ secrets.PHOENIX_API_URL }} # Your Phoenix domain API endpoint
run: |
# Create repo list for organization
echo "${{ github.repository_url }}" > current_repo.txt
# Run light scan with Phoenix integration
python3 enhanced_npm_compromise_detector_phoenix.py \
--repo-list current_repo.txt \
--light-scan \
--enable-phoenix \
--quiet
```
### **📖 附加资源
- 📘 **[QUICK_START.md](QUICK_START.md)** - Comprehensive usage guide with GitHub Actions
- 📄 **[COMMAND_REFERENCE.md](COMMAND_REFERENCE.md)** - Quick command reference card
- ⚡ **[QUICK_CONFIG_GUIDE.md](QUICK_CONFIG_GUIDE.md)** - Enhanced fallback system & configuration
- 🔗 **[PHOENIX_INTEGRATION_GUIDE.md](PHOENIX_INTEGRATION_GUIDE.md)** - Complete Phoenix integration guide
- 🔧 **[PHOENIX_CREDENTIALS_SETUP.md](PHOENIX_CREDENTIALS_SETUP.md)** - Step-by-step credentials configuration
- 💻 **[LOCAL_LAPTOP_USAGE_GUIDE.md](LOCAL_LAPTOP_USAGE_GUIDE.md)** - Local laptop usage with embedded credentials
- 🍦 **[VANILLA_SCRIPT_USAGE_GUIDE.md](VANILLA_SCRIPT_USAGE_GUIDE.md)** - Using without Phoenix integration
- 🎯 **[LOCAL_USAGE_DEMO.md](LOCAL_USAGE_DEMO.md)** - Complete local setup demo
- 🗂️ **[ORGANIZED_FOLDERS_GUIDE.md](ORGANIZED_FOLDERS_GUIDE.md)** - GitHub pulls & results organization
- 🌐 **[PULL_ALL_FEATURE_GUIDE.md](PULL_ALL_FEATURE_GUIDE.md)** - **NEW!** Auto-discover and scan all accessible repositories
- 🎯 **[ZAPIER_CONFIRMED_PACKAGES_UPDATE.md](ZAPIER_CONFIRMED_PACKAGES_UPDATE.md)** - **NEW!** 10 Zapier packages update details
- 📊 **[docs/RECURSIVE_SCANNING_GUIDE.md](docs/RECURSIVE_SCANNING_GUIDE.md)** - Recursive scanning capabilities
- 🔍 **[TEST_VARIATIONS_SUMMARY.md](TEST_VARIATIONS_SUMMARY.md)** - Test variations guide (mobile, backend, frontend)
**Remember**: Time is critical in supply chain attacks. Run these scans immediately and take action if compromised packages are detected.
标签：AMSI绕过, CI/CD安全, Cutter, GitHub自动化, GNU通用公共许可证, Llama, LNA, Node.js, NPM包安全, Phoenix Security, Sha1-Hulud, Shai Hulud, Shell脚本, 企业安全, 包完整性校验, 威胁检测, 安全应急响应, 安全扫描, 时序注入, 网络资产管理, 逆向工具