aiwaf-js 0.0.4 → 0.0.7

package/.dockerignore

@@ -0,0 +1,6 @@
+node_modules
+**/node_modules
+dist
+build
+npm-debug.log
+*.log

package/.github/workflows/node.js.yml

@@ -26,6 +26,6 @@
        with:
          node-version: ${{ matrix.node-version }}
          cache: 'npm'
-     - run: npm ci
+     - run: npm install
      - run: npm run build --if-present
      - run: npm test

package/.github/workflows/npm-publish.yml

@@ -8,6 +8,7 @@ on:
 jobs:
   build-and-publish:
     runs-on: ubuntu-latest
+    environment: npm-publish
 
     steps:
       - uses: actions/checkout@v4
@@ -19,7 +20,7 @@ jobs:
           node-version: 20
           registry-url: https://registry.npmjs.org/
 
-      - run: npm ci
+      - run: npm install
       - run: npm test
       - run: npm publish --access public
         env:

package/INSTALLATION.md

@@ -0,0 +1,144 @@
+# AIWAF-JS Installation Guide
+
+This guide covers local setup, Redis setup, training setup, and common failure modes.
+
+## Prerequisites
+
+- Node.js 18+ recommended
+- npm 9+ recommended
+- Build tooling required by `sqlite3` (platform dependent)
+
+## 1. Install Package
+
+For application use:
+
+```bash
+npm install aiwaf-js
+```
+
+For local development in this repository:
+
+```bash
+npm install
+```
+
+## 2. Basic Integration (Express)
+
+```js
+const express = require('express');
+const aiwaf = require('aiwaf-js');
+
+const app = express();
+app.use(express.json());
+
+app.use(aiwaf({
+  staticKeywords: ['.php', '.env', '.git'],
+  dynamicTopN: 10,
+  WINDOW_SEC: 10,
+  MAX_REQ: 20,
+  FLOOD_REQ: 40,
+  HONEYPOT_FIELD: 'hp_field',
+  uuidRoutePrefix: '/user'
+}));
+```
+
+## 3. Optional Redis Setup
+
+Set `REDIS_URL` (or `AIWAF_REDIS_URL`) before app startup:
+
+```bash
+export REDIS_URL=redis://localhost:6379
+```
+
+PowerShell:
+
+```powershell
+$env:REDIS_URL = 'redis://localhost:6379'
+```
+
+If Redis is not configured or not reachable, AIWAF-JS falls back to in-memory behavior.
+
+## 3.1 Optional GeoIP MMDB Setup
+
+Install MMDB reader:
+
+```bash
+npm install maxmind
+```
+
+Place your database at `geolock/ipinfo_lite.mmdb` or set:
+
+```bash
+export AIWAF_GEO_MMDB_PATH=/absolute/path/to/ipinfo_lite.mmdb
+```
+
+## 4. Train a Model from Logs
+
+By default, trainer reads `/var/log/nginx/access.log`. Override as needed:
+
+```bash
+NODE_LOG_PATH=/path/to/access.log npm run train
+```
+
+Include rotated logs:
+
+```bash
+NODE_LOG_GLOB='/path/to/access.log.*' npm run train
+```
+
+Output model artifact:
+
+- `resources/model.json`
+
+## 5. Verify Installation
+
+Run tests:
+
+```bash
+npm test
+```
+
+Check CLI wiring:
+
+```bash
+npm run aiwaf -- help
+```
+
+Run a minimal app and hit a known benign route (`/`) and a suspicious route (for example path with `.php`) to validate block behavior.
+
+## 6. Troubleshooting
+
+### `Failed to load pretrained model`
+
+- Run `npm run train` to generate `resources/model.json`.
+- Ensure process has read access to the `resources/` directory.
+
+### Redis warnings or connection failures
+
+- Verify `REDIS_URL` value and Redis server health.
+- Runtime is designed to continue with fallback behavior.
+
+### SQLite errors (`blocked_ips` table not found)
+
+- Ensure process can create/write `./aiwaf.sqlite`.
+- `blacklistManager` auto-initializes the table, but write permissions are required.
+- If DB logging is unavailable, enable CSV middleware logs:
+  - `AIWAF_MIDDLEWARE_LOG_CSV=true`
+  - `AIWAF_MIDDLEWARE_LOG_CSV_PATH=logs/aiwaf-requests.csv`
+- Core tables also fall back automatically to CSV files in `logs/storage/` when DB operations fail.
+
+### `sqlite3` install/build issues
+
+- Install platform-native build dependencies and reinstall packages.
+- On CI/container images, ensure compiler toolchain is present.
+
+### Training finds no logs
+
+- Confirm `NODE_LOG_PATH` exists and is readable.
+- If using rotation, set `NODE_LOG_GLOB` to a valid glob.
+
+## 7. Production Notes
+
+- Prefer Redis or a custom shared cache backend for multi-instance deployments.
+- Place middleware after body parsing middleware if honeypot detection is required.
+- Review rate limits and thresholds against real traffic profiles before broad rollout.

