wolfguard-next-waf 1.0.0

package/README.md

@@ -0,0 +1,178 @@
+
+# 🐺 WolfGuard WAF for Next.js
+
+A lightweight, edge-optimized Web Application Firewall (WAF) built specifically for Next.js Middleware. 
+
+WolfGuard helps protect your application against common Layer-7 attacks by combining threat signature detection, rate limiting, automated IP banning, and real-time security telemetry.
+
+## ✨ Features
+- **⚡ Edge Runtime Compatible**
+- **🛡️ Layer-7 Threat Detection**
+- **🍯 Honeypot Scanner Detection**
+- **🚦 Configurable Rate Limiting**
+- **🔨 Automatic Temporary IP Banning**
+- **📡 Discord SOC Alerting**
+- **🧩 Whitelist & Blacklist Support**
+- **🪶 Zero External Runtime Dependencies**
+
+<p align="center">
+  <img src="./architecture.svg" alt="WolfGuard Architecture Flow" width="100%">
+</p>
+
+---
+
+## 📦 Installation
+
+```bash
+npm install wolfguard-next-waf
+
+```
+
+*Also supports `yarn add` and `pnpm add`.*
+
+---
+
+## 🚀 Quick Start
+
+Secure your entire application in three lines of code. Create or update your `middleware.js` file:
+
+```javascript
+import { WolfGuardWAF } from "wolfguard-next-waf";
+
+const waf = new WolfGuardWAF();
+
+export async function middleware(request) {
+  return await waf.execute(request);
+}
+
+export const config = {
+  matcher: [
+    "/((?!_next/static|_next/image|favicon.ico).*)"
+  ]
+};
+
+```
+
+---
+
+## ⚙️ Advanced Configuration
+
+Customize the WAF to fit your exact threat model by passing a configuration object.
+
+```javascript
+import { WolfGuardWAF } from "wolfguard-next-waf";
+
+const waf = new WolfGuardWAF({
+  discordWebhook: process.env.DISCORD_WEBHOOK,
+
+  rateLimit: 100,
+  timeWindow: 60 * 1000,
+  banDuration: 24 * 60 * 60 * 1000,
+
+  whitelist: ["192.168.1.10", "10.0.0.5"],
+  blacklist: ["185.15.59.224"],
+  
+  customRules: [
+    { regex: /eval\(/i, type: "Malicious Eval Injection" }
+  ]
+});
+
+export async function middleware(request) {
+  return await waf.execute(request);
+}
+
+```
+
+### 📖 Configuration Reference
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `discordWebhook` | `string` | `null` | Discord webhook URL for real-time security alerts. |
+| `rateLimit` | `number` | `50` | Maximum requests allowed during the tracking window. |
+| `timeWindow` | `number` | `60000` | Tracking window in milliseconds. |
+| `banDuration` | `number` | `86400000` | Temporary ban duration in milliseconds. |
+| `whitelist` | `string[]` | `[]` | IP addresses that bypass all security checks. |
+| `blacklist` | `string[]` | `[]` | Permanently blocked IP addresses. |
+| `customRules` | `object[]` | `[]` | Array of custom Regex rules for threat detection. |
+
+---
+
+## 🛡️ Built-in Threat Detection
+
+WolfGuard currently detects and blocks:
+
+* **Cross-Site Scripting (XSS)** (`<script>alert(1)</script>`)
+* **SQL Injection (SQLi)** (`UNION SELECT username,password FROM users`)
+* **Path Traversal (LFI)** (`../../etc/passwd`)
+* **OS Command Injection** (`; bash -i`)
+* **Sensitive File Enumeration** (`.env`, `.git`, `config.yaml`, `backup.sql`)
+* **Admin Panel Scanners** (`/wp-admin`, `/phpmyadmin`, `/admin.php`)
+
+---
+
+## 🚦 Rate Limiting
+
+WolfGuard includes a built-in, edge-safe, in-memory rate limiter with probabilistic garbage collection to prevent memory leaks.
+
+Requests are tracked per IP. If the limit is exceeded, the IP is automatically banned for the configured `banDuration`, and future requests instantly receive an HTTP `429 Too Many Requests` status.
+
+---
+
+## 📡 Discord Security Operations Center (SOC) Alerts
+
+When an attack is detected, WolfGuard sends a detailed, throttled alert to your private Discord channel, including:
+
+* Threat Classification
+* Target URI
+* Attacker IP Address
+* ISP Information
+* Geo-Location & Coordinates
+* User-Agent Information
+
+This enables lightweight SOC-style monitoring without requiring expensive SIEM infrastructure.
+
+---
+
+## 📁 Project Structure
+
+```text
+wolfguard-next-waf/
+├── src/
+│   ├── index.js
+│   ├── rateLimiter.js
+│   ├── signatures.js
+│   ├── telemetry.js
+│   └── utils.js
+├── package.json
+├── README.md
+└── LICENSE
+
+```
+
+---
+
+## 🔒 Security Notes
+
+WolfGuard is intended to be an *additional* security layer and should not replace secure coding practices, input validation, or authentication controls. For production deployments, WolfGuard should be used alongside network-level protection such as Cloudflare or AWS Shield.
+
+---
+
+## 🛠️ Roadmap
+
+* Redis-backed distributed rate limiting
+* IP reputation intelligence (AbuseIPDB integration)
+* Express.js and Fastify adapters
+* Cloudflare Workers adapter
+
+---
+
+## 🤝 Contributing
+
+Contributions, bug reports, and feature requests are welcome. If you discover a security issue, please open a private issue before submitting a public disclosure.
+
+## 📄 License
+
+MIT License
+Copyright (c) 2026 Pugazhmani K.
+
+

