muaddib-scanner 2.9.6 → 2.9.8

package/bin/muaddib.js

@@ -33,6 +33,7 @@ let breakdownMode = false;
 let noDeobfuscate = false;
 let noModuleGraph = false;
 let noReachability = false;
+let configPath = null;
 let feedLimit = null;
 let feedSeverity = null;
 let feedSince = null;
@@ -124,6 +125,18 @@ for (let i = 0; i < options.length; i++) {
     noModuleGraph = true;
   } else if (options[i] === '--no-reachability') {
     noReachability = true;
+  } else if (options[i] === '--config') {
+    const cfgPath = options[i + 1];
+    if (!cfgPath || cfgPath.startsWith('-')) {
+      console.error('[ERROR] --config requires a file path argument');
+      process.exit(1);
+    }
+    if (cfgPath.includes('..')) {
+      console.error('[ERROR] --config path must not contain path traversal (..)');
+      process.exit(1);
+    }
+    configPath = cfgPath;
+    i++;
   } else if (options[i] === '--temporal') {
     temporalMode = true;
   } else if (options[i] === '--limit') {
@@ -426,6 +439,7 @@ const helpText = `
     --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)
     --save-dev, -D      Install as dev dependency
     -g, --global        Install globally
     --force             Force install despite threats
@@ -467,7 +481,8 @@ if (command === 'version' || command === '--version' || command === '-v') {
     breakdown: breakdownMode,
     noDeobfuscate: noDeobfuscate,
     noModuleGraph: noModuleGraph,
-    noReachability: noReachability
+    noReachability: noReachability,
+    configPath: configPath
   }).then(exitCode => {
     process.exit(exitCode);
   }).catch(err => {

package/package.json

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

package/scripts/sample-npm-random.js

@@ -0,0 +1,339 @@
+#!/usr/bin/env node
+/**
+ * MUAD'DIB — npm Random Package Sampler
+ *
+ * Samples 200 packages from the npm registry by stratified random sampling.
+ * Used to measure FPR on a representative npm sample (not curated).
+ *
+ * Strata (by dependency count):
+ *   small  (<10 deps):   80 packages  (40%)
+ *   medium (10-50 deps):  60 packages  (30%)
+ *   large  (50-100 deps): 40 packages  (20%)
+ *   vlarge (100+ deps):   20 packages  (10%)
+ *
+ * Exclusions: @types/*, deprecated, already in packages-npm.txt
+ *
+ * Usage:
+ *   node scripts/sample-npm-random.js [--seed N] [--output path]
+ */
+
+const https = require('https');
+const fs = require('fs');
+const path = require('path');
+
+const ROOT = path.join(__dirname, '..');
+const CURATED_FILE = path.join(ROOT, 'datasets', 'benign', 'packages-npm.txt');
+const DEFAULT_OUTPUT = path.join(ROOT, 'datasets', 'benign', 'packages-npm-random.txt');
+
+const STRATA = {
+  small:  { min: 0,   max: 9,   quota: 80 },
+  medium: { min: 10,  max: 50,  quota: 60 },
+  large:  { min: 51,  max: 100, quota: 40 },
+  vlarge: { min: 101, max: Infinity, quota: 20 }
+};
+
+// Search keywords — diverse enough to sample across npm
+const SEARCH_KEYWORDS = [
+  'util', 'helper', 'config', 'server', 'client', 'api', 'data',
+  'file', 'string', 'array', 'json', 'http', 'url', 'path', 'stream',
+  'log', 'debug', 'test', 'mock', 'format', 'parse', 'transform',
+  'crypto', 'hash', 'encode', 'decode', 'compress', 'cache', 'queue',
+  'event', 'promise', 'async', 'callback', 'middleware', 'router',
+  'database', 'mongo', 'redis', 'sql', 'orm', 'schema', 'validate',
+  'cli', 'terminal', 'color', 'progress', 'spinner', 'prompt',
+  'image', 'pdf', 'csv', 'xml', 'yaml', 'markdown', 'html',
+  'email', 'auth', 'token', 'session', 'cookie', 'proxy',
+  'date', 'time', 'math', 'random', 'uuid', 'id', 'slug',
+  'webpack', 'babel', 'eslint', 'prettier', 'rollup', 'vite',
+  'react', 'vue', 'angular', 'svelte', 'solid', 'preact',
+  'express', 'koa', 'fastify', 'socket', 'graphql', 'rest',
+  'aws', 'azure', 'gcp', 'docker', 'kubernetes', 'ci',
+  'i18n', 'locale', 'charset', 'buffer', 'binary', 'hex',
+  'retry', 'timeout', 'rate', 'limit', 'throttle', 'debounce',
+  'merge', 'deep', 'clone', 'diff', 'patch', 'compare',
+  'glob', 'pattern', 'regex', 'match', 'search', 'filter',
+  'tree', 'graph', 'list', 'map', 'set', 'stack',
+  'plugin', 'loader', 'adapter', 'wrapper', 'bridge', 'connector'
+];
+
+// Seeded PRNG (mulberry32) for reproducibility
+function mulberry32(seed) {
+  return function() {
+    seed |= 0; seed = seed + 0x6D2B79F5 | 0;
+    let t = Math.imul(seed ^ seed >>> 15, 1 | seed);
+    t = t + Math.imul(t ^ t >>> 7, 61 | t) ^ t;
+    return ((t ^ t >>> 14) >>> 0) / 4294967296;
+  };
+}
+
+function shuffleArray(arr, rng) {
+  for (let i = arr.length - 1; i > 0; i--) {
+    const j = Math.floor(rng() * (i + 1));
+    [arr[i], arr[j]] = [arr[j], arr[i]];
+  }
+  return arr;
+}
+
+function httpsGet(url) {
+  return new Promise((resolve, reject) => {
+    const req = https.get(url, { timeout: 15000 }, (res) => {
+      if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+        httpsGet(res.headers.location).then(resolve).catch(reject);
+        return;
+      }
+      if (res.statusCode !== 200) {
+        res.resume();
+        reject(new Error(`HTTP ${res.statusCode} for ${url}`));
+        return;
+      }
+      let data = '';
+      res.on('data', chunk => data += chunk);
+      res.on('end', () => {
+        try { resolve(JSON.parse(data)); }
+        catch (e) { reject(new Error(`JSON parse error: ${e.message}`)); }
+      });
+    });
+    req.on('error', reject);
+    req.on('timeout', () => { req.destroy(); reject(new Error('timeout')); });
+  });
+}
+
+/**
+ * Search npm registry for packages matching a keyword.
+ * Returns array of { name, version } objects.
+ */
+async function searchNpm(keyword, from = 0, size = 250) {
+  const url = `https://registry.npmjs.org/-/v1/search?text=${encodeURIComponent(keyword)}&size=${size}&from=${from}`;
+  try {
+    const data = await httpsGet(url);
+    return (data.objects || []).map(o => ({
+      name: o.package.name,
+      version: o.package.version,
+      description: o.package.description || '',
+      deprecated: o.package.deprecated || false
+    }));
+  } catch (err) {
+    console.error(`  [WARN] npm search "${keyword}" failed: ${err.message}`);
+    return [];
+  }
+}
+
+/**
+ * Get dependency count for a package via npm view.
+ * Returns { deps, devDeps } or null on failure.
+ */
+async function getDepCount(pkgName) {
+  const url = `https://registry.npmjs.org/${encodeURIComponent(pkgName)}/latest`;
+  try {
+    const data = await httpsGet(url);
+    const deps = data.dependencies ? Object.keys(data.dependencies).length : 0;
+    const devDeps = data.devDependencies ? Object.keys(data.devDependencies).length : 0;
+    return { deps, devDeps, totalDeps: deps + devDeps };
+  } catch {
+    return null;
+  }
+}
+
+function classifyStratum(depCount) {
+  for (const [name, { min, max }] of Object.entries(STRATA)) {
+    if (depCount >= min && depCount <= max) return name;
+  }
+  return 'small';
+}
+
+function loadCuratedPackages() {
+  try {
+    return new Set(
+      fs.readFileSync(CURATED_FILE, 'utf8')
+        .split(/\r?\n/)
+        .map(l => l.trim())
+        .filter(l => l && !l.startsWith('#'))
+    );
+  } catch {
+    return new Set();
+  }
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  let seed = 42;
+  let outputPath = DEFAULT_OUTPUT;
+
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--seed' && args[i + 1]) { seed = parseInt(args[i + 1], 10); i++; }
+    if (args[i] === '--output' && args[i + 1]) { outputPath = args[i + 1]; i++; }
+  }
+
+  const rng = mulberry32(seed);
+  const curated = loadCuratedPackages();
+  console.log(`  Loaded ${curated.size} curated packages to exclude`);
+  console.log(`  Seed: ${seed}`);
+
+  // Phase 1: Collect candidate packages from npm search
+  console.log(`\n  [1/3] Collecting candidates from npm search...`);
+  const candidates = new Map(); // name -> { name, version, description }
+  const shuffledKeywords = shuffleArray([...SEARCH_KEYWORDS], rng);
+
+  for (let i = 0; i < shuffledKeywords.length; i++) {
+    const keyword = shuffledKeywords[i];
+    if (process.stdout.isTTY) {
+      process.stdout.write(`\r  Searching "${keyword}" (${i + 1}/${shuffledKeywords.length})...          `);
+    }
+
+    // Search with random offset for diversity
+    const offset = Math.floor(rng() * 200);
+    const results = await searchNpm(keyword, offset, 250);
+
+    for (const pkg of results) {
+      // Exclusion filters
+      if (candidates.has(pkg.name)) continue;
+      if (curated.has(pkg.name)) continue;
+      if (pkg.name.startsWith('@types/')) continue;
+      if (pkg.deprecated) continue;
+      if (pkg.name.startsWith('_')) continue;
+
+      candidates.set(pkg.name, pkg);
+    }
+
+    // Stop early if we have enough candidates
+    if (candidates.size >= 2000) break;
+
+    // Rate limiting: ~100ms between requests
+    await new Promise(r => setTimeout(r, 100));
+  }
+
+  if (process.stdout.isTTY) {
+    process.stdout.write('\r' + ''.padEnd(80) + '\r');
+  }
+  console.log(`  Collected ${candidates.size} unique candidates`);
+
+  // Phase 2: Classify by dependency count
+  // Over-collect: allow 2x quota per stratum to enable backfill
+  console.log(`\n  [2/3] Classifying by dependency count...`);
+  const buckets = { small: [], medium: [], large: [], vlarge: [] };
+  const candidateList = shuffleArray([...candidates.keys()], rng);
+
+  const totalQuota = Object.values(STRATA).reduce((s, v) => s + v.quota, 0);
+  let classified = 0;
+  let processed = 0;
+  // Over-collect limit: 2x quota per stratum to provide backfill pool
+  const OVER_COLLECT = 2;
+
+  for (const pkgName of candidateList) {
+    // Check if all buckets have enough for backfill
+    const allOverCollected = Object.entries(STRATA).every(
+      ([name, { quota }]) => buckets[name].length >= quota * OVER_COLLECT
+    );
+    if (allOverCollected) break;
+
+    processed++;
+    if (process.stdout.isTTY && processed % 10 === 0) {
+      const bucketStatus = Object.entries(buckets).map(([k, v]) => `${k}:${v.length}/${STRATA[k].quota}`).join(' ');
+      process.stdout.write(`\r  Classifying [${processed}/${candidateList.length}] ${bucketStatus}          `);
+    }
+
+    const info = await getDepCount(pkgName);
+    if (!info) continue;
+
+    const stratum = classifyStratum(info.totalDeps);
+    if (buckets[stratum].length < STRATA[stratum].quota * OVER_COLLECT) {
+      buckets[stratum].push({ name: pkgName, deps: info.totalDeps, stratum });
+      classified++;
+    }
+
+    // Rate limiting
+    await new Promise(r => setTimeout(r, 50));
+  }
+
+  if (process.stdout.isTTY) {
+    process.stdout.write('\r' + ''.padEnd(80) + '\r');
+  }
+
+  // Phase 3: Output with backfill
+  // If large/vlarge strata can't meet quota, redistribute remaining slots
+  // to small/medium proportionally (reflects real npm distribution).
+  console.log(`\n  [3/3] Writing results...`);
+  const selected = [];
+  let deficit = 0;
+  for (const [name, { quota }] of Object.entries(STRATA)) {
+    const actual = Math.min(buckets[name].length, quota);
+    console.log(`    ${name}: ${actual}/${quota} packages`);
+    selected.push(...buckets[name].slice(0, actual));
+    deficit += quota - actual;
+  }
+
+  // Backfill deficit from small/medium overflow (proportional)
+  if (deficit > 0) {
+    console.log(`    Backfilling ${deficit} slots from small/medium overflow...`);
+    const backfillSources = ['small', 'medium']; // priority order
+    for (const src of backfillSources) {
+      if (deficit <= 0) break;
+      const overflow = buckets[src].slice(STRATA[src].quota);
+      const take = Math.min(overflow.length, deficit);
+      if (take > 0) {
+        selected.push(...overflow.slice(0, take));
+        deficit -= take;
+        console.log(`      +${take} from ${src} overflow`);
+      }
+    }
+  }
+
+  const totalSelected = selected.length;
+  console.log(`\n  Total: ${totalSelected}/200 packages`);
+
+  if (totalSelected < 200) {
+    console.warn(`\n  [WARN] Only ${totalSelected} packages found. Re-run with different --seed or add more search keywords.`);
+  }
+
+  // Write output file
+  // Use a Set to track already-written packages (avoid duplication from backfill)
+  const writtenNames = new Set();
+  const header = [
+    '# MUAD\'DIB Benign Random Dataset — npm stratified random sample',
+    `# Generated: ${new Date().toISOString()}`,
+    `# Seed: ${seed}`,
+    `# Total: ${totalSelected} packages`,
+    '# Strata: small (<10 deps): 80, medium (10-50): 60, large (51-100): 40, vlarge (100+): 20',
+    '# Backfill: unfilled large/vlarge slots redistributed to small/medium',
+    '# Used by `muaddib evaluate` to measure FPR on representative npm sample',
+    ''
+  ];
+
+  const lines = [];
+  for (const [name, { quota }] of Object.entries(STRATA)) {
+    const actual = Math.min(buckets[name].length, quota);
+    lines.push(`# === ${name} (${actual}/${quota}) ===`);
+    for (const pkg of buckets[name].slice(0, actual)) {
+      lines.push(pkg.name);
+      writtenNames.add(pkg.name);
+    }
+    lines.push('');
+  }
+
+  // Backfill section (additional packages from overflow)
+  const backfillPkgs = selected.filter(p => !writtenNames.has(p.name));
+  if (backfillPkgs.length > 0) {
+    lines.push(`# === backfill (${backfillPkgs.length}) ===`);
+    for (const pkg of backfillPkgs) {
+      lines.push(pkg.name);
+    }
+    lines.push('');
+  }
+
+  fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+  fs.writeFileSync(outputPath, header.join('\n') + lines.join('\n'));
+  console.log(`  Written to: ${path.relative(ROOT, outputPath)}`);
+
+  // Verify no overlap with curated
+  const overlap = selected.filter(p => curated.has(p.name));
+  if (overlap.length > 0) {
+    console.error(`\n  [ERROR] ${overlap.length} packages overlap with curated corpus: ${overlap.map(p => p.name).join(', ')}`);
+  } else {
+    console.log('  No overlap with curated corpus');
+  }
+}
+
+main().catch(err => {
+  console.error(`[ERROR] ${err.message}`);
+  process.exit(1);
+});

