@modular-intelligence/waf-detect 1.0.0

package/README.md

@@ -0,0 +1,412 @@
+# WAF Detection MCP Server
+
+A Model Context Protocol (MCP) server for Web Application Firewall (WAF) fingerprinting and detection. This server provides comprehensive tools for identifying, analyzing, and testing WAF deployments using both the wafw00f CLI tool and native HTTP analysis.
+
+## Features
+
+This is a **hybrid security testing tool** that combines:
+
+- **wafw00f CLI integration** for WAF fingerprinting using known signatures
+- **Native HTTP analysis** for header inspection, response comparison, and bypass testing
+- **Comprehensive security controls** including authorization checks, rate limiting, and input validation
+- **Six specialized tools** covering different aspects of WAF detection and analysis
+
+## Prerequisites
+
+### Required
+
+- **Bun** runtime (v1.0+)
+- **wafw00f** CLI tool: `pip install wafw00f`
+
+### Verification
+
+```bash
+# Verify wafw00f installation
+wafw00f --version
+
+# Verify Bun installation
+bun --version
+```
+
+## Installation
+
+```bash
+cd waf-detect
+bun install
+```
+
+## Usage
+
+### Starting the Server
+
+```bash
+# Development mode
+bun run src/index.ts
+
+# Production mode (after building)
+bun run build
+bun run dist/index.js
+```
+
+### Configuration in Claude Desktop
+
+Add to your Claude Desktop config file:
+
+**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+
+**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "waf-detect": {
+      "command": "bun",
+      "args": ["run", "/absolute/path/to/waf-detect/src/index.ts"]
+    }
+  }
+}
+```
+
+## Available Tools
+
+### 1. waf_fingerprint
+
+Identifies the Web Application Firewall protecting a target URL using wafw00f.
+
+**Parameters:**
+- `url` (string, required): Target URL to fingerprint
+- `authorized` (boolean, required): Confirmation of authorization (must be `true`)
+- `timeout` (number, optional): Max scan duration in seconds (10-300, default: 60)
+
+**Returns:**
+```json
+{
+  "target": "https://example.com",
+  "detected": true,
+  "waf_name": "Cloudflare",
+  "manufacturer": "Cloudflare Inc.",
+  "http_status": 200
+}
+```
+
+**Example:**
+```typescript
+await use_mcp_tool({
+  server: "waf-detect",
+  tool: "waf_fingerprint",
+  arguments: {
+    url: "https://example.com",
+    authorized: true,
+    timeout: 60
+  }
+});
+```
+
+### 2. waf_bypass_check
+
+Tests WAF bypass techniques using various encoding and obfuscation methods.
+
+**Parameters:**
+- `url` (string, required): Target URL to test
+- `authorized` (boolean, required): Confirmation of authorization
+- `payloads` (array, optional): Custom test payloads (max 20, 10KB each)
+- `timeout` (number, optional): Max scan duration (10-300, default: 60)
+
+**Encoding techniques tested:**
+- Original payload
+- URL encoding
+- Double URL encoding
+- Unicode encoding
+- Mixed case
+- HTML entities
+
+**Returns:**
+```json
+{
+  "target": "https://example.com",
+  "baseline_status": 200,
+  "results": [
+    {
+      "payload_type": "url_encoded",
+      "encoded_payload": "%3Cscript%3Ealert(1)%3C%2Fscript%3E",
+      "status_code": 403,
+      "blocked": true,
+      "response_size": 1234
+    }
+  ],
+  "bypass_found": false
+}
+```
+
+### 3. waf_rule_test
+
+Tests WAF detection rules against specific attack categories.
+
+**Parameters:**
+- `url` (string, required): Target URL to test
+- `authorized` (boolean, required): Confirmation of authorization
+- `attack_type` (enum, required): Type of attack pattern - one of:
+  - `xss`: Cross-Site Scripting
+  - `sqli`: SQL Injection
+  - `rfi`: Remote File Inclusion
+  - `lfi`: Local File Inclusion
+  - `rce`: Remote Code Execution
+  - `xxe`: XML External Entity
+  - `ssrf`: Server-Side Request Forgery
+- `timeout` (number, optional): Max scan duration (10-300, default: 60)
+
+**Returns:**
+```json
+{
+  "target": "https://example.com",
+  "attack_type": "xss",
+  "results": [
+    {
+      "payload": "<script>alert('XSS')</script>",
+      "blocked": true,
+      "status_code": 403,
+      "evidence": "Status 403, x-waf-event-id: abc123"
+    }
+  ],
+  "block_rate": 0.83
+}
+```
+
+### 4. waf_response_analysis
+
+Analyzes and compares WAF responses to normal vs malicious requests.
+
+**Parameters:**
+- `url` (string, required): Target URL to analyze
+- `authorized` (boolean, required): Confirmation of authorization
+- `timeout` (number, optional): Max scan duration (10-300, default: 60)
+
+**Returns:**
+```json
+{
+  "target": "https://example.com",
+  "normal_response": {
+    "status": 200,
+    "headers": {
+      "server": "cloudflare",
+      "content-type": "text/html"
+    },
+    "size": 5432,
+    "time_ms": 123
+  },
+  "blocked_response": {
+    "status": 403,
+    "headers": {
+      "server": "cloudflare",
+      "x-waf-event-id": "abc123"
+    },
+    "size": 234,
+    "time_ms": 89
+  },
+  "differences": [
+    "Status code changed: 200 -> 403",
+    "Response size changed significantly: 5432 -> 234 bytes (96%)",
+    "New headers in blocked response: x-waf-event-id"
+  ],
+  "waf_indicators": [
+    "Cloudflare: server=cloudflare"
+  ]
+}
+```
+
+### 5. waf_all_scan
+
+Scans target against all known WAF signatures for comprehensive detection.
+
+**Parameters:**
+- `url` (string, required): Target URL to scan
+- `authorized` (boolean, required): Confirmation of authorization
+- `timeout` (number, optional): Max scan duration (30-300, default: 120)
+
+**Returns:**
+```json
+{
+  "target": "https://example.com",
+  "results": [
+    {
+      "waf_name": "Cloudflare",
+      "detected": true,
+      "manufacturer": "Cloudflare Inc."
+    },
+    {
+      "waf_name": "ModSecurity",
+      "detected": false,
+      "manufacturer": "Trustwave"
+    }
+  ],
+  "total_tested": 87
+}
+```
+
+### 6. waf_header_analysis
+
+Analyzes HTTP response headers for WAF and CDN indicators.
+
+**Parameters:**
+- `url` (string, required): Target URL to analyze
+- `authorized` (boolean, required): Confirmation of authorization
+- `timeout` (number, optional): Max scan duration (10-300, default: 60)
+
+**Detects:**
+- Cloudflare
+- Akamai
+- AWS WAF/CloudFront
+- Incapsula
+- Sucuri
+- Fastly
+- Azure WAF
+- ModSecurity
+- F5 BIG-IP
+- Barracuda
+- Imperva
+- StackPath
+- Generic WAF headers
+
+**Returns:**
+```json
+{
+  "target": "https://example.com",
+  "headers": {
+    "server": "cloudflare",
+    "cf-ray": "abc123-SJC",
+    "cf-cache-status": "HIT"
+  },
+  "waf_indicators": [
+    {
+      "header": "server",
+      "value": "cloudflare",
+      "waf_hint": "Cloudflare"
+    },
+    {
+      "header": "cf-ray",
+      "value": "abc123-SJC",
+      "waf_hint": "Cloudflare"
+    }
+  ],
+  "detected_technologies": [
+    "Cloudflare"
+  ]
+}
+```
+
+## Security Features
+
+### Authorization Required
+
+All tools require explicit authorization confirmation. You must set `authorized: true` to confirm you have permission to test the target.
+
+### Input Validation
+
+- **URL validation**: Only `http` and `https` protocols allowed
+- **Private IP blocking**: Prevents scanning of private IP ranges:
+  - 10.0.0.0/8
+  - 172.16.0.0/12
+  - 192.168.0.0/16
+  - 127.0.0.0/8
+  - localhost, ::1, fe80:
+- **Payload size limits**: Maximum 10KB per payload
+- **Payload count limits**: Maximum 20 payloads per request
+- **Timeout constraints**: 10-300 seconds
+
+### Rate Limiting
+
+Built-in rate limiter restricts requests to 10 per second to prevent abuse.
+
+### Process Controls
+
+- Maximum buffer size: 10MB
+- Command timeout enforcement
+- SIGKILL for hung processes
+- Thread count validation (max 10)
+
+## Ethical Use
+
+This tool is designed for **authorized security testing only**. Users must:
+
+1. ✅ Have explicit permission to test the target system
+2. ✅ Comply with all applicable laws and regulations
+3. ✅ Follow responsible disclosure practices
+4. ✅ Respect rate limits and avoid DoS conditions
+5. ❌ Never use against systems without authorization
+
+**Unauthorized testing may be illegal and result in criminal prosecution.**
+
+## Error Handling
+
+All tools return structured error messages:
+
+```json
+{
+  "content": [{
+    "type": "text",
+    "text": "Error: Authorization required: You must explicitly set authorized=true"
+  }],
+  "isError": true
+}
+```
+
+Common errors:
+- `wafw00f command not found`: Install wafw00f with `pip install wafw00f`
+- `Invalid protocol`: Only http/https allowed
+- `Access to private IP addresses is blocked`: Target must be publicly accessible
+- `Rate limit exceeded`: Wait before making more requests
+- `Payload size exceeds maximum`: Reduce payload size below 10KB
+
+## Development
+
+### Building
+
+```bash
+bun run build
+```
+
+### Project Structure
+
+```
+waf-detect/
+├── package.json
+├── tsconfig.json
+├── README.md
+├── src/
+│   ├── index.ts              # Main server entry point
+│   ├── schemas.ts            # Zod validation schemas
+│   ├── security.ts           # Security validation utilities
+│   ├── cli-executor.ts       # wafw00f CLI wrapper
+│   └── tools/
+│       ├── waf-fingerprint.ts
+│       ├── waf-bypass-check.ts
+│       ├── waf-rule-test.ts
+│       ├── waf-response-analysis.ts
+│       ├── waf-all-scan.ts
+│       └── waf-header-analysis.ts
+└── dist/                     # Compiled output
+```
+
+## Use Cases
+
+1. **Security Auditing**: Verify WAF deployment and configuration
+2. **Penetration Testing**: Test WAF effectiveness during authorized assessments
+3. **Red Team Operations**: Identify defensive controls during authorized engagements
+4. **Blue Team Validation**: Verify WAF rules are working as expected
+5. **Research**: Study WAF behavior and bypass techniques in authorized environments
+
+## Limitations
+
+- Requires wafw00f to be installed and in PATH
+- Only tests publicly accessible targets
+- Rate limited to prevent abuse
+- Some advanced WAF bypass techniques may require manual testing
+- Results depend on wafw00f signature database currency
+
+## License
+
+MIT
+
+## Disclaimer
+
+This tool is provided for educational and authorized security testing purposes only. The authors and contributors are not responsible for misuse or damage caused by this tool. Always ensure you have proper authorization before testing any system.