package/architecture.svg

@@ -0,0 +1,52 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 800 400" width="100%" height="100%">
+  <rect width="800" height="400" fill="#0f172a" rx="10"/>
+  
+  <pattern id="grid" width="40" height="40" patternUnits="userSpaceOnUse">
+    <path d="M 40 0 L 0 0 0 40" fill="none" stroke="#1e293b" stroke-width="1"/>
+  </pattern>
+  <rect width="800" height="400" fill="url(#grid)" rx="10"/>
+
+  <defs>
+    <marker id="arrowGreen" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="6" markerHeight="6" orient="auto-start-reverse">
+      <path d="M 0 0 L 10 5 L 0 10 z" fill="#10b981" />
+    </marker>
+    <marker id="arrowRed" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="6" markerHeight="6" orient="auto-start-reverse">
+      <path d="M 0 0 L 10 5 L 0 10 z" fill="#ef4444" />
+    </marker>
+    <marker id="arrowBlue" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="6" markerHeight="6" orient="auto-start-reverse">
+      <path d="M 0 0 L 10 5 L 0 10 z" fill="#3b82f6" />
+    </marker>
+  </defs>
+
+  <path d="M 150 200 L 285 200" stroke="#3b82f6" stroke-width="3" fill="none" marker-end="url(#arrowBlue)" stroke-dasharray="5,5"/>
+  <path d="M 500 180 L 620 100" stroke="#ef4444" stroke-width="3" fill="none" marker-end="url(#arrowRed)"/>
+  <path d="M 500 220 L 620 300" stroke="#10b981" stroke-width="3" fill="none" marker-end="url(#arrowGreen)"/>
+
+  <rect x="30" y="160" width="120" height="80" rx="8" fill="#1e293b" stroke="#3b82f6" stroke-width="2"/>
+  <text x="90" y="195" fill="#f8fafc" font-family="sans-serif" font-size="16" font-weight="bold" text-anchor="middle">Public Web</text>
+  <text x="90" y="215" fill="#94a3b8" font-family="sans-serif" font-size="12" text-anchor="middle">Incoming Traffic</text>
+
+  <rect x="300" y="120" width="200" height="160" rx="8" fill="#020617" stroke="#8b5cf6" stroke-width="3"/>
+  <text x="400" y="160" fill="#f8fafc" font-family="sans-serif" font-size="18" font-weight="bold" text-anchor="middle">WolfGuard WAF</text>
+  <text x="400" y="185" fill="#a78bfa" font-family="sans-serif" font-size="14" text-anchor="middle">(Next.js Middleware)</text>
+  
+  <rect x="330" y="205" width="140" height="24" rx="4" fill="#1e1b4b"/>
+  <text x="400" y="222" fill="#c4b5fd" font-family="sans-serif" font-size="11" font-weight="bold" text-anchor="middle">Regex Signatures</text>
+  
+  <rect x="330" y="235" width="140" height="24" rx="4" fill="#1e1b4b"/>
+  <text x="400" y="252" fill="#c4b5fd" font-family="sans-serif" font-size="11" font-weight="bold" text-anchor="middle">Token Bucket Limiter</text>
+
+  <rect x="620" y="60" width="150" height="80" rx="8" fill="#1e293b" stroke="#ef4444" stroke-width="2"/>
+  <text x="695" y="95" fill="#f8fafc" font-family="sans-serif" font-size="16" font-weight="bold" text-anchor="middle">Discord SOC</text>
+  <text x="695" y="115" fill="#fca5a5" font-family="sans-serif" font-size="12" text-anchor="middle">Real-Time Alerts</text>
+  
+  <rect x="520" y="110" width="80" height="20" rx="10" fill="#ef4444"/>
+  <text x="560" y="124" fill="#ffffff" font-family="sans-serif" font-size="10" font-weight="bold" text-anchor="middle">BLOCKED (403)</text>
+
+  <rect x="620" y="260" width="150" height="80" rx="8" fill="#1e293b" stroke="#10b981" stroke-width="2"/>
+  <text x="695" y="295" fill="#f8fafc" font-family="sans-serif" font-size="16" font-weight="bold" text-anchor="middle">Next.js App</text>
+  <text x="695" y="315" fill="#6ee7b7" font-family="sans-serif" font-size="12" text-anchor="middle">Safe Rendering</text>
+  
+  <rect x="520" y="275" width="80" height="20" rx="10" fill="#10b981"/>
+  <text x="560" y="289" fill="#ffffff" font-family="sans-serif" font-size="10" font-weight="bold" text-anchor="middle">PASSED (200)</text>
+</svg>

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "wolfguard-next-waf",
+  "version": "1.0.0",
+  "description": "An edge-optimized Web Application Firewall (WAF), rate-limiter, and real-time SOC telemetry pipeline for Next.js Middleware.",
+  "main": "src/index.js",
+  "type": "module",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 0"
+  },
+  "keywords": [
+    "nextjs",
+    "middleware",
+    "waf",
+    "firewall",
+    "rate-limiting",
+    "security",
+    "owasp",
+    "discord-webhook",
+    "soc-telemetry"
+  ],
+  "author": "Pugazhmani K.",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "peerDependencies": {
+    "next": ">=13.0.0"
+  }
+}

