muad-dib v2.11.179
实时 npm/PyPI 供应链威胁检测。行为链分析、AST 扫描、IOC 情报源和复合评分引擎。
安装 | 用法 | 功能 | VS Code | CI/CD
为什么选择 MUAD'DIB？
npm 和 PyPI 供应链攻击正在爆发式增长。Shai-Hulud 在 2025 年入侵了 25K+ 个仓库。现有工具能够检测威胁，但无法帮助你进行响应。
MUAD'DIB 结合了 22 个并行扫描器（278 条检测规则）、反混淆引擎、模块间数据流分析、复合评分（21 条复合规则）以及 gVisor/Docker 沙箱，用于检测 npm 和 PyPI 包中的已知威胁和可疑行为模式。代码库中存在一个 XGBoost 分类器，但当前处于非激活状态（参见评估）。
定位
MUAD'DIB 是一款免费、开源且完全可审计的 npm 和 PyPI 供应链扫描器。它能够在本地检测已知威胁（225,000+ 个 IOC）、安装时 RCE、凭据窃取后外传流程、混淆载荷以及其他可疑行为模式——无需任何遥测。
它采用 AGPL-3.0 许可证；对于需要将其嵌入专有产品或作为封闭托管服务运行的组织，可提供商业许可证（参见许可证）。
它刻意不试图包揽一切——有关它具体检测什么和不检测什么的详细信息，请参见范围。
范围
检测（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）。坚决的反沙箱指纹识别和多阶段远程载荷是已知的漏报风险。完整详情：威胁模型。
无遥测。 你的代码和扫描结果永远不会离开你的机器——MUAD'DIB 仅下载威胁情报源（muaddib update），并且为了评分，会读取公共 npm 注册表元数据。Webhook 警报为可选启用。
安装
npm（推荐）
npm install -g muaddib-scanner
从源码安装
git clone https://github.com/DNSZLSK/muad-dib
cd muad-dib
npm install
npm link
用法
基本扫描
muaddib scan .
muaddib scan /path/to/project
扫描 npm（package.json、node_modules）和 Python（requirements.txt、setup.py、pyproject.toml）依赖。
交互模式
muaddib
安全安装
muaddib install <package>
muaddib install lodash axios --save-dev
muaddib install suspicious-pkg --force # 尽管存在威胁仍强制安装
在安装之前扫描包的威胁。阻止已知恶意包。
风险评分
每次扫描都会显示 0-100 的风险评分：
[SCORE] 58/100 [***********---------] HIGH
解释模式
muaddib scan . --explain
显示每次检测的规则 ID、MITRE ATT&CK 技术、参考链接和响应手册。
导出
muaddib scan . --json > results.json # JSON
muaddib scan . --html report.html # HTML
muaddib scan . --sarif results.sarif # SARIF（GitHub Security）
严重性阈值
muaddib scan . --fail-on critical # 仅在 CRITICAL 时失败
muaddib scan . --fail-on high # 在 HIGH 和 CRITICAL 时失败（默认）
偏执模式
muaddib scan . --paranoid
超严格检测，容错率更低。检测任何网络访问、子进程执行、动态代码评估和敏感文件访问。
Webhook 警报
muaddib scan . --webhook "https://discord.com/api/webhooks/..."
严格过滤（v2.1.2）：仅对 IOC 匹配、沙箱确认的威胁或蜜罐令牌外传发出警报。优先级分类（v2.10.21）：P1（红色，IOC/沙箱/蜜罐）、P2（橙色，高评分/复合）、P3（黄色，其余）。
行为异常检测（v2.0）
muaddib scan . --temporal-full # 全部 4 个时间特征
muaddib scan . --temporal # 突发生命周期脚本检测
muaddib scan . --temporal-ast # 版本间 AST 差异
muaddib scan . --temporal-publish # 发布频率异常
muaddib scan . --temporal-maintainer # 维护者变更检测
通过分析包版本之间的变化，在威胁出现在 IOC 数据库之前检测供应链攻击。详情参见评估方法论。
Docker 沙箱
muaddib sandbox <package-name>
muaddib sandbox <package-name> --strict
在隔离的 Docker 容器中进行动态分析：strace、tcpdump、文件系统差异、蜜罐令牌、CI 感知环境，以及用于时间炸弹检测的猴子补丁预加载（在 [0h、72h、7d] 偏移处多次运行）。
其他命令
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）
功能
22 个并行扫描器
| 扫描器 | 检测 |
|---|---|
| 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） |
278 条检测规则
所有规则（273 条 RULES + 5 条 PARANOID）都映射到 MITRE ATT&CK 技术。完整的规则参考请参见 SECURITY.md。
已检测的活动
| 活动 | 状态 |
|---|---|
| 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 项目。
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。
CI/CD
GitHub Actions（Marketplace）
最小配置（在 HIGH+ 威胁时使构建失败，单次扫描）：
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）：
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'
输入