aiwaf-js 0.0.7 → 0.0.8

package/README.md

@@ -1,6 +1,7 @@
 # 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.
+Supported frameworks: Express (native), Fastify, Hapi, Koa, NestJS (Express/Fastify wrappers), Next.js (API route wrapper), and AdonisJS.
 
 ## What It Does
 
@@ -62,6 +63,15 @@ AIWAF-JS is a Node.js/Express Web Application Firewall that combines determinist
 npm install aiwaf-js
 ```
 
+### Optional WASM Acceleration
+
+AIWAF can use the `aiwaf-wasm` optional dependency for faster IsolationForest scoring and deterministic feature validation.
+If the WASM module fails to load, it automatically falls back to the JS implementation.
+
+```bash
+npm install aiwaf-wasm
+```
+
 ## Quick Start
 
 ```js
@@ -88,6 +98,184 @@ app.get('/', (req, res) => res.send('Protected'));
 app.listen(3000);
 ```
 
+## Fastify Usage
+
+```js
+const fastify = require('fastify')({ logger: true });
+const aiwaf = require('aiwaf-js');
+
+fastify.register(aiwaf.fastify, {
+  staticKeywords: ['.php', '.env', '.git'],
+  dynamicTopN: 10,
+  WINDOW_SEC: 10,
+  MAX_REQ: 20,
+  FLOOD_REQ: 40,
+  HONEYPOT_FIELD: 'hp_field'
+});
+
+fastify.get('/', async () => 'Protected');
+fastify.listen({ port: 3000 });
+```
+
+## Hapi Usage
+
+```js
+const Hapi = require('@hapi/hapi');
+const aiwaf = require('aiwaf-js');
+
+const server = Hapi.server({ port: 3000 });
+await server.register({
+  plugin: aiwaf.hapi,
+  options: {
+    staticKeywords: ['.php', '.env', '.git'],
+    dynamicTopN: 10,
+    WINDOW_SEC: 10,
+    MAX_REQ: 20,
+    FLOOD_REQ: 40,
+    HONEYPOT_FIELD: 'hp_field'
+  }
+});
+
+server.route({ method: 'GET', path: '/', handler: () => 'Protected' });
+await server.start();
+```
+
+## Koa Usage
+
+```js
+const Koa = require('koa');
+const bodyParser = require('koa-bodyparser');
+const aiwaf = require('aiwaf-js');
+
+const app = new Koa();
+app.use(bodyParser());
+
+app.use(aiwaf.koa({
+  staticKeywords: ['.php', '.env', '.git'],
+  dynamicTopN: 10,
+  WINDOW_SEC: 10,
+  MAX_REQ: 20,
+  FLOOD_REQ: 40,
+  HONEYPOT_FIELD: 'hp_field'
+}));
+
+app.use(ctx => {
+  ctx.body = 'Protected';
+});
+
+app.listen(3000);
+```
+
+## NestJS (Express) Usage
+
+```ts
+import { Module, MiddlewareConsumer, NestModule } from '@nestjs/common';
+import aiwaf from 'aiwaf-js';
+
+@Module({})
+export class AppModule implements NestModule {
+  configure(consumer: MiddlewareConsumer) {
+    consumer
+      .apply(aiwaf.nest({
+        staticKeywords: ['.php', '.env', '.git'],
+        dynamicTopN: 10,
+        WINDOW_SEC: 10,
+        MAX_REQ: 20,
+        FLOOD_REQ: 40,
+        HONEYPOT_FIELD: 'hp_field'
+      }))
+      .forRoutes('*');
+  }
+}
+```
+
+If you need to guarantee ordering before other middleware/proxies, you can also attach the Express middleware directly in `main.ts`:
+
+```ts
+import { NestFactory } from '@nestjs/core';
+import aiwaf from 'aiwaf-js';
+import { AppModule } from './app.module';
+
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule);
+  app.use(aiwaf({
+    staticKeywords: ['.php', '.env', '.git'],
+    dynamicTopN: 10,
+    WINDOW_SEC: 10,
+    MAX_REQ: 20,
+    FLOOD_REQ: 40,
+    HONEYPOT_FIELD: 'hp_field'
+  }));
+  await app.listen(3000);
+}
+bootstrap();
+```
+
+## NestJS (Fastify) Usage
+
+Use the Fastify plugin when running Nest with `FastifyAdapter`:
+
+```ts
+import { NestFactory } from '@nestjs/core';
+import { FastifyAdapter } from '@nestjs/platform-fastify';
+import aiwaf from 'aiwaf-js';
+import { AppModule } from './app.module';
+
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule, new FastifyAdapter());
+  await app.register(aiwaf.fastify, {
+    staticKeywords: ['.php', '.env', '.git'],
+    dynamicTopN: 10,
+    WINDOW_SEC: 10,
+    MAX_REQ: 20,
+    FLOOD_REQ: 40,
+    HONEYPOT_FIELD: 'hp_field'
+  });
+  await app.listen(3000, '0.0.0.0');
+}
+bootstrap();
+```
+
+## Next.js (API Routes) Usage
+
+Use the `aiwaf.next` helper to wrap a Next.js API route handler.
+
+```ts
+import aiwaf from 'aiwaf-js';
+
+function handler(req, res) {
+  res.status(200).json({ ok: true });
+}
+
+export default aiwaf.next(handler, {
+  staticKeywords: ['.php', '.env', '.git'],
+  dynamicTopN: 10,
+  WINDOW_SEC: 10,
+  MAX_REQ: 20,
+  FLOOD_REQ: 40,
+  HONEYPOT_FIELD: 'hp_field'
+});
+```
+
+## AdonisJS Usage
+
+Register the middleware in your Adonis middleware stack:
+
+```ts
+import aiwaf from 'aiwaf-js';
+
+export const middleware = [
+  () => aiwaf.adonis({
+    staticKeywords: ['.php', '.env', '.git'],
+    dynamicTopN: 10,
+    WINDOW_SEC: 10,
+    MAX_REQ: 20,
+    FLOOD_REQ: 40,
+    HONEYPOT_FIELD: 'hp_field'
+  })
+];
+```
+
 ## Configuration
 
 ### Core Controls
@@ -105,6 +293,8 @@ app.listen(3000);
 | `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 |