package/src/index.js

@@ -0,0 +1,104 @@
+import { NextResponse } from 'next/server';
+import { extractClientIp } from './utils.js';
+import { detectThreat } from './signatures.js';
+import { RateLimiter } from './rateLimiter.js';
+import { dispatchSocAlert } from './telemetry.js';
+
+/**
+ * WolfGuardWAF - The main entry point wrapper for edge-optimized protection.
+ */
+export class WolfGuardWAF {
+  /**
+   * @param {Object} config - Custom configuration options for the firewall.
+   * @param {string} config.discordWebhook - Your private Discord SIEM channel webhook URL.
+   * @param {number} config.rateLimit - Max allowed requests per window before temporary ban.
+   * @param {number} config.timeWindow - Tracking time window in milliseconds (Default: 1 min).
+   * @param {number} config.banDuration - Punitive network block duration in milliseconds (Default: 24h).
+   * @param {Array<string>} config.whitelist - Array of IP addresses explicitly immune to restrictions.
+   * @param {Array<string>} config.blacklist - Array of IP addresses permanently dropped.
+   * @param {Array<Object>} config.customRules - Custom Regex threat signatures provided by the developer.
+   */
+  constructor(config = {}) {
+    this.discordWebhook = config.discordWebhook || null;
+    this.whitelist = new Set(config.whitelist || []);
+    this.blacklist = new Set(config.blacklist || []);
+    this.customRules = config.customRules || []; 
+    
+    // Anti-Spam: Prevents sending 1000 Discord alerts if an attacker spams a payload
+    this.alertCooldowns = new Map(); 
+
+    // Initialize the internal rate limiting state instance
+    const limit = config.rateLimit || 50;
+    const windowMs = config.timeWindow || 60000;
+    const banMs = config.banDuration || 86400000;
+    this.limiter = new RateLimiter(limit, windowMs, banMs);
+  }
+
+  /**
+   * The primary interceptor function meant to run inside Next.js edge middleware.
+   * @param {Request} request - The standard incoming Next.js Request object.
+   * @returns {Promise<NextResponse>} Next.js execution path alteration instructions.
+   */
+  async execute(request) {
+    const ip = extractClientIp(request);
+    // Include query parameters in the path to catch SQLi in URLs (e.g., ?id=1 UNION SELECT)
+    const path = request.nextUrl.pathname + request.nextUrl.search;
+    const userAgent = request.headers.get("user-agent") || "Missing User-Agent Context";
+
+    // 1. Evaluate Explicit Perma-Blacklist Constraints
+    if (this.blacklist.has(ip)) {
+      return new NextResponse(
+        JSON.stringify({ error: "FORBIDDEN", message: "IP network node permanently blacklisted." }),
+        { status: 403, headers: { 'content-type': 'application/json' } }
+      );
+    }
+
+    // 2. Evaluate Whitelist Exemption Strategy
+    if (this.whitelist.has(ip)) {
+      return NextResponse.next();
+    }
+
+    // 3. Layer-7 Threat Signature & Honeypot Assessment (Includes Developer Custom Rules)
+    const detectedThreatType = detectThreat(path, this.customRules);
+    if (detectedThreatType) {
+      this.triggerAlert(detectedThreatType, path, ip, userAgent);
+      return new NextResponse(
+        JSON.stringify({ error: "SECURITY_INTERCEPT", message: "Malicious signature vector detected." }),
+        { status: 403, headers: { 'content-type': 'application/json' } }
+      );
+    }
+
+    // 4. Rate Limiter Velocity & Flood Assessment
+    const rateCheck = this.limiter.checkLimit(ip);
+    if (rateCheck.blocked) {
+      if (rateCheck.reason === "RATE_LIMIT_EXCEEDED") {
+        this.triggerAlert("Volumetric Flood Detect (Auto-Ban Enforced)", path, ip, userAgent);
+      }
+      return new NextResponse(
+        JSON.stringify({ error: "TOO_MANY_REQUESTS", message: "Rate limit exceeded. Temporary lockout active." }),
+        { status: 429, headers: { 'content-type': 'application/json' } }
+      );
+    }
+
+    // If all checks pass clean, allow the request to flow through normally
+    return NextResponse.next();
+  }
+
+  /**
+   * Internal proxy to forward telemetry events cleanly to the telemetry pipeline.
+   * @private
+   */
+  triggerAlert(threatType, path, ip, userAgent) {
+    if (!this.discordWebhook) return;
+    
+    // Alert Throttling: Only alert Discord once per IP every 60 seconds
+    const lastAlert = this.alertCooldowns.get(ip) || 0;
+    if (Date.now() - lastAlert < 60000) return; 
+    
+    this.alertCooldowns.set(ip, Date.now());
+
+    // Execute async dispatch without awaiting to prevent latency blocks for the end-user
+    dispatchSocAlert(this.discordWebhook, { threatType, path, ip, userAgent })
+      .catch((err) => console.error("[WolfGuard WAF] Async alerting failure:", err));
+  }
+}

