muaddib-scanner 2.6.3 → 2.6.5

package/README.md

@@ -284,9 +284,14 @@ repos:
 | **Wild TPR** (Datadog 17K) | **88.2%** raw / **~100%** adjusted | 17,922 real malware. 2,077 out-of-scope (phishing, binaries, corrected) |
 | **TPR** (Ground Truth) | **93.9%** (46/49) | 51 real attacks. 3 out-of-scope: browser-only |
 | **FPR** (Benign) | **12.1%** (64/529) | 529 npm packages, real source via `npm pack` |
-| **ADR** (Adversarial + Holdout) | **94.8%** (73/77) | 53 adversarial + 40 holdout (77 available on disk) |
+| **ADR** (Adversarial + Holdout) | **92.2%** (71/77) | 53 adversarial + 40 holdout (77 available on disk), global threshold=20 |
 
-**1940 tests** across 44 files, 86% code coverage. **129 rules** (124 RULES + 5 PARANOID).
+**1974 tests** across 44 files, 86% code coverage. **129 rules** (124 RULES + 5 PARANOID).
+
+> **Methodology caveats:**
+> - TPR measured on 49 Node.js attack samples (3 browser-only excluded from 51 total)
+> - FPR measured on 529 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.
 
@@ -322,7 +327,7 @@ npm test
 
 ### Testing
 
-- **1940 tests** across 44 modular test files - 86% code coverage
+- **1974 tests** across 44 modular test files - 86% code coverage
 - **56 fuzz tests** - Malformed inputs, ReDoS, unicode, binary
 - **Datadog 17K benchmark** - 17,922 real malware samples
 - **Ground truth validation** - 51 real-world attacks (93.9% TPR)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "muaddib-scanner",