package/src/config.js

@@ -0,0 +1,250 @@
+/**
+ * MUAD'DIB Configuration Loader
+ *
+ * Loads and validates .muaddibrc.json configuration files.
+ * All fields are optional — missing values fall back to hardcoded defaults.
+ *
+ * Configurable: riskThresholds, maxFileSize, severityWeights
+ * NOT configurable: ADR_THRESHOLD, BENIGN_THRESHOLD, GT_THRESHOLD (evaluation constants),
+ *   FP_COUNT_THRESHOLDS, CONFIDENCE_FACTORS (too granular, modifying without expertise breaks the model)
+ *
+ * Security: parsed into Object.create(null) to prevent prototype pollution.
+ * Config files > 10KB are rejected (no legitimate config is that large).
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const MAX_CONFIG_SIZE = 10 * 1024; // 10KB
+
+const DEFAULTS = Object.freeze({
+  riskThresholds: Object.freeze({ critical: 75, high: 50, medium: 25 }),
+  maxFileSize: 10 * 1024 * 1024, // 10MB
+  severityWeights: Object.freeze({ critical: 25, high: 10, medium: 3, low: 1 })
+});
+
+const VALID_TOP_KEYS = new Set(['riskThresholds', 'maxFileSize', 'severityWeights']);
+const PROTO_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+
+/**
+ * Load and parse a JSON config file.
+ * Uses JSON.parse (never require) to prevent code execution.
+ * @param {string} filePath - absolute path to config file
+ * @returns {{ raw: object|null, error: string|null }}
+ */
+function loadConfigFile(filePath) {
+  try {
+    const stat = fs.statSync(filePath);
+    if (stat.size > MAX_CONFIG_SIZE) {
+      return { raw: null, error: `Config file exceeds 10KB limit (${stat.size} bytes)` };
+    }
+    const content = fs.readFileSync(filePath, 'utf8');
+    // Parse into null-prototype object to prevent prototype pollution
+    const parsed = JSON.parse(content);
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+      return { raw: null, error: 'Config file must contain a JSON object' };
+    }
+    // Deep copy into null-prototype objects
+    const safe = Object.create(null);
+    for (const key of Object.keys(parsed)) {
+      if (typeof parsed[key] === 'object' && parsed[key] !== null && !Array.isArray(parsed[key])) {
+        const inner = Object.create(null);
+        for (const k of Object.keys(parsed[key])) {
+          inner[k] = parsed[key][k];
+        }
+        safe[key] = inner;
+      } else {
+        safe[key] = parsed[key];
+      }
+    }
+    return { raw: safe, error: null };
+  } catch (err) {
+    if (err.code === 'ENOENT') {
+      return { raw: null, error: null }; // file not found is not an error for auto-detection
+    }
+    return { raw: null, error: `Failed to parse config: ${err.message}` };
+  }
+}
+
+/**
+ * Validate a parsed config object.
+ * @param {object} raw - parsed config (null-prototype object)
+ * @returns {{ config: object|null, warnings: string[], errors: string[] }}
+ */
+function validateConfig(raw) {
+  const warnings = [];
+  const errors = [];
+  const config = Object.create(null);
+
+  if (!raw) return { config: null, warnings, errors };
+
+  // Check for prototype pollution keys at all levels
+  for (const key of Object.keys(raw)) {
+    if (PROTO_KEYS.has(key)) {
+      errors.push(`Forbidden key "${key}" detected (prototype pollution attempt)`);
+      return { config: null, warnings, errors };
+    }
+    if (typeof raw[key] === 'object' && raw[key] !== null) {
+      for (const k of Object.keys(raw[key])) {
+        if (PROTO_KEYS.has(k)) {
+          errors.push(`Forbidden key "${key}.${k}" detected (prototype pollution attempt)`);
+          return { config: null, warnings, errors };
+        }
+      }
+    }
+  }
+
+  // Check for unknown top-level keys
+  for (const key of Object.keys(raw)) {
+    if (!VALID_TOP_KEYS.has(key)) {
+      warnings.push(`Unknown config key "${key}" — ignored`);
+    }
+  }
+
+  // Validate riskThresholds
+  if (raw.riskThresholds !== undefined) {
+    const rt = raw.riskThresholds;
+    if (typeof rt !== 'object' || rt === null || Array.isArray(rt)) {
+      errors.push('riskThresholds must be an object');
+    } else {
+      const validKeys = new Set(['critical', 'high', 'medium']);
+      for (const k of Object.keys(rt)) {
+        if (!validKeys.has(k)) {
+          warnings.push(`Unknown riskThresholds key "${k}" — ignored`);
+        }
+      }
+      const vals = Object.create(null);
+      for (const k of ['critical', 'high', 'medium']) {
+        if (rt[k] !== undefined) {
+          if (typeof rt[k] !== 'number' || !Number.isFinite(rt[k])) {
+            errors.push(`riskThresholds.${k} must be a finite number`);
+          } else if (rt[k] <= 0) {
+            errors.push(`riskThresholds.${k} must be > 0 (got ${rt[k]})`);
+          } else {
+            vals[k] = rt[k];
+          }
+        } else {
+          vals[k] = DEFAULTS.riskThresholds[k];
+        }
+      }
+      // Ordering: critical > high > medium
+      if (!errors.length) {
+        const c = vals.critical, h = vals.high, m = vals.medium;
+        if (c <= h || h <= m) {
+          errors.push(`riskThresholds ordering violation: critical (${c}) > high (${h}) > medium (${m}) required`);
+        }
+      }
+      if (!errors.length) {
+        config.riskThresholds = vals;
+        // Warn if thresholds are relaxed beyond defaults
+        if ((vals.critical > DEFAULTS.riskThresholds.critical) ||
+            (vals.high > DEFAULTS.riskThresholds.high) ||
+            (vals.medium > DEFAULTS.riskThresholds.medium)) {
+          warnings.push('Risk thresholds relaxed — detection sensitivity reduced');
+        }
+      }
+    }
+  }
+
+  // Validate maxFileSize
+  if (raw.maxFileSize !== undefined) {
+    const mfs = raw.maxFileSize;
+    if (typeof mfs !== 'number' || !Number.isFinite(mfs) || !Number.isInteger(mfs)) {
+      errors.push('maxFileSize must be a finite integer');
+    } else if (mfs < 1024 * 1024) {
+      errors.push(`maxFileSize must be >= 1MB (got ${mfs})`);
+    } else if (mfs > 100 * 1024 * 1024) {
+      errors.push(`maxFileSize must be <= 100MB (got ${mfs})`);
+    } else {
+      config.maxFileSize = mfs;
+    }
+  }
+
+  // Validate severityWeights
+  if (raw.severityWeights !== undefined) {
+    const sw = raw.severityWeights;
+    if (typeof sw !== 'object' || sw === null || Array.isArray(sw)) {
+      errors.push('severityWeights must be an object');
+    } else {
+      const validKeys = new Set(['critical', 'high', 'medium', 'low']);
+      for (const k of Object.keys(sw)) {
+        if (!validKeys.has(k)) {
+          warnings.push(`Unknown severityWeights key "${k}" — ignored`);
+        }
+      }
+      const vals = Object.create(null);
+      for (const k of ['critical', 'high', 'medium', 'low']) {
+        if (sw[k] !== undefined) {
+          if (typeof sw[k] !== 'number' || !Number.isFinite(sw[k])) {
+            errors.push(`severityWeights.${k} must be a finite number`);
+          } else if (sw[k] < 0) {
+            errors.push(`severityWeights.${k} must be >= 0 (got ${sw[k]})`);
+          } else {
+            vals[k] = sw[k];
+          }
+        } else {
+          vals[k] = DEFAULTS.severityWeights[k];
+        }
+      }
+      // Ordering: critical >= high >= medium >= low
+      if (!errors.length) {
+        const c = vals.critical, h = vals.high, m = vals.medium, l = vals.low;
+        if (c < h || h < m || m < l) {
+          errors.push(`severityWeights ordering violation: critical (${c}) >= high (${h}) >= medium (${m}) >= low (${l}) required`);
+        }
+      }
+      if (!errors.length) {
+        config.severityWeights = vals;
+      }
+    }
+  }
+
+  const hasKeys = Object.keys(config).length > 0;
+  return { config: hasKeys ? config : null, warnings, errors };
+}
+
+/**
+ * Resolve which config file to load.
+ * Priority: --config <path> > .muaddibrc.json at targetPath root
+ * @param {string} targetPath - scan target directory
+ * @param {string|null} configPath - explicit --config path (or null)
+ * @returns {{ config: object|null, warnings: string[], errors: string[], source: string|null }}
+ */
+function resolveConfig(targetPath, configPath) {
+  // Explicit --config path
+  if (configPath) {
+    const absPath = path.isAbsolute(configPath) ? configPath : path.resolve(configPath);
+    if (!fs.existsSync(absPath)) {
+      return { config: null, warnings: [], errors: [`Config file not found: ${configPath}`], source: null };
+    }
+    const { raw, error } = loadConfigFile(absPath);
+    if (error) {
+      return { config: null, warnings: [], errors: [error], source: null };
+    }
+    const result = validateConfig(raw);
+    if (result.config) {
+      result.warnings.unshift(`Loaded custom thresholds from ${configPath}`);
+    }
+    result.source = configPath;
+    return result;
+  }
+
+  // Auto-detect .muaddibrc.json at target root
+  const rcPath = path.join(targetPath, '.muaddibrc.json');
+  if (!fs.existsSync(rcPath)) {
+    return { config: null, warnings: [], errors: [], source: null };
+  }
+  const { raw, error } = loadConfigFile(rcPath);
+  if (error) {
+    // Auto-detected config with errors is a warning, not a fatal error
+    return { config: null, warnings: [`[CONFIG] ${error} — .muaddibrc.json ignored`], errors: [], source: null };
+  }
+  const result = validateConfig(raw);
+  if (result.config) {
+    result.warnings.unshift('Loaded custom thresholds from .muaddibrc.json');
+  }
+  result.source = rcPath;
+  return result;
+}
+
+module.exports = { DEFAULTS, loadConfigFile, validateConfig, resolveConfig };