package/src/rateLimiter.js

@@ -0,0 +1,53 @@
+export class RateLimiter {
+  constructor(limit = 50, windowMs = 60000, banMs = 86400000) {
+    this.limit = limit;               
+    this.windowMs = windowMs;         
+    this.banMs = banMs;               
+    this.requestTracker = new Map();
+    this.tempBans = new Map();
+  }
+
+  // Serverless Garbage Collection to prevent Memory Leaks
+  cleanup() {
+    const now = Date.now();
+    for (const [ip, data] of this.requestTracker) {
+      if (now > data.resetTime) this.requestTracker.delete(ip);
+    }
+    for (const [ip, unbanTime] of this.tempBans) {
+      if (now > unbanTime) this.tempBans.delete(ip);
+    }
+  }
+
+  checkLimit(ip) {
+    const now = Date.now();
+
+    // Probabilistic Cleanup: Runs on ~2% of requests to keep memory clean at the Edge
+    if (Math.random() < 0.02) this.cleanup();
+
+    if (this.tempBans.has(ip)) {
+      if (now > this.tempBans.get(ip)) {
+        this.tempBans.delete(ip);
+      } else {
+        return { blocked: true, reason: "AUTO_BANNED" };
+      }
+    }
+
+    let ipData = this.requestTracker.get(ip) || { count: 0, resetTime: now + this.windowMs };
+
+    if (now > ipData.resetTime) {
+      ipData = { count: 1, resetTime: now + this.windowMs };
+    } else {
+      ipData.count += 1;
+    }
+
+    this.requestTracker.set(ip, ipData);
+
+    if (ipData.count > this.limit) {
+      this.tempBans.set(ip, now + this.banMs); 
+      this.requestTracker.delete(ip); 
+      return { blocked: true, reason: "RATE_LIMIT_EXCEEDED" };
+    }
+
+    return { blocked: false, reason: null };
+  }
+}

