muad-dib

安装 | 使用方法 | 功能特性 | VS Code | CI/CD

法语版

为什么选择 MUAD'DIB？

npm 和 PyPI 供应链攻击正呈爆发式增长。Shai-Hulud 在 2025 年攻陷了 25K+ 个仓库。现有工具能够检测威胁，但无法帮助你做出响应。

MUAD'DIB 结合了 22 个并行扫描器（277 条检测规则）、反混淆引擎、模块间数据流分析、复合评分（21 条复合规则）以及 gVisor/Docker 沙箱，用于检测 npm 和 PyPI 包中的已知威胁和可疑行为模式。代码库中存在一个 XGBoost 分类器，但目前未启用（参见评估）。

定位

MUAD'DIB 是一款免费、开源、完全可审计的 npm 和 PyPI 供应链扫描器。它能在本地检测已知威胁（225,000+ 个 IOC）、安装时 RCE、先窃取凭据再外泄的流程、混淆载荷以及其他可疑行为模式 — 全程无遥测。

它采用 AGPL-3.0 许可证授权；对于需要将其嵌入专有产品或作为封闭托管服务运行的组织，可提供商业许可证（参见许可证）。

它刻意不试图包罗万象 — 关于它究竟能捕获什么、不能捕获什么，请参见范围。

范围

可检测（npm 和 PyPI）：已知恶意包（名称 + SHA256 IOC 匹配）、拼写仿冒包、安装时 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    # Force install despite threats

在安装之前扫描包是否存在威胁。阻止已知恶意包。

风险评分

每次扫描都会显示一个 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  # Fail only on CRITICAL
muaddib scan . --fail-on high      # Fail on HIGH and CRITICAL (default)

偏执模式

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     # All 4 temporal features
muaddib scan . --temporal          # Sudden lifecycle script detection
muaddib scan . --temporal-ast      # AST diff between versions
muaddib scan . --temporal-publish  # Publish frequency anomaly
muaddib scan . --temporal-maintainer # Maintainer change detection

通过分析包版本之间的变更，在供应链攻击出现在 IOC 数据库中之前就将其检测出来。详见评估方法。

Docker 沙箱

muaddib sandbox <package-name>
muaddib sandbox <package-name> --strict

在隔离的 Docker 容器中进行动态分析：strace、tcpdump、文件系统差异、金丝雀令牌、CI 感知环境，以及用于定时炸弹检测的 monkey-patching 预加载（在 [0h、72h、7d] 偏移处多次运行）。

其他命令

muaddib watch .                    # Real-time monitoring
muaddib daemon                     # Daemon mode (auto-scan npm install)
muaddib update                     # Update IOCs (fast, ~5s)
muaddib scrape                     # Full IOC refresh (~5min)
muaddib diff HEAD~1                # Compare threats with previous commit
muaddib init-hooks                 # Pre-commit hooks (husky/pre-commit/git)
muaddib scan . --breakdown         # Explainable score decomposition
muaddib replay                     # Ground truth validation (90/94 TPR@3, v2.11.48)

功能特性

22 个并行扫描器

277 条检测规则

所有规则（272 条常规规则 + 5 条偏执规则）均映射到 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）

name: Security Scan

on: [push, pull_request]

jobs:
  scan:
    runs-on: ubuntu-latest
    permissions:
      security-events: write
      contents: read
    steps:
      - uses: actions/checkout@v4
      - uses: DNSZLSK/muad-dib@v1
        with:
          path: '.'
          fail-on: 'high'
          sarif: 'results.sarif'

预提交钩子

muaddib init-hooks                        # Auto-detect (husky/pre-commit/git)
muaddib init-hooks --type husky           # Force husky
muaddib init-hooks --mode diff            # Only block NEW threats

配合 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 分类器：未启用。 src/ml/ 中有一个 XGBoost 模型，但从未接入 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 个测试，分布于 152 个模块化测试文件
• 56 个模糊测试 - 畸形输入、ReDoS、Unicode、二进制
• Datadog 17K 基准 - 14,587 个已确认的恶意软件样本（范围内）
• 真值验证 - 96 个真实攻击（95.74% TPR@3、88.30% TPR@20 — v2.11.48 对 94 个范围内样本的完整测量）
• 误报验证（v2.11.48 测量）- 规则 FPR 1.10%（6/545 已扫描）、200 个随机样本 2.50%、124/132 个 PyPI 样本 9.68%（Track-D 下载修复后的首次诚实测量）。ML 分类器当前未启用 — 参见评估指标 → ML 分类器。

社区

• Discord：https://discord.gg/y8zxSmue

文档

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

许可证

MUAD'DIB 采用 GNU Affero 通用公共许可证 v3.0 only（AGPL-3.0-only）授权 — 参见 LICENSE 和 NOTICE。

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

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

版权所有（C）2026 DNSZLSK。

香料必须流动。蠕虫必须灭亡。