package/src/index.js

@@ -28,10 +28,11 @@ const { computeReachableFiles } = require('./scanner/reachability.js');
 const { runTemporalAnalyses } = require('./temporal-runner.js');
 const { formatOutput } = require('./output-formatter.js');
 const { setExtraExcludes, getExtraExcludes, Spinner, listInstalledPackages, clearFileListCache, debugLog } = require('./utils.js');
-const { SEVERITY_WEIGHTS, RISK_THRESHOLDS, MAX_RISK_SCORE, isPackageLevelThreat, computeGroupScore, applyFPReductions, applyCompoundBoosts, calculateRiskScore } = require('./scoring.js');
+const { SEVERITY_WEIGHTS, RISK_THRESHOLDS, MAX_RISK_SCORE, isPackageLevelThreat, computeGroupScore, applyFPReductions, applyCompoundBoosts, calculateRiskScore, applyConfigOverrides, resetConfigOverrides, getSeverityWeights } = require('./scoring.js');
+const { resolveConfig } = require('./config.js');
 const { buildIntentPairs } = require('./intent-graph.js');
 
-const { MAX_FILE_SIZE, safeParse } = require('./shared/constants.js');
+const { MAX_FILE_SIZE, getMaxFileSize, setMaxFileSize, resetMaxFileSize, safeParse } = require('./shared/constants.js');
 const walk = require('acorn-walk');
 
 // Paranoid mode scanner