+| `AIWAF_WASM_VALIDATION` | `true` | Enable WASM validation when available (headers, URL, content, recent) |
+| `AIWAF_WASM_VALIDATE_RECENT` | `false` | Run WASM recent-behavior validation on recent request logs |
 
 ### Header Validation
 
@@ -318,6 +508,7 @@ node examples/sandbox/run-and-compare.js http://localhost:3001 http://localhost:
 ```
 
 The comparison output includes per‑attack block rates and total blocked requests.
+Fastify proxy is also available on `http://localhost:3002`.
 
 ## License
 

package/examples/sandbox/README.md

@@ -13,6 +13,12 @@ docker compose up --build
 Then open:
 
 - AIWAF-protected: `http://localhost:3000`
+- AIWAF-protected (Fastify): `http://localhost:3002`
+- AIWAF-protected (Hapi): `http://localhost:3003`
+- AIWAF-protected (Koa): `http://localhost:3004`
+- AIWAF-protected (NestJS): `http://localhost:3005`
+- AIWAF-protected (Next.js): `http://localhost:3006`
+- AIWAF-protected (AdonisJS): `http://localhost:3007`
 - Direct Juice Shop: `http://localhost:3001`
 
 ## Test
@@ -40,14 +46,50 @@ Run against AIWAF-protected Juice Shop:
 node attack-suite.js http://localhost:3000 protected
 ```
 
+Run against AIWAF-protected Juice Shop (Fastify):
+
+```bash
+node attack-suite.js http://localhost:3002 protected_fastify
+```
+
+Run against AIWAF-protected Juice Shop (Hapi):
+
+```bash
+node attack-suite.js http://localhost:3003 protected_hapi
+```
+
+Run against AIWAF-protected Juice Shop (Koa):
+
+```bash
+node attack-suite.js http://localhost:3004 protected_koa
+```
+
+Run against AIWAF-protected Juice Shop (NestJS):
+
+```bash
+node attack-suite.js http://localhost:3005 protected_nest
+```
+
+Run against AIWAF-protected Juice Shop (Next.js):
+
+```bash
+node attack-suite.js http://localhost:3006 protected_next
+```
+
+Run against AIWAF-protected Juice Shop (AdonisJS):
+
+```bash
+node attack-suite.js http://localhost:3007 protected_adonis
+```
+
 Compare results:
 
 ```bash
-node compare-results.js results_direct_*.json results_protected_*.json
+node compare-results.js results_direct_*.json results_protected_*.json results_protected_fastify_*.json results_protected_hapi_*.json results_protected_koa_*.json results_protected_nest_*.json results_protected_next_*.json results_protected_adonis_*.json
 ```
 
 Or run the full suite + comparison in one command:
 
 ```bash
