{"owner":"EnableSecurity","repo":"wafw00f","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["CLAUDE.md"],"skills":{"CLAUDE.md":"# CLAUDE.md\n\nThis file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.\n\n## Project Overview\n\nWAFW00F is a Web Application Firewall (WAF) fingerprinting and detection tool written in Python. It identifies WAF products protecting web applications through HTTP response analysis and behavioral testing.\n\n## Development Commands\n\n### Testing\n```bash\n# Run all tests\npytest\n\n# Run tests with verbose output\npytest -v\n\n# Run specific test file\npytest tests/test_evillib.py\n\n# Run specific test\npytest tests/test_evillib.py::TestWafToolsEngine::test_default_timeout\n\n# Run tests with coverage\npytest --cov=wafw00f --cov-report=term-missing\n```\n\n### Linting\n```bash\n# Run linter (prospector)\nprospector wafw00f --strictness veryhigh\n```\n\n### Building and Installing\n```bash\n# Install in development mode with dev dependencies\npip install -e .[dev,docs]\n\n# Build distribution packages\npython setup.py sdist bdist_wheel\n\n# Clean build artifacts\nmake clean\n```\n\n### Publishing New Release\n```bash\n# 1. Update version in wafw00f/__init__.py\n# 2. Update version in README.md (badge and ASCII art examples - 3 places)\n# 3. Run tests\npytest\n\n# 4. Build package\npython setup.py sdist bdist_wheel\n\n# 5. Upload to PyPI\ntwine upload dist/*\n\n# 6. Create GitHub release\ngh release create vX.Y.Z --title \"vX.Y.Z\" --notes \"Release notes here\"\n\n# 7. Commit version changes\ngit add wafw00f/__init__.py README.md\ngit commit -m \"Bump version to X.Y.Z\"\ngit push\n```\n\n## Architecture\n\n### Core Components\n\n**main.py** - Entry point and orchestration\n- `WAFW00F` class extends `waftoolsengine` and orchestrates the detection workflow\n- Contains attack payload definitions (XSS, SQLi, LFI, XXE, RCE)\n- Implements detection methods: `matchHeader()`, `matchStatus()`, `matchCookie()`, `matchContent()`, `matchReason()`\n- Provides attack request generators: `normalRequest()`, `xssAttack()`, `sqliAttack()`, `centralAttack()`, etc.\n- Two detection modes:\n  - `identwaf()`: Plugin-based detection using WAF-specific signatures\n  - `genericdetect()`: Behavioral detection when no plugin matches\n\n**manager.py** - Plugin loader\n- Dynamically discovers and loads all Python files from `wafw00f/plugins/`\n- Uses `importlib.util` for runtime module loading\n- Returns dictionary: `{plugin_name: plugin_module}`\n\n**wafprio.py** - Detection priority\n- Ordered list of 182 WAF names defining which plugins to check first\n- Optimization: fast header/cookie checks before complex logic\n- Plugins not in the list are still checked but after prioritized ones\n\n**evillib.py** - HTTP request engine\n- `waftoolsengine` class wraps the `requests` library\n- Enforces 100KB max response size to prevent hanging on streaming responses\n- Enforces timeout during response body reading (not just connection)\n- Default timeout: 7 seconds (configurable)\n- Disables SSL warnings for testing self-signed certificates\n- Streams responses in 8KB chunks\n\n### Detection Flow\n\n1. **Normal request**: Baseline HTTP request to establish normal behavior\n2. **Attack request**: `centralAttack()` sends combined XSS+SQLi+LFI payload\n3. **Plugin detection**: Iterate through prioritized plugins, each calling `is_waf(self)`\n4. **Generic detection**: If no plugin matches, analyze behavioral differences (status codes, headers, blocking)\n\n### Plugin System\n\nPlugins are minimal Python modules in `wafw00f/plugins/` with exactly 2 requirements:\n\n```python\nNAME = 'WAF Name (Manufacturer)'\n\ndef is_waf(self):\n    # 'self' is the WAFW00F instance\n    # Access: self.rq (normal response), self.attackres (attack response)\n    # Available methods: matchHeader, matchCookie, matchContent, matchStatus, matchReason\n    if self.matchHeader(('server', 'cloudflare')):\n        return True\n    return False\n```\n\n**Common detection patterns:**\n\n1. **Simple single-check** (e.g., `cloudflare.py`):\n   - Check for specific header, cookie, or content pattern\n\n2. **Multiple checks** (e.g., `incapsula.py`):\n   - Try several different signatures (OR logic)\n\n3. **Schema-based** (e.g., `modsecurity.py`):\n   - Multiple helper functions checking combinations of conditions (AND logic)\n   - Example: `check_schema_02()` requires both 403 status AND \"ModSecurity Action\" reason\n\n**Detection methods available to plugins:**\n- `matchHeader((name, pattern), attack=False)` - Regex match on header\n- `matchCookie(pattern, attack=False)` - Shortcut for Set-Cookie header\n- `matchContent(regex, attack=True)` - Regex match on response body\n- `matchStatus(code, attack=True)` - Match HTTP status code\n- `matchReason(phrase, attack=True)` - Match HTTP reason phrase\n\n## Adding New WAF Detection\n\n1. Create `wafw00f/plugins/newwaf.py`\n2. Define `NAME` constant with \"WAF Name (Manufacturer)\" format\n3. Define `is_waf(self)` function returning True/False\n4. Optionally add WAF name to `wafprio.py` for priority detection\n5. Add test to `tests/test_detection.py`:\n   ```python\n   @responses.activate\n   def test_detect_newwaf_by_header(self):\n       responses.add(responses.GET, 'https://example.com',\n                     headers={'Server': 'NewWAF'}, status=200)\n       engine = WAFW00F('https://example.com')\n       assert 'NewWAF' in engine.identwaf()\n   ```\n\n## Important Notes for Development\n\n### Timeout Handling (Issue #246)\nThe timeout parameter must be enforced during both:\n1. Connection establishment (handled by requests library)\n2. Response body reading (enforced manually in `evillib.py`)\n\nWhen modifying request logic, ensure timeouts are respected during streaming to prevent hangs on slow servers.\n\n### Response Size Limiting\nAlways use `stream=True` with requests and enforce `MAX_RESPONSE_SIZE` (100KB) to prevent memory issues and hanging on:\n- Streaming media servers (audio/video)\n- Infinite response generators\n- Large file downloads\n\n### Version Updates\nWhen bumping version, update **3 locations**:\n1. `wafw00f/__init__.py` - `__version__` variable\n2. `README.md` - Badge (line 18)\n3. `README.md` - ASCII art examples (lines 53 and 253)\n\n### Commit Messages\nFollow conventional format:\n- \"Fix X\" for bug fixes\n- \"Add X\" for new features\n- \"Update X\" for enhancements\n- Include issue references: \"Fix timeout enforcement (issue #246)\"\n\n### Testing WAF Plugins\nWhen testing plugin detection:\n- Use `@responses.activate` decorator\n- Mock HTTP responses with specific headers/content/status\n- Test both positive (WAF detected) and negative (not detected) cases\n- Check against actual attack responses when possible\n\n### Git Workflow\n- Main branch: `master`\n- Always run tests before committing\n- Push releases to both GitHub and PyPI\n- Create GitHub releases using `gh release create`\n"},"files":{"CLAUDE.md":"# CLAUDE.md\n\nThis file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.\n\n## Project Overview\n\nWAFW00F is a Web Application Firewall (WAF) fingerprinting and detection tool written in Python. It identifies WAF products protecting web applications through HTTP response analysis and behavioral testing.\n\n## Development Commands\n\n### Testing\n```bash\n# Run all tests\npytest\n\n# Run tests with verbose output\npytest -v\n\n# Run specific test file\npytest tests/test_evillib.py\n\n# Run specific test\npytest tests/test_evillib.py::TestWafToolsEngine::test_default_timeout\n\n# Run tests with coverage\npytest --cov=wafw00f --cov-report=term-missing\n```\n\n### Linting\n```bash\n# Run linter (prospector)\nprospector wafw00f --strictness veryhigh\n```\n\n### Building and Installing\n```bash\n# Install in development mode with dev dependencies\npip install -e .[dev,docs]\n\n# Build distribution packages\npython setup.py sdist bdist_wheel\n\n# Clean build artifacts\nmake clean\n```\n\n### Publishing New Release\n```bash\n# 1. Update version in wafw00f/__init__.py\n# 2. Update version in README.md (badge and ASCII art examples - 3 places)\n# 3. Run tests\npytest\n\n# 4. Build package\npython setup.py sdist bdist_wheel\n\n# 5. Upload to PyPI\ntwine upload dist/*\n\n# 6. Create GitHub release\ngh release create vX.Y.Z --title \"vX.Y.Z\" --notes \"Release notes here\"\n\n# 7. Commit version changes\ngit add wafw00f/__init__.py README.md\ngit commit -m \"Bump version to X.Y.Z\"\ngit push\n```\n\n## Architecture\n\n### Core Components\n\n**main.py** - Entry point and orchestration\n- `WAFW00F` class extends `waftoolsengine` and orchestrates the detection workflow\n- Contains attack payload definitions (XSS, SQLi, LFI, XXE, RCE)\n- Implements detection methods: `matchHeader()`, `matchStatus()`, `matchCookie()`, `matchContent()`, `matchReason()`\n- Provides attack request generators: `normalRequest()`, `xssAttack()`, `sqliAttack()`, `centralAttack()`, etc.\n- Two detection modes:\n  - `identwaf()`: Plugin-based detection using WAF-specific signatures\n  - `genericdetect()`: Behavioral detection when no plugin matches\n\n**manager.py** - Plugin loader\n- Dynamically discovers and loads all Python files from `wafw00f/plugins/`\n- Uses `importlib.util` for runtime module loading\n- Returns dictionary: `{plugin_name: plugin_module}`\n\n**wafprio.py** - Detection priority\n- Ordered list of 182 WAF names defining which plugins to check first\n- Optimization: fast header/cookie checks before complex logic\n- Plugins not in the list are still checked but after prioritized ones\n\n**evillib.py** - HTTP request engine\n- `waftoolsengine` class wraps the `requests` library\n- Enforces 100KB max response size to prevent hanging on streaming responses\n- Enforces timeout during response body reading (not just connection)\n- Default timeout: 7 seconds (configurable)\n- Disables SSL warnings for testing self-signed certificates\n- Streams responses in 8KB chunks\n\n### Detection Flow\n\n1. **Normal request**: Baseline HTTP request to establish normal behavior\n2. **Attack request**: `centralAttack()` sends combined XSS+SQLi+LFI payload\n3. **Plugin detection**: Iterate through prioritized plugins, each calling `is_waf(self)`\n4. **Generic detection**: If no plugin matches, analyze behavioral differences (status codes, headers, blocking)\n\n### Plugin System\n\nPlugins are minimal Python modules in `wafw00f/plugins/` with exactly 2 requirements:\n\n```python\nNAME = 'WAF Name (Manufacturer)'\n\ndef is_waf(self):\n    # 'self' is the WAFW00F instance\n    # Access: self.rq (normal response), self.attackres (attack response)\n    # Available methods: matchHeader, matchCookie, matchContent, matchStatus, matchReason\n    if self.matchHeader(('server', 'cloudflare')):\n        return True\n    return False\n```\n\n**Common detection patterns:**\n\n1. **Simple single-check** (e.g., `cloudflare.py`):\n   - Check for specific header, cookie, or content pattern\n\n2. **Multiple checks** (e.g., `incapsula.py`):\n   - Try several different signatures (OR logic)\n\n3. **Schema-based** (e.g., `modsecurity.py`):\n   - Multiple helper functions checking combinations of conditions (AND logic)\n   - Example: `check_schema_02()` requires both 403 status AND \"ModSecurity Action\" reason\n\n**Detection methods available to plugins:**\n- `matchHeader((name, pattern), attack=False)` - Regex match on header\n- `matchCookie(pattern, attack=False)` - Shortcut for Set-Cookie header\n- `matchContent(regex, attack=True)` - Regex match on response body\n- `matchStatus(code, attack=True)` - Match HTTP status code\n- `matchReason(phrase, attack=True)` - Match HTTP reason phrase\n\n## Adding New WAF Detection\n\n1. Create `wafw00f/plugins/newwaf.py`\n2. Define `NAME` constant with \"WAF Name (Manufacturer)\" format\n3. Define `is_waf(self)` function returning True/False\n4. Optionally add WAF name to `wafprio.py` for priority detection\n5. Add test to `tests/test_detection.py`:\n   ```python\n   @responses.activate\n   def test_detect_newwaf_by_header(self):\n       responses.add(responses.GET, 'https://example.com',\n                     headers={'Server': 'NewWAF'}, status=200)\n       engine = WAFW00F('https://example.com')\n       assert 'NewWAF' in engine.identwaf()\n   ```\n\n## Important Notes for Development\n\n### Timeout Handling (Issue #246)\nThe timeout parameter must be enforced during both:\n1. Connection establishment (handled by requests library)\n2. Response body reading (enforced manually in `evillib.py`)\n\nWhen modifying request logic, ensure timeouts are respected during streaming to prevent hangs on slow servers.\n\n### Response Size Limiting\nAlways use `stream=True` with requests and enforce `MAX_RESPONSE_SIZE` (100KB) to prevent memory issues and hanging on:\n- Streaming media servers (audio/video)\n- Infinite response generators\n- Large file downloads\n\n### Version Updates\nWhen bumping version, update **3 locations**:\n1. `wafw00f/__init__.py` - `__version__` variable\n2. `README.md` - Badge (line 18)\n3. `README.md` - ASCII art examples (lines 53 and 253)\n\n### Commit Messages\nFollow conventional format:\n- \"Fix X\" for bug fixes\n- \"Add X\" for new features\n- \"Update X\" for enhancements\n- Include issue references: \"Fix timeout enforcement (issue #246)\"\n\n### Testing WAF Plugins\nWhen testing plugin detection:\n- Use `@responses.activate` decorator\n- Mock HTTP responses with specific headers/content/status\n- Test both positive (WAF detected) and negative (not detected) cases\n- Check against actual attack responses when possible\n\n### Git Workflow\n- Main branch: `master`\n- Always run tests before committing\n- Push releases to both GitHub and PyPI\n- Create GitHub releases using `gh release create`\n"},"items":[{"name":"CLAUDE.md","path":"CLAUDE.md","title":"CLAUDE.md","content":"# CLAUDE.md\n\nThis file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.\n\n## Project Overview\n\nWAFW00F is a Web Application Firewall (WAF) fingerprinting and detection tool written in Python. It identifies WAF products protecting web applications through HTTP response analysis and behavioral testing.\n\n## Development Commands\n\n### Testing\n```bash\n# Run all tests\npytest\n\n# Run tests with verbose output\npytest -v\n\n# Run specific test file\npytest tests/test_evillib.py\n\n# Run specific test\npytest tests/test_evillib.py::TestWafToolsEngine::test_default_timeout\n\n# Run tests with coverage\npytest --cov=wafw00f --cov-report=term-missing\n```\n\n### Linting\n```bash\n# Run linter (prospector)\nprospector wafw00f --strictness veryhigh\n```\n\n### Building and Installing\n```bash\n# Install in development mode with dev dependencies\npip install -e .[dev,docs]\n\n# Build distribution packages\npython setup.py sdist bdist_wheel\n\n# Clean build artifacts\nmake clean\n```\n\n### Publishing New Release\n```bash\n# 1. Update version in wafw00f/__init__.py\n# 2. Update version in README.md (badge and ASCII art examples - 3 places)\n# 3. Run tests\npytest\n\n# 4. Build package\npython setup.py sdist bdist_wheel\n\n# 5. Upload to PyPI\ntwine upload dist/*\n\n# 6. Create GitHub release\ngh release create vX.Y.Z --title \"vX.Y.Z\" --notes \"Release notes here\"\n\n# 7. Commit version changes\ngit add wafw00f/__init__.py README.md\ngit commit -m \"Bump version to X.Y.Z\"\ngit push\n```\n\n## Architecture\n\n### Core Components\n\n**main.py** - Entry point and orchestration\n- `WAFW00F` class extends `waftoolsengine` and orchestrates the detection workflow\n- Contains attack payload definitions (XSS, SQLi, LFI, XXE, RCE)\n- Implements detection methods: `matchHeader()`, `matchStatus()`, `matchCookie()`, `matchContent()`, `matchReason()`\n- Provides attack request generators: `normalRequest()`, `xssAttack()`, `sqliAttack()`, `centralAttack()`, etc.\n- Two detection modes:\n  - `identwaf()`: Plugin-based detection using WAF-specific signatures\n  - `genericdetect()`: Behavioral detection when no plugin matches\n\n**manager.py** - Plugin loader\n- Dynamically discovers and loads all Python files from `wafw00f/plugins/`\n- Uses `importlib.util` for runtime module loading\n- Returns dictionary: `{plugin_name: plugin_module}`\n\n**wafprio.py** - Detection priority\n- Ordered list of 182 WAF names defining which plugins to check first\n- Optimization: fast header/cookie checks before complex logic\n- Plugins not in the list are still checked but after prioritized ones\n\n**evillib.py** - HTTP request engine\n- `waftoolsengine` class wraps the `requests` library\n- Enforces 100KB max response size to prevent hanging on streaming responses\n- Enforces timeout during response body reading (not just connection)\n- Default timeout: 7 seconds (configurable)\n- Disables SSL warnings for testing self-signed certificates\n- Streams responses in 8KB chunks\n\n### Detection Flow\n\n1. **Normal request**: Baseline HTTP request to establish normal behavior\n2. **Attack request**: `centralAttack()` sends combined XSS+SQLi+LFI payload\n3. **Plugin detection**: Iterate through prioritized plugins, each calling `is_waf(self)`\n4. **Generic detection**: If no plugin matches, analyze behavioral differences (status codes, headers, blocking)\n\n### Plugin System\n\nPlugins are minimal Python modules in `wafw00f/plugins/` with exactly 2 requirements:\n\n```python\nNAME = 'WAF Name (Manufacturer)'\n\ndef is_waf(self):\n    # 'self' is the WAFW00F instance\n    # Access: self.rq (normal response), self.attackres (attack response)\n    # Available methods: matchHeader, matchCookie, matchContent, matchStatus, matchReason\n    if self.matchHeader(('server', 'cloudflare')):\n        return True\n    return False\n```\n\n**Common detection patterns:**\n\n1. **Simple single-check** (e.g., `cloudflare.py`):\n   - Check for specific header, cookie, or content pattern\n\n2. **Multiple checks** (e.g., `incapsula.py`):\n   - Try several different signatures (OR logic)\n\n3. **Schema-based** (e.g., `modsecurity.py`):\n   - Multiple helper functions checking combinations of conditions (AND logic)\n   - Example: `check_schema_02()` requires both 403 status AND \"ModSecurity Action\" reason\n\n**Detection methods available to plugins:**\n- `matchHeader((name, pattern), attack=False)` - Regex match on header\n- `matchCookie(pattern, attack=False)` - Shortcut for Set-Cookie header\n- `matchContent(regex, attack=True)` - Regex match on response body\n- `matchStatus(code, attack=True)` - Match HTTP status code\n- `matchReason(phrase, attack=True)` - Match HTTP reason phrase\n\n## Adding New WAF Detection\n\n1. Create `wafw00f/plugins/newwaf.py`\n2. Define `NAME` constant with \"WAF Name (Manufacturer)\" format\n3. Define `is_waf(self)` function returning True/False\n4. Optionally add WAF name to `wafprio.py` for priority detection\n5. Add test to `tests/test_detection.py`:\n   ```python\n   @responses.activate\n   def test_detect_newwaf_by_header(self):\n       responses.add(responses.GET, 'https://example.com',\n                     headers={'Server': 'NewWAF'}, status=200)\n       engine = WAFW00F('https://example.com')\n       assert 'NewWAF' in engine.identwaf()\n   ```\n\n## Important Notes for Development\n\n### Timeout Handling (Issue #246)\nThe timeout parameter must be enforced during both:\n1. Connection establishment (handled by requests library)\n2. Response body reading (enforced manually in `evillib.py`)\n\nWhen modifying request logic, ensure timeouts are respected during streaming to prevent hangs on slow servers.\n\n### Response Size Limiting\nAlways use `stream=True` with requests and enforce `MAX_RESPONSE_SIZE` (100KB) to prevent memory issues and hanging on:\n- Streaming media servers (audio/video)\n- Infinite response generators\n- Large file downloads\n\n### Version Updates\nWhen bumping version, update **3 locations**:\n1. `wafw00f/__init__.py` - `__version__` variable\n2. `README.md` - Badge (line 18)\n3. `README.md` - ASCII art examples (lines 53 and 253)\n\n### Commit Messages\nFollow conventional format:\n- \"Fix X\" for bug fixes\n- \"Add X\" for new features\n- \"Update X\" for enhancements\n- Include issue references: \"Fix timeout enforcement (issue #246)\"\n\n### Testing WAF Plugins\nWhen testing plugin detection:\n- Use `@responses.activate` decorator\n- Mock HTTP responses with specific headers/content/status\n- Test both positive (WAF detected) and negative (not detected) cases\n- Check against actual attack responses when possible\n\n### Git Workflow\n- Main branch: `master`\n- Always run tests before committing\n- Push releases to both GitHub and PyPI\n- Create GitHub releases using `gh release create`\n","category":"root","tokens":1662}]}