npm package: @modular-intelligence/waf-detect
Description: MCP server for WAF fingerprinting and detection using wafw00f and native HTTP analysis
Latest version: 1.0.2

# 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.