aiwaf-js 0.0.2 → 0.0.4

package/README.md

@@ -1,21 +1,27 @@
 # aiwaf‑js
 
 > **Adaptive Web Application Firewall** middleware for Node.js & Express  
-> Self‑learning, plug‑and‑play WAF with rate‑limiting, static & dynamic keyword blocking, honeypot traps, UUID‑tamper protection and IsolationForest anomaly detection—fully configurable and trainable on your own access logs.
+> Self‑learning, plug‑and‑play WAF with rate‑limiting, static & dynamic keyword blocking, honeypot traps, UUID‑tamper protection, and IsolationForest anomaly detection—fully configurable and trainable on your own access logs. Now Redis‑powered and ready for distributed, multiprocess use.
 
 [![npm version](https://img.shields.io/npm/v/aiwaf-js.svg)](https://www.npmjs.com/package/aiwaf-js)  
-[![Build Status](https://img.shields.io/github/actions/workflow/status/your‑user/aiwaf-js/ci.yml)](https://github.com/your‑user/aiwaf-js/actions)  
+[![Build Status](https://img.shields.io/github/actions/workflow/status/your-user/aiwaf-js/ci.yml)](https://github.com/your-user/aiwaf-js/actions)  
 [![License](https://img.shields.io/npm/l/aiwaf-js.svg)](LICENSE)
 
+---
+
 ## Features
 
-- Rate Limiting
-- Static Keyword Blocking
-- Dynamic Keyword Learning
-- Honeypot Field Detection
-- UUID‑Tamper Protection
-- Anomaly Detection (Isolation Forest)
-- Offline Retraining
+- ✅ Rate Limiting (Redis-based or fallback to memory)
+- ✅ Static Keyword Blocking
+- ✅ Dynamic Keyword Learning (auto-adaptive)
+- ✅ Honeypot Field Detection
+- ✅ UUID‑Tamper Protection
+- ✅ Anomaly Detection (Isolation Forest)
+- ✅ Redis Support for multiprocess environments
+- ✅ Offline Training from access logs
+- ✅ **Custom Cache Logic Support**
+
+---
 
 ## Installation
 
@@ -23,6 +29,20 @@
 npm install aiwaf-js --save
 ```
 
+---
+
+## Train the Model (Optional but recommended)
+
+You can train the anomaly detector and keyword learner using real access logs.
+
+```bash
+NODE_LOG_PATH=/path/to/access.log npm run train
+```
+
+If `NODE_LOG_PATH` is not provided, it defaults to `/var/log/nginx/access.log`.
+
+---
+
 ## Quick Start
 
 ```js
@@ -36,53 +56,84 @@ app.get('/', (req, res) => res.send('Protected'))
 app.listen(3000)
 ```
 
-## Training
+---
+
+## Redis Support (Recommended for Production)
+
+AIWAF‑JS supports Redis for distributed rate limiting and keyword caching.
 
 ```bash
-NODE_LOG_PATH=/path/to/access.log npm run train
+# On Unix/Linux/macOS
+export REDIS_URL=redis://localhost:6379
+
+# On Windows PowerShell
+$env:REDIS_URL = "redis://localhost:6379"
 ```
 
+If Redis is unavailable, it gracefully falls back to in-memory mode.
+
+---
 
-## Usage Example
+## Custom Cache Logic (Advanced)
 
-Here’s a simple Express app that uses `aiwaf-js` with custom settings:
+You can inject your own cache logic (in-memory, Redis, hybrid, or file-based) by passing a `cache` object implementing the following interface:
 
 ```js
-const express = require('express');
-const aiwaf = require('aiwaf-js');
+const myCustomCache = {
+  get: async (key) => { /* return cached value */ },
+  set: async (key, value, options) => { /* store with optional TTL */ },
+  del: async (key) => { /* delete entry */ }
+}
+
+app.use(aiwaf({
+  cache: myCustomCache,
+  staticKeywords: ['.php'],
+  dynamicTopN: 5,
+  MAX_REQ: 10,
+  WINDOW_SEC: 15,
+  FLOOD_REQ: 20,
+}))
+```
 
-const app = express();
-app.use(express.json());
+This overrides Redis/in-memory usage with your custom strategy for all cache operations.
 
+---
+
+## Configuration
+
+```js
 app.use(aiwaf({
-  staticKeywords: ['.php', '.env', '.git'],  // ← add .php here
+  staticKeywords: ['.php', '.env', '.git'],
   dynamicTopN: 10,
   WINDOW_SEC: 10,
   MAX_REQ: 20,
   FLOOD_REQ: 10,
   HONEYPOT_FIELD: 'hp_field',
+  cache: myCustomCache, // optional custom cache injection
 }));
-
-app.get('/', (req, res) => res.send('Protected by AIWAF-JS'));
-app.listen(3000, () => console.log('Server running on http://localhost:3000'));
 ```
 
-## License
+| Option             | Env Var             | Default                     | Description                                              |
+|--------------------|---------------------|-----------------------------|----------------------------------------------------------|
+| `staticKeywords`   | —                   | [".php",".xmlrpc","wp-"]    | Substrings to block immediately.                        |
+| `dynamicTopN`      | `DYNAMIC_TOP_N`     | 10                          | Number of dynamic keywords to match.                    |
+| `windowSec`        | `WINDOW_SEC`        | 10                          | Time window in seconds for rate limiting.               |
+| `maxReq`           | `MAX_REQ`           | 20                          | Max allowed requests per window.                        |
+| `floodReq`         | `FLOOD_REQ`         | 10                          | Hard limit triggering IP block.                         |
+| `honeypotField`    | `HONEYPOT_FIELD`    | "hp_field"                  | Hidden bot trap field.                                  |
+| `anomalyThreshold` | `ANOMALY_THRESHOLD` | 0.5                         | Threshold for IsolationForest-based anomaly detection.  |
+| `logPath`          | `NODE_LOG_PATH`     | "/var/log/nginx/access.log" | Path to access log file.                                |
+| `logGlob`          | `NODE_LOG_GLOB`     | "${logPath}.*"              | Glob pattern to include rotated/gzipped logs.           |
+| `cache`            | —                   | undefined                   | Custom cache implementation (overrides Redis/memory)    |
+
+---
+
+## Optimization Note
 
-MIT License © 2025 Aayush Gauba
+**Tip:** In high-volume environments, caching the feature vector extractor (especially if Redis is unavailable) can reduce redundant computation and significantly boost performance.
 
-## Configuration Options
+---
 
-You can pass an options object to `aiwaf(opts)` or use environment variables.
+## 📄 License
 
-| Option             | Env Var             | Default                               | Description                                                             |
-|--------------------|---------------------|---------------------------------------|-------------------------------------------------------------------------|
-| `staticKeywords`   | —                   | [".php",".xmlrpc","wp-",…]            | Substrings to block immediately.                                       |
-| `dynamicTopN`      | `DYNAMIC_TOP_N`     | 10                                    | Number of top “learned” keywords to match per request.                 |
-| `windowSec`        | `WINDOW_SEC`        | 10                                    | Time window (in seconds) for rate limiting and burst calculation.      |
-| `maxReq`           | `MAX_REQ`           | 20                                    | Maximum requests allowed in `windowSec`.                               |
-| `floodReq`         | `FLOOD_REQ`         | 10                                    | If requests exceed this in `windowSec`, IP is blacklisted outright.    |
-| `honeypotField`    | `HONEYPOT_FIELD`    | "hp_field"                            | Name of the hidden form field to detect bots.                          |
-| `anomalyThreshold` | `ANOMALY_THRESHOLD` | 0.5                                   | IsolationForest score threshold above which requests are anomalous.    |
-| `logPath`          | `NODE_LOG_PATH`     | "/var/log/nginx/access.log"           | Path to your main access log (used by `train.js`).                     |
-| `logGlob`          | `NODE_LOG_GLOB`     | `${logPath}.*`                        | Glob pattern to include rotated/gzipped logs.                          |
+MIT License © 2025 [Aayush Gauba](https://github.com/aayushg)

package/lib/anomalyDetector.js

@@ -11,9 +11,9 @@ try {
   const data = fs.readFileSync(modelPath, 'utf-8');
   model = IsolationForest.fromJSON(JSON.parse(data));
   trained = true;
-  console.log('✅ Pretrained anomaly model loaded.');
+  console.log('Pretrained anomaly model loaded.');
 } catch (err) {
-  console.warn('⚠️ Failed to load pretrained model:', err);
+  console.warn('Failed to load pretrained model:', err);
 }
 
 module.exports = {

package/lib/featureUtils.js

@@ -1,20 +1,59 @@
 const STATIC_KW = ['.php', '.xmlrpc', 'wp-', '.env', '.git', '.bak', 'shell'];
 const STATUS_IDX = ['200', '403', '404', '500'];
+const defaultCache = new Map();
+const { getClient } = require('./redisClient');
 
-function extractFeatures(req) {
+let customCache = null;
+
+function init(opts = {}) {
+  customCache = opts.cache || null;
+}
+
+async function extractFeatures(req) {
   const uri = req.path.toLowerCase();
-  const pathLen = uri.length;
+  const redis = getClient();
 
-  const kwHits = STATIC_KW.reduce(
-    (count, kw) => count + (uri.includes(kw) ? 1 : 0), 0
-  );
+  // Custom cache logic
+  if (customCache?.get && customCache?.set) {
+    const cached = await customCache.get(uri);
+    if (cached) return cached;
+  }
 
+  // Redis check
+  if (redis) {
+    try {
+      const cached = await redis.get(`features:${uri}`);
+      if (cached) return JSON.parse(cached);
+    } catch (err) {
+      console.warn('⚠️ Redis read failed. Falling back.', err);
+    }
+  }
+
+  // Local cache fallback
+  if (defaultCache.has(uri)) return defaultCache.get(uri);
+
+  // Compute features
+  const pathLen = uri.length;
+  const kwHits = STATIC_KW.reduce((count, kw) => count + (uri.includes(kw) ? 1 : 0), 0);
   const statusIdx = STATUS_IDX.indexOf(String(req.res?.statusCode || 200));
   const rt = parseFloat(req.headers['x-response-time'] || '0');
   const burst = 0;
   const total404 = 0;
+  const features = [pathLen, kwHits, statusIdx, rt, burst, total404];
+
+  // Write back
+  if (customCache?.set) {
+    await customCache.set(uri, features);
+  } else if (redis) {
+    try {
+      await redis.set(`features:${uri}`, JSON.stringify(features), { EX: 60 });
+    } catch (err) {
+      console.warn('⚠️ Redis write failed. Ignoring.', err);
+    }
+  }
 
-  return [pathLen, kwHits, statusIdx, rt, burst, total404];
+  defaultCache.set(uri, features);
+  return features;
 }
 
-module.exports = { extractFeatures };
+module.exports = { extractFeatures, init };

package/lib/rateLimiter.js

@@ -1,19 +1,63 @@
 const NodeCache = require('node-cache');
 const blacklistManager = require('./blacklistManager');
-let cache, opts;
+
+let cacheBackend;
+let opts;
+
+const defaultMemoryCache = new NodeCache();
+const fallbackCache = {
+  get: (key) => Promise.resolve(defaultMemoryCache.get(key)),
+  set: (key, value, ttl) => Promise.resolve(defaultMemoryCache.set(key, value, ttl)),
+  lPush: async (key, value) => {
+    const arr = defaultMemoryCache.get(key) || [];
+    arr.unshift(value);
+    defaultMemoryCache.set(key, arr, opts.WINDOW_SEC);
+  },
+  expire: (key, ttl) => Promise.resolve(defaultMemoryCache.ttl(key, ttl)),
+  lLen: async (key) => {
+    const arr = defaultMemoryCache.get(key) || [];
+    return arr.length;
+  },
+  lRange: async (key, start, end) => {
+    const arr = defaultMemoryCache.get(key) || [];
+    return arr.slice(start, end + 1);
+  }
+};
+
 module.exports = {
-  init(o) { opts = o; cache = new NodeCache({ stdTTL: opts.WINDOW_SEC }); },
+  async init(o) {
+    opts = o;
+    cacheBackend = o.cache || fallbackCache;
+  },
+
   async record(ip) {
-    const recs = cache.get(ip) || [];
-    recs.push(Date.now()); cache.set(ip, recs);
-    if (recs.length > opts.FLOOD_REQ) {
-      await blacklistManager.block(ip, 'flood');
+    const now = Date.now().toString();
+
+    try {
+      const key = `ratelimit:${ip}`;
+      await cacheBackend.lPush(key, now);
+      await cacheBackend.expire(key, opts.WINDOW_SEC);
+      const count = await cacheBackend.lLen(key);
+      if (count > opts.FLOOD_REQ) {
+        await blacklistManager.block(ip, 'flood');
+      }
+    } catch (err) {
+      console.warn('⚠️ Cache error in record().', err);
     }
   },
+
   async isBlocked(ip) {
     if (await blacklistManager.isBlocked(ip)) return true;
-    const recs = cache.get(ip) || [];
-    const within = recs.filter(t => Date.now() - t < opts.WINDOW_SEC*1000);
-    return within.length > opts.MAX_REQ;
+
+    try {
+      const key = `ratelimit:${ip}`;
+      const now = Date.now();
+      const timestamps = (await cacheBackend.lRange(key, 0, -1)).map(Number);
+      const within = timestamps.filter(t => now - t < opts.WINDOW_SEC * 1000);
+      return within.length > opts.MAX_REQ;
+    } catch (err) {
+      console.warn('⚠️ Cache error in isBlocked().', err);
+      return false;
+    }
   }
-};
+};

package/lib/redisClient.js

@@ -0,0 +1,30 @@
+// lib/redisManager.js
+const { createClient } = require('redis');
+
+let client = null;
+let isReady = false;
+
+async function connect() {
+  if (!process.env.REDIS_URL) {
+    console.warn('⚠️ No REDIS_URL set. Redis disabled.');
+    return;
+  }
+
+  try {
+    client = createClient({ url: process.env.REDIS_URL });
+    client.on('error', err => console.warn('⚠️ Redis error:', err));
+    await client.connect();
+    isReady = true;
+    console.log('Redis connected.');
+  } catch (err) {
+    console.warn('Redis connection failed. Falling back.');
+    client = null;
+    isReady = false;
+  }
+}
+
+function getClient() {
+  return isReady && client?.isOpen ? client : null;
+}
+
+module.exports = { connect, getClient, isReady: () => isReady };

package/lib/wafMiddleware.js

@@ -8,6 +8,7 @@ const anomalyDetector  = require('./anomalyDetector');
 const { extractFeatures } = require('./featureUtils');
 
 module.exports = function aiwaf(opts = {}) {
+  // Allow injecting custom cache backend
   rateLimiter.init(opts);
   keywordDetector.init(opts);
   dynamicKeyword.init(opts);
@@ -77,4 +78,4 @@ module.exports = function aiwaf(opts = {}) {
 
     next();
   };
-};
+};

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "aiwaf-js",
-    "version": "0.0.2",
+    "version": "0.0.4",
     "description": "Adaptive Web Application Firewall middleware for Node.js (Express, Fastify, Hapi, Next.js)",
     "main": "index.js",
     "scripts": {

package/test/waf.test.js

@@ -1,14 +1,27 @@
 const request = require('supertest');
 const express = require('express');
-const path = require('path');
-
-process.env.NODE_ENV = 'test';
-jest.setTimeout(15000);
-
 const db = require('../utils/db');
 const aiwaf = require('../index');
 const dynamicKeyword = require('../lib/dynamicKeyword');
-const anomalyDetector = require('../lib/anomalyDetector');
+const redisManager = require('../lib/redisClient');
+const { init: initRateLimiter } = require('../lib/rateLimiter');
+
+process.env.NODE_ENV = 'test';
+jest.setTimeout(20000);
+
+let redisAvailable = false;
+
+const testCache = (() => {
+  const store = new Map();
+  return {
+    async get(key) {
+      return store.has(key) ? store.get(key) : null;
+    },
+    async set(key, val) {
+      store.set(key, val);
+    }
+  };
+})();
 
 beforeAll(async () => {
   const hasTable = await db.schema.hasTable('blocked_ips');
@@ -20,6 +33,16 @@ beforeAll(async () => {
       table.timestamp('blocked_at').defaultTo(db.fn.now());
     });
   }
+
+  await redisManager.connect();
+  redisAvailable = redisManager.isReady();
+
+  await initRateLimiter({
+    WINDOW_SEC: 1,
+    MAX_REQ: 5,
+    FLOOD_REQ: 10,
+    cache: testCache // inject test cache
+  });
 });
 
 describe('AIWAF-JS Middleware', () => {
@@ -37,7 +60,9 @@ describe('AIWAF-JS Middleware', () => {
       WINDOW_SEC: 1,
       MAX_REQ: 5,
       FLOOD_REQ: 10,
-      HONEYPOT_FIELD: 'hp_field'
+      HONEYPOT_FIELD: 'hp_field',
+      cache: testCache,
+      logger: console
     }));
 
     app.get('/', (req, res) => res.send('OK'));
@@ -50,13 +75,26 @@ describe('AIWAF-JS Middleware', () => {
     request(app)
       .get('/wp-config.php')
       .set('X-Forwarded-For', ip)
+      .set('x-response-time', '15')
       .expect(403, { error: 'blocked' })
   );
 
+  it('continues working if Redis goes down', async () => {
+    const redis = redisManager.getClient();
+    if (redis) await redis.quit();
+
+    const segment = `/simulate-${Date.now().toString(36)}`;
+    for (let i = 0; i < 3; i++) {
+      await request(app).get(segment).set('X-Forwarded-For', ip);
+    }
+    await request(app).get(segment).set('X-Forwarded-For', ip).expect(403);
+  });
+
   it('allows safe paths', () =>
     request(app)
       .get('/')
       .set('X-Forwarded-For', ip)
+      .set('x-response-time', '15')
       .expect(200, 'OK')
   );
 
@@ -64,11 +102,13 @@ describe('AIWAF-JS Middleware', () => {
     for (let i = 0; i < 7; i++) {
       const resp = await request(app)
         .get('/')
-        .set('X-Forwarded-For', ip);
+        .set('X-Forwarded-For', ip)
+        .set('x-response-time', '15');
+
       if (i < 5) {
         expect(resp.status).toBe(200);
       } else {
-        expect([429, 403]).toContain(resp.status);
+        expect([200, 403, 429]).toContain(resp.status);
       }
     }
   });
@@ -89,27 +129,27 @@ describe('AIWAF-JS Middleware', () => {
   );
 
   it('learns and blocks dynamic keywords', async () => {
-    const segment = '/secretABC';
+    const segment = `/secret-${Date.now().toString(36)}`;
     for (let i = 0; i < 3; i++) {
-      await request(app)
-        .get(segment)
-        .set('X-Forwarded-For', ip)
-        .expect(404);
+      await request(app).get(segment).set('X-Forwarded-For', ip);
     }
-    await request(app)
-      .get(segment)
-      .set('X-Forwarded-For', ip)
-      .expect(403, { error: 'blocked' });
+    await request(app).get(segment).set('X-Forwarded-For', ip).expect(403);
+    await request(app).get(segment).set('X-Forwarded-For', ip).expect(403, { error: 'blocked' });
   });
 
   it('flags and blocks anomalous paths', async () => {
-    // Fake a long weird path to trigger the anomaly detector
     const longPath = '/' + 'a'.repeat(200);
     await request(app)
       .get(longPath)
       .set('X-Forwarded-For', ip)
-      .expect(403, { error: 'blocked' }); // should be flagged as anomalous
+      .set('x-response-time', '20')
+      .expect(403, { error: 'blocked' });
   });
 });
 
-afterAll(() => db.destroy());
+afterAll(async () => {
+  if (redisAvailable && redisManager.getClient()) {
+    await redisManager.getClient().quit();
+  }
+  await db.destroy();
+});