cipher-shield 1.0.0

package/src/modules/ghostHandler.js

@@ -0,0 +1,279 @@
+/**
+ * Ghost Route Handler v2.1
+ *
+ * Advanced honeypot route detection system that identifies access to sensitive
+ * or trap endpoints. Implements multiple detection strategies for comprehensive
+ * coverage while maintaining high performance.
+ *
+ * Detection Strategies:
+ * - Exact path matching
+ * - Prefix matching for directory structures
+ * - File extension detection (e.g., .env, .git)
+ * - Pattern-based matching with wildcards
+ *
+ * Performance optimized with:
+ * - Pre-compiled regex patterns
+ * - Early termination on matches
+ * - Memory-efficient string operations
+ *
+ * @module ghostHandler
+ * @version 1.0.0
+ * @author Omindu Dissanayaka
+ * @license MIT
+ */
+
+/**
+ * Pre-compiled regex patterns for performance with security limits
+ * @private
+ * @type {Object.<string, RegExp>}
+ */
+const PATTERN_CACHE = new Map();
+
+/**
+ * Maximum pattern complexity to prevent ReDoS attacks
+ * @private
+ * @const {number}
+ */
+const MAX_PATTERN_LENGTH = 200;
+const MAX_WILDCARD_COUNT = 3;
+
+/**
+ * Compiles a ghost route pattern into an optimized regex with security checks
+ *
+ * @private
+ * @param {string} pattern - Ghost route pattern
+ * @returns {RegExp|null} Compiled regex for pattern matching or null if unsafe
+ */
+function compilePattern(pattern) {
+  if (PATTERN_CACHE.has(pattern)) {
+    return PATTERN_CACHE.get(pattern);
+  }
+
+  if (pattern.length > MAX_PATTERN_LENGTH) {
+    return null;
+  }
+
+  const wildcardCount = (pattern.match(/\*/g) || []).length;
+  if (wildcardCount > MAX_WILDCARD_COUNT) {
+    return null;
+  }
+
+  try {
+    const escaped = pattern.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+    const regexPattern = escaped.replace(/\\\*/g, '[^/]*?');
+
+    const regex = new RegExp(`^${regexPattern}`, 'i');
+
+    if (!isSafeRegex(regex)) {
+      return null;
+    }
+
+    PATTERN_CACHE.set(pattern, regex);
+    return regex;
+
+  } catch (error) {
+    return null;
+  }
+}
+
+/**
+ * Tests regex for potential ReDoS vulnerabilities
+ *
+ * @private
+ * @param {RegExp} regex - Regex to test
+ * @returns {boolean} True if regex appears safe
+ */
+function isSafeRegex(regex) {
+  const testInputs = [
+    'a'.repeat(1000),
+    'a/b/c/d/e/f/g/h/i/j/k/l/m/n/o/p/q/r/s/t/u/v/w/x/y/z',
+    '/admin/admin/admin/admin/admin/admin/admin/admin/admin',
+    '///admin///admin///admin///admin///admin'
+  ];
+
+  for (const input of testInputs) {
+    try {
+      const startTime = Date.now();
+      regex.test(input);
+      const executionTime = Date.now() - startTime;
+
+      if (executionTime > 100) {
+        return false;
+      }
+    } catch (error) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+/**
+ * Detects if a request path matches any configured ghost route
+ *
+ * Implements multi-strategy detection:
+ * 1. Exact path matching (fastest)
+ * 2. Prefix matching for directory structures
+ * 3. File extension detection
+ * 4. Pattern matching with wildcards
+ *
+ * @function detect
+ * @param {string} requestPath - The request URL path to check
+ * @param {string[]} ghostRoutes - Array of ghost route patterns to match against
+ * @returns {boolean} True if the path matches any ghost route pattern
+ *
+ * @example
+ * ```javascript
+ * const ghostRoutes = ['/admin', '.env', '/secret/*'];
+ * console.log(detect('/admin', ghostRoutes));        // true
+ * console.log(detect('/admin/login', ghostRoutes));  // true (prefix match)
+ * console.log(detect('/config/.env', ghostRoutes));  // true (extension match)
+ * console.log(detect('/secret/password', ghostRoutes)); // true (wildcard match)
+ * console.log(detect('/public', ghostRoutes));       // false
+ * ```
+ */
+function detect(requestPath, ghostRoutes) {
+  if (!requestPath || typeof requestPath !== 'string') {
+    return false;
+  }
+
+  if (!Array.isArray(ghostRoutes) || ghostRoutes.length === 0) {
+    return false;
+  }
+
+  const normalizedPath = requestPath.split('?')[0].toLowerCase().trim();
+
+  const cleanPath = normalizedPath.replace(/\/+$/, '') || '/';
+
+  for (const pattern of ghostRoutes) {
+    if (!pattern || typeof pattern !== 'string') {
+      continue;
+    }
+
+    const normalizedPattern = pattern.toLowerCase().trim();
+
+    if (cleanPath === normalizedPattern) {
+      return true;
+    }
+
+    if (cleanPath.startsWith(normalizedPattern + '/')) {
+      return true;
+    }
+
+    if (normalizedPattern.startsWith('.') && cleanPath.includes(normalizedPattern)) {
+      return true;
+    }
+
+    if (normalizedPattern.includes('*')) {
+      const regex = compilePattern(normalizedPattern);
+      if (regex && regex.test(cleanPath)) {
+        return true;
+      }
+    }
+
+    if (normalizedPattern.startsWith('/') && cleanPath.endsWith(normalizedPattern)) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Validates a ghost route pattern for correctness
+ *
+ * @function validatePattern
+ * @param {string} pattern - Pattern to validate
+ * @returns {boolean} True if pattern is valid
+ *
+ * @example
+ * ```javascript
+ * console.log(validatePattern('/admin'));     // true
+ * console.log(validatePattern('.env'));       // true
+ * console.log(validatePattern('/secret/*'));  // true
+ * console.log(validatePattern(''));           // false
+ * ```
+ */
+function validatePattern(pattern) {
+  if (!pattern || typeof pattern !== 'string') {
+    return false;
+  }
+
+  const trimmed = pattern.trim();
+  if (trimmed.length === 0) {
+    return false;
+  }
+
+  if (trimmed === '/' || trimmed === '/*') {
+    return false;
+  }
+
+  return true;
+}
+
+/**
+ * Gets statistics about ghost route patterns
+ *
+ * @function getPatternStats
+ * @param {string[]} ghostRoutes - Array of ghost route patterns
+ * @returns {Object} Statistics about the patterns
+ *
+ * @example
+ * ```javascript
+ * const stats = getPatternStats(['/admin', '.env', '/secret/*']);
+ * console.log(stats); // { total: 3, exact: 1, extensions: 1, wildcards: 1 }
+ * ```
+ */
+function getPatternStats(ghostRoutes) {
+  if (!Array.isArray(ghostRoutes)) {
+    return { total: 0, exact: 0, extensions: 0, wildcards: 0, invalid: 0 };
+  }
+
+  let exact = 0;
+  let extensions = 0;
+  let wildcards = 0;
+  let invalid = 0;
+
+  for (const pattern of ghostRoutes) {
+    if (!validatePattern(pattern)) {
+      invalid++;
+      continue;
+    }
+
+    if (pattern.includes('*')) {
+      wildcards++;
+    } else if (pattern.startsWith('.')) {
+      extensions++;
+    } else {
+      exact++;
+    }
+  }
+
+  return {
+    total: ghostRoutes.length,
+    exact,
+    extensions,
+    wildcards,
+    invalid
+  };
+}
+
+/**
+ * Clears the pattern cache (useful for testing or memory management)
+ *
+ * @function clearCache
+ * @returns {number} Number of cached patterns cleared
+ */
+function clearCache() {
+  const size = PATTERN_CACHE.size;
+  PATTERN_CACHE.clear();
+  return size;
+}
+
+module.exports = {
+  detect,
+  validatePattern,
+  getPatternStats,
+  clearCache
+};

package/src/modules/shadowHandler.js

@@ -0,0 +1,266 @@
+/**
+ * Shadow Ban Handler v2.1
+ *
+ * Intelligent time-wasting system for malicious IPs that delays responses
+ * without blocking the event loop or consuming excessive resources.
+ * Implements adaptive delays based on threat levels and DEFCON state.
+ *
+ * Key Features:
+ * - Non-blocking async delays that waste attacker time
+ * - Adaptive delay scaling based on DEFCON state
+ * - Configurable jitter to prevent timing analysis
+ * - Performance monitoring and statistics
+ * - Memory-efficient operation
+ *
+ * Shadow Ban vs Traditional Ban:
+ * - Doesn't immediately block (prevents attacker awareness)
+ * - Wastes attacker time with delays
+ * - Allows monitoring of attack patterns
+ * - Automatically expires via blacklist system
+ *
+ * @module shadowHandler
+ * @version 1.0.0
+ * @author Omindu Dissanayaka
+ * @license MIT
+ */
+
+/**
+ * Default configuration constants
+ * @readonly
+ */
+const DEFAULT_CONFIG = Object.freeze({
+  MIN_DELAY: 1000,
+  MAX_DELAY: 45000,
+  JITTER_PERCENT: 0.2,
+  RED_MULTIPLIER: 1.5,
+  YELLOW_MULTIPLIER: 1.2
+});
+
+/**
+ * Performance tracking statistics
+ * @private
+ */
+let stats = {
+  totalDelays: 0,
+  totalDelayTime: 0,
+  averageDelay: 0,
+  lastDelay: 0,
+  delaysByDefcon: {
+    GREEN: 0,
+    RED: 0
+  }
+};
+
+/**
+ * Calculates adaptive delay based on DEFCON state and base delay
+ *
+ * @private
+ * @param {number} baseDelay - Base delay time in milliseconds
+ * @param {string} defconState - Current DEFCON state ('GREEN', 'RED', etc.)
+ * @returns {number} Calculated delay with DEFCON multiplier applied
+ */
+function calculateAdaptiveDelay(baseDelay, defconState) {
+  let multiplier = 1.0;
+
+  switch (defconState) {
+    case 'RED':
+      multiplier = DEFAULT_CONFIG.RED_MULTIPLIER;
+      break;
+    case 'YELLOW':
+      multiplier = DEFAULT_CONFIG.YELLOW_MULTIPLIER;
+      break;
+    case 'GREEN':
+    default:
+      multiplier = 1.0;
+      break;
+  }
+
+  const adaptiveDelay = baseDelay * multiplier;
+
+  return Math.max(DEFAULT_CONFIG.MIN_DELAY,
+         Math.min(adaptiveDelay, DEFAULT_CONFIG.MAX_DELAY));
+}
+
+/**
+ * Applies random jitter to delay to prevent timing analysis attacks
+ * Uses cryptographically secure randomness for unpredictability
+ *
+ * @private
+ * @param {number} delay - Base delay time
+ * @returns {number} Delay with secure random jitter applied
+ */
+function applyJitter(delay) {
+  const jitterRange = delay * DEFAULT_CONFIG.JITTER_PERCENT;
+  const randomBytes = require('crypto').randomBytes(4);
+  const randomValue = randomBytes.readUInt32LE(0) / 0xFFFFFFFF;
+
+  const jitter = jitterRange * (randomValue * 2 - 1);
+  return Math.max(DEFAULT_CONFIG.MIN_DELAY, Math.floor(delay + jitter));
+}
+
+/**
+ * Delays request processing for blacklisted IPs using shadow ban technique
+ *
+ * This function implements the core shadow ban mechanism:
+ * 1. Calculates adaptive delay based on DEFCON state
+ * 2. Applies random jitter to prevent timing analysis
+ * 3. Performs non-blocking async delay
+ * 4. Updates performance statistics
+ * 5. Returns blocking decision
+ *
+ * The delay wastes attacker time while allowing legitimate monitoring
+ * of attack patterns and automated threat response.
+ *
+ * @function delay
+ * @param {string} ip - Client IP address being shadow banned
+ * @param {number} delayTime - Base delay duration in milliseconds
+ * @param {string} defconState - Current DEFCON state ('GREEN', 'RED', etc.)
+ * @returns {Promise<boolean>} Always returns true (indicating request should be blocked after delay)
+ *
+ * @example
+ * ```javascript
+ * // Shadow ban an IP for 5 seconds in GREEN state
+ * const shouldBlock = await shadowHandler.delay('192.168.1.100', 5000, 'GREEN');
+ * if (shouldBlock) {
+ *   res.status(408).json({ error: 'Request Timeout' });
+ * }
+ * ```
+ */
+async function delay(ip, delayTime, defconState = 'GREEN') {
+  const startTime = process.hrtime.bigint();
+
+  const baseDelay = Math.max(0, Math.min(delayTime || 0, DEFAULT_CONFIG.MAX_DELAY));
+  const cleanDefconState = (defconState || 'GREEN').toUpperCase();
+
+  const adaptiveDelay = calculateAdaptiveDelay(baseDelay, cleanDefconState);
+
+  const finalDelay = applyJitter(adaptiveDelay);
+
+  if (process.env.NODE_ENV === 'development') {
+    console.log(`[SHADOW] Delaying ${ip} for ${finalDelay}ms (${cleanDefconState} state)`);
+  }
+
+  await new Promise(resolve => {
+    setTimeout(resolve, finalDelay);
+  });
+
+  const delayDuration = Number(process.hrtime.bigint() - startTime) / 1000000;
+  stats.totalDelays++;
+  stats.totalDelayTime += delayDuration;
+  stats.averageDelay = stats.totalDelayTime / stats.totalDelays;
+  stats.lastDelay = delayDuration;
+  stats.delaysByDefcon[cleanDefconState] = (stats.delaysByDefcon[cleanDefconState] || 0) + 1;
+
+  return true;
+}
+
+/**
+ * Calculates random jitter for delay unpredictability (legacy function)
+ *
+ * @deprecated Use applyJitter() internally. This function is kept for backward compatibility.
+ * @function addJitter
+ * @param {number} baseDelay - Base delay time in milliseconds
+ * @returns {number} Delay with jitter applied
+ */
+function addJitter(baseDelay) {
+  return applyJitter(baseDelay);
+}
+
+/**
+ * Retrieves shadow ban performance statistics
+ *
+ * @function getStats
+ * @returns {Object} Performance statistics
+ * @property {number} totalDelays - Total number of delays performed
+ * @property {number} totalDelayTime - Total time spent delaying (ms)
+ * @property {number} averageDelay - Average delay duration (ms)
+ * @property {number} lastDelay - Most recent delay duration (ms)
+ * @property {Object} delaysByDefcon - Delays grouped by DEFCON state
+ *
+ * @example
+ * ```javascript
+ * const stats = shadowHandler.getStats();
+ * console.log(`Average delay: ${stats.averageDelay}ms`);
+ * ```
+ */
+function getStats() {
+  return {
+    ...stats,
+    config: DEFAULT_CONFIG
+  };
+}
+
+/**
+ * Resets performance statistics (useful for testing)
+ *
+ * @function resetStats
+ * @returns {Object} Previous statistics
+ */
+function resetStats() {
+  const previousStats = { ...stats };
+  stats = {
+    totalDelays: 0,
+    totalDelayTime: 0,
+    averageDelay: 0,
+    lastDelay: 0,
+    delaysByDefcon: {
+      GREEN: 0,
+      RED: 0
+    }
+  };
+  return previousStats;
+}
+
+/**
+ * Validates delay parameters for security and performance
+ *
+ * @function validateDelayParams
+ * @param {number} delayTime - Delay time to validate
+ * @param {string} defconState - DEFCON state to validate
+ * @returns {Object} Validation result
+ * @property {boolean} valid - Whether parameters are valid
+ * @property {string[]} errors - Array of validation errors
+ * @property {Object} sanitized - Sanitized parameters
+ */
+function validateDelayParams(delayTime, defconState) {
+  const errors = [];
+  const sanitized = {
+    delayTime: DEFAULT_CONFIG.MIN_DELAY,
+    defconState: 'GREEN'
+  };
+
+  if (typeof delayTime !== 'number' || isNaN(delayTime)) {
+    errors.push('Delay time must be a valid number');
+  } else if (delayTime < 0) {
+    errors.push('Delay time cannot be negative');
+    sanitized.delayTime = DEFAULT_CONFIG.MIN_DELAY;
+  } else if (delayTime > DEFAULT_CONFIG.MAX_DELAY) {
+    errors.push(`Delay time cannot exceed ${DEFAULT_CONFIG.MAX_DELAY}ms`);
+    sanitized.delayTime = DEFAULT_CONFIG.MAX_DELAY;
+  } else {
+    sanitized.delayTime = delayTime;
+  }
+
+  const validStates = ['GREEN', 'YELLOW', 'RED'];
+  const upperState = (defconState || '').toUpperCase();
+  if (!validStates.includes(upperState)) {
+    errors.push(`Invalid DEFCON state: ${defconState}. Must be one of: ${validStates.join(', ')}`);
+  } else {
+    sanitized.defconState = upperState;
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+    sanitized
+  };
+}
+
+module.exports = {
+  delay,
+  addJitter,
+  getStats,
+  resetStats,
+  validateDelayParams,
+  DEFAULT_CONFIG
+};