cipher-shield 1.0.0 → 1.1.0

package/README.md

@@ -2,7 +2,7 @@
 
 **Industrial-grade security middleware for Node.js/Express applications**
 
-[![Version](https://img.shields.io/badge/version-1.0.0-blue.svg)](https://github.com/OminduDissanayaka/cipher-shield)
+[![Version](https://img.shields.io/badge/version-1.1.0-blue.svg)](https://github.com/OminduDissanayaka/cipher-shield)
 [![NPM](https://img.shields.io/npm/v/cipher-shield.svg)](https://www.npmjs.com/package/cipher-shield)
 [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 [![Node.js](https://img.shields.io/badge/node-%3E%3D14.0.0-green.svg)](https://nodejs.org/)
@@ -242,35 +242,27 @@ app.use(cipherShield({
 
 ## 🚨 DEFCON System
 
-**Adaptive threat escalation that automatically adjusts security levels.**
+**Adaptive threat escalation that automatically adjusts security levels based on real-time threat patterns.**
 
-Monitors threat patterns and escalates security measures from GREEN (normal) to RED (maximum security) based on detected threats.
+The Cipher Shield DEFCON system monitors incoming traffic and automatically (or manually) escalates protection levels from 5 (Normal) to 1 (Maximum). Each level progressively activates deeper defensive layers.
 
-### Usage
+### 🛡️ DEFCON Level Technical Breakdown
 
-```javascript
-app.use(cipherShield({
-  adaptiveDefcon: true  // Enable automatic escalation
-}));
-```
+| Level | Posture | Features Activated | Performance Impact |
+|:---:|:---:|:--- |:---:|
+| **5** | **Normal** | Standard Passive Defense (Helmet headers, Security Signatures). | Low (Instant) |
+| **4** | **Guarded** | Enhanced Monitoring & Smart Logging (Recursive masking enabled). | Low (Instant) |
+| **3** | **Elevated** | **AI Gate** Analysis: Full payload scanning via Gemini/OpenAI integration. | Medium (+10-50ms) |
+| **2** | **High Alert** | **Ghost Routes** & **Active Shadow Banning**: Malicious IPs are trapped in honeypots. | High (+100ms+) |
+| **1** | **Maximum** | **Full Lockdown**: Minimal processing, strict authentication, and max-encryption. | Restricted |
 
-### DEFCON Levels
-
-- **GREEN**: Normal operation, standard security
-- **YELLOW**: Elevated threat, increased monitoring
-- **ORANGE**: High threat, reduced AI scanning
-- **RED**: Maximum threat, minimal processing
-
-### Manual Control
+### Manual Control Example
 
 ```javascript
 const { defconSystem } = require('cipher-shield');
 
-// Check current status
-const status = defconSystem.getStatus();
-
-// Manual escalation
-defconSystem.escalate('DDoS_ATTACK_DETECTED');
+// Manually escalate during a detected brute-force attempt
+defconSystem.escalate('DDoS_ATTACK_DETECTED'); // Moves to higher DEFCON level
 ```
 
 ---
@@ -633,9 +625,9 @@ const shield = cipherShield({
 
 ### 🆘 Getting Help
 
-- 📧 **Email**: hellow@omindu.dev
+- 📧 **Email**: support@cipher-shield.com
 - 🐛 **Issues**: [GitHub Issues](https://github.com/OminduDissanayaka/cipher-shield/issues)
-- 📖 **Documentation**: [Website](https://github.com/OminduDissanayaka/cipher-shield)
+- 📖 **Documentation**: [Website](https://cipher-shield.dev)
 
 ### 🤝 Contributing
 
@@ -663,4 +655,3 @@ const shield = cipherShield({
 
 **Built with ❤️ by [Omindu Dissanayaka](https://omindu.dev)**
 
-

package/index.js

@@ -6,7 +6,7 @@
  * threat detection, adaptive DEFCON escalation, and automated SSL certificate management.
  *
  * @module cipher-shield
- * @version 1.0.0
+ * @version 1.1.0
  * @author cipher-shield Team
  * @license MIT
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cipher-shield",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Advanced active defense middleware for Node.js/Express with AES encryption, honeypot detection, AI threat analysis, and adaptive security. Features 9 AES algorithms, ghost routes, shadow ban, and DEFCON system.",
   "main": "index.js",
   "files": [

package/src/core/aesEngine.js

@@ -12,7 +12,7 @@
  * - Performance optimized for high-throughput scenarios
  *
  * @module aesEngine
- * @version 1.0.0
+ * @version 1.1.0
  * @author Omindu Dissanayaka
  * @license MIT
  */
@@ -366,4 +366,4 @@ module.exports = {
   getSupportedAlgorithms,
   getAlgorithmInfo,
   ALGORITHMS
-};
+};

package/src/core/blacklistMem.js

@@ -13,7 +13,7 @@
  * - Thread-safe operations for concurrent requests
  *
  * @module blacklistMem
- * @version 1.0.0
+ * @version 1.1.0
  * @author Omindu Dissanayaka
  * @license MIT
  */
@@ -507,4 +507,4 @@ module.exports = {
   getEntry,
   events, // For advanced monitoring
   DEFAULT_CONFIG
-};
+};

package/src/core/defconSystem.js

@@ -6,8 +6,11 @@
  * system to prevent persistent high-security states while maintaining protection.
  *
  * DEFCON States:
- * - GREEN: Normal operation, all security features active but not aggressive
- * - RED: High alert, conservative security measures (may skip resource-intensive checks)
+ * - 5 (NORMAL): Standard passive defense, all features available
+ * - 4 (GUARDED): Enhanced monitoring and smart logging
+ * - 3 (ELEVATED): AI Gate analysis activated
+ * - 2 (HIGH_ALERT): Ghost routes and shadow banning active
+ * - 1 (MAXIMUM): Full lockdown with minimal processing
  *
  * Features:
  * - Automatic escalation based on threat patterns
@@ -16,7 +19,7 @@
  * - Performance monitoring and logging
  *
  * @module defconSystem
- * @version 1.0.0
+ * @version 1.1.0
  * @author Omindu Dissanayaka
  * @license MIT
  */
@@ -24,11 +27,14 @@
 /**
  * DEFCON security states enumeration
  * @readonly
- * @enum {string}
+ * @enum {number}
  */
 const DEFCON_STATES = Object.freeze({
-  GREEN: 'GREEN',
-  RED: 'RED'
+  NORMAL: 5,      // Standard Passive Defense
+  GUARDED: 4,     // Enhanced Monitoring & Smart Logging
+  ELEVATED: 3,    // AI Gate Analysis
+  HIGH_ALERT: 2,  // Ghost Routes & Active Shadow Banning
+  MAXIMUM: 1      // Full Lockdown
 });
 
 /**
@@ -45,7 +51,7 @@ const DEFAULT_CONFIG = Object.freeze({
  * Internal state management
  * @private
  */
-let currentState = DEFCON_STATES.GREEN;
+let currentState = DEFCON_STATES.NORMAL;
 let escalationCount = 0;
 let cooldownTimer = null;
 let lastEscalationTime = null;
@@ -68,7 +74,7 @@ let threatHistory = [];
  * ```
  */
 function initialize() {
-  currentState = DEFCON_STATES.GREEN;
+  currentState = DEFCON_STATES.NORMAL;
   escalationCount = 0;
   lastEscalationTime = null;
   threatHistory = [];
@@ -79,7 +85,7 @@ function initialize() {
   }
 
   if (process.env.NODE_ENV === 'development') {
-    console.log('[DEFCON] System initialized to GREEN state');
+    console.log('[DEFCON] System initialized to NORMAL (5) state');
   }
 }
 
@@ -87,13 +93,13 @@ function initialize() {
  * Retrieves the current DEFCON security state
  *
  * @function getState
- * @returns {string} Current DEFCON state ('GREEN' or 'RED')
+ * @returns {number} Current DEFCON level (1-5, where 5 is normal, 1 is maximum security)
  *
  * @example
  * ```javascript
- * const state = defconSystem.getState();
- * if (state === 'RED') {
- *   // Apply conservative security measures
+ * const level = defconSystem.getState();
+ * if (level <= 2) {
+ *   // Apply high security measures
  * }
  * ```
  */
@@ -104,13 +110,12 @@ function getState() {
 /**
  * Escalates the threat level based on detected malicious activity
  *
- * Increments the escalation counter and automatically transitions to RED state
- * when the threshold is reached. Implements cooldown-based auto-reset to
- * prevent indefinite high-security states.
+ * Decreases the DEFCON level (5→4→3→2→1) based on escalation thresholds.
+ * Implements cooldown-based auto-reset to prevent indefinite high-security states.
  *
  * @function escalate
  * @param {string} reason - Description of the threat that triggered escalation
- * @returns {boolean} True if escalation occurred, false if threshold not met
+ * @returns {boolean} True if escalation occurred, false if already at maximum
  *
  * @example
  * ```javascript
@@ -143,32 +148,63 @@ function escalate(reason) {
     threatHistory = threatHistory.slice(-100);
   }
 
-  if (escalationCount >= DEFAULT_CONFIG.ESCALATION_THRESHOLD && currentState === DEFCON_STATES.GREEN) {
-    currentState = DEFCON_STATES.RED;
+  // Progressive escalation based on threat count
+  let newState = currentState;
+  let escalated = false;
+
+  if (escalationCount >= DEFAULT_CONFIG.MAX_ESCALATION_COUNT && currentState > DEFCON_STATES.MAXIMUM) {
+    newState = DEFCON_STATES.MAXIMUM;
+    escalated = true;
+  } else if (escalationCount >= DEFAULT_CONFIG.ESCALATION_THRESHOLD * 4 && currentState > DEFCON_STATES.MAXIMUM) {
+    newState = DEFCON_STATES.MAXIMUM;
+    escalated = true;
+  } else if (escalationCount >= DEFAULT_CONFIG.ESCALATION_THRESHOLD * 3 && currentState > DEFCON_STATES.HIGH_ALERT) {
+    newState = DEFCON_STATES.HIGH_ALERT;
+    escalated = true;
+  } else if (escalationCount >= DEFAULT_CONFIG.ESCALATION_THRESHOLD * 2 && currentState > DEFCON_STATES.ELEVATED) {
+    newState = DEFCON_STATES.ELEVATED;
+    escalated = true;
+  } else if (escalationCount >= DEFAULT_CONFIG.ESCALATION_THRESHOLD && currentState > DEFCON_STATES.GUARDED) {
+    newState = DEFCON_STATES.GUARDED;
+    escalated = true;
+  }
+
+  if (escalated) {
+    const previousState = currentState;
+    currentState = newState;
 
     if (cooldownTimer) {
       clearTimeout(cooldownTimer);
     }
 
+    // Set cooldown timer to gradually increase security level back to normal
     cooldownTimer = setTimeout(() => {
-      currentState = DEFCON_STATES.GREEN;
-      escalationCount = Math.floor(escalationCount / 2);
-      cooldownTimer = null;
+      if (currentState < DEFCON_STATES.NORMAL) {
+        currentState = Math.min(currentState + 1, DEFCON_STATES.NORMAL);
+        escalationCount = Math.floor(escalationCount / 2);
+      }
 
-      if (process.env.NODE_ENV === 'development') {
-        console.log(`[DEFCON] Auto-reset to GREEN after ${DEFAULT_CONFIG.ESCALATION_TIMEOUT / 1000}s cooldown`);
+      if (currentState === DEFCON_STATES.NORMAL) {
+        escalationCount = 0;
+        cooldownTimer = null;
+        if (process.env.NODE_ENV === 'development') {
+          console.log(`[DEFCON] Auto-reset to NORMAL (5) after cooldown`);
+        }
+      } else {
+        // Continue cooldown for next level
+        setTimeout(() => {}, DEFAULT_CONFIG.ESCALATION_TIMEOUT);
       }
     }, DEFAULT_CONFIG.ESCALATION_TIMEOUT);
 
     if (process.env.NODE_ENV === 'development') {
-      console.warn(`[DEFCON] 🚨 ESCALATED to RED state: ${reason} (${escalationCount}/${DEFAULT_CONFIG.ESCALATION_THRESHOLD})`);
+      console.warn(`[DEFCON] 🚨 ESCALATED to Level ${currentState}: ${reason} (${escalationCount} threats)`);
     }
 
     return true;
   }
 
   if (process.env.NODE_ENV === 'development') {
-    console.log(`[DEFCON] Threat detected: ${reason} (${escalationCount}/${DEFAULT_CONFIG.ESCALATION_THRESHOLD})`);
+    console.log(`[DEFCON] Threat detected: ${reason} (${escalationCount} total threats, Level ${currentState})`);
   }
 
   return false;
@@ -182,27 +218,27 @@ function escalate(reason) {
  * and counter resets.
  *
  * @function setState
- * @param {string} state - Target state ('GREEN' or 'RED')
- * @returns {boolean} True if state was changed, false if invalid state provided
+ * @param {number} level - Target DEFCON level (1-5)
+ * @returns {boolean} True if state was changed, false if invalid level provided
  *
  * @example
  * ```javascript
- * defconSystem.setState('RED');   // Force high alert
- * defconSystem.setState('GREEN'); // Reset to normal
+ * defconSystem.setState(1); // Force maximum security
+ * defconSystem.setState(5); // Reset to normal
  * ```
  */
-function setState(state) {
-  if (state !== DEFCON_STATES.GREEN && state !== DEFCON_STATES.RED) {
+function setState(level) {
+  if (typeof level !== 'number' || level < 1 || level > 5) {
     if (process.env.NODE_ENV === 'development') {
-      console.error(`[DEFCON] Invalid state: ${state}. Must be 'GREEN' or 'RED'`);
+      console.error(`[DEFCON] Invalid level: ${level}. Must be a number between 1 and 5`);
     }
     return false;
   }
 
   const previousState = currentState;
-  currentState = state;
+  currentState = level;
 
-  if (state === DEFCON_STATES.GREEN) {
+  if (level === DEFCON_STATES.NORMAL) {
     escalationCount = 0;
     lastEscalationTime = null;
 
@@ -213,7 +249,7 @@ function setState(state) {
   }
 
   if (process.env.NODE_ENV === 'development') {
-    console.log(`[DEFCON] Manual state change: ${previousState} → ${state}`);
+    console.log(`[DEFCON] Manual state change: Level ${previousState} → Level ${level}`);
   }
 
   return true;
@@ -298,4 +334,4 @@ module.exports = {
   resetCounter,
   DEFCON_STATES,
   DEFAULT_CONFIG
-};
+};

package/src/magicAuth.js

@@ -5,7 +5,7 @@
  * secure defaults, and Express middleware integration.
  *
  * @module MagicAuth
- * @version 1.0.0
+ * @version 1.1.0
  * @author Omindu Dissanayaka
  * @license MIT
  */
@@ -269,4 +269,4 @@ class MagicAuth {
   }
 }
 
-module.exports = MagicAuth;
+module.exports = MagicAuth;

package/src/modules/aiScanner.js

@@ -6,7 +6,7 @@
  * injection attacks, and security threats.
  *
  * @module aiScanner
- * @version 1.0.0
+ * @version 1.1.0
  */
 
 const { GoogleGenerativeAI } = require('@google/generative-ai');
@@ -479,4 +479,4 @@ module.exports = {
   clearCache,
   validateConfig,
   DEFAULT_CONFIG
-};
+};

package/src/modules/ghostHandler.js

@@ -17,7 +17,7 @@
  * - Memory-efficient string operations
  *
  * @module ghostHandler
- * @version 1.0.0
+ * @version 1.1.0
  * @author Omindu Dissanayaka
  * @license MIT
  */
@@ -276,4 +276,4 @@ module.exports = {
   validatePattern,
   getPatternStats,
   clearCache
-};
+};

package/src/modules/shadowHandler.js

@@ -19,7 +19,7 @@
  * - Automatically expires via blacklist system
  *
  * @module shadowHandler
- * @version 1.0.0
+ * @version 1.1.0
  * @author Omindu Dissanayaka
  * @license MIT
  */
@@ -32,8 +32,11 @@ const DEFAULT_CONFIG = Object.freeze({
   MIN_DELAY: 1000,
   MAX_DELAY: 45000,
   JITTER_PERCENT: 0.2,
-  RED_MULTIPLIER: 1.5,
-  YELLOW_MULTIPLIER: 1.2
+  MAXIMUM_MULTIPLIER: 2.0,    // Level 1: Maximum security
+  HIGH_ALERT_MULTIPLIER: 1.8, // Level 2: High alert
+  ELEVATED_MULTIPLIER: 1.5,   // Level 3: Elevated
+  GUARDED_MULTIPLIER: 1.2,    // Level 4: Guarded
+  NORMAL_MULTIPLIER: 1.0      // Level 5: Normal
 });
 
 /**
@@ -46,8 +49,11 @@ let stats = {
   averageDelay: 0,
   lastDelay: 0,
   delaysByDefcon: {
-    GREEN: 0,
-    RED: 0
+    1: 0, // MAXIMUM
+    2: 0, // HIGH_ALERT
+    3: 0, // ELEVATED
+    4: 0, // GUARDED
+    5: 0  // NORMAL
   }
 };
 
@@ -59,17 +65,23 @@ let stats = {
  * @param {string} defconState - Current DEFCON state ('GREEN', 'RED', etc.)
  * @returns {number} Calculated delay with DEFCON multiplier applied
  */
-function calculateAdaptiveDelay(baseDelay, defconState) {
+function calculateAdaptiveDelay(baseDelay, defconLevel) {
   let multiplier = 1.0;
 
-  switch (defconState) {
-    case 'RED':
-      multiplier = DEFAULT_CONFIG.RED_MULTIPLIER;
+  switch (defconLevel) {
+    case 1: // MAXIMUM
+      multiplier = DEFAULT_CONFIG.MAXIMUM_MULTIPLIER;
       break;
-    case 'YELLOW':
-      multiplier = DEFAULT_CONFIG.YELLOW_MULTIPLIER;
+    case 2: // HIGH_ALERT
+      multiplier = DEFAULT_CONFIG.HIGH_ALERT_MULTIPLIER;
       break;
-    case 'GREEN':
+    case 3: // ELEVATED
+      multiplier = DEFAULT_CONFIG.ELEVATED_MULTIPLIER;
+      break;
+    case 4: // GUARDED
+      multiplier = DEFAULT_CONFIG.GUARDED_MULTIPLIER;
+      break;
+    case 5: // NORMAL
     default:
       multiplier = 1.0;
       break;
@@ -263,4 +275,4 @@ module.exports = {
   resetStats,
   validateDelayParams,
   DEFAULT_CONFIG
-};
+};

package/src/shield.js

@@ -6,7 +6,7 @@
  * threat detection with adaptive DEFCON escalation.
  *
  * @author Omindu Dissanayaka
- * @version 1.0.0
+ * @version 1.1.0
  * @license MIT
  */
 
@@ -363,7 +363,7 @@ function validateAndNormalizeConfig(config = {}) {
  * threat detection, adaptive DEFCON escalation, and automated SSL certificate management.
  *
  * @class CipherShield
- * @version 1.0.0
+ * @version 1.1.0
  * @author Omindu Dissanayaka
  * @license MIT
  */
@@ -496,34 +496,43 @@ class CipherShield {
 
     try {
       if (this.config.ghostRoutes.length > 0) {
-        const isGhostRoute = ghostHandler.detect(req.path, this.config.ghostRoutes);
+        const currentDefcon = this.config.adaptiveDefcon ? defconSystem.getState() : 5;
 
-        if (isGhostRoute) {
-          blacklistMem.add(clientIP, 'ghost_route_access');
+        // Ghost Routes activate at DEFCON Level 2 and below (High Alert, Maximum)
+        if (currentDefcon <= 2) {
+          const isGhostRoute = ghostHandler.detect(req.path, this.config.ghostRoutes);
 
-          if (this.config.adaptiveDefcon) {
-            defconSystem.escalate('GHOST_ROUTE_HIT');
-          }
+          if (isGhostRoute) {
+            blacklistMem.add(clientIP, 'ghost_route_access');
+
+            if (this.config.adaptiveDefcon) {
+              defconSystem.escalate('GHOST_ROUTE_HIT');
+            }
 
+          }
         }
       }
 
       if (this.config.shadowBan.enabled && blacklistMem.isBlacklisted(clientIP)) {
-        const currentDefcon = this.config.adaptiveDefcon ? defconSystem.getState() : 'GREEN';
-        const shouldBlock = await shadowHandler.delay(
-          clientIP,
-          this.config.shadowBan.delayTime,
-          currentDefcon
-        );
+        const currentDefcon = this.config.adaptiveDefcon ? defconSystem.getState() : 5;
 
-        if (shouldBlock) {
-          const processingTime = Number(process.hrtime.bigint() - startTime) / 1000000;
-          console.log(`[cipher-shield] Blocked ${clientIP} after ${processingTime.toFixed(2)}ms`);
+        // Shadow Ban activates at DEFCON Level 2 and below (High Alert, Maximum)
+        if (currentDefcon <= 2) {
+          const shouldBlock = await shadowHandler.delay(
+            clientIP,
+            this.config.shadowBan.delayTime,
+            currentDefcon
+          );
 
-          return res.status(408).json(addSecurityBranding({
-            error: 'Request Timeout',
-            message: 'The server timed out waiting for the request'
-          }, this.config.signature));
+          if (shouldBlock) {
+            const processingTime = Number(process.hrtime.bigint() - startTime) / 1000000;
+            console.log(`[cipher-shield] Blocked ${clientIP} after ${processingTime.toFixed(2)}ms`);
+
+            return res.status(408).json(addSecurityBranding({
+              error: 'Request Timeout',
+              message: 'The server timed out waiting for the request'
+            }, this.config.signature));
+          }
         }
       }
 
@@ -617,9 +626,10 @@ class CipherShield {
         );
 
         if (shouldScanRoute) {
-          const currentDefcon = this.config.adaptiveDefcon ? defconSystem.getState() : 'GREEN';
+          const currentDefcon = this.config.adaptiveDefcon ? defconSystem.getState() : 5;
 
-          if (currentDefcon !== 'RED' || !this.config.adaptiveDefcon) {
+          // AI Gate activates at DEFCON Level 3 and below (Elevated, High Alert, Maximum)
+          if (currentDefcon <= 3 || !this.config.adaptiveDefcon) {
             try {
               const aiConfig = {
                 provider: this.config.aiGate.provider,
@@ -691,4 +701,4 @@ class CipherShield {
   }
 }
 
-module.exports = CipherShield;
+module.exports = CipherShield;

package/src/smartLogger.js

@@ -6,7 +6,7 @@
  * like passwords, tokens, and API keys.
  *
  * @module SmartLogger
- * @version 1.0.0
+ * @version 1.1.0
  * @author Omindu Dissanayaka
  * @license MIT
  */
@@ -265,4 +265,4 @@ class SmartLogger {
   }
 }
 
-module.exports = SmartLogger;
+module.exports = SmartLogger;

package/src/sslManager.js

@@ -5,7 +5,7 @@
  * Supports HTTP-01 challenge automation, secure certificate storage, and auto-renewal.
  *
  * @module SSLManager
- * @version 1.0.0
+ * @version 1.1.0
  * @author Omindu Dissanayaka
  * @license MIT
  */
@@ -342,4 +342,4 @@ class SSLManager {
   }
 }
 
-module.exports = SSLManager;
+module.exports = SSLManager;