@@ -75,7 +76,7 @@ function scanParanoid(targetPath) {
   function scanFileAST(filePath) {
     try {
       const stat = fs.statSync(filePath);
-      if (stat.size > MAX_FILE_SIZE) return;
+      if (stat.size > getMaxFileSize()) return;
       const content = fs.readFileSync(filePath, 'utf8');
       const relFile = path.relative(targetPath, filePath);
 
@@ -209,7 +210,7 @@ function scanParanoid(targetPath) {
   function scanFile(filePath) {
     try {
       const stat = fs.statSync(filePath);
-      if (stat.size > MAX_FILE_SIZE) return;
+      if (stat.size > getMaxFileSize()) return;
       const ext = path.extname(filePath);
       if (ext === '.js' || ext === '.mjs' || ext === '.cjs') {
         scanFileAST(filePath);
@@ -353,6 +354,19 @@ async function run(targetPath, options = {}) {
     setExtraExcludes(options.exclude, targetPath);
   }
 
+  // Load custom configuration (.muaddibrc.json or --config)
+  let configApplied = false;
+  const configResult = resolveConfig(targetPath, options.configPath || null);
+  if (configResult.errors.length > 0) {
+    for (const err of configResult.errors) console.error(`[CONFIG ERROR] ${err}`);
+    throw new Error('Invalid configuration file.');
+  }
+  if (configResult.config) {
+    applyConfigOverrides(configResult.config);
+    if (configResult.config.maxFileSize) setMaxFileSize(configResult.config.maxFileSize);
+    configApplied = true;
+  }
+
   // Detect Python project (synchronous, fast file reads)
   const pythonDeps = detectPythonProject(targetPath);
 
@@ -376,6 +390,9 @@ async function run(targetPath, options = {}) {
   const MODULE_GRAPH_TIMEOUT_MS = 5000;
   const warnings = [];
   if (iocStalenessWarning) warnings.push(iocStalenessWarning);
+  if (configResult.warnings.length > 0) {
+    for (const w of configResult.warnings) warnings.push(`[CONFIG] ${w}`);
+  }
   let crossFileFlows = [];
   if (!options.noModuleGraph) {
     const moduleGraphWork = async () => {
@@ -630,7 +647,7 @@ async function run(targetPath, options = {}) {
   const enrichedThreats = deduped.map(t => {
     const rule = getRule(t.type);
     const confFactor = { high: 1.0, medium: 0.85, low: 0.6 }[rule.confidence] || 1.0;
-    const points = Math.round((SEVERITY_WEIGHTS[t.severity] || 0) * confFactor);
+    const points = Math.round((getSeverityWeights()[t.severity] || 0) * confFactor);
     return {
       ...t,
       rule_id: rule.id || t.type,
@@ -695,6 +712,7 @@ async function run(targetPath, options = {}) {
   if (options._capture) {
     setExtraExcludes([]);
     clearFileListCache();
+    if (configApplied) { resetConfigOverrides(); resetMaxFileSize(); }
     return result;
   }
 
@@ -729,6 +747,7 @@ async function run(targetPath, options = {}) {
   // Clear runtime state
   setExtraExcludes([]);
   clearFileListCache();
+  if (configApplied) { resetConfigOverrides(); resetMaxFileSize(); }
 
   return Math.min(failingThreats.length, 125);
 }

package/src/scanner/github-actions.js

@@ -1,7 +1,7 @@
 const fs = require('fs');
 const path = require('path');
 
-const { MAX_FILE_SIZE } = require('../shared/constants.js');
+const { MAX_FILE_SIZE, getMaxFileSize } = require('../shared/constants.js');
 
 const YAML_EXTENSIONS = ['.yml', '.yaml'];
 const MAX_DEPTH = 10;
@@ -40,7 +40,7 @@ function scanDirRecursive(dirPath, targetPath, threats, depth = 0) {
         continue;
       }
       if (!stat.isFile()) continue;
-      if (stat.size > MAX_FILE_SIZE) continue;
+      if (stat.size > getMaxFileSize()) continue;
     } catch {
       continue;
     }

package/src/scanner/hash.js

@@ -3,7 +3,7 @@ const path = require('path');
 const nodeCrypto = require('crypto');
 const { loadCachedIOCs } = require('../ioc/updater.js');
 const { findFiles } = require('../utils.js');
-const { MAX_FILE_SIZE } = require('../shared/constants.js');
+const { MAX_FILE_SIZE, getMaxFileSize } = require('../shared/constants.js');
 
 // Hash cache: filePath -> { hash, mtime }
 const hashCache = new Map();
@@ -57,7 +57,7 @@ async function scanHashes(targetPath) {
 function computeHashCached(filePath) {
   try {
     const stat = fs.statSync(filePath);
-    if (stat.size > MAX_FILE_SIZE) return null;
+    if (stat.size > getMaxFileSize()) return null;
     const mtime = stat.mtimeMs;
 
     // Check the cache

package/src/scanner/shell.js

@@ -1,7 +1,7 @@
 const fs = require('fs');
 const path = require('path');
 const { findFiles, forEachSafeFile, debugLog } = require('../utils.js');
-const { MAX_FILE_SIZE } = require('../shared/constants.js');
+const { MAX_FILE_SIZE, getMaxFileSize } = require('../shared/constants.js');
 
 const SHELL_EXCLUDED_DIRS = ['node_modules', '.git', '.muaddib-cache'];
 
@@ -66,7 +66,7 @@ function findExtensionlessFiles(dir, excludedDirs, results = [], depth = 0) {
       if (lstat.isSymbolicLink()) continue;
       if (lstat.isDirectory()) {
         findExtensionlessFiles(fullPath, excludedDirs, results, depth + 1);
-      } else if (lstat.isFile() && !path.extname(item) && lstat.size <= MAX_FILE_SIZE) {
+      } else if (lstat.isFile() && !path.extname(item) && lstat.size <= getMaxFileSize()) {
         results.push(fullPath);
       }
     } catch (e) { debugLog('[SHELL] stat error:', e?.message); }

package/src/scoring.js

@@ -47,6 +47,44 @@ const PROTO_HOOK_MEDIUM_CAP = 15;
 // Unknown/paranoid rules default to 1.0 (no penalty).
 const CONFIDENCE_FACTORS = { high: 1.0, medium: 0.85, low: 0.6 };
 
+// Mutable copies for configurable overrides (reset after each scan)
+let _severityWeights = { ...SEVERITY_WEIGHTS };
+let _riskThresholds = { ...RISK_THRESHOLDS };
+
+/**
+ * Apply config overrides to scoring parameters.
+ * @param {object} config - validated config from config.js
+ */
+function applyConfigOverrides(config) {
+  if (config.severityWeights) {
+    if (config.severityWeights.critical !== undefined) _severityWeights.CRITICAL = config.severityWeights.critical;
+    if (config.severityWeights.high !== undefined) _severityWeights.HIGH = config.severityWeights.high;
+    if (config.severityWeights.medium !== undefined) _severityWeights.MEDIUM = config.severityWeights.medium;
+    if (config.severityWeights.low !== undefined) _severityWeights.LOW = config.severityWeights.low;
+  }
+  if (config.riskThresholds) {
+    if (config.riskThresholds.critical !== undefined) _riskThresholds.CRITICAL = config.riskThresholds.critical;
+    if (config.riskThresholds.high !== undefined) _riskThresholds.HIGH = config.riskThresholds.high;
+    if (config.riskThresholds.medium !== undefined) _riskThresholds.MEDIUM = config.riskThresholds.medium;
+  }
+}
+
+/** Reset scoring parameters to defaults (call after each scan to prevent state leak). */
+function resetConfigOverrides() {
+  _severityWeights = { ...SEVERITY_WEIGHTS };
+  _riskThresholds = { ...RISK_THRESHOLDS };
+}
+
+/** Get current severity weights (for enrichment in index.js). */
+function getSeverityWeights() {
+  return _severityWeights;
+}
+
+/** Get current risk thresholds (for external consumers). */
+function getRiskThresholds() {
+  return _riskThresholds;
+}
+
 // ============================================
 // PER-FILE MAX SCORING (v2.2.11)
 // ============================================
@@ -91,7 +129,7 @@ function computeGroupScore(threats) {
   let protoHookMediumPoints = 0;
 
   for (const t of threats) {
-    const weight = SEVERITY_WEIGHTS[t.severity] || 0;
+    const weight = _severityWeights[t.severity] || 0;
     const rule = getRule(t.type);
     const factor = CONFIDENCE_FACTORS[rule.confidence] || 1.0;
 
@@ -585,9 +623,9 @@ function calculateRiskScore(deduped, intentResult) {
   const mediumCount = deduped.filter(t => t.severity === 'MEDIUM').length;
   const lowCount = deduped.filter(t => t.severity === 'LOW').length;
 
-  const riskLevel = riskScore >= RISK_THRESHOLDS.CRITICAL ? 'CRITICAL'
-                  : riskScore >= RISK_THRESHOLDS.HIGH ? 'HIGH'
-                  : riskScore >= RISK_THRESHOLDS.MEDIUM ? 'MEDIUM'
+  const riskLevel = riskScore >= _riskThresholds.CRITICAL ? 'CRITICAL'
+                  : riskScore >= _riskThresholds.HIGH ? 'HIGH'
+                  : riskScore >= _riskThresholds.MEDIUM ? 'MEDIUM'
                   : riskScore > 0 ? 'LOW'
                   : 'SAFE';
 
@@ -600,5 +638,6 @@ function calculateRiskScore(deduped, intentResult) {
 
 module.exports = {
   SEVERITY_WEIGHTS, RISK_THRESHOLDS, MAX_RISK_SCORE, CONFIDENCE_FACTORS,
-  isPackageLevelThreat, computeGroupScore, applyFPReductions, applyCompoundBoosts, calculateRiskScore
+  isPackageLevelThreat, computeGroupScore, applyFPReductions, applyCompoundBoosts, calculateRiskScore,
+  applyConfigOverrides, resetConfigOverrides, getSeverityWeights, getRiskThresholds
 };

package/src/shared/constants.js

@@ -88,6 +88,14 @@ const DOWNLOAD_TIMEOUT = 30_000; // 30 seconds
 
 // Shared scanner constants
 const MAX_FILE_SIZE = 10 * 1024 * 1024; // 10MB — skip files larger than this to avoid memory issues
+let _maxFileSize = MAX_FILE_SIZE;
+
+/** Get current max file size (configurable via .muaddibrc.json). */
+function getMaxFileSize() { return _maxFileSize; }
+/** Set max file size override. */
+function setMaxFileSize(size) { _maxFileSize = size; }
+/** Reset max file size to default. */
+function resetMaxFileSize() { _maxFileSize = MAX_FILE_SIZE; }
 const ACORN_OPTIONS = { ecmaVersion: 2024, sourceType: 'module', allowHashBang: true };
 
 const acorn = require('acorn');
@@ -110,4 +118,4 @@ function safeParse(code, extraOptions = {}) {
   }
 }
 
-module.exports = { REHABILITATED_PACKAGES, NPM_PACKAGE_REGEX, MAX_TARBALL_SIZE, DOWNLOAD_TIMEOUT, MAX_FILE_SIZE, ACORN_OPTIONS, safeParse };
+module.exports = { REHABILITATED_PACKAGES, NPM_PACKAGE_REGEX, MAX_TARBALL_SIZE, DOWNLOAD_TIMEOUT, MAX_FILE_SIZE, ACORN_OPTIONS, safeParse, getMaxFileSize, setMaxFileSize, resetMaxFileSize };

package/src/temporal-ast-diff.js

@@ -8,7 +8,7 @@ const { findJsFiles, forEachSafeFile, debugLog } = require('./utils.js');
 const { fetchPackageMetadata, getLatestVersions } = require('./temporal-analysis.js');
 const { downloadToFile, extractTarGz, sanitizePackageName } = require('./shared/download.js');
 
-const { MAX_FILE_SIZE, ACORN_OPTIONS, safeParse } = require('./shared/constants.js');
+const { MAX_FILE_SIZE, getMaxFileSize, ACORN_OPTIONS, safeParse } = require('./shared/constants.js');
 
 const REGISTRY_URL = 'https://registry.npmjs.org';
 const METADATA_TIMEOUT = 10_000;

package/src/utils.js

@@ -1,6 +1,6 @@
 const fs = require('fs');
 const path = require('path');
-const { MAX_FILE_SIZE } = require('./shared/constants.js');
+const { MAX_FILE_SIZE, getMaxFileSize } = require('./shared/constants.js');
 
 /**
  * Directories excluded from scanning.
@@ -285,7 +285,7 @@ function forEachSafeFile(files, callback) {
   for (const file of files) {
     try {
       const stat = fs.statSync(file);
-      if (stat.size > MAX_FILE_SIZE) continue;
+      if (stat.size > getMaxFileSize()) continue;
     } catch { continue; }
     let content;
     try {