package/src/signatures.js

@@ -0,0 +1,30 @@
+export const DEFAULT_SIGNATURES = [
+  { regex: /(%3C|<)script(%3E|>)/i, type: "XSS (Cross-Site Scripting)" },
+  { regex: /UNION.+SELECT|SELECT.+FROM/i, type: "SQL Injection (SQLi)" },
+  { regex: /(\.\.\/|\.\.\\)/i, type: "Path Traversal (LFI)" },
+  { regex: /\.(env|git|bak|sql|php|yaml|config|pem|key)$/i, type: "Sensitive File Honeypot" },
+  { regex: /(wp-admin|phpmyadmin|admin\.php)/i, type: "Admin Panel Honeypot" },
+  { regex: /(\$|%24)\{.*?\}/i, type: "Template Injection (SSTI)" },
+  { regex: /(;|\||&&|`|%60).*(bash|sh|wget|curl|nc|ping)/i, type: "OS Command Injection" }
+];
+
+export function detectThreat(urlPath, customSignatures = []) {
+  // 1. Sanitize and Normalize the Input to prevent bypasses
+  let normalizedPath = urlPath;
+  try {
+    normalizedPath = decodeURIComponent(urlPath).toLowerCase();
+  } catch (e) {
+    // If decoding fails, it's likely a malformed payload anyway
+    normalizedPath = urlPath.toLowerCase(); 
+  }
+
+  // 2. Combine default and developer-provided custom rules
+  const allSignatures = [...DEFAULT_SIGNATURES, ...customSignatures];
+
+  for (const signature of allSignatures) {
+    if (signature.regex.test(normalizedPath) || signature.regex.test(urlPath)) {
+      return signature.type;
+    }
+  }
+  return null;
+}

package/src/telemetry.js

@@ -0,0 +1,93 @@
+/**
+ * Queries a secure, HTTPS IP geolocation API to resolve ISP and coordinate telemetry.
+ * * @param {string} ip - Target IP address
+ * @returns {Promise<object>} Resolved geolocation and network data
+ */
+async function fetchIpIntelligence(ip) {
+  // Prevent API thrashing and rate-limiting blocks during local testing
+  if (ip === "127.0.0.1" || ip === "::1" || ip.startsWith("192.168.")) {
+    return {
+      location: "Internal Security Sandbox (Localhost)",
+      coordinates: "N/A",
+      isp: "Local Loopback Interface"
+    };
+  }
+
+  try {
+    // Querying the endpoint with a strict 2-second timeout constraint
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), 2000);
+
+    const response = await fetch(`https://ipwho.is/${ip}`, { signal: controller.signal });
+    clearTimeout(timeoutId);
+
+    if (response.ok) {
+      const data = await response.json();
+      if (data.success) {
+        return {
+          location: `${data.city || "Unknown City"}, ${data.region || "Unknown Region"}, ${data.country || "Unknown Country"}`,
+          coordinates: `${data.latitude || 0}, ${data.longitude || 0}`,
+          isp: data.connection.isp || data.connection.org || "Unknown ISP Provider"
+        };
+      }
+    }
+  } catch (error) {
+    // Silent mitigation to ensure a failed lookup doesn't crash the host application
+    console.error("[WolfGuard WAF] Threat intelligence lookup bypassed or timed out.");
+  }
+
+  return {
+    location: "Unknown Location (Lookup Failed)",
+    coordinates: "N/A",
+    isp: "Autonomous System / Hidden Proxy"
+  };
+}
+
+/**
+ * Compiles a detailed threat report and dispatches it via a structured Discord Webhook embed.
+ */
+export async function dispatchSocAlert(webhookUrl, { threatType, path, ip, userAgent }) {
+  if (!webhookUrl) return;
+
+  // Sanitize and truncate data to prevent Discord payload injection errors (max length limits)
+  const safePath = path.substring(0, 300);
+  const safeUA = (userAgent || "Missing User-Agent Header").substring(0, 300);
+  
+  // Resolve Geo-IP and ISP context before compiling report
+  const intel = await fetchIpIntelligence(ip);
+
+  const payload = {
+    username: "WolfGuard Active Defense Engine",
+    avatar_url: "https://images.unsplash.com/photo-1614064641938-3bbee52942c7?q=80&w=128&auto=format&fit=crop", // Abstract shield
+    embeds: [
+      {
+        title: "🚨 SEC-OPS: EDGE INTERCEPT DETECTED",
+        description: "The incoming network packet triggered a high-severity rule violation and was successfully dropped at the application perimeter.",
+        color: 16711680, // High-visibility red hex code
+        fields: [
+          { name: "🎚️ Threat Classification", value: `**${threatType}**`, inline: false },
+          { name: "🎯 Target URI Vector", value: `\`\`\`text\n${safePath}\n\`\`\``, inline: false },
+          { name: "🌐 Client IP Address", value: `\`${ip}\``, inline: true },
+          { name: "🏢 Network ISP Provider", value: intel.isp, inline: true },
+          { name: "📍 Geo-Location Matrix", value: intel.location, inline: true },
+          { name: "💻 Device Identity String", value: `\`\`\`text\n${safeUA}\n\`\`\``, inline: false }
+        ],
+        footer: {
+          text: "System telemetry verified • WolfGuard WAF Framework",
+          icon_url: "https://images.unsplash.com/photo-1614064641938-3bbee52942c7?q=80&w=128&auto=format&fit=crop"
+        },
+        timestamp: new Date().toISOString()
+      }
+    ]
+  };
+
+  try {
+    await fetch(webhookUrl, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(payload)
+    });
+  } catch (err) {
+    console.error("[WolfGuard WAF] Failed to transmit alert vector to target SIEM channel.");
+  }
+}

package/src/utils.js

@@ -0,0 +1,26 @@
+/**
+ * Safely extracts the client's public IP address from Next.js request headers.
+ * Accounts for edge proxies, load balancers, and local loopbacks.
+ * * @param {Request} request - The incoming Next.js Request object
+ * @returns {string} The resolved IP address
+ */
+export function extractClientIp(request) {
+  // Check standard proxy headers populated by Vercel / Cloudflare
+  const xForwardedFor = request.headers.get("x-forwarded-for");
+  const xRealIp = request.headers.get("x-real-ip");
+
+  if (xForwardedFor) {
+    // x-forwarded-for can contain a comma-separated chain of IPs (client, proxy1, proxy2).
+    // The first IP in the list is always the original client.
+    const ipChain = xForwardedFor.split(",");
+    const clientIp = ipChain[0].trim();
+    if (clientIp) return clientIp;
+  }
+
+  if (xRealIp) {
+    return xRealIp.trim();
+  }
+
+  // Fallback if no proxy headers are present (e.g., raw local dev environment)
+  return "127.0.0.1";
+}