mdefender-pro 1.2.0 → 1.2.1

package/README.md

@@ -1,194 +1,166 @@
-# MDefender Pro
+# MDefender Pro — Node.js / Express WAF Middleware
 
 [![npm version](https://img.shields.io/npm/v/mdefender-pro.svg)](https://www.npmjs.com/package/mdefender-pro)
-[![license](https://img.shields.io/npm/l/mdefender-pro.svg)](https://github.com/mahabub251595/mdefender-pro/blob/main/LICENSE)
+[![license](https://img.shields.io/npm/l/mdefender-pro.svg)](https://github.com/mdefender/mdefender/blob/main/LICENSE)
+[![Zero Config](https://img.shields.io/badge/Block%20Page-Bundled%20Auto-green.svg)](#bundled-403-block-page)
 
-**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.
+**MDefender Pro** is an enterprise-grade Web Application Firewall (WAF) middleware for Node.js and Express. It inspects incoming HTTP requests in real-time against **2,000 verified signatures** and a **5.2M+ attack vector Machine Learning engine**, automatically blocking SQL injection, Cross-Site Scripting (XSS), Remote Code Execution (RCE), Directory Traversal (LFI), bot scrapers, and zero-day vulnerabilities.
 
-## Installation
+---
+
+## Key Features
+
+- 🛡️ **Zero Setup Cyber Block Page**: Bundled automatically with the package — no external HTML or static file hosting required.
+- ⚡ **Sub-Millisecond In-Memory Caching**: Template and rules are cached in memory for instantaneous rendering (<5ms).
+- 🔑 **Flexible API Key Authentication**: Configure via `mdefender.config.js`, interactive CLI (`npx mdefender-pro init`), environment variables, or inline parameters.
+- 🚦 **Fail-Open Safety Mechanism**: If cloud telemetry times out, legitimate traffic passes smoothly without blocking customers.
+- 📦 **Zero External Runtime Dependencies**: Pure Node.js standard libraries (`http`, `https`, `crypto`).
+
+---
+
+## 1. Installation
+
+Install the official package in your Node.js / Express backend project:
 
 ```bash
 npm install mdefender-pro
 ```
 
-## Quick Start
+*(When you install `mdefender-pro`, the responsive Cyber 403 Block Page is bundled automatically).*
 
-```js
-const express = require('express');
-const mdefender = require('mdefender-pro');
+---
 
-const app = express();
+## 2. Quick Setup
 
-// Protect all routes
-app.use(mdefender({
-  apiKey: 'your-api-key-here',
-  domain: 'example.com',
-}));
+### Option A: Interactive CLI (1-Click)
 
-app.get('/', (req, res) => {
-  res.send('Hello, protected world!');
-});
+Run the interactive setup tool in your project directory:
 
-app.listen(3000, () => {
-  console.log('Server running on port 3000');
-});
+```bash
+npx mdefender-pro init
 ```
 
-## Configuration
+This prompts for your API key and creates a ready-to-use `mdefender.config.js`.
 
-You can configure MDefender in three ways:
+### Option B: Manual Config File (`mdefender.config.js`)
 
-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`
+Create `mdefender.config.js` in your project root:
 
 ```js
+// mdefender.config.js
 module.exports = {
-  apiKey: process.env.MDEFENDER_API_KEY,
-  domain: 'example.com',
-  mode: 'block',
-  skipPaths: ['/health', '/ping', '/favicon.ico'],
-  logBlocked: true,
-};
-```
+  // Your Website API Key from MDefender Dashboard -> Websites
+  apiKey: process.env.MDEFENDER_API_KEY || 'your_64_char_api_key_here',
 
-### Config File: `mdefender.json`
+  // Domain registered in MDefender
+  domain: 'yourdomain.com',
 
-```json
-{
-  "apiKey": "your-api-key-here",
-  "domain": "example.com",
-  "mode": "block",
-  "skipPaths": ["/health", "/ping"],
-  "onError": "allow"
-}
-```
+  // WAF Cloud / Self-hosted endpoint
+  apiEndpoint: 'https://mdefender-pro-6e3r.onrender.com', // or 'http://127.0.0.1:8000' for local dev
 
-### `package.json`
+  // Protection mode: 'block' (active) | 'monitor' (log-only) | 'off'
+  mode: 'block',
 
-```json
-{
-  "name": "my-app",
-  "mdefender": {
-    "apiKey": "your-api-key-here",
-    "domain": "example.com"
-  }
-}
+  // Log blocked attacks in console
+  logBlocked: true
+};
 ```
 
-## Advanced Usage
+---
 
-### Custom Block Page
+## 3. Attach Middleware to Express
 
-Provide a path to your own HTML file:
+Add `app.use(mdefender())` after your standard body parsers (`express.json()`) and before your routes:
 
 ```js
-app.use(mdefender({
-  apiKey: 'your-key',
-  domain: 'example.com',
-  customBlockPage: path.join(__dirname, 'views', 'block.html'),
-}));
-```
+const express = require('express');
+const cors = require('cors');
+const mdefender = require('mdefender-pro');
 
-### Monitor Mode (Log Only)
+const app = express();
 
-Run in monitoring mode to analyze requests without blocking:
+// Standard middleware
+app.use(cors());
+app.use(express.json());
+app.use(express.urlencoded({ extended: true }));
 
-```js
-app.use(mdefender({
-  apiKey: 'your-key',
-  domain: 'example.com',
-  mode: 'monitor',
-}));
-```
+// Attach MDefender Pro WAF
+// Automatically loads mdefender.config.js and serves bundled 403 block page
+app.use(mdefender());
 
-### Skip Specific Paths
+// Your application routes
+app.use('/api/books', require('./routes/books'));
+app.use('/api/users', require('./routes/users'));
 
-```js
-app.use(mdefender({
-  apiKey: 'your-key',
-  domain: 'example.com',
-  skipPaths: ['/health', '/api/webhook', '/static/'],
-}));
+app.listen(5000, () => {
+  console.log('Server running with MDefender Pro active protection!');
+});
 ```
 
-### Block on API Error
+---
+
+## 4. Inline Configuration (Alternative)
 
-By default, requests are allowed if the WAF API is unreachable. To block instead:
+If you prefer not using a config file, pass options directly:
 
 ```js
 app.use(mdefender({
-  apiKey: 'your-key',
-  domain: 'example.com',
-  onError: 'block',
+  apiKey: 'your_64_char_api_key_here',
+  domain: 'yourdomain.com',
+  apiEndpoint: 'http://127.0.0.1:8000',
+  mode: 'block'
 }));
 ```
 
-### Accessing Analysis Results
+---
 
-After the middleware processes a request, analysis data is attached to `req.mdefender`:
+## 5. Bundled 403 Block Page
 
-```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?)`
+When a malicious request is detected (such as `?id=<script>alert(1)</script>` or SQL injection):
+1. MDefender Pro immediately returns HTTP status **`403 Forbidden`**.
+2. Renders the cyber-security dark glassmorphic Block Page displaying:
+   - **Incident Reference ID** (e.g. `MDF-BB46BF9D`) with 1-click clipboard copy.
+   - **Attack Type** (e.g. `XSS - Dangerous HTML Tag (<script>) #1`).
+   - **Client IP & Timestamp** for security auditing.
+   - **Return to Homepage** action button.
 
-Returns an Express middleware function.
+---
 
-**Parameters:**
-- `config` *(optional)* - `MDefenderConfig` object. Options merge with file-based config and defaults.
+## 6. How to Test Your Protection
 
-**Returns:** `Express middleware function`
-
-### `mdefender.loadConfig(overrides?)`
+### Test 1: XSS Attack Payload (Expect 403 Blocked)
+```bash
+curl -i "http://localhost:5000/api/books?id=%3Cscript%3Ealert(1)%3C/script%3E"
+```
 
-Utility to load configuration from file sources with optional overrides.
+### Test 2: SQL Injection Payload (Expect 403 Blocked)
+```bash
+curl -i "http://localhost:5000/api/books?search=%27%20UNION%20SELECT%20null,password%20FROM%20users--"
+```
 
-### `mdefender.DEFAULT_CONFIG`
+### Test 3: Safe Request (Expect 200 OK)
+```bash
+curl -i "http://localhost:5000/api/books"
+```
 
-The default configuration object.
+---
 
-## How It Works
+## Configuration Reference
 
-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
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `apiKey` | `string` | `''` | **Required.** Your website API key from dashboard. |
+| `domain` | `string` | `''` | Registered domain name or hostname. |
+| `apiEndpoint` | `string` | `'http://127.0.0.1:8000'` | WAF inspection endpoint URL. |
+| `mode` | `'block' \| 'monitor' \| 'off'` | `'block'` | `block` = active defense, `monitor` = log only. |
+| `blockStatusCode` | `number` | `403` | HTTP status code for blocked requests. |
+| `timeout` | `number` | `5000` | Request timeout in ms (fails open safely). |
+| `skipPaths` | `string[]` | `['/health', '/favicon.ico']` | URL paths to bypass WAF inspection. |
+| `logBlocked` | `boolean` | `true` | Log blocked attacks in console. |
+| `customBlockPage` | `string \| null` | `null` | Optional path to custom HTML file. |
+
+---
 
 ## License
 
-MIT
+MIT &copy; MDefender Pro

package/bin/mdefender.js

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const readline = require('readline');
+
+const args = process.argv.slice(2);
+const command = args[0] || 'init';
+
+console.log(`\n\x1b[36m\x1b[1m========================================\x1b[0m`);
+console.log(`\x1b[36m\x1b[1m   MDefender Pro - Quick Setup CLI      \x1b[0m`);
+console.log(`\x1b[36m\x1b[1m========================================\x1b[0m\n`);
+
+if (command === 'init' || command === 'setup') {
+  const targetConfig = path.join(process.cwd(), 'mdefender.config.js');
+
+  if (fs.existsSync(targetConfig)) {
+    console.log(`\x1b[33m[!] mdefender.config.js already exists in current directory.\x1b[0m`);
+    process.exit(0);
+  }
+
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+
+  rl.question('\x1b[32mEnter your MDefender Pro API Key (from Dashboard): \x1b[0m', (apiKey) => {
+    rl.question('\x1b[32mEnter your Website Domain (e.g. myapp.com or default): \x1b[0m', (domain) => {
+      const trimmedKey = (apiKey || 'YOUR_API_KEY_HERE').trim();
+      const trimmedDomain = (domain || 'default').trim();
+
+      const configTemplate = `/**
+ * MDefender Pro Web Application Firewall Configuration
+ * Generated automatically by @mdefender/pro CLI
+ */
+module.exports = {
+  // Your Secret Website API Key from MDefender Dashboard
+  apiKey: process.env.MDEFENDER_API_KEY || '${trimmedKey}',
+
+  // Domain registered in MDefender Pro
+  domain: '${trimmedDomain}',
+
+  // Cloud / Self-hosted Inspection Endpoint
+  apiEndpoint: process.env.MDEFENDER_API_ENDPOINT || 'https://mdefender-pro-6e3r.onrender.com',
+
+  // Mode: 'block' (active defense), 'monitor' (log-only), or 'off'
+  mode: 'block',
+
+  // Request timeout for cloud inspection in milliseconds (fails open safely)
+  timeout: 3000,
+
+  // Paths to bypass from inspection (e.g. static assets)
+  skipPaths: ['/favicon.ico', '/robots.txt', '/static', '/assets', '/health'],
+
+  // HTTP methods to bypass
+  skipMethods: ['OPTIONS'],
+
+  // Log blocked attacks in console
+  logBlocked: true
+};
+`;
+
+      fs.writeFileSync(targetConfig, configTemplate, 'utf8');
+      console.log(`\n\x1b[32m[+] Created mdefender.config.js successfully!\x1b[0m`);
+      console.log(`\n\x1b[36mHow to use in your Express app:\x1b[0m`);
+      console.log(`\x1b[90m---------------------------------------------------\x1b[0m`);
+      console.log(`  const express = require('express');`);
+      console.log(`  const mdefender = require('mdefender-pro');`);
+      console.log(`  `);
+      console.log(`  const app = express();`);
+      console.log(`  app.use(express.json());`);
+      console.log(`  app.use(mdefender()); // Connects WAF with bundled block page`);
+      console.log(`\x1b[90m---------------------------------------------------\x1b[0m\n`);
+      rl.close();
+    });
+  });
+} else {
+  console.log(`Usage: npx mdefender-pro init`);
+  process.exit(0);
+}