-  "version": "2.6.3",
+  "version": "2.6.5",
   "description": "Supply-chain threat detection & response for npm & PyPI/Python",
   "main": "src/index.js",
   "bin": {
@@ -48,8 +48,7 @@
     "acorn": "8.16.0",
     "acorn-walk": "8.3.5",
     "adm-zip": "0.5.16",
-    "js-yaml": "4.1.1",
-    "muaddib-scanner": "^2.6.2"
+    "js-yaml": "4.1.1"
   },
   "overrides": {
     "loadash": "0.0.0-security"

package/src/index.js

@@ -18,7 +18,7 @@ const fs = require('fs');
 const path = require('path');
 const { scanGitHubActions } = require('./scanner/github-actions.js');
 const { detectPythonProject, normalizePythonName } = require('./scanner/python.js');
-const { loadCachedIOCs } = require('./ioc/updater.js');
+const { loadCachedIOCs, checkIOCStaleness } = require('./ioc/updater.js');
 const { ensureIOCs } = require('./ioc/bootstrap.js');
 const { scanEntropy } = require('./scanner/entropy.js');
 const { scanAIConfig } = require('./scanner/ai-config.js');
@@ -92,18 +92,32 @@ function scanParanoid(targetPath) {
 
       const found = new Set(); // deduplicate: one finding per rule per file
 
+      // v2.6.5: Track aliases of eval, Function, require for bypass detection
+      // e.g., const e = eval; e(code) — or — const F = Function; new F(code)
+      const ALIAS_TARGETS = new Set(['eval', 'Function', 'require']);
+      const aliases = new Map(); // aliasName → originalName
+
       walk.simple(ast, {
+        VariableDeclarator(node) {
+          // const e = eval / const F = Function / const r = require
+          if (node.id?.type === 'Identifier' && node.init?.type === 'Identifier' &&
+              ALIAS_TARGETS.has(node.init.name)) {
+            aliases.set(node.id.name, node.init.name);
+          }
+        },
         CallExpression(node) {
           // Direct calls: eval(), exec(), fetch(), etc.
           if (node.callee.type === 'Identifier') {
-            const name = node.callee.name;
+            // Resolve alias to original name if applicable
+            const name = aliases.get(node.callee.name) || node.callee.name;
             for (const [ruleKey, detector] of Object.entries(PARANOID_AST_DETECTORS)) {
               if (detector.callNames && detector.callNames.has(name) && !found.has(ruleKey)) {
                 found.add(ruleKey);
                 const rule = PARANOID_RULES[ruleKey];
                 threats.push({
                   type: rule.id, severity: rule.severity.toUpperCase(),
-                  message: `${rule.message}: "${name}"`, file: relFile, mitre: rule.mitre
+                  message: `${rule.message}: "${node.callee.name}"${aliases.has(node.callee.name) ? ` (alias of ${name})` : ''}`,
+                  file: relFile, mitre: rule.mitre
                 });
               }
             }
@@ -130,14 +144,16 @@ function scanParanoid(targetPath) {
         },
         NewExpression(node) {
           if (node.callee.type === 'Identifier') {
-            const name = node.callee.name;
+            // Resolve alias: const F = Function; new F(code)
+            const name = aliases.get(node.callee.name) || node.callee.name;
             for (const [ruleKey, detector] of Object.entries(PARANOID_AST_DETECTORS)) {
               if (detector.newNames && detector.newNames.has(name) && !found.has(ruleKey)) {
                 found.add(ruleKey);
                 const rule = PARANOID_RULES[ruleKey];
                 threats.push({
                   type: rule.id, severity: rule.severity.toUpperCase(),
-                  message: `${rule.message}: "new ${name}"`, file: relFile, mitre: rule.mitre
+                  message: `${rule.message}: "new ${node.callee.name}"${aliases.has(node.callee.name) ? ` (alias of ${name})` : ''}`,
+                  file: relFile, mitre: rule.mitre
                 });
               }
             }
@@ -333,6 +349,9 @@ async function run(targetPath, options = {}) {
   // Ensure IOCs are downloaded (first run only, graceful failure)
   await ensureIOCs();
 
+  // Check IOC freshness — warn if database is older than 30 days
+  const iocStalenessWarning = checkIOCStaleness(30);
+
   // Apply --exclude dirs for this scan
   if (options.exclude && options.exclude.length > 0) {
     setExtraExcludes(options.exclude, targetPath);
@@ -359,10 +378,16 @@ async function run(targetPath, options = {}) {
   // Wrapped in yieldThen to unblock spinner animation
   // Bounded: 5s timeout to prevent DoS on large/adversarial packages
   const MODULE_GRAPH_TIMEOUT_MS = 5000;
+  const warnings = [];
+  if (iocStalenessWarning) warnings.push(iocStalenessWarning);
   let crossFileFlows = [];
   if (!options.noModuleGraph) {
     const moduleGraphWork = async () => {
       const graph = await yieldThen(() => buildModuleGraph(targetPath));
+      if (Object.keys(graph).length === 0) {
+        // buildModuleGraph returns empty when MAX_GRAPH_NODES exceeded
+        warnings.push('Module graph skipped: package exceeds 100 files limit');
+      }
       const tainted = await yieldThen(() => annotateTaintedExports(graph, targetPath));
       const sinkAnnotations = await yieldThen(() => annotateSinkExports(graph, targetPath));
       crossFileFlows = await yieldThen(() => detectCrossFileFlows(graph, tainted, sinkAnnotations, targetPath));
@@ -381,6 +406,9 @@ async function run(targetPath, options = {}) {
     } catch (e) {
       // Graceful fallback — module graph is best-effort
       debugLog('[MODULE-GRAPH] Error:', e && e.message);
+      if (e && e.message === 'Module graph timeout') {
+        warnings.push(`Module graph analysis timed out (${MODULE_GRAPH_TIMEOUT_MS / 1000}s) — cross-file flows may be incomplete`);
+      }
     }
   }
 
@@ -593,6 +621,10 @@ async function run(targetPath, options = {}) {
     threats: pythonThreats.length + pypiTyposquatThreats.length
   } : null;
 
+  // Track deobfuscation failures
+  // (deobfuscate returns {deobfuscatedThreats, failures} but failures aren't surfaced)
+  // We detect this via scannerErrors for now
+
   const result = {
     target: targetPath,
     timestamp: new Date().toISOString(),
@@ -614,6 +646,7 @@ async function run(targetPath, options = {}) {
       breakdown
     },
     sandbox: sandboxData,
+    warnings: warnings.length > 0 ? warnings : undefined,
     scannerErrors: scannerErrors.length > 0 ? scannerErrors : undefined
   };
 

package/src/intent-graph.js

@@ -24,11 +24,14 @@ const SOURCE_TYPES = {
   credential_regex_harvest: 'credential_read', // regex patterns for tokens/passwords
   llm_api_key_harvest: 'credential_read',     // OPENAI_API_KEY, ANTHROPIC_API_KEY
   credential_cli_steal: 'credential_read',    // gh auth token, gcloud auth
-  // env_access EXCLUDED — standard config (process.env.PORT, AWS_REGION, NODE_ENV)
+  // env_access: conditionally classified — see classifySource()
   // suspicious_dataflow EXCLUDED — already compound detection
   // cross_file_dataflow EXCLUDED — already scored CRITICAL by module-graph
 };
 
+// Sensitive env var patterns — env_access referencing these is credential theft, not config
+const SENSITIVE_ENV_PATTERNS = /TOKEN|KEY|SECRET|PASSWORD|CREDENTIAL|API_KEY|AUTH/i;
+
 // ============================================
 // SINK CLASSIFICATION (from existing threats only)
 // ============================================
@@ -105,9 +108,17 @@ const CROSS_FILE_MULTIPLIER = 0.5;
 function classifySource(threat) {
   if (SOURCE_TYPES[threat.type]) return SOURCE_TYPES[threat.type];
 
+  // env_access: only classify as credential_read if accessing sensitive vars
+  // Standard config (NODE_ENV, PORT, DEBUG) → null (no pairing)
+  if (threat.type === 'env_access') {
+    if (threat.message && SENSITIVE_ENV_PATTERNS.test(threat.message)) {
+      return 'credential_read';
+    }
+    return null;
+  }
+
   // Explicitly excluded types
   if (threat.type === 'suspicious_dataflow') return null;
-  if (threat.type === 'env_access') return null;
   if (threat.type === 'cross_file_dataflow') return null;
 
   // Message-based: only for threats referencing sensitive file paths

package/src/ioc/scraper.js

@@ -10,6 +10,38 @@ const HOME_IOC_FILE = path.join(os.homedir(), '.muaddib', 'data', 'iocs.json');
 const STATIC_IOCS_FILE = path.join(__dirname, '../../data/static-iocs.json');
 const { generateCompactIOCs } = require('./updater.js');
 const { Spinner } = require('../utils.js');
+const { NPM_PACKAGE_REGEX } = require('../shared/constants.js');
+
+// Version format validation (semver-like + wildcard)
+const VERSION_RE = /^(\*|0|[1-9]\d*(\.\d+){0,2}(-[\w.]+)?(\+[\w.]+)?)$/;
+
+/**
+ * Validate an IOC package entry before insertion.
+ * Returns true if valid, false if should be skipped.
+ */
+function validateIOCEntry(pkgName, version, ecosystem) {
+  if (!pkgName || typeof pkgName !== 'string') return false;
+  // npm: validate with NPM_PACKAGE_REGEX
+  if (ecosystem === 'npm' || !ecosystem) {
+    if (!NPM_PACKAGE_REGEX.test(pkgName)) {
+      console.warn(`[WARN] Invalid ${ecosystem || 'npm'} package name skipped: ${pkgName}`);
+      return false;
+    }
+  }
+  // PyPI: basic check — no path traversal, no slashes
+  if (ecosystem === 'pypi') {
+    if (/[/\\]|\.\./.test(pkgName)) {
+      console.warn(`[WARN] Invalid PyPI package name skipped: ${pkgName}`);
+      return false;
+    }
+  }
+  // Version validation
+  if (version && !VERSION_RE.test(version)) {
+    console.warn(`[WARN] Invalid version skipped: ${version} for ${pkgName}`);
+    return false;
+  }
+  return true;
+}
 
 // Allowed domains for redirections (SSRF security)
 const ALLOWED_REDIRECT_DOMAINS = [
@@ -1110,10 +1142,15 @@ async function runScraper() {
     dedupMap.set(key, pkg);
   }
 
-  // Merge new IOCs with smart replacement
+  // Merge new IOCs with smart replacement (with input validation)
   let addedPackages = 0;
   let upgradedPackages = 0;
+  let skippedInvalid = 0;
   for (const pkg of allPackages) {
+    if (!validateIOCEntry(pkg.name, pkg.version, 'npm')) {
+      skippedInvalid++;
+      continue;
+    }
     const key = pkg.name + '@' + pkg.version;
     if (!dedupMap.has(key)) {
       dedupMap.set(key, pkg);
@@ -1148,6 +1185,10 @@ async function runScraper() {
   }
   let addedPyPIPackages = 0;
   for (const pkg of pypiPackages) {
+    if (!validateIOCEntry(pkg.name, pkg.version, 'pypi')) {
+      skippedInvalid++;
+      continue;
+    }
     const key = pkg.name + '@' + pkg.version;
     if (!pypiDedupMap.has(key)) {
       pypiDedupMap.set(key, pkg);
@@ -1308,6 +1349,7 @@ module.exports = {
   // Pure utility functions (exported for testing)
   parseCSVLine, parseCSV, extractVersions, parseOSVEntry,
   createFreshness, isAllowedRedirect, loadStaticIOCs,
+  validateIOCEntry,
   CONFIDENCE_ORDER, ALLOWED_REDIRECT_DOMAINS
 };
 

package/src/ioc/updater.js

@@ -463,6 +463,34 @@ function invalidateCache() {
   cachedIOCsTime = 0;
 }
 
+/**
+ * Check IOC freshness based on cached file mtime.
+ * Returns a warning string if IOCs are older than maxAgeDays, null otherwise.
+ * @param {number} maxAgeDays - Maximum acceptable age in days (default: 30)
+ * @returns {string|null} Warning message or null
+ */
+function checkIOCStaleness(maxAgeDays = 30) {
+  const filesToCheck = [CACHE_IOC_FILE, LOCAL_IOC_FILE, LOCAL_COMPACT_FILE];
+  let newestMtime = 0;
+
+  for (const f of filesToCheck) {
+    try {
+      const stat = fs.statSync(f);
+      if (stat.mtimeMs > newestMtime) newestMtime = stat.mtimeMs;
+    } catch {
+      // File doesn't exist — skip
+    }
+  }
+
+  if (newestMtime === 0) return null; // No IOC files found — bootstrap will handle
+
+  const ageDays = (Date.now() - newestMtime) / (1000 * 60 * 60 * 24);
+  if (ageDays > maxAgeDays) {
+    return `IOC database is ${Math.floor(ageDays)} days old (threshold: ${maxAgeDays}d). Run "muaddib update" for latest threat data.`;
+  }
+  return null;
+}
+
 // ============================================
 // IOC INTEGRITY: HMAC-SHA256 signing/verification
 // ============================================
@@ -510,4 +538,4 @@ function verifyIOCHMAC(data, hmac) {
   }
 }
 
-module.exports = { updateIOCs, loadCachedIOCs, invalidateCache, generateCompactIOCs, expandCompactIOCs, mergeIOCs, createOptimizedIOCs, generateIOCHMAC, verifyIOCHMAC, NEVER_WILDCARD };
+module.exports = { updateIOCs, loadCachedIOCs, invalidateCache, generateCompactIOCs, expandCompactIOCs, mergeIOCs, createOptimizedIOCs, generateIOCHMAC, verifyIOCHMAC, checkIOCStaleness, NEVER_WILDCARD };

package/src/scanner/dataflow.js

@@ -110,6 +110,32 @@ function buildTaintMap(ast) {
         }
       }
 
+      // B8 fix: const fn = tools.read — resolve object property alias to tainted method
+      if (node.id.type === 'Identifier' && init.type === 'MemberExpression' &&
+          init.object?.type === 'Identifier' && init.property?.type === 'Identifier') {
+        const aliasKey = `${init.object.name}.${init.property.name}`;
+        const aliasTaint = taintMap.get(aliasKey);
+        if (aliasTaint && TRACKED_MODULES.has(aliasTaint.source)) {
+          taintMap.set(node.id.name, aliasTaint);
+        }
+      }
+
+      // B9 fix: const [x] = [fs.readFileSync(...)] — array destructuring taint
+      if (node.id.type === 'ArrayPattern' && init.type === 'ArrayExpression') {
+        for (let i = 0; i < node.id.elements.length && i < init.elements.length; i++) {
+          const elem = node.id.elements[i];
+          const val = init.elements[i];
+          if (!elem || elem.type !== 'Identifier' || !val) continue;
+          if (val.type === 'CallExpression' && val.callee?.type === 'MemberExpression' &&
+              val.callee.object?.type === 'Identifier' && val.callee.property?.type === 'Identifier') {
+            const parentTaint = taintMap.get(val.callee.object.name);
+            if (parentTaint && TRACKED_MODULES.has(parentTaint.source)) {
+              taintMap.set(elem.name, { source: parentTaint.source, detail: `${parentTaint.source}.${val.callee.property.name}` });
+            }
+          }
+        }
+      }
+
       // B5 fix: const tools = { read: fs.readFileSync, home: os.homedir }
       // Track object properties that reference tainted module methods as tainted aliases
       if (node.id.type === 'Identifier' && init.type === 'ObjectExpression') {
@@ -193,6 +219,18 @@ function analyzeFile(content, filePath, basePath) {
     },
 
     VariableDeclarator(node) {
+      // B9: Array destructuring taint propagation: const [data] = [fs.readFileSync('.npmrc')]
+      if (node.id?.type === 'ArrayPattern' && node.init?.type === 'ArrayExpression') {
+        for (let i = 0; i < node.id.elements.length && i < node.init.elements.length; i++) {
+          const elem = node.id.elements[i];
+          const val = node.init.elements[i];
+          if (!elem || elem.type !== 'Identifier' || !val) continue;
+          if (containsSensitiveLiteral(val)) {
+            sensitivePathVars.add(elem.name);
+          }
+        }
+      }
+
       if (node.id?.type === 'Identifier' && node.init) {
         let initNode = node.init;
         if (initNode.type === 'AwaitExpression') initNode = initNode.argument;

package/src/scanner/module-graph.js

@@ -5,9 +5,10 @@ const { findFiles, EXCLUDED_DIRS, debugLog } = require('../utils');
 const { ACORN_OPTIONS: BASE_ACORN_OPTIONS, safeParse } = require('../shared/constants.js');
 
 // --- Bounded path limits ---
-const MAX_GRAPH_NODES = 50;   // Max files in dependency graph
-const MAX_GRAPH_EDGES = 200;  // Max total import edges
+const MAX_GRAPH_NODES = 100;  // Max files in dependency graph (covers ~86% of npm packages)
+const MAX_GRAPH_EDGES = 400;  // Max total import edges
 const MAX_FLOWS = 20;         // Max cross-file flow findings per package
+const MAX_TAINT_DEPTH = 50;   // Max AST recursion depth (DoS guard)
 
 // --- Sensitive source patterns ---
 const SENSITIVE_MODULES = new Set(['fs', 'child_process', 'dns', 'os', 'dgram']);
@@ -103,7 +104,9 @@ function tryResolveConcatRequire(node, depth) {
   return null;
 }
 
-function walkForRequires(node, fileDir, packagePath, imports) {
+function walkForRequires(node, fileDir, packagePath, imports, depth) {
+  if (depth === undefined) depth = 0;
+  if (depth > MAX_TAINT_DEPTH) return;
   if (!node || typeof node !== 'object') return;
   if (
     node.type === 'CallExpression' &&
@@ -130,11 +133,11 @@ function walkForRequires(node, fileDir, packagePath, imports) {
     if (Array.isArray(child)) {
       for (const item of child) {
         if (item && typeof item === 'object' && item.type) {
-          walkForRequires(item, fileDir, packagePath, imports);
+          walkForRequires(item, fileDir, packagePath, imports, depth + 1);
         }
       }
     } else if (child && typeof child === 'object' && child.type) {
-      walkForRequires(child, fileDir, packagePath, imports);
+      walkForRequires(child, fileDir, packagePath, imports, depth + 1);
     }
   }
 }
@@ -1462,7 +1465,9 @@ function parseFile(filePath) {
   return safeParse(content, { allowReturnOutsideFunction: true, allowImportExportEverywhere: true });
 }
 
-function walkAST(node, visitor) {
+function walkAST(node, visitor, depth) {
+  if (depth === undefined) depth = 0;
+  if (depth > MAX_TAINT_DEPTH) return;
   if (!node || typeof node !== 'object') return;
   if (node.type) visitor(node);
   for (const key of Object.keys(node)) {
@@ -1470,10 +1475,10 @@ function walkAST(node, visitor) {
     const child = node[key];
     if (Array.isArray(child)) {
       for (const item of child) {
-        if (item && typeof item === 'object' && item.type) walkAST(item, visitor);
+        if (item && typeof item === 'object' && item.type) walkAST(item, visitor, depth + 1);
       }
     } else if (child && typeof child === 'object' && child.type) {
-      walkAST(child, visitor);
+      walkAST(child, visitor, depth + 1);
     }
   }
 }
@@ -1536,10 +1541,12 @@ function getFunctionBody(node) {
   return null;
 }
 
-function getMemberChain(node) {
+function getMemberChain(node, depth) {
+  if (depth === undefined) depth = 0;
+  if (depth > MAX_TAINT_DEPTH) return '';
   if (node.type === 'Identifier') return node.name;
   if (node.type === 'MemberExpression') {
-    const obj = getMemberChain(node.object);
+    const obj = getMemberChain(node.object, depth + 1);
     const prop = node.property.name || node.property.value || '';
     return `${obj}.${prop}`;
   }
@@ -2084,5 +2091,5 @@ module.exports = {
   annotateSinkExports, detectCallbackCrossFileFlows, detectEventEmitterFlows,
   resolveLocal, extractLocalImports, parseFile, isLocalImport, toRel, isFileExists,
   tryResolveConcatRequire,
-  MAX_GRAPH_NODES, MAX_GRAPH_EDGES, MAX_FLOWS
+  MAX_GRAPH_NODES, MAX_GRAPH_EDGES, MAX_FLOWS, MAX_TAINT_DEPTH
 };

package/src/scoring.js

@@ -232,17 +232,13 @@ function applyFPReductions(threats, reachableFiles, packageName) {
     const rule = FP_COUNT_THRESHOLDS[t.type];
     if (rule && typeCounts[t.type] > rule.maxCount && (!rule.from || t.severity === rule.from)) {
       const typeRatio = typeCounts[t.type] / totalThreats;
-      // suspicious_dataflow: full bypass of percentage guard. Packages with >3 suspicious_dataflow
-      // findings are always legitimate SDKs (SMTP, monitoring, analytics). Real malware has 1-2
-      // targeted source→sink pairs. The count >3 threshold is sufficient protection.
-      // P7: removed 80% ratio cap — it caused ~30k FP hits in production on SDK packages
-      // where dataflow was the dominant finding type (e.g. @darajs/core, addio-admin-sdk).
-      // vm_code_execution: full bypass — packages with only vm.Script calls (cassandra-driver,
-      // webpack, jest) are legitimate. Real malware using vm always has other signals
-      // (network, fs, obfuscation). The >3 count threshold is sufficient protection.
+      // suspicious_dataflow: bypass percentage guard when count exceeds threshold.
+      // Packages with >3 suspicious_dataflow findings are always legitimate SDKs.
+      // But a single suspicious_dataflow at 50% ratio should NOT be downgraded.
+      // vm_code_execution: same logic — bypass only when count exceeds threshold.
       if (typeRatio < 0.4 ||
-          t.type === 'suspicious_dataflow' ||
-          t.type === 'vm_code_execution') {
+          (t.type === 'suspicious_dataflow' && typeCounts[t.type] > rule.maxCount) ||
+          (t.type === 'vm_code_execution' && typeCounts[t.type] > rule.maxCount)) {
         t.severity = rule.to;
       }
     }

package/src/shared/download.js

@@ -41,13 +41,27 @@ function normalizeHostname(hostname) {
       return ipv4Part;
     }
   }
-  // Convert decimal IP notation: 2130706433 → 127.0.0.1
-  if (/^\d+$/.test(hostname)) {
-    const num = parseInt(hostname, 10);
+  // Convert integer IP notation (decimal or hex): 2130706433 or 0x7f000001 → 127.0.0.1
+  if (/^(0x[\da-f]+|\d+)$/i.test(hostname)) {
+    const num = hostname.startsWith('0x') ? parseInt(hostname, 16) : parseInt(hostname, 10);
     if (num > 0 && num < 4294967296) {
       return [(num >>> 24) & 255, (num >>> 16) & 255, (num >>> 8) & 255, num & 255].join('.');
     }
   }
+  // Convert dotted IP with octal/hex octets: 0177.0.0.01 or 0x7f.0.0.1 → 127.0.0.1
+  if (/^[\da-fox.]+$/i.test(hostname)) {
+    const parts = hostname.split('.');
+    if (parts.length === 4) {
+      const octets = parts.map(p => {
+        if (/^0x[\da-f]+$/i.test(p)) return parseInt(p, 16);
+        if (/^0\d+$/.test(p)) return parseInt(p, 8);
+        return parseInt(p, 10);
+      });
+      if (octets.every(o => !isNaN(o) && o >= 0 && o <= 255)) {
+        return octets.join('.');
+      }
+    }
+  }
   return hostname;
 }
 
@@ -121,12 +135,18 @@ async function safeDnsResolve(hostname) {
  * @param {number} [timeoutMs] - Download timeout in ms (default: DOWNLOAD_TIMEOUT)
  * @returns {Promise<number>} Number of bytes downloaded
  */
+const MAX_REDIRECTS = 5;
+
 function downloadToFile(url, destPath, timeoutMs = DOWNLOAD_TIMEOUT) {
   // DNS rebinding protection: validate hostname before connecting
   const parsedUrl = new URL(url);
   return safeDnsResolve(parsedUrl.hostname).then(() => {
     return new Promise((resolve, reject) => {
-      const doRequest = (requestUrl) => {
+      const doRequest = (requestUrl, redirectCount) => {
+        if (redirectCount === undefined) redirectCount = 0;
+        if (redirectCount >= MAX_REDIRECTS) {
+          return reject(new Error(`Too many redirects (${MAX_REDIRECTS}) for ${url}`));
+        }
         const req = https.get(requestUrl, { timeout: timeoutMs }, (res) => {
           if (res.statusCode === 301 || res.statusCode === 302) {
             res.resume();
@@ -138,7 +158,7 @@ function downloadToFile(url, destPath, timeoutMs = DOWNLOAD_TIMEOUT) {
             if (!check.allowed) {
               return reject(new Error(check.error));
             }
-            return doRequest(absoluteLocation);
+            return doRequest(absoluteLocation, redirectCount + 1);
           }
           if (res.statusCode < 200 || res.statusCode >= 300) {
             res.resume();
@@ -246,5 +266,6 @@ module.exports = {
   isPrivateIP,
   safeDnsResolve,
   ALLOWED_DOWNLOAD_DOMAINS,
-  PRIVATE_IP_PATTERNS
+  PRIVATE_IP_PATTERNS,
+  MAX_REDIRECTS
 };