muaddib-scanner 2.10.21 → 2.10.23

package/README.md

@@ -30,7 +30,7 @@
 
 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 **14 parallel scanners** (162 detection rules), a **deobfuscation engine**, **inter-module dataflow analysis**, **compound scoring**, **ML classifiers** (XGBoost), and Docker sandbox to detect known threats and suspicious behavioral patterns in npm and PyPI packages.
+MUAD'DIB combines **14 parallel scanners** (176 detection rules), a **deobfuscation engine**, **inter-module dataflow analysis**, **compound scoring**, **ML classifiers** (XGBoost), and Docker sandbox to detect known threats and suspicious behavioral patterns in npm and PyPI packages.
 
 ---
 
@@ -136,7 +136,7 @@ Ultra-strict detection with lower tolerance. Detects any network access, subproc
 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.5): P1 (red, IOC/sandbox/canary), P2 (orange, high-score/compounds), P3 (yellow, rest).
+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)
 
@@ -195,9 +195,9 @@ muaddib replay                     # Ground truth validation (46/49 TPR)
 | GitHub Actions | Shai-Hulud backdoor detection |
 | Hash Scanner | Known malicious file hashes |
 
-### 162 detection rules
+### 176 detection rules
 
-All rules are mapped to MITRE ATT&CK techniques. See [SECURITY.md](SECURITY.md#detection-rules-v2105) for the complete rules reference.
+All rules are mapped to MITRE ATT&CK techniques. See [SECURITY.md](SECURITY.md#detection-rules-v21021) for the complete rules reference.
 
 ### Detected campaigns
 
@@ -271,7 +271,7 @@ With pre-commit framework:
 ```yaml
 repos:
   - repo: https://github.com/DNSZLSK/muad-dib
-    rev: v2.6.6
+    rev: v2.10.21
     hooks:
       - id: muaddib-scan
 ```
@@ -284,11 +284,11 @@ repos:
 |--------|--------|---------|
 | **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** (Ground Truth) | **93.9%** (46/49) | 51 real attacks. 3 out-of-scope: browser-only |
-| **FPR** (Benign curated) | **11.0%** (58/529) | 529 npm packages, real source via `npm pack` |
+| **FPR** (Benign curated) | **10.6%** (56/529) | 529 npm packages, real source via `npm pack` |
 | **FPR** (Benign random) | **7.5%** (15/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 |
+| **ADR** (Adversarial + Holdout) | **94.0%** (101/107) | 67 adversarial + 40 holdout (107 available on disk), global threshold=20 |
 
-**2643 tests** across 57 files. **162 rules** (157 RULES + 5 PARANOID).
+**2793 tests** across 57 files. **176 rules** (171 RULES + 5 PARANOID).
 
 > **Methodology caveats:**
 > - TPR measured on 49 Node.js attack samples (3 browser-only excluded from 51 total)
@@ -329,11 +329,11 @@ npm test
 
 ### Testing
 
-- **2643 tests** across 57 modular test files
+- **2793 tests** across 57 modular test files
 - **56 fuzz tests** - Malformed inputs, ReDoS, unicode, binary
 - **Datadog 17K benchmark** - 14,587 confirmed malware samples (in-scope)
 - **Ground truth validation** - 51 real-world attacks (93.9% TPR)
-- **False positive validation** - 11.0% FPR on 529 curated npm packages, 7.5% on 200 random
+- **False positive validation** - 10.6% FPR on 529 curated npm packages, 7.5% on 200 random
 
 ---
 
@@ -351,7 +351,7 @@ npm test
 - [Evaluation Methodology](docs/EVALUATION_METHODOLOGY.md) - Experimental protocol, holdout scores
 - [Threat Model](docs/threat-model.md) - What MUAD'DIB detects and doesn't detect
 - [Adversarial Evaluation](ADVERSARIAL.md) - Red team samples and ADR results
-- [Security Policy](SECURITY.md) - Detection rules reference (162 rules)
+- [Security Policy](SECURITY.md) - Detection rules reference (176 rules)
 - [Security Audit](docs/SECURITY_AUDIT.md) - Bypass validation report
 - [FP Analysis](docs/EVALUATION.md) - Historical false positive analysis
 

package/bin/muaddib.js

@@ -1,4 +1,26 @@
 #!/usr/bin/env node
+
+// Auto-respawn with memory flags for evaluate command (OOM prevention)
+if (process.argv[2] === 'evaluate') {
+  const hasMaxOld = process.execArgv.some(a => a.includes('--max-old-space-size'));
+  const hasGC = process.execArgv.some(a => a === '--expose-gc');
+  if (!hasMaxOld || !hasGC) {
+    const { execFileSync } = require('child_process');
+    const flags = [];
+    if (!hasMaxOld) flags.push('--max-old-space-size=8192');
+    if (!hasGC) flags.push('--expose-gc');
+    try {
+      execFileSync(process.execPath, [...flags, __filename, ...process.argv.slice(2)], {
+        stdio: 'inherit',
+        env: process.env
+      });
+      process.exit(0);
+    } catch (e) {
+      process.exit(e.status || 1);
+    }
+  }
+}
+
 const { execFile } = require('child_process');
 const { run } = require('../src/index.js');
 const { updateIOCs } = require('../src/ioc/updater.js');
@@ -13,6 +35,9 @@ const args = process.argv.slice(2);
 const command = args[0];
 const options = args.slice(1);
 
+// Helper: detect --help / -h in options
+const wantHelp = options.includes('--help') || options.includes('-h');
+
 // Parse options
 let target = '.';
 let jsonOutput = false;
@@ -394,19 +419,45 @@ const helpText = `
     muaddib diff <ref> [path]        Compare threats with a previous version
     muaddib install <pkg> [options]  Safe install (scan before install)
     muaddib watch [path]             Watch in real-time
+    muaddib sandbox <pkg> [options]  Analyze in isolated Docker container
+    muaddib sandbox-report <pkg>     Sandbox + detailed network report
+    muaddib evaluate [options]       Run TPR/FPR/ADR evaluation suite
+    muaddib monitor [options]        Start real-time npm/PyPI monitor
     muaddib daemon [options]         Start daemon
     muaddib init-hooks [options]     Setup git pre-commit hooks
     muaddib remove-hooks [path]      Remove MUAD'DIB git hooks
     muaddib update                   Update IOCs
     muaddib scrape                   Scrape new IOCs
-    muaddib sandbox <pkg> [--strict] [--no-canary]  Analyze in isolated Docker container
-    muaddib sandbox-report <pkg>     Sandbox + detailed network report
+    muaddib feed [options]           Threat feed (JSON)
+    muaddib serve [options]          Threat feed HTTP server
+    muaddib detections [options]     View monitor detections
+    muaddib stats [options]          View scan statistics
+    muaddib replay [options]         Replay ground-truth attacks
     muaddib version                  Show version
 
-  Replay Options:
-    --verbose           Show detailed findings per attack
-    --json              Machine-readable JSON output
-    GT-NNN              Replay single attack by ID
+  Scan Options:
+    --json              JSON output
+    --html [file]       HTML report (default: muaddib-report.html)
+    --sarif [file]      SARIF report (default: muaddib-results.sarif)
+    --explain           Detailed explanations with MITRE references
+    --breakdown         Show score breakdown by threat
+    --fail-on [level]   Exit code threshold (critical|high|medium|low, default: high)
+    --webhook [url]     Discord/Slack webhook (HTTPS only)
+    --paranoid          Ultra-strict detection mode
+    --exclude [dir]     Exclude directory from scan (repeatable)
+    --config [file]     Custom config file (.muaddibrc.json format)
+    --entropy-threshold [n]  Custom entropy threshold (0-8, default: 5.5)
+    --no-deobfuscate    Disable deobfuscation pre-processing
+    --no-module-graph   Disable cross-file dataflow analysis
+    --no-reachability   Disable entry-point reachability analysis
+    --auto-sandbox      Auto-trigger sandbox when static scan score >= 20 (requires Docker)
+
+  Temporal Options (scan):
+    --temporal          Detect sudden lifecycle script changes
+    --temporal-ast      Detect sudden dangerous API additions via AST diff
+    --temporal-publish  Detect publish frequency anomalies
+    --temporal-maintainer  Detect maintainer changes
+    --temporal-full     All temporal analyses combined
 
   Diff Examples:
     muaddib diff HEAD~1              Compare with previous commit
@@ -414,40 +465,303 @@ const helpText = `
     muaddib diff main                Compare with branch
     muaddib diff abc1234 ./myproject Compare specific commit
 
+  Install Options:
+    --save-dev, -D      Install as dev dependency
+    -g, --global        Install globally
+    --force             Force install despite threats
+
+  Sandbox Options:
+    --local             Analyze a local path instead of npm package
+    --strict            Block non-essential network access
+    --no-canary         Disable honey token injection
+
   Init-hooks Options:
     --type [auto|husky|pre-commit|git]  Hook system (default: auto)
     --mode [scan|diff]                  scan=all threats, diff=new only
 
+  Evaluate Options:
+    --json              JSON output
+    --benign-limit [n]  Limit benign packages to scan
+    --refresh-benign    Re-download benign packages
+
+  Feed/Serve Options:
+    --limit [n]         Limit feed entries (default: 50)
+    --severity [level]  Filter by severity (CRITICAL|HIGH|MEDIUM|LOW)
+    --since [date]      Filter detections after date (ISO 8601)
+    --port [n]          HTTP server port (default: 3000)
+
+  Monitor Options:
+    --verbose           Show detailed output
+    --temporal --test <pkg>      Test temporal analysis on a single package
+    --temporal-ast --test <pkg>  Test AST diff on a single package
+
+  Detections Options:
+    --json              JSON output
+    --stats             Show aggregated detection statistics
+
+  Stats Options:
+    --json              JSON output
+    --daily             Show daily breakdown (last 7 days)
+
+  Replay Options:
+    --verbose           Show detailed findings per attack
+    --json              Machine-readable JSON output
+    GT-NNN              Replay single attack by ID
+`;
+
+// Per-command help texts for subcommand --help
+const commandHelp = {
+  scan: `
+  Usage: muaddib scan [path] [options]
+
+  Scan a project for supply-chain threats.
+
+  Arguments:
+    path                Target directory to scan (default: .)
+
   Options:
     --json              JSON output
-    --html [file]       HTML report
-    --sarif [file]      SARIF report (GitHub Security)
-    --explain           Detailed explanations
+    --html [file]       HTML report (default: muaddib-report.html)
+    --sarif [file]      SARIF report (default: muaddib-results.sarif)
+    --explain           Detailed explanations with MITRE references
     --breakdown         Show score breakdown by threat
-    --fail-on [level]   Fail level (critical|high|medium|low)
-    --webhook [url]     Discord/Slack webhook
-    --paranoid          Ultra-strict mode
-    --temporal          Detect sudden lifecycle script changes (network requests per package)
-    --temporal-ast      Detect sudden dangerous API additions via AST diff (downloads tarballs)
-    --temporal-publish  Detect publish frequency anomalies (bursts, dormant spikes)
-    --temporal-maintainer  Detect maintainer changes (new maintainer, account takeover)
-    --temporal-full     All temporal analyses (lifecycle + AST + publish + maintainer)
-    --auto-sandbox      Auto-trigger sandbox when static scan score >= 20 (requires Docker)
-    --no-canary         Disable honey token injection in sandbox
+    --fail-on [level]   Exit code threshold (critical|high|medium|low, default: high)
+    --webhook [url]     Discord/Slack webhook (HTTPS only)
+    --paranoid          Ultra-strict detection mode
+    --exclude [dir]     Exclude directory from scan (repeatable)
+    --config [file]     Custom config file (.muaddibrc.json format)
+    --entropy-threshold [n]  Custom entropy threshold (0-8, default: 5.5)
     --no-deobfuscate    Disable deobfuscation pre-processing
     --no-module-graph   Disable cross-file dataflow analysis
     --no-reachability   Disable entry-point reachability analysis
-    --exclude [dir]     Exclude directory from scan (repeatable)
-    --limit [n]         Limit feed entries (default: 50)
-    --severity [level]  Filter by severity (CRITICAL|HIGH|MEDIUM|LOW)
-    --since [date]      Filter detections after date (ISO 8601)
-    --port [n]          HTTP server port (default: 3000, serve only)
-    --entropy-threshold [n]  Custom string-level entropy threshold (default: 5.5)
-    --config [file]     Custom config file (.muaddibrc.json format)
+    --auto-sandbox      Auto-trigger sandbox when static scan score >= 20 (requires Docker)
+    --temporal          Detect sudden lifecycle script changes
+    --temporal-ast      Detect sudden dangerous API additions
+    --temporal-publish  Detect publish frequency anomalies
+    --temporal-maintainer  Detect maintainer changes
+    --temporal-full     All temporal analyses combined
+
+  Examples:
+    muaddib scan .
+    muaddib scan ./my-project --explain --paranoid
+    muaddib scan . --json > results.json
+    muaddib scan . --html report.html --explain
+`,
+  diff: `
+  Usage: muaddib diff <ref> [path] [options]
+
+  Compare threats between two versions of a project.
+  Without <ref>, shows available tags and recent commits.
+
+  Arguments:
+    ref                 Commit hash, tag, or branch to compare with
+    path                Target directory (default: .)
+
+  Options:
+    --json              JSON output
+    --explain           Detailed explanations
+    --fail-on [level]   Exit code threshold (critical|high|medium|low)
+    --paranoid          Ultra-strict detection mode
+
+  Examples:
+    muaddib diff HEAD~1
+    muaddib diff v1.2.0
+    muaddib diff main ./myproject
+`,
+  install: `
+  Usage: muaddib install <package> [<package>...] [options]
+
+  Scan packages for threats before installing them.
+
+  Options:
     --save-dev, -D      Install as dev dependency
     -g, --global        Install globally
-    --force             Force install despite threats
-`;
+    --force             Force install despite detected threats
+
+  Examples:
+    muaddib install lodash
+    muaddib install express morgan --save-dev
+    muaddib install -g typescript
+`,
+  sandbox: `
+  Usage: muaddib sandbox <package-name|path> [options]
+
+  Run dynamic analysis in an isolated Docker container.
+  Requires Docker to be installed and running.
+
+  Options:
+    --local             Analyze a local path instead of npm package
+    --strict            Block non-essential network access
+    --no-canary         Disable honey token injection
+
+  Examples:
+    muaddib sandbox suspicious-pkg
+    muaddib sandbox ./local-pkg --local --strict
+`,
+  'sandbox-report': `
+  Usage: muaddib sandbox-report <package-name|path> [options]
+
+  Run sandbox analysis with detailed network traffic report.
+  Same options as 'muaddib sandbox'.
+`,
+  evaluate: `
+  Usage: muaddib evaluate [options]
+
+  Run the full TPR/FPR/ADR evaluation suite against ground truth,
+  benign packages, and adversarial samples.
+
+  Options:
+    --json              JSON output
+    --benign-limit [n]  Limit benign packages to scan
+    --refresh-benign    Re-download benign packages
+
+  Examples:
+    muaddib evaluate
+    muaddib evaluate --json > eval-results.json
+`,
+  monitor: `
+  Usage: muaddib monitor [options]
+
+  Start real-time monitoring of npm/PyPI registries for
+  newly published malicious packages.
+
+  Options:
+    --verbose                        Show detailed output
+    --temporal --test <pkg>          Test temporal analysis on a single package
+    --temporal-ast --test <pkg>      Test AST diff on a single package
+
+  Examples:
+    muaddib monitor
+    muaddib monitor --verbose
+    muaddib monitor --temporal --test lodash
+`,
+  feed: `
+  Usage: muaddib feed [options]
+
+  Output the threat detection feed as JSON.
+
+  Options:
+    --limit [n]         Limit entries (default: 50)
+    --severity [level]  Filter by severity (CRITICAL|HIGH|MEDIUM|LOW)
+    --since [date]      Filter after date (ISO 8601)
+
+  Examples:
+    muaddib feed
+    muaddib feed --severity CRITICAL --limit 10
+`,
+  serve: `
+  Usage: muaddib serve [options]
+
+  Start an HTTP server serving the threat feed.
+
+  Options:
+    --port [n]          Server port (default: 3000)
+
+  Examples:
+    muaddib serve
+    muaddib serve --port 8080
+`,
+  detections: `
+  Usage: muaddib detections [options]
+
+  View detections recorded by the monitor.
+
+  Options:
+    --json              Full JSON output
+    --stats             Show aggregated detection statistics
+
+  Examples:
+    muaddib detections
+    muaddib detections --stats
+    muaddib detections --json > detections.json
+`,
+  stats: `
+  Usage: muaddib stats [options]
+
+  View scan statistics from the monitor.
+
+  Options:
+    --json              JSON output
+    --daily             Show daily breakdown (last 7 days)
+
+  Examples:
+    muaddib stats
+    muaddib stats --daily
+`,
+  replay: `
+  Usage: muaddib replay [options] [GT-NNN]
+
+  Replay ground-truth attack samples to verify detection.
+
+  Options:
+    --verbose, -v       Show detailed findings per attack
+    --json              Machine-readable JSON output
+    GT-NNN              Replay a single attack by ID
+
+  Examples:
+    muaddib replay
+    muaddib replay --verbose
+    muaddib replay GT-001
+`,
+  'init-hooks': `
+  Usage: muaddib init-hooks [options]
+
+  Setup git pre-commit hooks for automatic scanning.
+
+  Options:
+    --type [auto|husky|pre-commit|git]  Hook system (default: auto)
+    --mode [scan|diff]                  scan=all threats, diff=new only
+
+  Examples:
+    muaddib init-hooks
+    muaddib init-hooks --type husky --mode diff
+`,
+  'remove-hooks': `
+  Usage: muaddib remove-hooks [path]
+
+  Remove MUAD'DIB git hooks from a project.
+`,
+  watch: `
+  Usage: muaddib watch [path]
+
+  Watch a project directory and re-scan on file changes.
+
+  Examples:
+    muaddib watch
+    muaddib watch ./my-project
+`,
+  daemon: `
+  Usage: muaddib daemon [options]
+
+  Start the MUAD'DIB daemon for background monitoring.
+
+  Options:
+    --webhook [url]     Discord/Slack webhook URL
+
+  Examples:
+    muaddib daemon
+    muaddib daemon --webhook https://discord.com/api/webhooks/...
+`,
+  report: `
+  Usage: muaddib report --now | --status
+
+  Send or check status of daily monitor reports.
+
+  Options:
+    --now               Send report immediately
+    --status            Show report status
+`,
+};
+
+// Show per-command help or global help
+function showHelp(cmd) {
+  if (cmd && commandHelp[cmd]) {
+    console.log(commandHelp[cmd]);
+  } else {
+    console.log(helpText);
+  }
+  process.exit(0);
+}
 
 // Main
 if (command === 'version' || command === '--version' || command === '-v') {
@@ -456,18 +770,14 @@ if (command === 'version' || command === '--version' || command === '-v') {
   process.exit(0);
 } else if (!command || command === '--help' || command === '-h') {
   if (command === '--help' || command === '-h') {
-    console.log(helpText);
-    process.exit(0);
+    showHelp();
   }
   interactiveMenu().catch(err => {
     console.error('[ERROR]', err.message);
     process.exit(1);
   });
 } else if (command === 'scan') {
-  if (options.includes('--help') || options.includes('-h')) {
-    console.log(helpText);
-    process.exit(0);
-  }
+  if (wantHelp) showHelp('scan');
   run(target, {
     json: jsonOutput,
     html: htmlOutput,
@@ -495,6 +805,7 @@ if (command === 'version' || command === '--version' || command === '-v') {
     process.exit(1);
   });
 } else if (command === 'feed') {
+  if (wantHelp) showHelp('feed');
   const { getFeed } = require('../src/threat-feed.js');
   const feedOpts = {};
   if (feedLimit) feedOpts.limit = feedLimit;
@@ -504,10 +815,12 @@ if (command === 'version' || command === '--version' || command === '-v') {
   console.log(JSON.stringify(result, null, 2));
   process.exit(0);
 } else if (command === 'serve') {
+  if (wantHelp) showHelp('serve');
   const { startServer } = require('../src/serve.js');
   startServer({ port: servePort || 3000 });
   // Server runs indefinitely — no process.exit
 } else if (command === 'watch') {
+  if (wantHelp) showHelp('watch');
   watch(target);
 } else if (command === 'update') {
   updateIOCs().then(() => {
@@ -525,6 +838,7 @@ if (command === 'version' || command === '--version' || command === '-v') {
     process.exit(1);
   });
 } else if (command === 'monitor') {
+  if (wantHelp) showHelp('monitor');
   const testPkg = options.filter(o => !o.startsWith('-'));
   const isTemporal = options.includes('--temporal');
   const isTemporalAst = options.includes('--temporal-ast');
@@ -614,9 +928,11 @@ if (command === 'version' || command === '--version' || command === '-v') {
     });
   }
 } else if (command === 'daemon') {
+  if (wantHelp) showHelp('daemon');
   const { startDaemon } = require('../src/daemon.js');
   startDaemon({ webhook: webhookUrl });
 } else if (command === 'install' || command === 'i') {
+  if (wantHelp) showHelp('install');
   const packages = options.filter(o => !o.startsWith('-'));
   const isDev = options.includes('--save-dev') || options.includes('-D');
   const isGlobal = options.includes('-g') || options.includes('--global');
@@ -637,13 +953,14 @@ if (command === 'version' || command === '--version' || command === '-v') {
     process.exit(1);
   });
 } else if (command === 'sandbox') {
+  if (wantHelp) showHelp('sandbox');
   const sandboxOpts = options.filter(o => !o.startsWith('-'));
   const packageName = sandboxOpts[0];
   const strict = options.includes('--strict');
   const canary = !options.includes('--no-canary');
   const local = options.includes('--local');
   if (!packageName) {
-    console.log('Usage: muaddib sandbox <package-name|path> [--local] [--strict] [--no-canary]');
+    console.log(commandHelp['sandbox']);
     process.exit(1);
   }
 
@@ -657,13 +974,14 @@ if (command === 'version' || command === '--version' || command === '-v') {
       process.exit(1);
     });
 } else if (command === 'sandbox-report') {
+  if (wantHelp) showHelp('sandbox-report');
   const sandboxOpts = options.filter(o => !o.startsWith('-'));
   const packageName = sandboxOpts[0];
   const strict = options.includes('--strict');
   const canary = !options.includes('--no-canary');
   const local = options.includes('--local');
   if (!packageName) {
-    console.log('Usage: muaddib sandbox-report <package-name|path> [--local] [--strict] [--no-canary]');
+    console.log(commandHelp['sandbox-report']);
     process.exit(1);
   }
 
@@ -680,6 +998,7 @@ if (command === 'version' || command === '--version' || command === '-v') {
       process.exit(1);
     });
 } else if (command === 'diff') {
+  if (wantHelp) showHelp('diff');
   // Parse diff arguments: muaddib diff <ref> [path] [options]
   const diffArgs = options.filter(o => !o.startsWith('-'));
   const baseRef = diffArgs[0];
@@ -702,6 +1021,7 @@ if (command === 'version' || command === '--version' || command === '-v') {
     process.exit(1);
   });
 } else if (command === 'detections') {
+  if (wantHelp) showHelp('detections');
   const { loadDetections, getDetectionStats } = require('../src/monitor.js');
   const wantStats = options.includes('--stats');
   const wantJson = options.includes('--json');
@@ -753,6 +1073,7 @@ if (command === 'version' || command === '--version' || command === '-v') {
   console.log('');
   process.exit(0);
 } else if (command === 'stats') {
+  if (wantHelp) showHelp('stats');
   const { loadScanStats } = require('../src/monitor.js');
   const wantDaily = options.includes('--daily');
   const wantJson = options.includes('--json');
@@ -796,6 +1117,7 @@ if (command === 'version' || command === '--version' || command === '-v') {
   console.log('');
   process.exit(0);
 } else if (command === 'evaluate') {
+  if (wantHelp) showHelp('evaluate');
   const { evaluate } = require('../src/commands/evaluate.js');
   const evalOpts = { json: jsonOutput };
   for (let i = 0; i < options.length; i++) {
@@ -813,6 +1135,7 @@ if (command === 'version' || command === '--version' || command === '-v') {
     process.exit(1);
   });
 } else if (command === 'init-hooks') {
+  if (wantHelp) showHelp('init-hooks');
   // Parse init-hooks arguments
   let hookType = 'auto';
   let hookMode = 'scan';
@@ -834,6 +1157,7 @@ if (command === 'version' || command === '--version' || command === '-v') {
     process.exit(1);
   });
 } else if (command === 'remove-hooks') {
+  if (wantHelp) showHelp('remove-hooks');
   removeHooks(target).then(success => {
     process.exit(success ? 0 : 1);
   }).catch(err => {
@@ -841,6 +1165,7 @@ if (command === 'version' || command === '--version' || command === '-v') {
     process.exit(1);
   });
 } else if (command === 'replay' || command === 'ground-truth') {
+  if (wantHelp) showHelp('replay');
   const { replay } = require('../tests/ground-truth/replay.js');
   const replayOpts = {};
   for (const o of options) {
@@ -858,7 +1183,7 @@ if (command === 'version' || command === '--version' || command === '-v') {
     process.exit(1);
   });
 } else if (command === 'report') {
-  // Hidden/internal — not in --help
+  if (wantHelp) showHelp('report');
   if (options.includes('--now')) {
     const { sendReportNow } = require('../src/monitor.js');
     sendReportNow().then(result => {
@@ -889,8 +1214,9 @@ if (command === 'version' || command === '--version' || command === '-v') {
     process.exit(1);
   }
 } else if (command === 'help') {
-  console.log(helpText);
-  process.exit(0);
+  // muaddib help <command> — show per-command help
+  const helpCmd = options.filter(o => !o.startsWith('-'))[0];
+  showHelp(helpCmd);
 } else {
   console.log(`Unknown command: ${String(command).replace(/[\x00-\x1f\x7f-\x9f]/g, '')}`);
   console.log('Type "muaddib help" to see available commands.');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "muaddib-scanner",
-  "version": "2.10.21",
+  "version": "2.10.23",
   "description": "Supply-chain threat detection & response for npm & PyPI/Python",
   "main": "src/index.js",
   "bin": {