package/README.md

@@ -1,139 +1,324 @@
-# aiwaf‑js
+# aiwaf-js
+
+AIWAF-JS is a Node.js/Express Web Application Firewall that combines deterministic protections with anomaly detection and continuous learning. It ships as middleware, a CLI for ops workflows, and an offline trainer for IsolationForest models.
+
+## What It Does
+
+- Blocks known bad traffic with static keyword rules and IP blacklisting
+- Enforces rate limits with flood detection
+- Detects bot-like form abuse using honeypot field checks and timing gates
+- Enforces optional method policies (405) and suspicious method usage
+- Blocks suspicious UUID probing on route prefixes (with optional existence resolver)
+- Learns high-frequency malicious segments as dynamic suspicious keywords
+- Runs IsolationForest anomaly checks with recent-behavior analysis
+- Supports Redis/custom cache backends with memory fallback
+- Optional GeoIP blocking (MMDB) with allow/block lists and dynamic blocklist
+- CSV fallback storage when DB is unavailable
+- Operational CLI for blacklist, exemptions, geo, request logs, training and diagnostics
+
+## Repository Layout
+
+- `index.js`: package entrypoint
+- `lib/wafMiddleware.js`: main middleware orchestration
+- `lib/rateLimiter.js`: rate-window and flood logic
+- `lib/blacklistManager.js`: blocked IP persistence and operations
+- `lib/keywordDetector.js`: static keyword checks
+- `lib/dynamicKeyword.js`: in-memory dynamic keyword learning/checking
+- `lib/uuidDetector.js`: UUID tamper detection
+- `lib/honeypotDetector.js`: honeypot trap detection
+- `lib/anomalyDetector.js`: pretrained model loading and anomaly scoring
+- `lib/featureUtils.js`: request feature extraction and short-lived caching
+- `lib/isolationForest.js`: IsolationForest implementation
+- `lib/redisClient.js`: optional Redis client lifecycle
+- `lib/headerValidation.js`: header caps, suspicious UA, and header quality scoring
+- `lib/geoBlocker.js`: GeoIP allow/block checks + MMDB lookup + cache
+- `lib/middlewareLogger.js`: JSONL/CSV/DB request logging
+- `lib/*Store.js`: DB/CSV storage adapters (blacklist, exemptions, geo, logs, keywords, models)
+- `train.js`: offline model training from access logs
+- `resources/model.json`: pretrained anomaly model artifact
+- `utils/db.js`: SQLite connection (memory DB in test)
+- `test/`: Jest test suite
+
+## Request Processing Flow
+
+1. Initialize module options for rate limiter, keyword detectors, honeypot, UUID checks, and anomaly detector.
+2. Resolve client IP (`x-forwarded-for` first, then `req.ip`) and normalized path.
+3. Enforce optional method policy (405) if enabled.
+4. Block immediately if IP is already in blacklist.
+5. Header validation (required headers, suspicious UA, header caps, quality score).
+6. Geo checks (allow/block lists + DB-backed blocklist).
+7. Honeypot field + timing checks.
+8. Rate-limit + flood handling.
+9. Static keyword blocking.
+10. Dynamic keyword blocking.
+11. UUID tamper checks (optional existence resolver).
+12. Anomaly detection for unknown routes with recent-behavior analysis.
+13. Request logging (JSONL/CSV/DB) and optional dynamic keyword learning on 404s.
+14. Allow request through `next()` when no rule triggers.
 
