{"id":44197880,"url":"https://github.com/dnszlsk/muad-dib","last_synced_at":"2026-05-25T00:02:03.644Z","repository":{"id":331371816,"uuid":"1126372664","full_name":"DNSZLSK/muad-dib","owner":"DNSZLSK","description":"Real-time npm/PyPI supply-chain threat detection. Production sensor with gVisor sandbox, behavioral analysis, and 200+ heuristic rules.","archived":false,"fork":false,"pushed_at":"2026-04-26T08:35:49.000Z","size":36520,"stargazers_count":8,"open_issues_count":5,"forks_count":2,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-04-26T10:23:02.861Z","etag":null,"topics":["ast","dependency-scanner","malware","mitre-attack","npm","pypi","python","sarif","scanner","security","shai-hulud","shai-hulud2","supply-chain","supply-chain-security","typosquatting"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/muaddib-scanner","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/DNSZLSK.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-01T19:14:43.000Z","updated_at":"2026-04-26T08:34:31.000Z","dependencies_parsed_at":null,"dependency_job_id":"a689f02f-ddb4-46c3-8e3c-9e7f0f67079d","html_url":"https://github.com/DNSZLSK/muad-dib","commit_stats":null,"previous_names":["dnszlsk/muad-dib"],"tags_count":287,"template":false,"template_full_name":null,"purl":"pkg:github/DNSZLSK/muad-dib","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DNSZLSK%2Fmuad-dib","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DNSZLSK%2Fmuad-dib/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DNSZLSK%2Fmuad-dib/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DNSZLSK%2Fmuad-dib/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DNSZLSK","download_url":"https://codeload.github.com/DNSZLSK/muad-dib/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DNSZLSK%2Fmuad-dib/sbom","scorecard":{"id":1242620,"data":{"date":"2026-01-29T00:23:05Z","repo":{"name":"github.com/DNSZLSK/muad-dib","commit":"bf5396a31f534ec63402b46fc7ad4c5b1d70ccc3"},"scorecard":{"version":"v5.0.0","commit":"ea7e27ed41b76ab879c862fa0ca4cc9c61764ee4"},"score":5.5,"checks":[{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/ea7e27ed41b76ab879c862fa0ca4cc9c61764ee4/docs/checks.md#binary-artifacts"}},{"name":"Branch-Protection","score":-1,"reason":"internal error: error during branchesHandler.setup: internal error: githubv4.Query: Resource not accessible by integration","details":null,"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/ea7e27ed41b76ab879c862fa0ca4cc9c61764ee4/docs/checks.md#branch-protection"}},{"name":"CI-Tests","score":8,"reason":"7 out of 8 merged PRs checked by a CI test -- score normalized to 8","details":null,"documentation":{"short":"Determines if the project runs tests before pull requests are merged.","url":"https://github.com/ossf/scorecard/blob/ea7e27ed41b76ab879c862fa0ca4cc9c61764ee4/docs/checks.md#ci-tests"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/ea7e27ed41b76ab879c862fa0ca4cc9c61764ee4/docs/checks.md#cii-best-practices"}},{"name":"Code-Review","score":0,"reason":"Found 0/17 approved changesets -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/ea7e27ed41b76ab879c862fa0ca4cc9c61764ee4/docs/checks.md#code-review"}},{"name":"Contributors","score":0,"reason":"project has 0 contributing companies or organizations -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project has a set of contributors from multiple organizations (e.g., companies).","url":"https://github.com/ossf/scorecard/blob/ea7e27ed41b76ab879c862fa0ca4cc9c61764ee4/docs/checks.md#contributors"}},{"name":"Dangerous-Workflow","score":10,"reason":"no dangerous workflow patterns detected","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/ea7e27ed41b76ab879c862fa0ca4cc9c61764ee4/docs/checks.md#dangerous-workflow"}},{"name":"Dependency-Update-Tool","score":10,"reason":"update tool detected","details":["Info: detected update tool: Dependabot: .github/dependabot.yml:1"],"documentation":{"short":"Determines if the project uses a dependency update tool.","url":"https://github.com/ossf/scorecard/blob/ea7e27ed41b76ab879c862fa0ca4cc9c61764ee4/docs/checks.md#dependency-update-tool"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/ea7e27ed41b76ab879c862fa0ca4cc9c61764ee4/docs/checks.md#fuzzing"}},{"name":"License","score":10,"reason":"license file detected","details":["Info: project has a license file: LICENSE:0","Info: FSF or OSI recognized license: MIT License: LICENSE:0"],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/ea7e27ed41b76ab879c862fa0ca4cc9c61764ee4/docs/checks.md#license"}},{"name":"Maintained","score":0,"reason":"project was created in last 90 days. please review its contents carefully","details":["Warn: Repository was created in last 90 days."],"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/ea7e27ed41b76ab879c862fa0ca4cc9c61764ee4/docs/checks.md#maintained"}},{"name":"Packaging","score":-1,"reason":"packaging workflow not detected","details":["Warn: no GitHub/GitLab publishing workflow detected."],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/ea7e27ed41b76ab879c862fa0ca4cc9c61764ee4/docs/checks.md#packaging"}},{"name":"Pinned-Dependencies","score":2,"reason":"dependency not pinned by hash detected -- score normalized to 2","details":["Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/scan.yml:38: update your workflow using https://app.stepsecurity.io/secureworkflow/DNSZLSK/muad-dib/scan.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/scan.yml:39: update your workflow using https://app.stepsecurity.io/secureworkflow/DNSZLSK/muad-dib/scan.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/scan.yml:44: update your workflow using https://app.stepsecurity.io/secureworkflow/DNSZLSK/muad-dib/scan.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/scan.yml:13: update your workflow using https://app.stepsecurity.io/secureworkflow/DNSZLSK/muad-dib/scan.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/scan.yml:14: update your workflow using https://app.stepsecurity.io/secureworkflow/DNSZLSK/muad-dib/scan.yml/master?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/scan.yml:23: update your workflow using https://app.stepsecurity.io/secureworkflow/DNSZLSK/muad-dib/scan.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/scorecard.yml:22: update your workflow using https://app.stepsecurity.io/secureworkflow/DNSZLSK/muad-dib/scorecard.yml/master?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/scorecard.yml:27: update your workflow using https://app.stepsecurity.io/secureworkflow/DNSZLSK/muad-dib/scorecard.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/scorecard.yml:34: update your workflow using https://app.stepsecurity.io/secureworkflow/DNSZLSK/muad-dib/scorecard.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/scorecard.yml:41: update your workflow using https://app.stepsecurity.io/secureworkflow/DNSZLSK/muad-dib/scorecard.yml/master?enable=pin","Warn: containerImage not pinned by hash: docker/Dockerfile:1: pin your Docker image by updating node:20-alpine to node:20-alpine@sha256:09e2b3d9726018aecf269bd35325f46bf75046a643a66d28360ec71132750ec8","Warn: downloadThenRun not pinned by hash: tests/samples/shell/malicious.sh:4","Warn: downloadThenRun not pinned by hash: tests/samples/shell/malicious.sh:7","Warn: npmCommand not pinned by hash: .github/workflows/scan.yml:20","Info:   0 out of   8 GitHub-owned GitHubAction dependencies pinned","Info:   0 out of   2 third-party GitHubAction dependencies pinned","Info:   0 out of   1 containerImage dependencies pinned","Info:   0 out of   2 downloadThenRun dependencies pinned","Info:   2 out of   3 npmCommand dependencies pinned"],"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/ea7e27ed41b76ab879c862fa0ca4cc9c61764ee4/docs/checks.md#pinned-dependencies"}},{"name":"SAST","score":8,"reason":"SAST tool is not run on all commits -- score normalized to 8","details":["Warn: 14 commits out of 16 are checked with a SAST tool"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/ea7e27ed41b76ab879c862fa0ca4cc9c61764ee4/docs/checks.md#sast"}},{"name":"Security-Policy","score":10,"reason":"security policy file detected","details":["Info: security policy file detected: SECURITY.md:1","Info: Found linked content: SECURITY.md:1","Info: Found disclosure, vulnerability, and/or timelines in security policy: SECURITY.md:1","Info: Found text in security policy: SECURITY.md:1"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/ea7e27ed41b76ab879c862fa0ca4cc9c61764ee4/docs/checks.md#security-policy"}},{"name":"Signed-Releases","score":-1,"reason":"no releases found","details":null,"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/ea7e27ed41b76ab879c862fa0ca4cc9c61764ee4/docs/checks.md#signed-releases"}},{"name":"Token-Permissions","score":0,"reason":"detected GitHub workflow tokens with excessive permissions","details":["Info: jobLevel 'contents' permission set to 'read': .github/workflows/scan.yml:36","Warn: no topLevel permission defined: .github/workflows/scan.yml:1","Info: topLevel permissions set to 'read-all': .github/workflows/scorecard.yml:10","Info: no jobLevel write permissions found"],"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/ea7e27ed41b76ab879c862fa0ca4cc9c61764ee4/docs/checks.md#token-permissions"}},{"name":"Vulnerabilities","score":10,"reason":"0 existing vulnerabilities detected","details":null,"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/ea7e27ed41b76ab879c862fa0ca4cc9c61764ee4/docs/checks.md#vulnerabilities"}}]},"last_synced_at":"2026-01-29T14:11:26.522Z","repository_id":331371816,"created_at":"2026-01-29T14:11:26.522Z","updated_at":"2026-01-29T14:11:26.522Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32514340,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-30T13:12:12.517Z","status":"online","status_checked_at":"2026-05-01T02:00:05.856Z","response_time":64,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ast","dependency-scanner","malware","mitre-attack","npm","pypi","python","sarif","scanner","security","shai-hulud","shai-hulud2","supply-chain","supply-chain-security","typosquatting"],"created_at":"2026-02-09T20:11:47.078Z","updated_at":"2026-05-25T00:02:03.629Z","avatar_url":"https://github.com/DNSZLSK.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/muaddibLogo.png\" alt=\"MUAD'DIB Logo\" width=\"700\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.npmjs.com/package/muaddib-scanner\"\u003e\u003cimg src=\"https://img.shields.io/npm/v/muaddib-scanner\" alt=\"npm version\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/DNSZLSK/muad-dib/actions/workflows/scan.yml\"\u003e\u003cimg src=\"https://github.com/DNSZLSK/muad-dib/actions/workflows/scan.yml/badge.svg\" alt=\"CI\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://codecov.io/gh/DNSZLSK/muad-dib\"\u003e\u003cimg src=\"https://codecov.io/gh/DNSZLSK/muad-dib/branch/master/graph/badge.svg\" alt=\"Coverage\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://scorecard.dev/viewer/?uri=github.com/DNSZLSK/muad-dib\"\u003e\u003cimg src=\"https://api.scorecard.dev/projects/github.com/DNSZLSK/muad-dib/badge\" alt=\"OpenSSF Scorecard\"\u003e\u003c/a\u003e\n  \u003cimg src=\"https://img.shields.io/badge/license-MIT-green\" alt=\"License\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/node-%3E%3D18-brightgreen\" alt=\"Node\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/IOCs-225%2C000%2B-red\" alt=\"IOCs\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#installation\"\u003eInstallation\u003c/a\u003e |\n  \u003ca href=\"#usage\"\u003eUsage\u003c/a\u003e |\n  \u003ca href=\"#features\"\u003eFeatures\u003c/a\u003e |\n  \u003ca href=\"#vs-code\"\u003eVS Code\u003c/a\u003e |\n  \u003ca href=\"#cicd\"\u003eCI/CD\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"docs/README.fr.md\"\u003eVersion francaise\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n## Why MUAD'DIB?\n\nnpm and PyPI supply-chain attacks are exploding. Shai-Hulud compromised 25K+ repos in 2025. Existing tools detect threats but don't help you respond.\n\nMUAD'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.\n\n---\n\n## Positioning\n\nMUAD'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.\n\n**For enterprise protection**, use:\n- [Socket.dev](https://socket.dev) - ML behavioral analysis, cloud sandboxing\n- [Snyk](https://snyk.io) - Massive vulnerability database, CI/CD integrations\n- [Opengrep](https://opengrep.dev) - Advanced dataflow analysis, Semgrep rules\n\n---\n\n## Installation\n\n### npm (recommended)\n\n```bash\nnpm install -g muaddib-scanner\n```\n\n### From source\n\n```bash\ngit clone https://github.com/DNSZLSK/muad-dib\ncd muad-dib\nnpm install\nnpm link\n```\n\n---\n\n## Usage\n\n### Basic scan\n\n```bash\nmuaddib scan .\nmuaddib scan /path/to/project\n```\n\nScans both npm (package.json, node_modules) and Python (requirements.txt, setup.py, pyproject.toml) dependencies.\n\n### Interactive mode\n\n```bash\nmuaddib\n```\n\n### Safe install\n\n```bash\nmuaddib install \u003cpackage\u003e\nmuaddib install lodash axios --save-dev\nmuaddib install suspicious-pkg --force    # Force install despite threats\n```\n\nScans packages for threats BEFORE installing. Blocks known malicious packages.\n\n### Risk score\n\nEach scan displays a 0-100 risk score:\n\n```\n[SCORE] 58/100 [***********---------] HIGH\n```\n\n### Explain mode\n\n```bash\nmuaddib scan . --explain\n```\n\nShows rule ID, MITRE ATT\u0026CK technique, references, and response playbook for each detection.\n\n### Export\n\n```bash\nmuaddib scan . --json \u003e results.json     # JSON\nmuaddib scan . --html report.html        # HTML\nmuaddib scan . --sarif results.sarif     # SARIF (GitHub Security)\n```\n\n### Severity threshold\n\n```bash\nmuaddib scan . --fail-on critical  # Fail only on CRITICAL\nmuaddib scan . --fail-on high      # Fail on HIGH and CRITICAL (default)\n```\n\n### Paranoid mode\n\n```bash\nmuaddib scan . --paranoid\n```\n\nUltra-strict detection with lower tolerance. Detects any network access, subprocess execution, dynamic code evaluation, and sensitive file access.\n\n### Webhook alerts\n\n```bash\nmuaddib scan . --webhook \"https://discord.com/api/webhooks/...\"\n```\n\nStrict 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).\n\n### Behavioral anomaly detection (v2.0)\n\n```bash\nmuaddib scan . --temporal-full     # All 4 temporal features\nmuaddib scan . --temporal          # Sudden lifecycle script detection\nmuaddib scan . --temporal-ast      # AST diff between versions\nmuaddib scan . --temporal-publish  # Publish frequency anomaly\nmuaddib scan . --temporal-maintainer # Maintainer change detection\n```\n\nDetects supply-chain attacks **before** they appear in IOC databases by analyzing changes between package versions. See [Evaluation Methodology](docs/EVALUATION_METHODOLOGY.md) for details.\n\n### Docker sandbox\n\n```bash\nmuaddib sandbox \u003cpackage-name\u003e\nmuaddib sandbox \u003cpackage-name\u003e --strict\n```\n\nDynamic 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).\n\n### Other commands\n\n```bash\nmuaddib watch .                    # Real-time monitoring\nmuaddib daemon                     # Daemon mode (auto-scan npm install)\nmuaddib update                     # Update IOCs (fast, ~5s)\nmuaddib scrape                     # Full IOC refresh (~5min)\nmuaddib diff HEAD~1                # Compare threats with previous commit\nmuaddib init-hooks                 # Pre-commit hooks (husky/pre-commit/git)\nmuaddib scan . --breakdown         # Explainable score decomposition\nmuaddib replay                     # Ground truth validation (61/65 TPR@3)\n```\n\n---\n\n## Features\n\n### 17 parallel scanners\n\n| Scanner | Detection |\n|---------|-----------|\n| AST Parse (acorn) | eval, Function, credential theft, binary droppers, prototype hooks |\n| Pattern Matching | Shell commands, reverse shells, dead man's switch |\n| Dataflow Analysis | Credential read + network send (intra-file and cross-file) |\n| Obfuscation Detection | JS obfuscation patterns (skip .min.js) |\n| Deobfuscation Pre-processing | String concat, charcode, base64, hex array, const propagation |\n| Inter-module Dataflow | Cross-file taint propagation (3-hop chains, class methods) |\n| Intent Coherence | Intra-file source-sink pairing (credential + eval/network) |\n| Typosquatting | npm + PyPI (Levenshtein distance) |\n| Python Scanner | requirements.txt, setup.py, pyproject.toml, 14K+ PyPI IOCs |\n| Shannon Entropy | High-entropy strings (5.5 bits + 50 chars min) |\n| AI Config Scanner | .cursorrules, CLAUDE.md, copilot-instructions.md injection |\n| Package/Dependencies | Lifecycle scripts, IOC matching (225K+ packages) |\n| GitHub Actions | Shai-Hulud backdoor detection |\n| Hash Scanner | Known malicious file hashes |\n| IOC Strings (intel-triage P1.1) | YARA-style string matching (Axios 2026, TeamPCP, GlassWorm, CanisterSprawl) |\n| Anti-Forensic AST (intel-triage P1.2) | XOR loop + self-delete + decoy write compound (csec autodelete) |\n| Stub Package (intel-triage P1.3) | Tiny main file + external dep URL + lifecycle hook (ltidi chain) |\n| Monorepo Scanner | Lerna/pnpm-workspace/turbo detection (Sprint 1 audit MR-C2 fix) |\n\n### 234 detection rules\n\nAll rules (229 RULES + 5 PARANOID) are mapped to MITRE ATT\u0026CK techniques. See [SECURITY.md](SECURITY.md#detection-rules-v21021) for the complete rules reference.\n\n### Detected campaigns\n\n| Campaign | Status |\n|----------|--------|\n| GlassWorm (2026, 433+ packages) | Detected |\n| Shai-Hulud v1/v2/v3 (2025) | Detected |\n| event-stream (2018) | Detected |\n| eslint-scope (2018) | Detected |\n| Protestware (node-ipc, colors, faker) | Detected |\n| Typosquats (crossenv, mongose, babelcli) | Detected |\n\n---\n\n## VS Code\n\nThe VS Code extension automatically scans your npm projects.\n\n```bash\ncode --install-extension dnszlsk.muaddib-vscode\n```\n\n- `MUAD'DIB: Scan Project` - Scan entire project\n- `MUAD'DIB: Scan Current File` - Scan current file\n- Settings: `muaddib.autoScan`, `muaddib.webhookUrl`, `muaddib.failLevel`\n\nSee [vscode-extension/README.md](vscode-extension/README.md) for full documentation.\n\n---\n\n## CI/CD\n\n### GitHub Actions (Marketplace)\n\n```yaml\nname: Security Scan\n\non: [push, pull_request]\n\njobs:\n  scan:\n    runs-on: ubuntu-latest\n    permissions:\n      security-events: write\n      contents: read\n    steps:\n      - uses: actions/checkout@v4\n      - uses: DNSZLSK/muad-dib@v1\n        with:\n          path: '.'\n          fail-on: 'high'\n          sarif: 'results.sarif'\n```\n\n| Input | Description | Default |\n|-------|-------------|---------|\n| `path` | Path to scan | `.` |\n| `fail-on` | Minimum severity to fail | `high` |\n| `sarif` | SARIF output file path | |\n| `paranoid` | Ultra-strict detection | `false` |\n\n### Pre-commit hooks\n\n```bash\nmuaddib init-hooks                        # Auto-detect (husky/pre-commit/git)\nmuaddib init-hooks --type husky           # Force husky\nmuaddib init-hooks --mode diff            # Only block NEW threats\n```\n\nWith pre-commit framework:\n```yaml\nrepos:\n  - repo: https://github.com/DNSZLSK/muad-dib\n    rev: v2.11.24\n    hooks:\n      - id: muaddib-scan\n```\n\n---\n\n## Evaluation Metrics\n\n| Metric | Result | Details |\n|--------|--------|---------|\n| **ML FPR** | **2.85%** (239/8,393 holdout) | XGBoost retrained on 56,564 samples, 64 features, threshold=0.710 |\n| **ML TPR** | **99.93%** (2,918/2,920 holdout) | 377 confirmed_malicious via OSSF/GHSA/npm correlation |\n| **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% |\n| **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 |\n| **TPR@20** (alert rate) | **86.2%** (56/65) | Operational alert threshold=20, aligned with ADR/FPR |\n| **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 |\n| **FPR after ML** (v2.10.95 measure) | **10.28%** (56/545 scanned) | ML filters 29/30 T1 benign, 0 GT/ADR suppressed |\n| **FPR** (Benign random, v2.10.95 measure) | **7.0%** (14/200) | 200 random npm packages, stratified sampling |\n| **ADR** (Adversarial + Holdout) | **96.3%** (103/107) | 67 adversarial + 40 holdout (107 available on disk), global threshold=20 |\n\n**3664 tests** across 93 files. **234 rules** (229 RULES + 5 PARANOID).\n\n\u003e **ML retrain methodology (v2.10.51):**\n\u003e - Ground truth: 377 confirmed_malicious via auto-labeler (OSSF malicious-packages, GitHub Advisory Database, npm registry takedown correlation)\n\u003e - Dataset: 56,564 samples (14,602 malicious, 41,962 clean). Stratified 80/20 split\n\u003e - Grid search: depth=4, estimators=300, lr=0.05. AUC-ROC=0.999, F1=0.960\n\u003e - Leaky feature filter: 23 dead/leaky features removed (source-identity proxies)\n\u003e\n\u003e **Static evaluation caveats:**\n\u003e - 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)\n\u003e - TPR@3 = detection rate (any signal); TPR@20 = operational alert threshold\n\u003e - FPR measured on 532 curated popular npm packages (not a random sample)\n\u003e - ADR measured with global threshold (score \u003e= 20) as of v2.6.5\n\nSee [Evaluation Methodology](docs/EVALUATION_METHODOLOGY.md) for the full experimental protocol, holdout history, and Datadog benchmark details.\n\n---\n\n## Contributing\n\n### Add IOCs\n\nEdit YAML files in `iocs/`:\n\n```yaml\n- id: NEW-MALWARE-001\n  name: \"malicious-package\"\n  version: \"*\"\n  severity: critical\n  confidence: high\n  source: community\n  description: \"Threat description\"\n  references:\n    - https://example.com/article\n  mitre: T1195.002\n```\n\n### Development\n\n```bash\ngit clone https://github.com/DNSZLSK/muad-dib\ncd muad-dib\nnpm install\nnpm test\n```\n\n### Testing\n\n- **3664 tests** across 93 modular test files\n- **56 fuzz tests** - Malformed inputs, ReDoS, unicode, binary\n- **Datadog 17K benchmark** - 14,587 confirmed malware samples (in-scope)\n- **Ground truth validation** - 67 real-world attacks (93.85% TPR@3, 86.2% TPR@20 — v2.10.95 measure)\n- **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\n\n---\n\n## Community\n\n- Discord: https://discord.gg/y8zxSmue\n\n---\n\n## Documentation\n\n- [Blog](https://dnszlsk.github.io/muad-dib/blog/) - Technical articles on supply-chain threat detection\n- [Carnet de bord](docs/CARNET_DE_BORD_MUADDIB.md) - Development journal (in French)\n- [Documentation Index](docs/INDEX.md) - All documentation in one place\n- [Evaluation Methodology](docs/EVALUATION_METHODOLOGY.md) - Experimental protocol, holdout scores\n- [Threat Model](docs/threat-model.md) - What MUAD'DIB detects and doesn't detect\n- [Security Policy](SECURITY.md) - Detection rules reference (234 rules)\n- [Security Audit](docs/SECURITY_AUDIT.md) - Bypass validation report\n- [FP Analysis](docs/EVALUATION.md) - Historical false positive analysis\n\n---\n\n## License\n\nMIT\n\n---\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eThe spice must flow. The worms must die.\u003c/strong\u003e\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdnszlsk%2Fmuad-dib","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdnszlsk%2Fmuad-dib","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdnszlsk%2Fmuad-dib/lists"}