DNSZLSK/muad-dib
GitHub: DNSZLSK/muad-dib
专注于npm和PyPI生态的供应链安全扫描工具，结合静态分析、动态沙箱和行为异常检测来识别恶意包。
Stars: 7 | Forks: 0
安装 |
使用 |
功能 |
VS Code |
CI/CD
法语版本
## 为什么选择 MUAD'DIB？
npm 和 PyPI 供应链攻击呈爆发式增长。Shai-Hulud 在 2025 年入侵了超过 2.5 万个代码库。现有工具可以检测威胁，但无法帮助你进行响应。
MUAD'DIB 结合了静态分析 + **反混淆引擎** (v2.2.5) + **模块间数据流** (v2.2.6) + **单文件最大评分** (v2.2.11) + 动态分析（具有 **monkey-patching preload** 的 Docker 沙箱，用于检测定时炸弹，v2.4.9）+ **行为异常检测** (v2.0) + **真值验证** (v2.1) + **安全审计**（修复了 41 个问题，v2.5.0–v2.5.6），不仅能检测威胁，还能指导你的响应 —— 甚至在它们出现在任何 IOC 数据库之前。
## 定位
MUAD'DIB 是一个教育工具和免费的第一道防线。它检测**已知**的 npm 和 PyPI 威胁（225,000+ IOC）以及基本的可疑模式。
**如需企业级保护**，请使用：
- [Socket.dev](https://socket.dev) - ML 行为分析，云端沙箱
- [Snyk](https://snyk.io) - 海量漏洞数据库，CI/CD 集成
- [Opengrep](https://opengrep.dev) - 高级数据流分析，Semgrep 规则
MUAD'DIB 不能替代这些工具。对于那些希望在安装未知包之前进行快速、免费检查的开发者，它是这些工具的补充。
## 安装
### 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
muaddib install lodash axios --save-dev
muaddib i express -g
muaddib install suspicious-pkg --force # Force install despite threats
```
在安装前扫描包中的威胁。拦截已知的恶意包。
### 风险评分
每次扫描显示 0-100 的风险评分：
```
[SCORE] 58/100 [***********---------] HIGH
```
### 解释模式（完整详情）
```
muaddib scan . --explain
```
显示每次检测的：
- 规则 ID
- MITRE ATT&CK 技术
- 参考资料（文章、CVE）
- 响应剧本
### 导出
```
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 . --fail-on medium # Fail on MEDIUM, HIGH, CRITICAL
```
### 偏执模式
```
muaddib scan . --paranoid
```
超严格的检测，容忍度更低。适用于关键项目。检测任何网络访问、子进程执行、动态代码评估和敏感文件访问。
### Discord/Slack Webhook
```
muaddib scan . --webhook "https://discord.com/api/webhooks/..."
```
向 Discord 或 Slack 发送包含评分和威胁的警报。严格过滤 (v2.1.2)：仅在 IOC 匹配、沙箱确认的威胁或金丝雀令牌（canary token）泄露时发送警报 —— 减少仅基于启发式检测的噪音。
### 实时监控
```
muaddib watch .
```
### 守护进程模式
```
muaddib daemon
muaddib daemon --webhook "https://discord.com/api/webhooks/..."
```
自动监控所有 `npm install` 命令并扫描新包。
### 更新 IOC（快速，约 5 秒）
```
muaddib update
```
加载包中内置的 225,000+ 个 IOC，合并 YAML IOC 和额外的 GitHub 源（GenSecAI, DataDog）。在 `npm install` 后运行此命令可立即刷新 IOC。
### 抓取 IOC（完整，约 5 分钟）
```
muaddib scrape
```
从所有主要来源进行完整刷新。下载 npm 和 PyPI 的 OSV 批量转储（约 100-200MB）、OSSF 和所有其他来源。当你想要绝对最新的数据时运行此命令。
来源：
- **OSV.dev npm dump** - 所有 MAL-* 条目的批量下载
- **OSV.dev PyPI dump** - 所有 PyPI MAL-* 条目的批量下载
- **GenSecAI Shai-Hulud 2.0 Detector** - 700+ 个 Shai-Hulud 包的整合列表
- **DataDog Security Labs** - 来自多个供应商的整合 IOC
- **OSSF Malicious Packages** - OpenSSF 数据库（通过 OSV.dev 获取 8000+ 份报告）
- **GitHub Advisory Database** - 标记为恶意软件的公告
- **Snyk Known Malware** - 历史恶意软件包
- **Static IOCs** - Socket.dev, Phylum, npm-removed 包
### Docker 沙箱
```
muaddib sandbox
muaddib sandbox --strict
```
动态分析：在隔离的 Docker 容器中安装包，并通过 strace、tcpdump 和文件系统差异监控运行时行为。
多层监控：
- **系统追踪** (strace)：文件访问、进程生成、系统调用监控
- **网络捕获** (tcpdump)：DNS 解析（包含解析的 IP）、HTTP 请求（方法、主机、路径、正文）、TLS SNI 检测
- **文件系统差异**：安装前/后快照，检测在可疑位置创建的文件
- **数据泄露检测**：16 种敏感模式（令牌、凭据、SSH 密钥、私钥、.env）
- **CI 感知环境** (v2.1.2)：模拟 CI 环境（GITHUB_ACTIONS, GITLAB_CI, TRAVIS, CIRCLECI, JENKINS）以触发原本会处于休眠状态的 CI 感知恶意软件
- **增强型金丝雀令牌** (v2.1.2)：6 个作为环境变量注入的蜜罐凭据（GITHUB_TOKEN, NPM_TOKEN, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, SLACK_WEBHOOK_URL, DISCORD_WEBHOOK_URL）。如果通过网络、DNS 或文件系统泄露，则触发 CRITICAL 警报并增加 50 分
- **Monkey-patching preload** (v2.4.9)：通过 `NODE_OPTIONS=--require /opt/preload.js` 进行运行时插桩。修补时间 API（Date.now, setTimeout→0, setInterval→immediate），拦截网络/文件系统/进程/环境调用。在 [0h, 72h, 7d] 偏移量下多轮运行，以检测定时炸弹恶意软件（MITRE T1497.003）
- **评分引擎**：基于行为严重程度的 0-100 风险评分
使用 `--strict` 通过 iptables 阻止所有非必要的出站网络流量。
需要安装 Docker Desktop。
```
muaddib sandbox lodash # Safe package
muaddib sandbox suspicious-pkg # Analyze unknown package
```
### 沙箱网络报告
```
muaddib sandbox-report
muaddib sandbox-report --strict
```
与 `sandbox` 相同，但显示详细的网络报告：DNS 解析、HTTP 请求、TLS 连接、被阻止的连接（严格模式）和数据泄露警报。
### Diff（版本对比）
```
muaddib diff [ [path]
```
比较当前版本与先前 commit/tag 之间的威胁。仅显示自参考点以来引入的**新**威胁。
```
muaddib diff HEAD~1 # Compare with previous commit
muaddib diff v1.2.0 # Compare with tag
muaddib diff main # Compare with branch
muaddib diff abc1234 # Compare with specific commit
```
示例输出：
```
[MUADDIB DIFF] Comparing abc1234 -> def5678
Risk Score: 25 -> 45 (+20 worse)
Threats: 3 -> 5
NEW threats: 2
REMOVED threats: 0
Unchanged: 3
NEW THREATS (introduced since v1.2.0)
------------------------------------
1. [HIGH] suspicious_dependency
Known malicious package detected
File: package.json
```
在 CI 中使用，以便仅在出现**新**威胁时失败，而不是因为现有的技术债务：
```
- run: muaddib diff ${{ github.event.pull_request.base.sha }} --fail-on high
```
### Pre-commit 钩子
```
muaddib init-hooks [options]
```
在每次提交前自动扫描。支持多种钩子系统：
```
muaddib init-hooks # Auto-detect (husky/pre-commit/git)
muaddib init-hooks --type husky # Force husky
muaddib init-hooks --type pre-commit # Force pre-commit framework
muaddib init-hooks --type git # Force native git hooks
muaddib init-hooks --mode diff # Only block NEW threats
```
#### 使用 pre-commit 框架
添加到 `.pre-commit-config.yaml`：
```
repos:
- repo: https://github.com/DNSZLSK/muad-dib
rev: v2.5.8
hooks:
- id: muaddib-scan # Scan all threats
# - id: muaddib-diff # Or: only new threats
# - id: muaddib-paranoid # Or: ultra-strict mode
```
#### 使用 husky
```
npx husky add .husky/pre-commit "npx muaddib scan . --fail-on high"
# 或者用于 diff 模式：
npx husky add .husky/pre-commit "npx muaddib diff HEAD --fail-on high"
```
#### 移除钩子
```
muaddib remove-hooks [path]
```
移除所有 MUAD'DIB 钩子（husky 和 git 原生）。
#### 原生 git 钩子
```
muaddib init-hooks --type git
# 创建 .git/hooks/pre-commit
```
### 零日监控
MUAD'DIB 实时持续监控 npm 和 PyPI 注册表中的新包，使用 Docker 沙箱分析和 Webhook 警报自动扫描每一个新包。这在我们的基础设施内部运行 —— 检测到的威胁会输入到 IOC 数据库和威胁源 API 中。
### 评分细分
```
muaddib scan . --breakdown
```
显示可解释的评分细分：每项发现如何影响最终风险评分，包含单规则权重和严重性乘数。
### 真值回放
```
muaddib replay
muaddib ground-truth
```
针对扫描器回放真实世界的供应链攻击，以验证检测覆盖率。当前结果：**45/49 已检测 (91.8% TPR)**，来自 51 个样本（49 个活跃）。
4 个超出范围的漏检：lottie-player, polyfill-io, trojanized-jquery（仅浏览器 DOM 攻击），websocket-rat（误报风险高的模式）。
### 版本检查
MUAD'DIB 在启动时自动检查新版本，并在有更新可用时通知你。
## 功能
### Python / PyPI 支持
MUAD'DIB 自动检测并扫描 Python 项目：
- **requirements.txt** - 所有格式，包括 `-r` 递归包含、extras、环境标记
- **setup.py** - 提取 `install_requires` 和 `setup_requires`
- **pyproject.toml** - PEP 621 依赖和 Poetry 依赖
Python 包会根据 14,000+ 个已知恶意 PyPI 包（来自 OSV.dev）进行检查，并使用 PEP 503 名称规范化针对流行的 PyPI 包（requests, numpy, flask, django, pandas 等）进行拼写欺诈（typosquatting）测试。
```
[PYTHON] Detected Python project (3 dependency files)
requirements.txt: 12 packages
setup.py: 3 packages
pyproject.toml: 8 packages
[CRITICAL] PyPI IOC match: malicious-pkg (all versions)
[HIGH] PyPI typosquat: "reqeusts" looks like "requests"
```
### 拼写欺诈检测
MUAD'DIB 检测名称与流行包相似的包（npm 和 PyPI）：
```
[HIGH] Package "lodahs" looks like "lodash" (swapped_chars). Possible typosquatting.
```
### 数据流分析
检测代码何时读取凭据并通过网络发送它们：
```
[CRITICAL] Suspicious flow: credential read (readFileSync, GITHUB_TOKEN) + network send (fetch)
```
### GitHub Actions 扫描
检测 `.github/workflows/` YAML 文件中的恶意模式，包括 Shai-Hulud 2.0 后门指标。
### 检测到的攻击
| 攻击活动 | 包名 | 状态 |
|----------|----------|--------|
| Shai-Hulud v1 (2025 年 9 月) | @ctrl/tinycolor, ng2-file-upload | 已检测 |
| Shai-Hulud v2 (2025 年 11 月) | @asyncapi/specs, posthog-node, kill-port | 已检测 |
| Shai-Hulud v3 (2025 年 12 月) | @vietmoney/react-big-calendar | 已检测 |
| event-stream (2018) | flatmap-stream, event-stream | 已检测 |
| eslint-scope (2018) | eslint-scope | 已检测 |
| Protestware | node-ipc, colors, faker | 已检测 |
| Typosquats | crossenv, mongose, babelcli | 已检测 |
### 检测到的技术
| 技术 | MITRE | 检测方式 |
|-----------|-------|-----------|
| 凭据窃取 (.npmrc, .ssh) | T1552.001 | AST |
| 环境变量泄露 | T1552.001 | AST |
| 远程代码执行 | T1105 | Pattern |
| 反向 Shell | T1059.004 | Pattern |
| 死人开关 | T1485 | Pattern |
| 混淆代码 | T1027 | Heuristics |
| JS 混淆模式 | T1027.002 | Pattern detection |
| 香农熵（字符串） | T1027 | Entropy calculation |
| 拼写欺诈 (npm + PyPI) | T1195.002 | Levenshtein |
| 供应链入侵 | T1195.002 | IOC matching |
| PyPI 恶意包 | T1195.002 | IOC matching |
| 沙箱动态分析 | Multiple | Docker + strace + tcpdump |
| 突然添加生命周期脚本 | T1195.002 | Temporal analysis |
| 版本间危险 API 注入 | T1195.002 | Temporal AST diff |
| 发布频率异常 | T1195.002 | Registry metadata |
| 维护者/发布者变更 | T1195.002 | Registry metadata |
| 金丝雀令牌泄露 | T1552.001 | Sandbox honey tokens |
| AI Agent 武器化 | T1059.004 | AST (s1ngularity/Nx flags) |
| AI 配置提示注入 | T1059.004 | File scanning (.cursorrules, CLAUDE.md) |
| 凭据 CLI 窃取 (gh, gcloud, aws) | T1552.001 | AST |
| 二进制投放器 (chmod + exec /tmp) | T1105 | AST |
| 原型钩子 (fetch, XMLHttpRequest) | T1557 | AST |
| 工作流注入 (.github/workflows) | T1195.002 | AST |
| 加密货币钱包窃取 | T1005 | Dataflow |
| Require 缓存污染 | T1574.001 | AST |
| 分阶段 eval 解码 (eval+atob/Buffer) | T1140 | AST |
| 反混淆（字符串拼接、charcode、base64、hex） | T1140 | AST pre-processing| 跨文件数据流（模块间泄露） | T1041 | Module graph |
## 供应链异常检测 (v2.0)
MUAD'DIB 2.0 引入了一个范式转变：从**基于 IOC 的检测**（被动，需要已知威胁）转变为**行为异常检测**（主动，通过发现可疑变更来检测未知威胁）。
传统的供应链扫描器依赖于已知恶意包的黑名单。问题在于：它们只能在威胁被识别和报告**之后**才能检测到。像 **ua-parser-js** (2021)、**event-stream** (2018) 和 **Shai-Hulud** (2025) 这样的攻击在数小时或数天内未被发现，因为当时还没有 IOC。
MUAD'DIB 2.0 增加了 5 项行为检测功能，可以通过分析包版本之间的变更，在这些攻击出现在任何 IOC 数据库**之前**捕获它们。
### 新功能
#### 1. 突发生命周期脚本检测 (`--temporal`)
检测 `preinstall`、`install` 或 `postinstall` 脚本是否突然出现在以前从未有过这些脚本的新版本包中。这是供应链攻击的头号攻击媒介。
```
muaddib scan . --temporal
```
#### 2. 时序 AST 差异 (`--temporal-ast`)
下载每个依赖项的最新两个版本，并比较它们的 AST（抽象语法树）以检测新添加的危险 API：`child_process`、`eval`、`Function`、`net.connect`、`process.env`、`fetch` 等。
```
muaddib scan . --temporal-ast
```
#### 3. 发布频率异常 (`--temporal-publish`)
检测异常的发布模式：24 小时内版本爆发、休眠 6 个月以上的包突然更新、快速版本连续（1 小时内多次发布）。
```
muaddib scan . --temporal-publish
```
#### 4. 维护者变更检测 (`--temporal-maintainer`)
检测版本之间包维护者的变更：添加了新维护者、唯一维护者被替换（event-stream 模式）、可疑的维护者名称、新发布者。
```
muaddib scan . --temporal-maintainer
```
#### 5. 金丝雀令牌 / 蜜罐令牌 (沙箱)
在安装包之前将虚假凭据注入沙箱环境。如果包尝试通过 HTTP、DNS、文件系统或 stdout 泄露这些蜜罐令牌，则将其标记为已确认的恶意软件。
注入了 6 个蜜罐凭据：
- `GITHUB_TOKEN` / `NPM_TOKEN` — 包注册表令牌
- `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` — 云凭据
- `SLACK_WEBHOOK_URL` / `DISCORD_WEBHOOK_URL` — 消息 Webhook
同时使用动态令牌（每个会话随机，来自 `canary-tokens.js`）和静态后备令牌（在 `sandbox-runner.sh` 中）以实现纵深防御。
```
muaddib sandbox suspicious-package
```
### 完整时序扫描
一次启用所有时序分析功能：
```
muaddib scan . --temporal-full
```
### 使用示例
```
# 完整行为扫描 (所有 5 个功能)
muaddib scan . --temporal-full
# 仅生命周期脚本检测
muaddib scan . --temporal
# AST diff + 维护者变更
muaddib scan . --temporal-ast --temporal-maintainer
# 带有 canary tokens 的沙箱 (默认启用)
muaddib sandbox suspicious-package
# 不带有 canary tokens 的沙箱
muaddib sandbox suspicious-package --no-canary
```
### 新检测规则 (v2.0)
| 规则 ID | 名称 | 严重性 | 功能 |
|---------|------|----------|---------|
| MUADDIB-TEMPORAL-001 | Sudden Lifecycle Script Added (Critical) | CRITICAL | `--temporal` |
| MUADDIB-TEMPORAL-002 | Sudden Lifecycle Script Added | HIGH | `--temporal` |
| MUADDIB-TEMPORAL-003 | Lifecycle Script Modified | MEDIUM | `--temporal` |
| MUADDIB-TEMPORAL-AST-001 | Dangerous API Added (Critical) | CRITICAL | `--temporal-ast` |
| MUADDIB-TEMPORAL-AST-002 | Dangerous API Added (High) | HIGH | `--temporal-ast` |
| MUADDIB-TEMPORAL-AST-003 | Dangerous API Added (Medium) | MEDIUM | `--temporal-ast` |
| MUADDIB-PUBLISH-001 | Publish Burst Detected | HIGH | `--temporal-publish` |
| MUADDIB-PUBLISH-002 | Dormant Package Spike | HIGH | `--temporal-publish` |
| MUADDIB-PUBLISH-003 | Rapid Version Succession | MEDIUM | `--temporal-publish` |
| MUADDIB-MAINTAINER-001 | New Maintainer Added | HIGH | `--temporal-maintainer` |
| MUADDIB-MAINTAINER-002 | Suspicious Maintainer Detected | CRITICAL | `--temporal-maintainer` |
| MUADDIB-MAINTAINER-003 | Sole Maintainer Changed | HIGH | `--temporal-maintainer` |
| MUADDIB-MAINTAINER-004 | New Publisher Detected | MEDIUM | `--temporal-maintainer` |
| MUADDIB-CANARY-001 | Canary Token Exfiltration | CRITICAL | sandbox |
### 为何重要
这些功能可以检测如下攻击：
- **Shai-Hulud** (2025)：可以通过时序生命周期 + AST 差异捕获（突然添加 `postinstall` + `child_process`）
- **ua-parser-js** (2021)：可以通过维护者变更 + 生命周期脚本检测捕获
- **event-stream** (2018)：可以通过唯一维护者变更 + AST 差异（带有 `eval` 的新 `flatmap-stream` 依赖项）捕获
- **coa/rc** (2021)：可以通过发布爆发 + 生命周期脚本检测捕获
所有这些都不需要任何 IOC 条目。
## IOC 来源
MUAD'DIB 仅汇总来自经过验证来源的威胁情报：
| 来源 | 类型 | 覆盖范围 |
|--------|------|----------|
| [OSV.dev npm dump](https://osv.dev) | Bulk zip | 200,000+ npm MAL-* entries |
| [OSV.dev PyPI dump](https://osv.dev) | Bulk zip | 14,000+ PyPI MAL-* entries |
| [GenSecAI Shai-Hulud Detector](https://github.com/gensecaihq/Shai-Hulud-2.0-Detector) | GitHub | 700+ Shai-Hulud packages |
| [DataDog Security Labs](https://github.com/DataDog/indicators-of-compromise) | GitHub | Consolidated IOCs from 7 vendors |
| [OSSF Malicious Packages](https://github.com/ossf/malicious-packages) | OSV API | 8000+ malware reports |
| [GitHub Advisory](https://github.com/advisories?query=type%3Amalware) | OSV API | Malware-tagged advisories |
| Snyk Known Malware | Static | Historical attacks |
| Socket.dev / Phylum | Static | Manual additions |
## VS Code
VS Code 扩展会自动扫描你的 npm 项目。
### 安装
在 VS Code 扩展中搜索 "MUAD'DIB"，或者：
```
code --install-extension dnszlsk.muaddib-vscode
```
### 命令
- `MUAD'DIB: Scan Project` - 扫描整个项目
- `MUAD'DIB: Scan Current File` - 扫描当前文件
### 设置
- `muaddib.autoScan` - 打开项目时自动扫描（默认：true）
- `muaddib.webhookUrl` - Discord/Slack Webhook URL
- `muaddib.failLevel` - 警报级别
## CI/CD
### GitHub Actions (Marketplace)
使用 GitHub Marketplace 中的官方 MUAD'DIB Action：
```
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'
```
#### Action 输入
| 输入项 | 描述 | 默认值 |
|-------|-------------|---------|
| `path` | 要扫描的路径 | `.` |
| `fail-on` | 失败的最低严重性 | `high` |
| `sarif` | SARIF 输出文件的路径 | `` |
| `paranoid` | 启用超严格检测 | `false` |
#### Action 输出
| 输出项 | 描述 |
|--------|-------------|
| `sarif-file` | 生成的 SARIF 文件的路径 |
| `risk-score` | 风险评分 (0-100) |
| `threats-count` | 检测到的威胁数量 |
| `exit-code` | 退出代码 (0 = clean) |
警报会显示在 Security > Code scanning alerts 中。
## 架构
```
MUAD'DIB 2.5.8 Scanner
|
+-- IOC Match (225,000+ packages, JSON DB)
| +-- OSV.dev npm dump (200K+ MAL-* entries)
| +-- OSV.dev PyPI dump (14K+ MAL-* entries)
| +-- GenSecAI Shai-Hulud Detector
| +-- DataDog Consolidated IOCs
| +-- OSSF Malicious Packages (via OSV)
| +-- GitHub Advisory (malware)
| +-- Snyk Known Malware
| +-- Static IOCs (Socket, Phylum)
|
+-- Deobfuscation Pre-processing (v2.2.5, --no-deobfuscate to disable)
| +-- String concat folding, CharCode reconstruction
| +-- Base64 decode, Hex array resolution
| +-- Const propagation (Phase 2)
|
+-- Inter-module Dataflow (v2.2.6, --no-module-graph to disable)
| +-- Module dependency graph, tainted export annotation
| +-- 3-hop re-export chains, class method analysis
| +-- Cross-file credential read -> network sink detection
|
+-- 14 Parallel Scanners (113 rules)
| +-- AST Parse (acorn) — eval/Function, credential CLI theft, binary droppers, prototype hooks
| +-- Pattern Matching (shell, scripts)
| +-- Obfuscation Detection (skip .min.js, ignore hex/unicode alone)
| +-- Typosquat Detection (npm + PyPI, Levenshtein)
| +-- Python Scanner (requirements.txt, setup.py, pyproject.toml)
| +-- Shannon Entropy (string-level, 5.5 bits + 50 chars min)
| +-- JS Obfuscation Patterns (_0x* vars, encoded arrays, eval+entropy)
| +-- GitHub Actions Scanner
| +-- AI Config Scanner (.cursorrules, CLAUDE.md, copilot-instructions.md)
| +-- Package, Dependencies, Hash, npm-registry, Dataflow scanners
|
+-- Supply Chain Anomaly Detection (v2.0)
| +-- Temporal Lifecycle Script Detection (--temporal)
| +-- Temporal AST Diff (--temporal-ast)
| +-- Publish Frequency Anomaly (--temporal-publish)
| +-- Maintainer Change Detection (--temporal-maintainer)
| +-- Canary Tokens / Honey Tokens (sandbox)
|
+-- Validation & Observability (v2.1)
| +-- Datadog 17K Benchmark (88.2% raw, ~100% JS/Node.js adjusted)
| +-- Ground Truth Dataset (51 real-world attacks, 91.8% TPR)
| +-- Detection Time Logging (first_seen tracking, lead time metrics)
| +-- FP Rate Tracking (daily stats, false positive rate)
| +-- Score Breakdown (explainable per-rule scoring)
| +-- Threat Feed API (HTTP server, JSON feed for SIEM)
|
+-- FP Reduction Post-processing (v2.2.8-v2.2.9, v2.3.0-v2.3.1, v2.5.7-v2.5.8)
| +-- Count-based severity downgrade (dynamic_require, dataflow, module_compile, etc.)
| +-- Framework prototype scoring cap + HTTP client whitelist
| +-- Obfuscation in dist/build/.cjs/.mjs → LOW
| +-- Safe env var + prefix filtering
| +-- Dataflow telemetry source categorization (os.platform/arch → telemetry_read)
| +-- DEP whitelist (es5-ext, bootstrap-sass) + npm alias skip
| +-- IOC wildcard audit (v2.5.8): FPR 10.8% → 6.0%
|
+-- Per-File Max Scoring (v2.2.11)
| +-- Score = max(file_scores) + package_level_score
| +-- Eliminates score accumulation across many files
| +-- Package-level threats (lifecycle, typosquat, IOC) scored separately
|
+-- Sandbox Monkey-Patching Preload (v2.4.9)
| +-- Runtime time manipulation (Date.now, setTimeout→0, setInterval→immediate)
| +-- Network/filesystem/process/env interception and logging
| +-- Multi-run [0h, 72h, 7d] for time-bomb detection (T1497.003)
|
+-- Security Audit (v2.5.0-v2.5.6)
| +-- 41 issues remediated (14 CRITICAL, 18 HIGH, 9 MEDIUM)
| +-- Native addon path traversal, atomic writes, AST bypasses
|
+-- Paranoid Mode (ultra-strict)
+-- Docker Sandbox (behavioral analysis, network capture, canary tokens, CI-aware, preload)
+-- Zero-Day Monitor (internal: npm + PyPI RSS polling, Discord alerts, daily report)
|
v
Dataflow Analysis (credential read -> network send)
|
v
Threat Enrichment (rules, MITRE ATT&CK, playbooks)
|
v
Output (CLI, JSON, HTML, SARIF, Webhook, Threat Feed)
```
## 评估指标
| 指标 | 结果 | 详情 |
|--------|--------|---------|
| **Wild TPR** (Datadog 17K) | **88.2%** 原始 · **~100%** 调整后 | 17,922 个真实恶意软件样本。2,077 个漏检均属超出范围（见下文） |
| **TPR** (Ground Truth) | **91.8%** (45/49) | 51 个真实世界攻击（49 个活跃）。4 个超出范围：仅浏览器 (3) + 高 FP 风险 (1) |
| **FPR** (Benign, global) | **6.0%** (32/529) | 529 个 npm 包，通过 `npm pack` 获取真实源代码，阈值 > 20 |
| **ADR** (Adversarial + Holdout) | **98.8%** (82/83) | 43 个对抗性 + 40 个保留集逃避样本。1 个记录在案的漏检：`require-cache-poison`（接受的权衡） |
**Datadog 17K 基准测试** — [DataDog Malicious Software Packages Dataset](https://github.com/DataDog/malicious-software-packages-dataset)，17,922 个真实恶意软件样本。原始 TPR：88.2% (15,810/17,922)。2,077 个漏检（score=0）被人工分类为：
| 类别 | 数量 | 原因 |
|----------|-------|--------|
| 钓鱼页面（HTML/CSS/JS 前端） | 1,233 | 无 Node.js API（无 `require`, `child_process`, `fs`, `process.env`）。虚假登录页面、重定向、验证码。 |
| 原生二进制文件（无 JS 文件） | 824 | 特定于平台的二进制文件（darwin-arm64, linux-x64 等）。仅 @42ailab 就有 201 个。 |
| 已修正的库 | 20 | 暂时被入侵随后修复。扫描前已移除恶意代码。 |
所有 2,077 个漏检都缺乏 Node.js 恶意软件模式。MUAD'DIB 执行基于 AST 的 Node.js 静态分析 —— 钓鱼 HTML 和原生二进制文件超出范围。针对 JS/Node.js 恶意软件的调整后 TPR：**~100%** (15,810/~15,845)。参见[评估方法](docs/EVALUATION_METHODOLOGY.md#14-datadog-17k-benchmark)。
**按包大小的 FPR** — FPR 与包大小呈线性相关。单文件最大评分 (v2.2.11) 显著降低了中型/大型包上的 FP：
| 类别 | 包数量 | FP | FPR |
|----------|----------|-----|-----|
| 小型（<10 个 JS 文件） | 290 | 18 | **6.2%** |
| 中型（10-50 个 JS 文件） | 135 | 16 | 11.9% |
| 大型（50-100 个 JS 文件） | 40 | 10 | 25.0% |
| 超大型（100+ 个 JS 文件） | 62 | 25 | 40.3% |
**FPR 演进**：0%（无效，空目录，v2.2.0-v2.2.6）→ 38%（首次实际测量，v2.2.7）→ 19.4% (v2.2.8) → 17.5% (v2.2.9) → ~13% (v2.2.11，单文件最大评分) → 8.9% (v2.3.0, P2) → 7.4% (v2.3.1, P3) → **6.0%** (v2.5.8, P4 + IOC 通配符审计)
**保留集演进**（调优前分数，规则冻结）：
| 保留集 | 分数 | 重点 |
|---------|-------|-------|
| v1 | 30% (3/10) | 通用模式 |
| v2 | 40% (4/10) | Env charcode, lifecycle, prototype |
| v3 | 60% (6/10) | Require cache, DNS TXT, reverse shell |
| v4 | **80%** (8/10) | 反混淆有效性 |
| v5 | 50% (5/10) | 模块间数据流（新扫描器） |
- **Wild TPR**（Datadog 基准测试）：针对来自 [DataDog Malicious Software Packages Dataset](https://github.com/DataDog/malicious-software-packages-dataset) 的 17,922 个真实恶意软件包的检测率。原始 88.2% (15,810/17,922)。排除超出范围的样本（1,233 个钓鱼 HTML 页面，824 个原生二进制文件，20 个已修正的库）后，针对 JS/Node.js 恶意软件的调整后 TPR 约为 100%。参见[评估方法](docs/EVALUATION_METHODOLOGY.md#14-datadog-17k-benchmark)。
- **TPR**（真阳性率）：针对 49 个真实世界供应链攻击（event-stream, ua-parser-js coa, flatmap-stream, eslint-scope, solana-web3js 等 43 个）的检测率。4 个漏检是仅浏览器端的或修复风险较高的—— 参见[威胁模型](docs/threat-model.md)。
- **FPR**（假阳性率）：529 个真实 npm 包中评分 > 20 的包比例（扫描源代码，而非空目录）。
- **ADR**（对抗性检测率）：针对 83 个逃避性恶意样本的检测率 —— 43 个对抗性 + 40 个保留集（5 批次，每批 10 个，测试混淆、模块间数据流等）。1 个记录在案的漏检：`require-cache-poison`（分数 10 < 阈值 20，FP 缩减 P3 带来的可接受权衡）。
- **保留集**（调优前）：规则冻结情况下对 10 个未见样本的检测率（衡量泛化能力）
数据集：17,922 个 Datadog 恶意软件样本，529 个 npm + 132 个 PyPI 良性包，83 个对抗性/保留集样本，51 个真值攻击（65 个记录在案的恶意软件包）。**1656 项测试**，86% 代码覆盖率。
完整实验方案请参见[评估方法](docs/EVALUATION_METHODOLOGY.md)。
## 贡献
### 添加 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
```
### 测试
- **1656 个单元/集成测试**，分布在 42 个模块化测试文件中 - 通过 [Codecov](https://codecov.io/gh/DNSZLSK/muad-dib) 实现了 86% 的代码覆盖率
- **56 个模糊测试** - 格式错误的 YAML、无效的 JSON、二进制文件、ReDoS、unicode、10MB 输入
- **Datadog 17K 基准测试** - 17,922 个真实恶意软件样本，88.2% 原始 TPR，针对 JS/Node.js 恶意软件约 100%（2,077 个超出范围的漏检：钓鱼、二进制文件、已修正库）
- **83 个对抗性/保留集样本** - 43 个对抗性 + 40 个保留集，82/83 检测率（98.8% ADR）。1 个记录在案的漏检：`require-cache-poison`（接受的权衡）
- **真值验证** - 51 个真实世界攻击（45/49 已检测 = 91.8% TPR）。4 个超出范围：仅浏览器 (3) + 高 FP 风险 (1)
- **假阳性验证** - 通过 `npm pack` 在真实 npm 源代码上进行的 6.0% 全局 FPR (32/529)
- **ESLint 安全审计** - 启用了 14 条规则的 `eslint-plugin-security`
## 社区
- Discord: https://discord.gg/y8zxSmue
## 文档
- [评估方法](docs/EVALUATION_METHODOLOGY.md) - 实验方案、原始保留集分数、攻击来源
- [威胁模型](docs/threat-model.md) - MUAD'DIB 能检测和不能检测什么
- [安全审计报告 v1.4.1](docs/MUADDIB_Security_Audit_Report_v1.4.1.pdf) - 完整安全审计（已修复 58 个问题）
- [IOCs YAML](iocs/) - 威胁数据库
## 许可证
MIT
]
香料必须流淌。虫子必须死。
标签：AMSI绕过, C2通信, CI/CD安全, DNS 反向解析, DNS重绑定攻击, GitHub Actions, IOCs, IP 地址批量处理, Llama, MITM代理, Monkey-Patching, Node.js安全, npm安全, PyPI安全, Shai-Hulud, typo-squatting, typosquatting, 云安全监控, 供应链攻击, 反弹Shell, 反混淆引擎, 域名仿冒, 威胁检测, 定时炸弹, 异常检测, 文档安全, 沙箱, 混淆检测, 自动笔记, 自定义脚本, 请求拦截, 软件开发工具包, 防御 evasion, 静态分析