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. Now Redis‑powered and ready for distributed, multiprocess use.

---

Features

• ✅ 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

npm install aiwaf-js --save

---

Train the Model (Optional but recommended)

You can train the anomaly detector and keyword learner using real access logs.

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

const express = require('express')
const aiwaf   = require('aiwaf-js')

const app = express()
app.use(express.json())
app.use(aiwaf())
app.get('/', (req, res) => res.send('Protected'))
app.listen(3000)

---

Redis Support (Recommended for Production)

AIWAF‑JS supports Redis for distributed rate limiting and keyword caching.

# 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.

---

Custom Cache Logic (Advanced)

You can inject your own cache logic (in-memory, Redis, hybrid, or file-based) by passing a cache object implementing the following interface:

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,
}))

This overrides Redis/in-memory usage with your custom strategy for all cache operations.

---

Configuration

app.use(aiwaf({
  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
}));

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

Tip: In high-volume environments, caching the feature vector extractor (especially if Redis is unavailable) can reduce redundant computation and significantly boost performance.

---

📄 License

MIT License © 2025 Aayush Gauba