实时 npm/PyPI 供应链威胁检测。行为链分析、AST 扫描、IOC 情报源和复合评分引擎。
<p align="center">
<img src="https://assets.kitploit.com/production/public/readmes/10373/84132538a800a2879cff088259fe9e98e975a3fe37f8462fe731d6a06f82314a.png" alt="MUAD'DIB Logo" width="700">
</p>
<p align="center">
<a href="https://www.npmjs.com/package/muaddib-scanner"><img src="https://img.shields.io/npm/v/muaddib-scanner" alt="npm version"></a>
<a href="https://github.com/DNSZLSK/muad-dib/actions/workflows/scan.yml"><img src="https://github.com/DNSZLSK/muad-dib/actions/workflows/scan.yml/badge.svg" alt="CI"></a>
<a href="https://codecov.io/gh/DNSZLSK/muad-dib"><img src="https://codecov.io/gh/DNSZLSK/muad-dib/branch/master/graph/badge.svg" alt="Coverage"></a>
<a href="https://scorecard.dev/viewer/?uri=github.com/DNSZLSK/muad-dib"><img src="https://api.scorecard.dev/projects/github.com/DNSZLSK/muad-dib/badge" alt="OpenSSF Scorecard"></a>
<img src="https://img.shields.io/badge/license-AGPL--3.0--only-blue" alt="License">
<img src="https://img.shields.io/badge/node-%3E=18-brightgreen" alt="Node">
<img src="https://img.shields.io/badge/IOCs-225,000+-red" alt="IOCs">
</p>
<p align="center">
<a href="#installation">安装</a> |
<a href="#usage">用法</a> |
<a href="#features">功能</a> |
<a href="#vs-code">VS Code</a> |
<a href="#cicd">CI/CD</a>
</p>
<p align="center">
<a href="https://github.com/dnszlsk/muad-dib/blob/master/docs/README.fr.md">Version francaise</a>
</p>
---
## 为什么选择 MUAD'DIB？
npm 和 PyPI 供应链攻击正在爆发式增长。Shai-Hulud 在 2025 年入侵了 25K+ 个仓库。现有工具能够检测威胁，但无法帮助你进行响应。
MUAD'DIB 结合了 **<!--stat:scanners-->22<!--/stat:scanners--> 个并行扫描器**（<!--stat:rulesTotal-->278<!--/stat:rulesTotal--> 条检测规则）、**反混淆引擎**、**模块间数据流分析**、**复合评分**（<!--stat:compound-->21<!--/stat:compound--> 条复合规则）以及 gVisor/Docker 沙箱，用于检测 npm 和 PyPI 包中的已知威胁和可疑行为模式。代码库中存在一个 XGBoost 分类器，但**当前处于非激活状态**（参见[评估](#evaluation)）。
---
## 定位
MUAD'DIB 是一款免费、开源且完全可审计的 npm 和 PyPI 供应链扫描器。它能够在本地检测**已知**威胁（225,000+ 个 IOC）、安装时 RCE、凭据窃取后外传流程、混淆载荷以及其他可疑行为模式——无需任何遥测。
它采用 **AGPL-3.0** 许可证；对于需要将其嵌入专有产品或作为封闭托管服务运行的组织，可提供**商业许可证**（参见[许可证](#license)）。
它刻意不试图包揽一切——有关它具体检测什么和不检测什么的详细信息，请参见[范围](#scope)。
---
## 范围
**检测**（npm 和 PyPI）：已知恶意包（名称 + SHA256 IOC 匹配）、域名仿冒（typosquatting）、安装时 RCE（生命周期 `preinstall`/`postinstall`、`curl | sh`、Python 导入时、`binding.gyp`）、凭据读取后网络外传（文件内和跨文件）、混淆/高熵/存根加载器载荷、二进制投放器（`chmod +x` + exec/spawn）以及反分析规避标记。
**不在范围内**：仅浏览器攻击（DOM/`window`，无 Node.js API）、原生二进制/WASM 的*内容*（无二进制分析）、零日未知包（IOC 源是被动响应的）以及非 npm/PyPI 生态系统（RubyGems、Maven、Go）。坚决的反沙箱指纹识别和多阶段远程载荷是已知的漏报风险。完整详情：[威胁模型](https://github.com/dnszlsk/muad-dib/blob/master/docs/threat-model.md)。
**无遥测。** 你的代码和扫描结果永远不会离开你的机器——MUAD'DIB 仅*下载*威胁情报源（`muaddib update`），并且为了评分，会读取公共 npm 注册表元数据。Webhook 警报为可选启用。
---
## 安装
### npm（推荐）
```bash
npm install -g muaddib-scanner
```
### 从源码安装
```bash
git clone https://github.com/DNSZLSK/muad-dib
cd muad-dib
npm install
npm link
```
---
## 用法
### 基本扫描
```bash
muaddib scan .
muaddib scan /path/to/project
```
扫描 npm（package.json、node_modules）和 Python（requirements.txt、setup.py、pyproject.toml）依赖。
### 交互模式
```bash
muaddib
```
### 安全安装
```bash
muaddib install <package>
muaddib install lodash axios --save-dev
muaddib install suspicious-pkg --force # 尽管存在威胁仍强制安装
```
在安装**之前**扫描包的威胁。阻止已知恶意包。
### 风险评分
每次扫描都会显示 0-100 的风险评分：
```
[SCORE] 58/100 [***********---------] HIGH
```
### 解释模式
```bash
muaddib scan . --explain
```
显示每次检测的规则 ID、MITRE ATT&CK 技术、参考链接和响应手册。
### 导出
```bash
muaddib scan . --json > results.json # JSON
muaddib scan . --html report.html # HTML
muaddib scan . --sarif results.sarif # SARIF（GitHub Security）
```
### 严重性阈值
```bash
muaddib scan . --fail-on critical # 仅在 CRITICAL 时失败
muaddib scan . --fail-on high # 在 HIGH 和 CRITICAL 时失败（默认）
```
### 偏执模式
```bash
muaddib scan . --paranoid
```
超严格检测，容错率更低。检测任何网络访问、子进程执行、动态代码评估和敏感文件访问。
### Webhook 警报
```bash
muaddib scan . --webhook "https://discord.com/api/webhooks/..."
```
严格过滤（v2.1.2）：仅对 IOC 匹配、沙箱确认的威胁或蜜罐令牌外传发出警报。优先级分类（v2.10.21）：P1（红色，IOC/沙箱/蜜罐）、P2（橙色，高评分/复合）、P3（黄色，其余）。
### 行为异常检测（v2.0）
```bash
muaddib scan . --temporal-full # 全部 4 个时间特征
muaddib scan . --temporal # 突发生命周期脚本检测
muaddib scan . --temporal-ast # 版本间 AST 差异
muaddib scan . --temporal-publish # 发布频率异常
muaddib scan . --temporal-maintainer # 维护者变更检测
```
通过分析包版本之间的变化，在威胁**出现**在 IOC 数据库**之前**检测供应链攻击。详情参见[评估方法论](https://github.com/dnszlsk/muad-dib/blob/master/docs/EVALUATION_METHODOLOGY.md)。
### Docker 沙箱
```bash
muaddib sandbox <package-name>
muaddib sandbox <package-name> --strict
```
在隔离的 Docker 容器中进行动态分析：strace、tcpdump、文件系统差异、蜜罐令牌、CI 感知环境，以及用于时间炸弹检测的猴子补丁预加载（在 [0h、72h、7d] 偏移处多次运行）。
### 其他命令
```bash
muaddib watch . # 实时监控
muaddib daemon # 守护进程模式（自动扫描 npm install）
muaddib update # 更新 IOC（快速，约 5 秒）
muaddib scrape # 完整 IOC 刷新（约 5 分钟）
muaddib diff HEAD~1 # 与上一个提交的威胁比较
muaddib init-hooks # 预提交钩子（husky/pre-commit/git）
muaddib scan . --breakdown # 可解释的评分分解
muaddib replay # 真实数据验证（90/94 TPR@3，v2.11.48）
```
---
## 功能
### <!--stat:scanners-->22<!--/stat:scanners--> 个并行扫描器
| 扫描器 | 检测 |
|---------|-----------|
| AST 解析（acorn） | eval、Function、凭据窃取、二进制投放器、原型钩子 |
| 模式匹配 | Shell 命令、反向 shell、死手开关 |
| 数据流分析 | 凭据读取 + 网络发送（文件内和跨文件） |
| 混淆检测 | JS 混淆模式（跳过 .min.js） |
| 反混淆预处理 | 字符串拼接、charcode、base64、十六进制数组、常量传播 |
| 模块间数据流 | 跨文件污点传播（3 跳链、类方法） |
| 意图一致性 | 文件内源-汇配对（凭据 + eval/网络） |
| 域名仿冒 | npm + PyPI（Levenshtein 距离） |
| Python 扫描器 | requirements.txt、setup.py、pyproject.toml、14K+ PyPI IOC |
| Shannon 熵 | 高熵字符串（5.5 位 + 最少 50 字符） |
| AI 配置扫描器 | .cursorrules、CLAUDE.md、copilot-instructions.md 注入 |
| 包/依赖 | 生命周期脚本、IOC 匹配（225K+ 包） |
| GitHub Actions | Shai-Hulud 后门检测 |
| 哈希扫描器 | 已知恶意文件哈希 |
| IOC 字符串（intel-triage P1.1） | YARA 风格字符串匹配（Axios 2026、TeamPCP、GlassWorm、CanisterSprawl） |
| 反取证 AST（intel-triage P1.2） | XOR 循环 + 自删除 + 诱饵写入复合（csec autodelete） |
| 存根包（intel-triage P1.3） | 微型主文件 + 外部依赖 URL + 生命周期钩子（ltidi 链） |
| Monorepo 扫描器 | Lerna/pnpm-workspace/turbo 检测（Sprint 1 审计 MR-C2 修复） |
| 可信依赖差异（可选） | 与注册表中的可信依赖 tarball 进行差异比较（v2.10.x） |
| Python 源码（PYSRC） | `__init__.py` / `setup.py` 中的导入时/安装时 RCE 模式（v2.11.41——弥补 TrapDoor PyPI 缺口） |
| Python AST（PYAST） | 带污点感知检测器的 Tree-sitter-Python AST（v2.11.42+） |
| 反扫描器注入（ASI） | 注释/字符串中的提示注入文本，诱导 LLM 代码审查者给出干净结论或跳过混淆载荷（ASI-001..004，Hades 活动 2026-06） |
### <!--stat:rulesTotal-->278<!--/stat:rulesTotal--> 条检测规则
所有规则（<!--stat:rulesCore-->273<!--/stat:rulesCore--> 条 RULES + <!--stat:rulesParanoid-->5<!--/stat:rulesParanoid--> 条 PARANOID）都映射到 MITRE ATT&CK 技术。完整的规则参考请参见 [SECURITY.md](https://github.com/dnszlsk/muad-dib/blob/master/SECURITY.md#detection-rules)。
### 已检测的活动
| 活动 | 状态 |
|----------|--------|
| GlassWorm（2026，433+ 个包） | 已检测 |
| Shai-Hulud v1/v2/v3（2025） | 已检测 |
| event-stream（2018） | 已检测 |
| eslint-scope（2018） | 已检测 |
| 抗议软件（node-ipc、colors、faker） | 已检测 |
| 域名仿冒（crossenv、mongose、babelcli） | 已检测 |
---
## VS Code
VS Code 扩展会自动扫描你的 npm 项目。
```bash
code --install-extension dnszlsk.muaddib-vscode
```
- `MUAD'DIB: Scan Project` - 扫描整个项目
- `MUAD'DIB: Scan Current File` - 扫描当前文件
- 设置：`muaddib.autoScan`、`muaddib.webhookUrl`、`muaddib.failLevel`
完整文档请参见 [vscode-extension/README.md](https://github.com/dnszlsk/muad-dib/blob/master/vscode-extension/README.md)。
---
## CI/CD
### GitHub Actions（Marketplace）
最小配置（在 HIGH+ 威胁时使构建失败，单次扫描）：
```yaml
name: Security Scan
on: [push, pull_request]
jobs:
scan:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: DNSZLSK/[email protected] # 固定到已发布的标签
with:
fail-on: 'high'
```
将 SARIF 上传到 **Security** 标签页（需要 `security-events: write`；运行第二次扫描以生成 SARIF）：
```yaml
jobs:
scan:
runs-on: ubuntu-latest
permissions:
contents: read
security-events: write
steps:
- uses: actions/checkout@v4
- uses: DNSZLSK/[email protected]
with:
path: '.'
fail-on: 'high'
sarif: 'results.sarif'
```
**输入**
| 输入 | 描述 | 默认值 |
|-------|-------------|---------|
| `path` | 要扫描的路径 | `.` |
| `fail-on` | 失败的最低严重性（`critical`/`high`/`medium`/`low`/`none`） | `high` |
| `sarif` | SARIF 输出文件路径——设置后也会上传到 Security 标签页 | |
| `paranoid` | 超严格检测（更高的误报率） | `false` |
| `version` | 要安装的 `muaddib-scanner` npm 版本 | `latest` |
**输出**（可在后续步骤中通过 `steps.<id>.outputs.*` 使用）
| 输出 | 描述 |
|--------|-------------|
| `risk-score` | 风险评分 0–100 |
| `risk-level` | `SAFE` / `LOW` / `MEDIUM` / `HIGH` / `CRITICAL` |
| `threats-count` | 检测到的威胁总数 |
| `critical-count` / `high-count` | 按严重性分类的威胁 |
| `exit-code` | `0` = 通过 `fail-on` 门槛，否则非零 |
| `sarif-file` | SARIF 文件的路径（如果未设置 `sarif` 则为空） |
### 预提交钩子
```bash
muaddib init-hooks # 自动检测（husky/pre-commit/git）
muaddib init-hooks --type husky # 强制使用 husky
muaddib init-hooks --mode diff # 仅阻止新增威胁
```
使用 pre-commit 框架：
```yaml
repos:
- repo: https://github.com/DNSZLSK/muad-dib
rev: v2.11.139
hooks:
- id: muaddib-scan
```
---
## 评估
上次测量 **v2.11.48**（2026-05-26），**仅规则**（ML 分类器处于非激活状态——见下文）。真实数据：94 个范围内的真实世界攻击 + 200 个随机 npm + 124 个 PyPI + 107 个对抗性/保留集。
| 指标 | 结果 |
|--------|--------|
| 检测率（TPR@3） | **95.74%**（90/94） |
| 警报率（TPR@20） | **88.30%**（83/94） |
| FPR — 精选 npm（548） | **1.10%**（6/545） |
| FPR — 随机 npm（200） | **2.50%**（5/200） |
| FPR — PyPI（132） | **9.68%**（12/124） |
| ADR — 对抗性 + 保留集 | **96.26%**（103/107） |
| 野外 TPR（Datadog 17K） | **92.8%**（13,538/14,587） |
**ML 分类器：非激活。** 一个 XGBoost 模型位于 `src/ml/` 中，但从未接入 `muaddib scan`，并且自 2026-04-08 起在监控器中仅以 LOG-ONLY 模式运行（训练模型已崩溃，等待重新训练）。以上所有数字均为仅规则结果。
完整协议、各轨道历史、PyPI cap-35 注意事项、运营（GHSA 计）覆盖率以及 ML 重训练方法论：[评估方法论](https://github.com/dnszlsk/muad-dib/blob/master/docs/EVALUATION_METHODOLOGY.md)。
---
## 贡献
### 添加 IOC
编辑 `iocs/` 中的 YAML 文件：
```yaml
- id: NEW-MALWARE-001
name: "malicious-package"
version: "*"
severity: critical
confidence: high
source: community
description: "Threat description"
references:
- https://example.com/article
mitre: T1195.002
```
### 开发
```bash
git clone https://github.com/DNSZLSK/muad-dib
cd muad-dib
npm install
npm test
```
### 测试
- **<!--stat:tests-->4545<!--/stat:tests--> 个测试**，分布在 <!--stat:testFiles-->155<!--/stat:testFiles--> 个模块化测试文件中
- **56 个模糊测试** - 畸形输入、ReDoS、Unicode、二进制
- **Datadog 17K 基准测试** - 14,587 个已确认的恶意软件样本（范围内）
- **真实数据验证** - 96 个真实世界攻击（95.74% TPR@3，88.30% TPR@20——v2.11.48 对 94 个范围内样本的完整测量）
- **误报验证**（v2.11.48 测量）- 1.10% 规则 FPR（6/545 扫描），200 个随机样本上 2.50%，124/132 PyPI 上 9.68%（Track-D 下载修复后的首次诚实测量）。ML 分类器当前处于非激活状态——参见评估指标 → ML 分类器。
---
## 社区
- Discord：https://discord.gg/y8zxSmue
---
## 文档
- [博客](https://dnszlsk.github.io/muad-dib/blog/) - 关于供应链威胁检测的技术文章
- [Carnet de bord](https://github.com/dnszlsk/muad-dib/blob/master/docs/CARNET_DE_BORD_MUADDIB.md) - 开发日志（法语）
- [文档索引](https://github.com/dnszlsk/muad-dib/blob/master/docs/INDEX.md) - 所有文档集中在一处
- [评估方法论](https://github.com/dnszlsk/muad-dib/blob/master/docs/EVALUATION_METHODOLOGY.md) - 实验协议、保留集评分
- [威胁模型](https://github.com/dnszlsk/muad-dib/blob/master/docs/threat-model.md) - MUAD'DIB 检测什么和不检测什么
- [安全策略](https://github.com/dnszlsk/muad-dib/blob/master/SECURITY.md) - 检测规则参考（<!--stat:rulesTotal-->278<!--/stat:rulesTotal--> 条规则）
- [安全审计](https://github.com/dnszlsk/muad-dib/blob/master/docs/SECURITY_AUDIT.md) - 绕过验证报告
- [误报分析](https://github.com/dnszlsk/muad-dib/blob/master/docs/EVALUATION.md) - 历史误报分析
---
## 许可证
MUAD'DIB 采用 **GNU Affero General Public License v3.0 only**（`AGPL-3.0-only`）许可证——参见 [LICENSE](https://github.com/dnszlsk/muad-dib/blob/master/LICENSE) 和 [NOTICE](https://github.com/dnszlsk/muad-dib/blob/master/NOTICE)。
你可以自由使用、研究、修改和重新分发它——包括通过网络——前提是衍生作品和网络部署的修改在相同许可证下发布。
**商业许可：** 要将 MUAD'DIB 嵌入专有/闭源产品，或作为托管服务提供而无需承担 AGPL 的源代码披露义务，可提供单独的商业许可证。请提交 issue 或联系作者（[DNSZLSK](https://github.com/DNSZLSK)）。
版权所有（C）2026 DNSZLSK。
---
<p align="center">
<strong>香料必须流动。沙虫必须消灭。</strong>
</p>