https://github.com/dnszlsk/muad-dib
Real-time npm/PyPI supply-chain threat detection. Production sensor with gVisor sandbox, behavioral analysis, and 200+ heuristic rules.
https://github.com/dnszlsk/muad-dib
ast dependency-scanner malware mitre-attack npm pypi python sarif scanner security shai-hulud shai-hulud2 supply-chain supply-chain-security typosquatting
Last synced: 9 days ago
JSON representation
Real-time npm/PyPI supply-chain threat detection. Production sensor with gVisor sandbox, behavioral analysis, and 200+ heuristic rules.
- Host: GitHub
- URL: https://github.com/dnszlsk/muad-dib
- Owner: DNSZLSK
- License: mit
- Created: 2026-01-01T19:14:43.000Z (5 months ago)
- Default Branch: master
- Last Pushed: 2026-04-26T08:35:49.000Z (about 1 month ago)
- Last Synced: 2026-04-26T10:23:02.861Z (about 1 month ago)
- Topics: ast, dependency-scanner, malware, mitre-attack, npm, pypi, python, sarif, scanner, security, shai-hulud, shai-hulud2, supply-chain, supply-chain-security, typosquatting
- Language: JavaScript
- Homepage: https://www.npmjs.com/package/muaddib-scanner
- Size: 34.8 MB
- Stars: 8
- Watchers: 0
- Forks: 2
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Security: SECURITY.md
Awesome Lists containing this project
README
Installation |
Usage |
Features |
VS Code |
CI/CD
---
## Why MUAD'DIB?
npm and PyPI supply-chain attacks are exploding. Shai-Hulud compromised 25K+ repos in 2025. Existing tools detect threats but don't help you respond.
MUAD'DIB combines **17 parallel scanners** (234 detection rules), a **deobfuscation engine**, **inter-module dataflow analysis**, **compound scoring** (16 compound rules), **ML classifiers** (XGBoost), and gVisor/Docker sandbox to detect known threats and suspicious behavioral patterns in npm and PyPI packages.
---
## Positioning
MUAD'DIB is an educational tool and a free first line of defense. It detects **known** npm and PyPI threats (225,000+ IOCs) and suspicious behavioral patterns.
**For enterprise protection**, use:
- [Socket.dev](https://socket.dev) - ML behavioral analysis, cloud sandboxing
- [Snyk](https://snyk.io) - Massive vulnerability database, CI/CD integrations
- [Opengrep](https://opengrep.dev) - Advanced dataflow analysis, Semgrep rules
---
## Installation
### npm (recommended)
```bash
npm install -g muaddib-scanner
```
### From source
```bash
git clone https://github.com/DNSZLSK/muad-dib
cd muad-dib
npm install
npm link
```
---
## Usage
### Basic scan
```bash
muaddib scan .
muaddib scan /path/to/project
```
Scans both npm (package.json, node_modules) and Python (requirements.txt, setup.py, pyproject.toml) dependencies.
### Interactive mode
```bash
muaddib
```
### Safe install
```bash
muaddib install
muaddib install lodash axios --save-dev
muaddib install suspicious-pkg --force # Force install despite threats
```
Scans packages for threats BEFORE installing. Blocks known malicious packages.
### Risk score
Each scan displays a 0-100 risk score:
```
[SCORE] 58/100 [***********---------] HIGH
```
### Explain mode
```bash
muaddib scan . --explain
```
Shows rule ID, MITRE ATT&CK technique, references, and response playbook for each detection.
### Export
```bash
muaddib scan . --json > results.json # JSON
muaddib scan . --html report.html # HTML
muaddib scan . --sarif results.sarif # SARIF (GitHub Security)
```
### Severity threshold
```bash
muaddib scan . --fail-on critical # Fail only on CRITICAL
muaddib scan . --fail-on high # Fail on HIGH and CRITICAL (default)
```
### Paranoid mode
```bash
muaddib scan . --paranoid
```
Ultra-strict detection with lower tolerance. Detects any network access, subprocess execution, dynamic code evaluation, and sensitive file access.
### Webhook alerts
```bash
muaddib scan . --webhook "https://discord.com/api/webhooks/..."
```
Strict filtering (v2.1.2): alerts only for IOC matches, sandbox-confirmed threats, or canary token exfiltration. Priority triage (v2.10.21): P1 (red, IOC/sandbox/canary), P2 (orange, high-score/compounds), P3 (yellow, rest).
### Behavioral anomaly detection (v2.0)
```bash
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
```
Detects supply-chain attacks **before** they appear in IOC databases by analyzing changes between package versions. See [Evaluation Methodology](docs/EVALUATION_METHODOLOGY.md) for details.
### Docker sandbox
```bash
muaddib sandbox
muaddib sandbox --strict
```
Dynamic analysis in an isolated Docker container: strace, tcpdump, filesystem diff, canary tokens, CI-aware environment, and monkey-patching preload for time-bomb detection (multi-run at [0h, 72h, 7d] offsets).
### Other commands
```bash
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 (61/65 TPR@3)
```
---
## Features
### 17 parallel scanners
| Scanner | Detection |
|---------|-----------|
| AST Parse (acorn) | eval, Function, credential theft, binary droppers, prototype hooks |
| Pattern Matching | Shell commands, reverse shells, dead man's switch |
| Dataflow Analysis | Credential read + network send (intra-file and cross-file) |
| Obfuscation Detection | JS obfuscation patterns (skip .min.js) |
| Deobfuscation Pre-processing | String concat, charcode, base64, hex array, const propagation |
| Inter-module Dataflow | Cross-file taint propagation (3-hop chains, class methods) |
| Intent Coherence | Intra-file source-sink pairing (credential + eval/network) |
| Typosquatting | npm + PyPI (Levenshtein distance) |
| Python Scanner | requirements.txt, setup.py, pyproject.toml, 14K+ PyPI IOCs |
| Shannon Entropy | High-entropy strings (5.5 bits + 50 chars min) |
| AI Config Scanner | .cursorrules, CLAUDE.md, copilot-instructions.md injection |
| Package/Dependencies | Lifecycle scripts, IOC matching (225K+ packages) |
| GitHub Actions | Shai-Hulud backdoor detection |
| Hash Scanner | Known malicious file hashes |
| IOC Strings (intel-triage P1.1) | YARA-style string matching (Axios 2026, TeamPCP, GlassWorm, CanisterSprawl) |
| Anti-Forensic AST (intel-triage P1.2) | XOR loop + self-delete + decoy write compound (csec autodelete) |
| Stub Package (intel-triage P1.3) | Tiny main file + external dep URL + lifecycle hook (ltidi chain) |
| Monorepo Scanner | Lerna/pnpm-workspace/turbo detection (Sprint 1 audit MR-C2 fix) |
### 234 detection rules
All rules (229 RULES + 5 PARANOID) are mapped to MITRE ATT&CK techniques. See [SECURITY.md](SECURITY.md#detection-rules-v21021) for the complete rules reference.
### Detected campaigns
| Campaign | Status |
|----------|--------|
| GlassWorm (2026, 433+ packages) | Detected |
| Shai-Hulud v1/v2/v3 (2025) | Detected |
| event-stream (2018) | Detected |
| eslint-scope (2018) | Detected |
| Protestware (node-ipc, colors, faker) | Detected |
| Typosquats (crossenv, mongose, babelcli) | Detected |
---
## VS Code
The VS Code extension automatically scans your npm projects.
```bash
code --install-extension dnszlsk.muaddib-vscode
```
- `MUAD'DIB: Scan Project` - Scan entire project
- `MUAD'DIB: Scan Current File` - Scan current file
- Settings: `muaddib.autoScan`, `muaddib.webhookUrl`, `muaddib.failLevel`
See [vscode-extension/README.md](vscode-extension/README.md) for full documentation.
---
## CI/CD
### GitHub Actions (Marketplace)
```yaml
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'
```
| Input | Description | Default |
|-------|-------------|---------|
| `path` | Path to scan | `.` |
| `fail-on` | Minimum severity to fail | `high` |
| `sarif` | SARIF output file path | |
| `paranoid` | Ultra-strict detection | `false` |
### Pre-commit hooks
```bash
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
```
With pre-commit framework:
```yaml
repos:
- repo: https://github.com/DNSZLSK/muad-dib
rev: v2.11.24
hooks:
- id: muaddib-scan
```
---
## Evaluation Metrics
| Metric | Result | Details |
|--------|--------|---------|
| **ML FPR** | **2.85%** (239/8,393 holdout) | XGBoost retrained on 56,564 samples, 64 features, threshold=0.710 |
| **ML TPR** | **99.93%** (2,918/2,920 holdout) | 377 confirmed_malicious via OSSF/GHSA/npm correlation |
| **Wild TPR** (Datadog 17K) | **92.8%** (13,538/14,587 in-scope) | 17,922 packages. 3,335 skipped (no JS). By category: compromised_lib 97.8%, malicious_intent 92.1% |
| **TPR@3** (detection rate) | **93.85%** (61/65) | 67 real attacks (65 active, 2 out-of-scope: GT-005 colors, GT-009 faker — protestware with min_threats=0). Threshold=3: any signal |
| **TPR@20** (alert rate) | **86.2%** (56/65) | Operational alert threshold=20, aligned with ADR/FPR |
| **FPR rules** (Benign curated, v2.10.95 measure) | **15.6%** (85/545 scanned, 548 total) | npm packages, real source via `npm pack`; v2.10.74 estimated 6-9% reduction did NOT materialize on rebuilt corpus |
| **FPR after ML** (v2.10.95 measure) | **10.28%** (56/545 scanned) | ML filters 29/30 T1 benign, 0 GT/ADR suppressed |
| **FPR** (Benign random, v2.10.95 measure) | **7.0%** (14/200) | 200 random npm packages, stratified sampling |
| **ADR** (Adversarial + Holdout) | **96.3%** (103/107) | 67 adversarial + 40 holdout (107 available on disk), global threshold=20 |
**3664 tests** across 93 files. **234 rules** (229 RULES + 5 PARANOID).
> **ML retrain methodology (v2.10.51):**
> - Ground truth: 377 confirmed_malicious via auto-labeler (OSSF malicious-packages, GitHub Advisory Database, npm registry takedown correlation)
> - Dataset: 56,564 samples (14,602 malicious, 41,962 clean). Stratified 80/20 split
> - Grid search: depth=4, estimators=300, lr=0.05. AUC-ROC=0.999, F1=0.960
> - Leaky feature filter: 23 dead/leaky features removed (source-identity proxies)
>
> **Static evaluation caveats:**
> - TPR measured on 65 active Node.js attack samples (2 out-of-scope: GT-005 colors, GT-009 faker, both protestware with min_threats=0; from 67 total)
> - TPR@3 = detection rate (any signal); TPR@20 = operational alert threshold
> - FPR measured on 532 curated popular npm packages (not a random sample)
> - ADR measured with global threshold (score >= 20) as of v2.6.5
See [Evaluation Methodology](docs/EVALUATION_METHODOLOGY.md) for the full experimental protocol, holdout history, and Datadog benchmark details.
---
## Contributing
### Add IOCs
Edit YAML files in `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
```
### Development
```bash
git clone https://github.com/DNSZLSK/muad-dib
cd muad-dib
npm install
npm test
```
### Testing
- **3664 tests** across 93 modular test files
- **56 fuzz tests** - Malformed inputs, ReDoS, unicode, binary
- **Datadog 17K benchmark** - 14,587 confirmed malware samples (in-scope)
- **Ground truth validation** - 67 real-world attacks (93.85% TPR@3, 86.2% TPR@20 — v2.10.95 measure)
- **False positive validation** (v2.10.95 measure) - 15.6% FPR rules (85/545 scanned), 10.28% after ML (56/545 scanned), 7.0% on 200 random
---
## Community
- Discord: https://discord.gg/y8zxSmue
---
## Documentation
- [Blog](https://dnszlsk.github.io/muad-dib/blog/) - Technical articles on supply-chain threat detection
- [Carnet de bord](docs/CARNET_DE_BORD_MUADDIB.md) - Development journal (in French)
- [Documentation Index](docs/INDEX.md) - All documentation in one place
- [Evaluation Methodology](docs/EVALUATION_METHODOLOGY.md) - Experimental protocol, holdout scores
- [Threat Model](docs/threat-model.md) - What MUAD'DIB detects and doesn't detect
- [Security Policy](SECURITY.md) - Detection rules reference (234 rules)
- [Security Audit](docs/SECURITY_AUDIT.md) - Bypass validation report
- [FP Analysis](docs/EVALUATION.md) - Historical false positive analysis
---
## License
MIT
---
The spice must flow. The worms must die.