Configuration and Authentication
Configuration and Authentication
Relevant source files
This page documents all configuration and authentication mechanisms in WSHawk. This includes authentication sequence configuration for stateful WebSocket testing, custom header injection, session-based authentication for specialized tests, and environment-based configuration options.
For information about using the Python API programmatically, see Python API Usage. For CI/CD-specific configuration examples, see CI/CD Integration.
Overview
WSHawk supports multiple configuration and authentication mechanisms to accommodate diverse WebSocket implementations:
| Configuration Type | Use Case | Primary Interface |
| --- | --- | --- |
| Authentication Sequences | Stateful WebSocket sessions requiring login flows | YAML files loaded via auth_sequence parameter |
| Custom Headers | Bearer tokens, API keys, session cookies | headers dictionary parameter |
| Session Test Auth | Session hijacking test customization | auth_config dictionary in SessionHijackingTester |
| Environment Variables | Runtime behavior customization | PYTHONUNBUFFERED, TIMEOUT, etc. |
| Docker Configuration | Containerized deployment settings | Volume mounts, environment variables, network modes |
Authentication Sequences (YAML)
Purpose and Loading Mechanism
Authentication sequences enable WSHawk to test WebSocket applications that require multi-step login flows before vulnerability testing can begin. The SessionStateMachine class manages these sequences.
Configuration Flow:
Sources: wshawk/scanner_v2.py L33-L63
YAML File Format
Authentication sequences are defined in YAML format with the following structure:
Each step in the sequence supports:
- action: Descriptive name for the step (used in state tracking)
- message: The WebSocket message payload (JSON object)
- wait_for_response: Boolean flag indicating whether to wait for server response
- timeout: Optional timeout in seconds for response waiting
Loading Authentication Sequences
Python API:
CLI Usage:
Currently, authentication sequences must be configured programmatically via the Python API. CLI support for external YAML files is planned for future releases.
Sources: wshawk/scanner_v2.py L60-L62
Custom Headers Configuration
HTTP Header Injection
Custom headers are passed to the WebSocket connection during the initial HTTP handshake. This is essential for authentication mechanisms that use bearer tokens, API keys, or session cookies.
Header Configuration Flow:
Sources: wshawk/scanner_v2.py L33-L85
Common Header Patterns
| Authentication Type | Header Format | Example |
| --- | --- | --- |
| Bearer Token | Authorization: Bearer <token> | {"Authorization": "Bearer eyJhbG..."} |
| API Key | X-API-Key: <key> | {"X-API-Key": "sk_live_12345"} |
| Session Cookie | Cookie: session=<value> | {"Cookie": "session=abc123; Path=/"} |
| Custom Auth | Custom header name | {"X-Custom-Auth": "value"} |
Configuration Examples
Python API with Bearer Token:
Multiple Headers:
Sources: wshawk/scanner_v2.py L33-L37
Session Hijacking Test Authentication
SessionHijackingTester Authentication Configuration
The SessionHijackingTester class requires its own authentication configuration to test session security vulnerabilities. This configuration is separate from the main scanner's authentication.
Authentication Configuration Structure:
Sources: wshawk/session_hijacking_tester.py L61-L114
Default Authentication Configuration
The default configuration assumes a simple login-based authentication:
This generates the following WebSocket message:
Sources: wshawk/session_hijacking_tester.py L84-L90
Custom Authentication Configuration
Example 1: Custom Field Names
This generates:
Example 2: Custom Payload Structure
For non-standard authentication flows:
This sends the custom payload directly without field transformation.
Sources: wshawk/session_hijacking_tester.py L92-L114
Authentication Payload Generation
The _get_auth_payload() method handles two configuration modes:
Sources: wshawk/session_hijacking_tester.py L92-L114
Environment Variables
Supported Environment Variables
WSHawk respects standard Python and container environment variables:
| Variable | Purpose | Default | Example |
| --- | --- | --- | --- |
| PYTHONUNBUFFERED | Disable Python output buffering (useful for real-time logs) | 0 | PYTHONUNBUFFERED=1 |
| TIMEOUT | Custom timeout for WebSocket operations | 3.0 | TIMEOUT=30 |
Usage in Docker
Environment variables can be set in multiple ways when using Docker:
Command Line:
Docker Compose:
Sources: docker-compose.yml L17-L18
Docker-Specific Configuration
Volume Mounting for Configuration Files
To use YAML authentication sequences or save configuration files in Docker:
Directory Structure:
./config/
├── auth_sequence.yaml
└── custom_payloads.txt
./reports/
└── wshawk_report_*.html
Sources: docs/DOCKER.md L56-L63
Network Configuration
Host Network Mode (for local testing):
Custom Network:
Docker Compose Network Configuration:
Sources: docs/DOCKER.md L66-L70
User and Permission Configuration
The Docker image runs as non-root user wshawk:1000 by default. To avoid permission issues with volume mounts:
Sources: docs/DOCKER.md L169-L174
Configuration Precedence and Override
Configuration Loading Order
Example: Header Configuration Override
Sources: wshawk/scanner_v2.py L33-L85
Complete Configuration Example
Full Python API Configuration
Session Hijacking Test Configuration
Sources: wshawk/scanner_v2.py L28-L76
wshawk/session_hijacking_tester.py L48-L91
Configuration Best Practices
Security Considerations
| Practice | Rationale | Implementation |
| --- | --- | --- |
| Never hardcode credentials | Prevents credential leakage in version control | Use environment variables or external config files |
| Use environment-specific configs | Different credentials for dev/staging/prod | Separate YAML files per environment |
| Rotate authentication tokens | Limits exposure window | Update headers/configs before each scan |
| Restrict file permissions | Prevents unauthorized config access | chmod 600 auth_sequence.yaml |
Configuration File Management
Example .gitignore:
config/
reports/
*.yaml
Sources: Project best practices, standard security guidelines
Troubleshooting
Common Configuration Issues
| Issue | Symptom | Solution |
| --- | --- | --- |
| Authentication sequence not loading | TypeError: load_sequence_from_yaml() | Ensure YAML file path is absolute or relative to execution directory |
| Headers not applied | Authentication fails despite correct credentials | Verify headers are passed to WSHawkV2.__init__(), not connect() |
| Docker volume permissions | Cannot write reports | Use --user $(id -u):$(id -g) or adjust host directory permissions |
| Session test auth fails | Tests skip or error | Verify auth_config structure matches server expectations |
Debug Configuration Loading
To verify configuration is loaded correctly, enable verbose logging:
Sources: wshawk/logger.py L37-L70
Configuration Reference Tables
WSHawkV2 Constructor Parameters
| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| url | str | Required | WebSocket URL (ws:// or wss://) |
| headers | Optional[Dict] | None | Custom HTTP headers for handshake |
| auth_sequence | Optional[str] | None | Path to YAML authentication sequence file |
| max_rps | int | 10 | Maximum requests per second (rate limiting) |
Sources: wshawk/scanner_v2.py L33-L35
SessionHijackingTester Auth Config Fields
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| action | str | No | Action type for auth message |
| username_field | str | No | Field name for username (default: "username") |
| password_field | str | No | Field name for password (default: "password") |
| username | str | No | Username value (default: "user1") |
| password | str | No | Password value (default: "pass1") |
| custom_payload | Dict | No | Complete custom authentication payload |
Sources: wshawk/session_hijacking_tester.py L84-L114
Sources: wshawk/scanner_v2.py L1-L681