muad-dib

安装 | 用法 | 功能 | VS Code | CI/CD

Version francaise

为什么选择 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 个并行扫描器

278 条检测规则

所有规则（273 条 RULES + 5 条 PARANOID）都映射到 MITRE ATT&CK 技术。完整的规则参考请参见 SECURITY.md。

已检测的活动

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'

输入

输出（可在后续步骤中通过 steps.<id>.outputs.* 使用）

预提交钩子

muaddib init-hooks                        # 自动检测（husky/pre-commit/git）
muaddib init-hooks --type husky           # 强制使用 husky
muaddib init-hooks --mode diff            # 仅阻止新增威胁

使用 pre-commit 框架：

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 个对抗性/保留集。

ML 分类器：非激活。 一个 XGBoost 模型位于 src/ml/ 中，但从未接入 muaddib scan，并且自 2026-04-08 起在监控器中仅以 LOG-ONLY 模式运行（训练模型已崩溃，等待重新训练）。以上所有数字均为仅规则结果。

完整协议、各轨道历史、PyPI cap-35 注意事项、运营（GHSA 计）覆盖率以及 ML 重训练方法论：评估方法论。

贡献

添加 IOC

编辑 iocs/ 中的 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

开发

git clone https://github.com/DNSZLSK/muad-dib
cd muad-dib
npm install
npm test

测试

• 4545 个测试，分布在 155 个模块化测试文件中
• 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

文档

• 博客 - 关于供应链威胁检测的技术文章
• Carnet de bord - 开发日志（法语）
• 文档索引 - 所有文档集中在一处
• 评估方法论 - 实验协议、保留集评分
• 威胁模型 - MUAD'DIB 检测什么和不检测什么
• 安全策略 - 检测规则参考（278 条规则）
• 安全审计 - 绕过验证报告
• 误报分析 - 历史误报分析

许可证

MUAD'DIB 采用 GNU Affero General Public License v3.0 only（AGPL-3.0-only）许可证——参见 LICENSE 和 NOTICE。

你可以自由使用、研究、修改和重新分发它——包括通过网络——前提是衍生作品和网络部署的修改在相同许可证下发布。

商业许可： 要将 MUAD'DIB 嵌入专有/闭源产品，或作为托管服务提供而无需承担 AGPL 的源代码披露义务，可提供单独的商业许可证。请提交 issue 或联系作者（DNSZLSK）。

版权所有（C）2026 DNSZLSK。

香料必须流动。沙虫必须消灭。