-> **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.
-
-[![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)  
-[![License](https://img.shields.io/npm/l/aiwaf-js.svg)](LICENSE)
+## Installation
 
----
+```bash
+npm install aiwaf-js
+```
 
-## Features
+## Quick Start
 
-- ✅ 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**
+```js
+const express = require('express');
+const aiwaf = require('aiwaf-js');
 
----
+const app = express();
+app.use(express.json());
 
-## Installation
+app.use(aiwaf({
+  staticKeywords: ['.php', '.env', '.git'],
+  dynamicTopN: 10,
+  WINDOW_SEC: 10,
+  MAX_REQ: 20,
+  FLOOD_REQ: 40,
+  HONEYPOT_FIELD: 'hp_field',
+  uuidRoutePrefix: '/user',
+  AIWAF_HEADER_VALIDATION: true,
+  AIWAF_METHOD_POLICY_ENABLED: true,
+  AIWAF_ALLOWED_METHODS: ['GET', 'POST', 'HEAD', 'OPTIONS']
+}));
 
-```bash
-npm install aiwaf-js --save
+app.get('/', (req, res) => res.send('Protected'));
+app.listen(3000);
 ```
 
----
-
-## Train the Model (Optional but recommended)
+## Configuration
 
-You can train the anomaly detector and keyword learner using real access logs.
+### Core Controls
+
+| Option | Default | Description |
+|---|---|---|
+| `staticKeywords` | `[]` | Substrings that trigger immediate block + blacklist |
+| `dynamicTopN` or `DYNAMIC_TOP_N` | `10` | Frequency threshold for dynamic segment blocking |
+| `WINDOW_SEC` | `60` | Time window for rate limiting |
+| `MAX_REQ` | `100` | Max allowed requests in window before rate block |
+| `FLOOD_REQ` | `200` | Hard threshold that blacklists IP |
+| `HONEYPOT_FIELD` | `undefined` | Body field name used as bot trap |
+| `uuidRoutePrefix` | `"/user"` | Path prefix monitored for UUID tamper attempts |
+| `uuidResolver` | `undefined` | Optional async resolver `(uuid, req) => boolean` for existence checks |
+| `cache` | fallback memory cache | Custom cache backend used by limiter/features |
+| `nTrees` | `100` | IsolationForest trees when model is initialized in-process |
+| `sampleSize` | `256` | IsolationForest sample size |
+
+### Header Validation
+
+| Option | Default | Description |
+|---|---|---|
+| `AIWAF_HEADER_VALIDATION` | `false` | Enable header validation pipeline |
+| `AIWAF_REQUIRED_HEADERS` | `[]` | Required headers array, or `{ DEFAULT, GET, POST }` mapping |
+| `AIWAF_HEADER_QUALITY_MIN_SCORE` | `3` | Minimum header quality score |
+| `AIWAF_MAX_HEADER_BYTES` | `32768` | Max header bytes before blocking |
+| `AIWAF_MAX_HEADER_COUNT` | `100` | Max header count before blocking |
+| `AIWAF_MAX_USER_AGENT_LENGTH` | `500` | Max User-Agent length |
+| `AIWAF_MAX_ACCEPT_LENGTH` | `4096` | Max Accept header length |
+| `AIWAF_BLOCKED_USER_AGENTS` | list | Substring deny list |
+| `AIWAF_SUSPICIOUS_USER_AGENTS` | regex list | Regex list for suspicious UA detection |
+| `AIWAF_LEGITIMATE_BOTS` | regex list | Regex allow list for legitimate crawlers |
+
+### Method Policy
+
+| Option | Default | Description |
+|---|---|---|
+| `AIWAF_METHOD_POLICY_ENABLED` | `false` | Enforce method allowlist (returns 405) |
+| `AIWAF_ALLOWED_METHODS` | `['GET','POST','HEAD','OPTIONS']` | Allowed methods when policy enabled |
+| `AIWAF_POST_ONLY_SUFFIXES` | `['/create/','/submit/','/upload/','/delete/','/process/']` | GET to these triggers 405 when policy enabled |
+| `AIWAF_LOGIN_PATH_PREFIXES` | common login paths | Shorten min form time for login |
+
+### Keyword Learning
+
+| Option | Default | Description |
+|---|---|---|
+| `AIWAF_ENABLE_KEYWORD_LEARNING` | `true` | Enable dynamic keyword learning |
+| `AIWAF_DYNAMIC_TOP_N` | `10` | Dynamic keyword learning threshold |
+| `AIWAF_EXEMPT_KEYWORDS` | `[]` | Skip these keywords |
+| `AIWAF_ALLOWED_PATH_KEYWORDS` | `[]` | Allowlist of path fragments |
+
+### Model / Training
+
+| Option | Default | Description |
+|---|---|---|
+| `AIWAF_MIN_TRAIN_LOGS` | `50` | Minimum logs to run training |
+| `AIWAF_MIN_AI_LOGS` | `10000` | Minimum logs to train AI model |
+| `AIWAF_FORCE_AI_TRAINING` | `false` | Force AI training below minimum logs |
+| `AIWAF_MODEL_STORAGE` | `file` | `file`, `db`, or `cache` |
+| `AIWAF_MODEL_PATH` | `resources/model.json` | Model file path (file backend) |
+| `AIWAF_MODEL_STORAGE_FALLBACK` | `file` | Fallback model backend |
+| `AIWAF_MODEL_CACHE_KEY` | `aiwaf:model` | Cache key when using cache backend |
+| `AIWAF_MODEL_CACHE_TTL` | `0` | Cache TTL in seconds |
+
+### Geo Blocking
+
+| Option | Default | Description |
+|---|---|---|
+| `AIWAF_GEO_BLOCK_ENABLED` | `false` | Enable geo blocking |
+| `AIWAF_GEO_BLOCK_COUNTRIES` | `[]` | Block list (country codes) |
+| `AIWAF_GEO_ALLOW_COUNTRIES` | `[]` | Allow list (country codes) |
+| `AIWAF_GEO_MMDB_PATH` | `geolock/ipinfo_lite.mmdb` | MMDB path |
+| `AIWAF_GEO_CACHE_SECONDS` | `3600` | Geo cache TTL |
+| `AIWAF_GEO_CACHE_PREFIX` | `aiwaf:geo:` | Geo cache key prefix |
+
+### Logging / Storage
+
+| Option | Default | Description |
+|---|---|---|
+| `AIWAF_MIDDLEWARE_LOGGING` | `false` | Enable JSONL logging |
+| `AIWAF_MIDDLEWARE_LOG_PATH` | `logs/aiwaf-requests.jsonl` | JSONL log path |
+| `AIWAF_MIDDLEWARE_LOG_DB` | `false` | Store logs in DB |
+| `AIWAF_MIDDLEWARE_LOG_CSV` | `false` | Store logs in CSV |
+| `AIWAF_MIDDLEWARE_LOG_CSV_PATH` | `logs/aiwaf-requests.csv` | CSV log path |
+| `AIWAF_BLOCKED_IPS_CSV_PATH` | `logs/storage/blocked_ips.csv` | CSV fallback for blocked IPs |
+| `AIWAF_IP_EXEMPTIONS_CSV_PATH` | `logs/storage/ip_exemptions.csv` | CSV fallback for IP exemptions |
+| `AIWAF_PATH_EXEMPTIONS_CSV_PATH` | `logs/storage/path_exemptions.csv` | CSV fallback for path exemptions |
+| `AIWAF_GEO_BLOCKED_COUNTRIES_CSV_PATH` | `logs/storage/geo_blocked_countries.csv` | CSV fallback for geo blocklist |
+| `AIWAF_REQUEST_LOGS_CSV_PATH` | `logs/storage/request_logs.csv` | CSV fallback for request logs |
+| `AIWAF_DYNAMIC_KEYWORDS_CSV_PATH` | `logs/storage/dynamic_keywords.csv` | CSV fallback for dynamic keywords |
+
+### Redis / Cache
+## Redis and Cache Behavior
+
+- Set `REDIS_URL` (or `AIWAF_REDIS_URL`) to enable Redis connectivity (`lib/redisClient.js`).
+- If Redis is unavailable, runtime falls back to in-memory behavior.
+- You can inject a custom cache object.
+
+Rate limiter custom cache must implement:
+
+- `lPush(key, value)`
+- `expire(key, ttl)`
+- `lLen(key)`
+- `lRange(key, start, end)`
+
+Feature cache custom backend supports:
+
+- `get(key)`
+- `set(key, value, ttl)`
+
+## Geo Blocking (MMDB)
+
+- Put your DB at `geolock/ipinfo_lite.mmdb` (default) or set `AIWAF_GEO_MMDB_PATH`.
+- Enable with `AIWAF_GEO_BLOCK_ENABLED: true`.
+- Configure `AIWAF_GEO_BLOCK_COUNTRIES` and/or `AIWAF_GEO_ALLOW_COUNTRIES`.
+- Install MMDB reader dependency in your app:
+  - `npm install maxmind`
+- If MMDB is unavailable, the middleware falls back to `x-country-code` header.
+
+## Offline Training
+
+Train a model using access logs:
 
 ```bash
-NODE_LOG_PATH=/path/to/access.log npm run train
+AIWAF_ACCESS_LOG=/path/to/access.log npm run train
 ```
 
-If `NODE_LOG_PATH` is not provided, it defaults to `/var/log/nginx/access.log`.
+Optional rotated/gz support:
 
----
-
-## Quick Start
-
-```js
-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)
+```bash
+NODE_LOG_GLOB='/path/to/access.log.*' npm run train
 ```
 
----
+Training pipeline in `train.js`:
 
-## Redis Support (Recommended for Production)
+- Reads raw and rotated (including `.gz`) access logs
+- Parses request fields (IP, URI, status, response time, timestamp)
+- Builds feature vectors: `[pathLen, kwHits, statusIdx, responseTime, burst, total404]`
+- Enforces `AIWAF_MIN_TRAIN_LOGS` and `AIWAF_MIN_AI_LOGS`
+- Trains IsolationForest when log volume is sufficient
+- Learns dynamic keywords from suspicious 4xx/5xx traffic
+- Removes exempt keywords and unblocks exempt IPs
+- Writes model artifact to `resources/model.json` with metadata
+- Model storage backends:
+  - `AIWAF_MODEL_STORAGE`: `file` (default), `db`, `cache`
+  - `AIWAF_MODEL_PATH` (file backend)
+  - `AIWAF_MODEL_STORAGE_FALLBACK` (fallback backend)
+  - `AIWAF_MODEL_CACHE_KEY`, `AIWAF_MODEL_CACHE_TTL` (cache backend)
 
-AIWAF‑JS supports Redis for distributed rate limiting and keyword caching.
+## Testing
 
 ```bash
-# On Unix/Linux/macOS
-export REDIS_URL=redis://localhost:6379
-
-# On Windows PowerShell
-$env:REDIS_URL = "redis://localhost:6379"
+npm test
 ```
 
-If Redis is unavailable, it gracefully falls back to in-memory mode.
-
----
-
-## Custom Cache Logic (Advanced)
+Current tests cover:
+
+- Header validation (caps, suspicious UA, quality scoring)
+- Method policy enforcement
+- Geo blocking and MMDB lookup
+- Honeypot timing policies
+- UUID tamper detection (with resolver)
+- Anomaly detection and recent-behavior analysis
+- Dynamic keyword learning and trainer behaviors
+- CSV/DB fallback storage
+- CLI and settings compatibility
+
+## Data and Persistence
+
+- Runtime blacklist storage uses SQLite through `utils/db.js`.
+- Production DB file defaults to `./aiwaf.sqlite`.
+- Test environment uses in-memory SQLite (`NODE_ENV=test`).
+- Primary blocked IP table: `blocked_ips`.
+- Middleware logging supports JSONL, optional SQLite, and CSV fallback.
+- CSV settings:
+  - `AIWAF_MIDDLEWARE_LOG_CSV`
+  - `AIWAF_MIDDLEWARE_LOG_CSV_PATH`
+- Table storage CSV fallbacks are enabled automatically when DB operations fail:
+  - `blocked_ips` -> `logs/storage/blocked_ips.csv` (`AIWAF_BLOCKED_IPS_CSV_PATH`)
+  - `ip_exemptions` -> `logs/storage/ip_exemptions.csv` (`AIWAF_IP_EXEMPTIONS_CSV_PATH`)
+  - `path_exemptions` -> `logs/storage/path_exemptions.csv` (`AIWAF_PATH_EXEMPTIONS_CSV_PATH`)
+  - `geo_blocked_countries` -> `logs/storage/geo_blocked_countries.csv` (`AIWAF_GEO_BLOCKED_COUNTRIES_CSV_PATH`)
+  - `request_logs` -> `logs/storage/request_logs.csv` (`AIWAF_REQUEST_LOGS_CSV_PATH`)
+  - `dynamic_keywords` -> `logs/storage/dynamic_keywords.csv` (`AIWAF_DYNAMIC_KEYWORDS_CSV_PATH`)
+
+## Operational Notes
+
+- Middleware order matters; place AIWAF after body parsers if honeypot checks depend on parsed JSON/form body.
+- If no trained model exists or loading fails, anomaly detector fails open.
+- Dynamic keyword learning persists to DB/CSV via `dynamicKeywordStore`.
+- Multi-instance deployments should use Redis/custom shared cache for limiter consistency.
+
+## Development
 
-You can inject your own cache logic (in-memory, Redis, hybrid, or file-based) by passing a `cache` object implementing the following interface:
+```bash
+npm install
+npm test
+npm run train
+npm run aiwaf -- help
+```
 
-```js
-const myCustomCache = {
-  get: async (key) => { /* return cached value */ },
-  set: async (key, value, options) => { /* store with optional TTL */ },
-  del: async (key) => { /* delete entry */ }
-}
+## Operations CLI
 
-app.use(aiwaf({
-  cache: myCustomCache,
-  staticKeywords: ['.php'],
-  dynamicTopN: 5,
-  MAX_REQ: 10,
-  WINDOW_SEC: 15,
-  FLOOD_REQ: 20,
-}))
+```bash
+npm run aiwaf -- list blacklist
+npm run aiwaf -- list exemptions
+npm run aiwaf -- add ip-exemption 203.0.113.10 "trusted monitor"
+npm run aiwaf -- add path-exemption /health "health probes"
+npm run aiwaf -- geo block CN "manual block"
+npm run aiwaf -- geo summary
+npm run aiwaf -- diagnose 203.0.113.10
 ```
 
-This overrides Redis/in-memory usage with your custom strategy for all cache operations.
+## Sandbox (OWASP Juice Shop)
 
----
+The repository includes a runnable sandbox that proxies OWASP Juice Shop behind AIWAF. It also includes an attack suite that generates comparable results for direct vs protected traffic.
 
-## Configuration
+Run sandbox:
 
-```js
-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
-}));
+```bash
+docker compose -f examples/sandbox/docker-compose.yml up --build
 ```
 
-| 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
+Run the attack suite and compare:
 
-**Tip:** In high-volume environments, caching the feature vector extractor (especially if Redis is unavailable) can reduce redundant computation and significantly boost performance.
+```bash
+node examples/sandbox/run-and-compare.js http://localhost:3001 http://localhost:3000
+```
 
----
+The comparison output includes per‑attack block rates and total blocked requests.
 
-## 📄 License
+## License
 
-MIT License © 2025 [Aayush Gauba](https://github.com/aayushg)
+MIT