-node run-and-compare.js http://localhost:3001 http://localhost:3000
+node run-and-compare.js
 ```

package/examples/sandbox/aiwaf-adonis-proxy/Dockerfile

@@ -0,0 +1,16 @@
+FROM node:20-bullseye
+
+WORKDIR /workspace
+COPY . /workspace
+
+RUN apt-get update && apt-get install -y python3 make g++ \
+  && rm -rf /var/lib/apt/lists/*
+
+RUN npm_config_build_from_source=true npm install
+
+WORKDIR /workspace/examples/sandbox/aiwaf-adonis-proxy
+
+RUN npm_config_build_from_source=true npm install
+
+EXPOSE 3007
+CMD ["npm", "start"]

package/examples/sandbox/aiwaf-adonis-proxy/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "aiwaf-adonis-proxy-sandbox",
+  "version": "1.0.0",
+  "private": true,
+  "type": "commonjs",
+  "scripts": {
+    "start": "node server.js"
+  },
+  "dependencies": {
+    "aiwaf-js": "file:../../..",
+    "http-proxy-middleware": "^3.0.0"
+  }
+}

package/examples/sandbox/aiwaf-adonis-proxy/server.js

@@ -0,0 +1,71 @@
+const { createProxyMiddleware } = require('http-proxy-middleware');
+const aiwaf = require('aiwaf-js');
+
+const PORT = process.env.PORT || 3007;
+const TARGET_BASE_URL = process.env.TARGET_BASE_URL || 'http://localhost:3001';
+
+const proxy = createProxyMiddleware({
+  target: TARGET_BASE_URL,
+  changeOrigin: true,
+  ws: true,
+  logLevel: 'warn'
+});
+
+function createCtx(req, res) {
+  const response = {
+    response: res,
+    statusCode: res.statusCode || 200,
+    status(code) {
+      response.statusCode = code;
+      res.statusCode = code;
+      return response;
+    },
+    send(payload) {
+      res.end(payload);
+      return response;
+    },
+    json(payload) {
+      res.setHeader('content-type', 'application/json');
+      res.end(JSON.stringify(payload));
+      return response;
+    }
+  };
+
+  const request = {
+    request: req,
+    url: () => req.url,
+    headers: () => req.headers || {},
+    ip: () => (req.headers?.['x-forwarded-for'] || req.socket?.remoteAddress),
+    method: () => req.method
+  };
+
+  return { request, response };
+}
+
+const middleware = aiwaf.adonis({
+  staticKeywords: ['.php', '.env', '.git', '../'],
+  dynamicTopN: 5,
+  WINDOW_SEC: 10,
+  MAX_REQ: 25,
+  FLOOD_REQ: 50,
+  HONEYPOT_FIELD: 'hp_field',
+  AIWAF_METHOD_POLICY_ENABLED: true,
+  AIWAF_ALLOWED_METHODS: ['GET', 'POST', 'HEAD', 'OPTIONS'],
+  AIWAF_HEADER_VALIDATION: true,
+  AIWAF_REQUIRED_HEADERS: [],
+  AIWAF_MIDDLEWARE_LOGGING: true,
+  AIWAF_MIDDLEWARE_LOG_PATH: process.env.AIWAF_MIDDLEWARE_LOG_PATH || 'logs/aiwaf-requests.jsonl'
+});
+
+require('http')
+  .createServer(async (req, res) => {
+    console.log(`[sandbox-adonis] ${req.method} ${req.url}`);
+    const ctx = createCtx(req, res);
+    await middleware(ctx, () => new Promise(resolve => {
+      proxy(req, res, resolve);
+    }));
+  })
+  .listen(PORT, '0.0.0.0', () => {
+    console.log(`AIWAF Adonis sandbox proxy running on port ${PORT}`);
+    console.log(`Forwarding traffic to ${TARGET_BASE_URL}`);
+  });

package/examples/sandbox/aiwaf-fastify-proxy/Dockerfile

@@ -0,0 +1,21 @@
+FROM node:20-bullseye
+
+WORKDIR /workspace
+
+COPY . /workspace
+
+WORKDIR /workspace
+
+RUN apt-get update && apt-get install -y python3 make g++ && rm -rf /var/lib/apt/lists/*
+
+ENV npm_config_build_from_source=sqlite3
+
+RUN npm install
+
+WORKDIR /workspace/examples/sandbox/aiwaf-fastify-proxy
+
+RUN npm install
+
+EXPOSE 3002
+
+CMD ["npm", "start"]

package/examples/sandbox/aiwaf-fastify-proxy/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "aiwaf-fastify-proxy-sandbox",
+  "version": "1.0.0",
+  "private": true,
+  "main": "server.js",
+  "type": "commonjs",
+  "scripts": {
+    "start": "node server.js"
+  },
+  "dependencies": {
+    "aiwaf-js": "file:../../..",
+    "fastify": "^4.29.1",
+    "@fastify/middie": "^8.0.0",
+    "http-proxy-middleware": "^3.0.0"
+  }
+}

package/examples/sandbox/aiwaf-fastify-proxy/server.js

@@ -0,0 +1,42 @@
+const fastify = require('fastify')({ logger: true });
+const aiwaf = require('aiwaf-js');
+const { createProxyMiddleware } = require('http-proxy-middleware');
+
+const PORT = process.env.PORT || 3002;
+const TARGET_BASE_URL = process.env.TARGET_BASE_URL || 'http://localhost:3001';
+
+fastify.register(aiwaf.fastify, {
+  staticKeywords: ['.php', '.env', '.git', '../'],
+  dynamicTopN: 5,
+  WINDOW_SEC: 10,
+  MAX_REQ: 25,
+  FLOOD_REQ: 50,
+  HONEYPOT_FIELD: 'hp_field',
+  AIWAF_METHOD_POLICY_ENABLED: true,
+  AIWAF_ALLOWED_METHODS: ['GET', 'POST', 'HEAD', 'OPTIONS'],
+  AIWAF_HEADER_VALIDATION: true,
+  AIWAF_REQUIRED_HEADERS: [],
+  AIWAF_MIDDLEWARE_LOGGING: true,
+  AIWAF_MIDDLEWARE_LOG_PATH: process.env.AIWAF_MIDDLEWARE_LOG_PATH || 'logs/aiwaf-requests.jsonl'
+});
+
+fastify.addHook('onRequest', async (request, reply) => {
+  fastify.log.info(`[sandbox-fastify] ${request.method} ${request.url}`);
+});
+
+fastify.register(require('@fastify/middie')).then(() => {
+  fastify.use(
+    '/',
+    createProxyMiddleware({
+      target: TARGET_BASE_URL,
+      changeOrigin: true,
+      ws: true,
+      logLevel: 'warn'
+    })
+  );
+});
+
+fastify.listen({ port: PORT, host: '0.0.0.0' }).then(() => {
+  fastify.log.info(`AIWAF Fastify sandbox proxy running on port ${PORT}`);
+  fastify.log.info(`Forwarding traffic to ${TARGET_BASE_URL}`);
+});

package/examples/sandbox/aiwaf-hapi-proxy/Dockerfile

@@ -0,0 +1,16 @@
+FROM node:20-bullseye
+
+WORKDIR /workspace
+COPY . /workspace
+
+RUN apt-get update && apt-get install -y python3 make g++ \
+  && rm -rf /var/lib/apt/lists/*
+
+RUN npm_config_build_from_source=true npm install
+
+WORKDIR /workspace/examples/sandbox/aiwaf-hapi-proxy
+
+RUN npm_config_build_from_source=true npm install
+
+EXPOSE 3003
+CMD ["npm", "start"]

package/examples/sandbox/aiwaf-hapi-proxy/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "aiwaf-hapi-proxy-sandbox",
+  "version": "1.0.0",
+  "private": true,
+  "main": "server.js",
+  "type": "commonjs",
+  "scripts": {
+    "start": "node server.js"
+  },
+  "dependencies": {
+    "aiwaf-js": "file:../../..",
+    "@hapi/hapi": "^21.3.12",
+    "@hapi/h2o2": "^10.0.4"
+  }
+}

package/examples/sandbox/aiwaf-hapi-proxy/server.js

@@ -0,0 +1,55 @@
+const Hapi = require('@hapi/hapi');
+const H2o2 = require('@hapi/h2o2');
+const aiwaf = require('aiwaf-js');
+
+const PORT = process.env.PORT || 3003;
+const TARGET_BASE_URL = process.env.TARGET_BASE_URL || 'http://localhost:3001';
+
+async function start() {
+  const server = Hapi.server({ port: PORT, host: '0.0.0.0' });
+
+  await server.register(H2o2);
+  await server.register({
+    plugin: aiwaf.hapi,
+    options: {
+      staticKeywords: ['.php', '.env', '.git', '../'],
+      dynamicTopN: 5,
+      WINDOW_SEC: 10,
+      MAX_REQ: 25,
+      FLOOD_REQ: 50,
+      HONEYPOT_FIELD: 'hp_field',
+      AIWAF_METHOD_POLICY_ENABLED: true,
+      AIWAF_ALLOWED_METHODS: ['GET', 'POST', 'HEAD', 'OPTIONS'],
+      AIWAF_HEADER_VALIDATION: true,
+      AIWAF_REQUIRED_HEADERS: [],
+      AIWAF_MIDDLEWARE_LOGGING: true,
+      AIWAF_MIDDLEWARE_LOG_PATH: process.env.AIWAF_MIDDLEWARE_LOG_PATH || 'logs/aiwaf-requests.jsonl'
+    }
+  });
+
+  server.ext('onRequest', (request, h) => {
+    console.log(`[sandbox-hapi] ${request.method.toUpperCase()} ${request.url.pathname}`);
+    return h.continue;
+  });
+
+  server.route({
+    method: '*',
+    path: '/{path*}',
+    handler: {
+      proxy: {
+        uri: TARGET_BASE_URL,
+        passThrough: true,
+        xforward: true
+      }
+    }
+  });
+
+  await server.start();
+  console.log(`AIWAF Hapi sandbox proxy running on port ${PORT}`);
+  console.log(`Forwarding traffic to ${TARGET_BASE_URL}`);
+}
+
+start().catch(err => {
+  console.error(err);
+  process.exit(1);
+});

package/examples/sandbox/aiwaf-koa-proxy/Dockerfile

@@ -0,0 +1,16 @@
+FROM node:20-bullseye
+
+WORKDIR /workspace
+COPY . /workspace
+
+RUN apt-get update && apt-get install -y python3 make g++ \
+  && rm -rf /var/lib/apt/lists/*
+
+RUN npm_config_build_from_source=true npm install
+
+WORKDIR /workspace/examples/sandbox/aiwaf-koa-proxy
+
+RUN npm_config_build_from_source=true npm install
+
+EXPOSE 3004
+CMD ["npm", "start"]

package/examples/sandbox/aiwaf-koa-proxy/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "aiwaf-koa-proxy-sandbox",
+  "version": "1.0.0",
+  "private": true,
+  "main": "server.js",
+  "type": "commonjs",
+  "scripts": {
+    "start": "node server.js"
+  },
+  "dependencies": {
+    "aiwaf-js": "file:../../..",
+    "koa": "^2.15.4",
+    "koa-bodyparser": "^4.4.1",
+    "koa-proxies": "^0.12.4"
+  }
+}

package/examples/sandbox/aiwaf-koa-proxy/server.js

@@ -0,0 +1,41 @@
+const Koa = require('koa');
+const bodyParser = require('koa-bodyparser');
+const proxy = require('koa-proxies');
+const aiwaf = require('aiwaf-js');
+
+const PORT = process.env.PORT || 3004;
+const TARGET_BASE_URL = process.env.TARGET_BASE_URL || 'http://localhost:3001';
+
+const app = new Koa();
+
+app.use(bodyParser());
+app.use((ctx, next) => {
+  console.log(`[sandbox-koa] ${ctx.method} ${ctx.url}`);
+  return next();
+});
+
+app.use(aiwaf.koa({
+  staticKeywords: ['.php', '.env', '.git', '../'],
+  dynamicTopN: 5,
+  WINDOW_SEC: 10,
+  MAX_REQ: 25,
+  FLOOD_REQ: 50,
+  HONEYPOT_FIELD: 'hp_field',
+  AIWAF_METHOD_POLICY_ENABLED: true,
+  AIWAF_ALLOWED_METHODS: ['GET', 'POST', 'HEAD', 'OPTIONS'],
+  AIWAF_HEADER_VALIDATION: true,
+  AIWAF_REQUIRED_HEADERS: [],
+  AIWAF_MIDDLEWARE_LOGGING: true,
+  AIWAF_MIDDLEWARE_LOG_PATH: process.env.AIWAF_MIDDLEWARE_LOG_PATH || 'logs/aiwaf-requests.jsonl'
+}));
+
+app.use(proxy('/', {
+  target: TARGET_BASE_URL,
+  changeOrigin: true,
+  logs: true
+}));
+
+app.listen(PORT, () => {
+  console.log(`AIWAF Koa sandbox proxy running on port ${PORT}`);
+  console.log(`Forwarding traffic to ${TARGET_BASE_URL}`);
+});

package/examples/sandbox/aiwaf-nest-proxy/Dockerfile

@@ -0,0 +1,17 @@
+FROM node:20-bullseye
+
+WORKDIR /workspace
+COPY . /workspace
+
+RUN apt-get update && apt-get install -y python3 make g++ \
+  && rm -rf /var/lib/apt/lists/*
+
+RUN npm_config_build_from_source=true npm install
+
+WORKDIR /workspace/examples/sandbox/aiwaf-nest-proxy
+
+RUN npm_config_build_from_source=true npm install
+RUN npm_config_build_from_source=true npm install http-proxy-middleware
+
+EXPOSE 3005
+CMD ["npm", "start"]