mdefender-pro 1.1.0

package/README.md

@@ -0,0 +1,194 @@
+# MDefender Pro
+
+[![npm version](https://img.shields.io/npm/v/mdefender.svg)](https://www.npmjs.com/package/mdefender)
+[![license](https://img.shields.io/npm/l/mdefender.svg)](https://github.com/mdefender/mdefender/blob/main/LICENSE)
+
+**MDefender Pro** is a Web Application Firewall (WAF) middleware for Node.js/Express. It intercepts incoming HTTP requests and sends them to the MDefender Pro API for real-time threat analysis, blocking malicious traffic such as XSS, SQLi, CSRF, and other OWASP Top 10 attacks.
+
+## Installation
+
+```bash
+npm install mdefender
+```
+
+## Quick Start
+
+```js
+const express = require('express');
+const mdefender = require('mdefender');
+
+const app = express();
+
+// Protect all routes
+app.use(mdefender({
+  apiKey: 'your-api-key-here',
+  domain: 'example.com',
+}));
+
+app.get('/', (req, res) => {
+  res.send('Hello, protected world!');
+});
+
+app.listen(3000, () => {
+  console.log('Server running on port 3000');
+});
+```
+
+## Configuration
+
+You can configure MDefender in three ways:
+
+1. **Inline** - Pass options directly to the middleware
+2. **Config file** - Use `mdefender.config.js` or `mdefender.json`
+3. **package.json** - Add a `"mdefender"` key to your `package.json`
+
+Priority order: **Inline options > Config file > package.json**
+
+### Options
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `apiKey` | `string` | `''` | **Required.** Your MDefender Pro API key |
+| `domain` | `string` | `''` | **Required.** The domain to protect |
+| `apiEndpoint` | `string` | `'https://mdefender-pro.onrender.com'` | MDefender API base URL |
+| `mode` | `'block' \| 'monitor' \| 'off'` | `'block'` | `block` = block threats, `monitor` = log only, `off` = disabled |
+| `blockStatusCode` | `number` | `403` | HTTP status code for blocked requests |
+| `timeout` | `number` | `5000` | API request timeout in milliseconds |
+| `maxBodySize` | `number` | `1048576` | Max request body size in bytes (1MB) |
+| `logBlocked` | `boolean` | `true` | Log blocked requests to console |
+| `customBlockPage` | `string \| null` | `null` | Path to a custom HTML file for block page |
+| `skipPaths` | `string[]` | `['/health', '/favicon.ico']` | Paths to skip WAF checking |
+| `skipUserAgents` | `string[]` | `[]` | User agents to skip (substring match) |
+| `skipMethods` | `string[]` | `[]` | HTTP methods to skip entirely |
+| `headers` | `boolean` | `true` | Forward original request headers to API |
+| `onError` | `'allow' \| 'block'` | `'allow'` | Behavior when API is unreachable |
+
+### Config File: `mdefender.config.js`
+
+```js
+module.exports = {
+  apiKey: process.env.MDEFENDER_API_KEY,
+  domain: 'example.com',
+  mode: 'block',
+  skipPaths: ['/health', '/ping', '/favicon.ico'],
+  logBlocked: true,
+};
+```
+
+### Config File: `mdefender.json`
+
+```json
+{
+  "apiKey": "your-api-key-here",
+  "domain": "example.com",
+  "mode": "block",
+  "skipPaths": ["/health", "/ping"],
+  "onError": "allow"
+}
+```
+
+### `package.json`
+
+```json
+{
+  "name": "my-app",
+  "mdefender": {
+    "apiKey": "your-api-key-here",
+    "domain": "example.com"
+  }
+}
+```
+
+## Advanced Usage
+
+### Custom Block Page
+
+Provide a path to your own HTML file:
+
+```js
+app.use(mdefender({
+  apiKey: 'your-key',
+  domain: 'example.com',
+  customBlockPage: path.join(__dirname, 'views', 'block.html'),
+}));
+```
+
+### Monitor Mode (Log Only)
+
+Run in monitoring mode to analyze requests without blocking:
+
+```js
+app.use(mdefender({
+  apiKey: 'your-key',
+  domain: 'example.com',
+  mode: 'monitor',
+}));
+```
+
+### Skip Specific Paths
+
+```js
+app.use(mdefender({
+  apiKey: 'your-key',
+  domain: 'example.com',
+  skipPaths: ['/health', '/api/webhook', '/static/'],
+}));
+```
+
+### Block on API Error
+
+By default, requests are allowed if the WAF API is unreachable. To block instead:
+
+```js
+app.use(mdefender({
+  apiKey: 'your-key',
+  domain: 'example.com',
+  onError: 'block',
+}));
+```
+
+### Accessing Analysis Results
+
+After the middleware processes a request, analysis data is attached to `req.mdefender`:
+
+```js
+app.get('/dashboard', (req, res) => {
+  if (req.mdefender) {
+    console.log('Threat score:', req.mdefender.threat_score);
+    console.log('Request ID:', req.mdefender.request_id);
+  }
+  res.send('Dashboard');
+});
+```
+
+## API Reference
+
+### `mdefender(config?)`
+
+Returns an Express middleware function.
+
+**Parameters:**
+- `config` *(optional)* - `MDefenderConfig` object. Options merge with file-based config and defaults.
+
+**Returns:** `Express middleware function`
+
+### `mdefender.loadConfig(overrides?)`
+
+Utility to load configuration from file sources with optional overrides.
+
+### `mdefender.DEFAULT_CONFIG`
+
+The default configuration object.
+
+## How It Works
+
+1. A request hits your Express app
+2. MDefender intercepts it and builds a payload (method, URL, headers, body, IP, etc.)
+3. The payload is sent to the MDefender Pro API for analysis
+4. If the API detects a threat, it returns a `blocked` status with attack details
+5. MDefender renders a block page and responds with the configured status code
+6. If safe, the request continues to your route handler
+
+## License
+
+MIT

package/config-loader.js

@@ -0,0 +1,35 @@
+'use strict';
+
+const path = require('path');
+const fs = require('fs');
+
+function findConfig(startDir) {
+  const configs = [
+    'mdefender.config.js',
+    'mdefender.config.cjs',
+    'mdefender.json',
+  ];
+  
+  let dir = startDir || process.cwd();
+  
+  while (dir !== path.dirname(dir)) {
+    for (const name of configs) {
+      const fp = path.join(dir, name);
+      if (fs.existsSync(fp)) return fp;
+    }
+    dir = path.dirname(dir);
+  }
+  return null;
+}
+
+function load(startDir) {
+  const configPath = findConfig(startDir);
+  if (!configPath) return null;
+  
+  if (configPath.endsWith('.json')) {
+    return JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+  }
+  return require(configPath);
+}
+
+module.exports = { findConfig, load };

package/index.d.ts

@@ -0,0 +1,37 @@
+import { Request, Response, NextFunction } from 'express';
+
+interface MDefenderConfig {
+  apiKey?: string;
+  domain?: string;
+  apiEndpoint?: string;
+  mode?: 'block' | 'monitor' | 'off';
+  blockStatusCode?: number;
+  timeout?: number;
+  maxBodySize?: number;
+  logBlocked?: boolean;
+  customBlockPage?: string | null;
+  skipPaths?: string[];
+  skipUserAgents?: string[];
+  skipMethods?: string[];
+  headers?: boolean;
+  onError?: 'allow' | 'block';
+}
+
+interface MDefenderRequest extends Request {
+  mdefender?: {
+    status: string;
+    threat_score: number;
+    request_id: string | null;
+  };
+}
+
+type MDefenderMiddleware = (req: MDefenderRequest, res: Response, next: NextFunction) => void;
+
+declare function mdefender(config?: MDefenderConfig): MDefenderMiddleware;
+
+declare namespace mdefender {
+  export function loadConfig(overrides?: Partial<MDefenderConfig>): MDefenderConfig;
+  export const DEFAULT_CONFIG: MDefenderConfig;
+}
+
+export = mdefender;

package/index.js

@@ -0,0 +1,284 @@
+'use strict';
+
+const axios = require('axios');
+const path = require('path');
+const fs = require('fs');
+const crypto = require('crypto');
+
+const DEFAULT_CONFIG = {
+  apiKey: '',
+  domain: '',
+  apiEndpoint: 'https://mdefender-pro.onrender.com',
+  mode: 'block',         // 'block' | 'monitor' | 'off'
+  blockStatusCode: 403,
+  timeout: 5000,
+  maxBodySize: 1024 * 1024, // 1MB
+  logBlocked: true,
+  customBlockPage: null,     // path to custom HTML file
+  skipPaths: ['/health', '/favicon.ico'],
+  skipUserAgents: [],
+  skipMethods: [],
+  headers: true,             // forward original headers
+  onError: 'allow',          // 'allow' | 'block' - what to do if API is unreachable
+};
+
+function loadConfig(overrides = {}) {
+  let fileConfig = {};
+  
+  // Try mdefender.config.js
+  const jsPath = path.resolve(process.cwd(), 'mdefender.config.js');
+  if (fs.existsSync(jsPath)) {
+    fileConfig = require(jsPath);
+  }
+  
+  // Try mdefender.json
+  const jsonPath = path.resolve(process.cwd(), 'mdefender.json');
+  if (!fileConfig.apiKey && fs.existsSync(jsonPath)) {
+    fileConfig = JSON.parse(fs.readFileSync(jsonPath, 'utf-8'));
+  }
+  
+  // Try package.json "mdefender" key
+  if (!fileConfig.apiKey) {
+    try {
+      const pkg = require(path.resolve(process.cwd(), 'package.json'));
+      if (pkg.mdefender) fileConfig = pkg.mdefender;
+    } catch (e) {}
+  }
+
+  return { ...DEFAULT_CONFIG, ...fileConfig, ...overrides };
+}
+
+function getClientIP(req) {
+  return req.headers['x-forwarded-for']?.split(',')[0]?.trim()
+    || req.headers['x-real-ip']
+    || req.connection?.remoteAddress
+    || req.socket?.remoteAddress
+    || 'unknown';
+}
+
+function buildPayload(req, config) {
+  const ip = getClientIP(req);
+  const originalUrl = req.originalUrl || req.url;
+  const parsedUrl = new URL(originalUrl, `http://${req.headers.host || 'localhost'}`);
+  
+  const payload = {
+    domain: config.domain,
+    method: req.method,
+    url: parsedUrl.pathname,
+    query_string: parsedUrl.search || '',
+    query_params: Object.fromEntries(parsedUrl.searchParams),
+    ip: ip,
+    headers: config.headers ? req.headers : {},
+    user_agent: req.headers['user-agent'] || '',
+    referer: req.headers['referer'] || req.headers['referrer'] || '',
+    content_type: req.headers['content-type'] || '',
+    body: '',
+    body_fields: {},
+    body_field_values: '',
+    timestamp: new Date().toISOString(),
+  };
+
+  return payload;
+}
+
+function readBody(req) {
+  return new Promise((resolve) => {
+    if (req.body) {
+      if (typeof req.body === 'string') return resolve(req.body);
+      if (typeof req.body === 'object') return resolve(JSON.stringify(req.body));
+      return resolve(String(req.body));
+    }
+
+    let body = '';
+    const maxBytes = 1024 * 1024;
+    let bytesRead = 0;
+
+    const onData = (chunk) => {
+      bytesRead += chunk.length;
+      if (bytesRead > maxBytes) {
+        req.removeListener('data', onData);
+        req.removeListener('end', onEnd);
+        resolve(body);
+        return;
+      }
+      body += chunk.toString();
+    };
+
+    const onEnd = () => {
+      req.removeListener('data', onData);
+      resolve(body);
+    };
+
+    req.on('data', onData);
+    req.on('end', onEnd);
+
+    // If stream already ended
+    if (req.readableEnded || req.complete) {
+      req.removeListener('data', onData);
+      req.removeListener('end', onEnd);
+      resolve(body);
+    }
+  });
+}
+
+function parseBody(body, contentType) {
+  if (!body) return { fields: {}, values: '' };
+  
+  try {
+    if (contentType && contentType.includes('application/json')) {
+      const parsed = JSON.parse(body);
+      return { fields: parsed, values: Object.values(parsed).join(' ') };
+    }
+    if (contentType && contentType.includes('application/x-www-form-urlencoded')) {
+      const params = new URLSearchParams(body);
+      const fields = Object.fromEntries(params);
+      return { fields, values: Object.values(fields).join(' ') };
+    }
+  } catch (e) {}
+  
+  return { fields: {}, values: body };
+}
+
+function renderBlockPage(config, result) {
+  if (config.customBlockPage && fs.existsSync(config.customBlockPage)) {
+    return fs.readFileSync(config.customBlockPage, 'utf-8');
+  }
+  
+  const attackType = result.attack_type || 'Unknown';
+  const confidence = result.confidence || 0;
+  const referenceId = result.reference_id || crypto.randomUUID();
+  
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Access Blocked - MDefender Pro</title>
+  <style>
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    body { min-height: 100vh; display: flex; align-items: center; justify-content: center;
+      background: linear-gradient(135deg, #1a1a2e 0%, #16213e 50%, #0f3460 100%);
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+      color: #fff; }
+    .container { text-align: center; padding: 40px; max-width: 600px; }
+    .icon { font-size: 80px; margin-bottom: 20px; opacity: 0.9; }
+    h1 { font-size: 28px; margin-bottom: 12px; font-weight: 700; }
+    .subtitle { font-size: 16px; color: rgba(255,255,255,0.7); margin-bottom: 30px; }
+    .details { background: rgba(255,255,255,0.08); border-radius: 12px; padding: 20px;
+      text-align: left; margin-bottom: 30px; backdrop-filter: blur(10px); }
+    .details p { font-size: 14px; color: rgba(255,255,255,0.8); margin: 8px 0; }
+    .details strong { color: #e74c3c; }
+    .footer { font-size: 12px; color: rgba(255,255,255,0.4); }
+  </style>
+</head>
+<body>
+  <div class="container">
+    <div class="icon">&#x1F6AB;</div>
+    <h1>Access Blocked</h1>
+    <p class="subtitle">This request has been blocked by MDefender Pro WAF</p>
+    <div class="details">
+      <p><strong>Attack Type:</strong> ${attackType}</p>
+      <p><strong>Confidence:</strong> ${(confidence * 100).toFixed(1)}%</p>
+      <p><strong>Reference ID:</strong> ${referenceId}</p>
+      <p><strong>Time:</strong> ${new Date().toISOString()}</p>
+    </div>
+    <p class="footer">MDefender Pro - Web Application Firewall</p>
+  </div>
+</body>
+</html>`;
+}
+
+function mdefender(overrides = {}) {
+  const config = loadConfig(overrides);
+
+  if (!config.apiKey) {
+    console.error('[MDefender] ERROR: No API key provided. Set it in mdefender.config.js or pass it as an option.');
+    return (req, res, next) => next();
+  }
+
+  if (config.mode === 'off') {
+    return (req, res, next) => next();
+  }
+
+  const client = axios.create({
+    baseURL: config.apiEndpoint,
+    timeout: config.timeout,
+    headers: {
+      'Authorization': `Bearer ${config.apiKey}`,
+      'Content-Type': 'application/json',
+      'X-MDefender-Version': '1.0.0',
+    },
+  });
+
+  return async function mdefenderMiddleware(req, res, next) {
+    // Skip certain paths
+    if (config.skipPaths.some(p => req.url.startsWith(p))) return next();
+    
+    // Skip certain methods
+    if (config.skipMethods.includes(req.method)) return next();
+    
+    // Skip certain user agents
+    const ua = req.headers['user-agent'] || '';
+    if (config.skipUserAgents.some(s => ua.toLowerCase().includes(s.toLowerCase()))) return next();
+
+    try {
+      // Read and parse request body
+      const rawBody = await readBody(req);
+      const contentType = req.headers['content-type'] || '';
+      const { fields, values } = parseBody(rawBody, contentType);
+      
+      // Build payload
+      const payload = buildPayload(req, config);
+      payload.body = rawBody;
+      payload.body_fields = fields;
+      payload.body_field_values = values;
+
+      // Send to MDefender API
+      const response = await client.post('/api/analyze', {
+        request: payload,
+        domain: config.domain,
+      });
+
+      const result = response.data;
+
+      if (result.status === 'blocked') {
+        if (config.logBlocked) {
+          console.log(`[MDefender] BLOCKED ${req.method} ${req.url} - ${result.attack_type} (${(result.confidence * 100).toFixed(1)}%)`);
+        }
+        
+        const blockPage = result.block_page || renderBlockPage(config, result);
+        res.writeHead(config.blockStatusCode, {
+          'Content-Type': 'text/html; charset=utf-8',
+          'X-MDefender-Status': 'blocked',
+          'X-MDefender-Attack-Type': result.attack_type || 'unknown',
+        });
+        return res.end(blockPage);
+      }
+
+      // Request is safe - attach result to request for downstream use
+      req.mdefender = {
+        status: 'allowed',
+        threat_score: result.threat_score || 0,
+        request_id: result.request_id || null,
+      };
+
+      return next();
+
+    } catch (error) {
+      console.error(`[MDefender] API Error: ${error.message}`);
+      
+      if (config.onError === 'block') {
+        res.writeHead(503, { 'Content-Type': 'text/html' });
+        return res.end('<html><body><h1>Service Temporarily Unavailable</h1><p>WAF service is currently unreachable. Please try again later.</p></body></html>');
+      }
+      
+      // Default: allow request on error
+      return next();
+    }
+  };
+}
+
+mdefender.loadConfig = loadConfig;
+mdefender.DEFAULT_CONFIG = DEFAULT_CONFIG;
+
+module.exports = mdefender;

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "mdefender-pro",
+  "version": "1.1.0",
+  "description": "MDefender Pro - Web Application Firewall middleware for Node.js/Express. Protects against XSS, SQLi, CSRF, and other OWASP Top 10 attacks.",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "keywords": [
+    "waf",
+    "web-application-firewall",
+    "security",
+    "firewall",
+    "xss",
+    "sqli",
+    "csrf",
+    "protection",
+    "middleware",
+    "express",
+    "nodejs",
+    "owasp"
+  ],
+  "author": "MDefender Pro",
+  "license": "MIT",
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "dependencies": {
+    "axios": "^1.6.0"
+  },
+  "peerDependencies": {
+    "express": ">=4.0.0"
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "README.md",
+    "config-loader.js"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mdefender/mdefender"
+  },
+  "homepage": "https://mdefender-pro-6e3r.onrender.com",
+  "bugs": {
+    "url": "https://github.com/mdefender/mdefender/issues"
+  }
+}