Dependency Reference

Dependency Reference

The following files were used as context for generating this wiki page:

Purpose and Scope

This document provides a comprehensive reference of all external dependencies used by WSHawk, including their version requirements, roles in the system, and specific features utilized. This reference covers both runtime dependencies required for operation and development dependencies needed for testing and contribution.

For information about installing WSHawk and its dependencies, see Installation Methods. For details on development environment setup, see Development Environment Setup.

Dependency Architecture

The following diagram illustrates how WSHawk's core dependencies relate to different functional areas of the system:

graph TB
    subgraph "WSHawk Core"
        Scanner["WSHawkV2<br/>(scanner_v2.py)"]
        Defensive["DefensiveValidationModule<br/>(defensive_validation.py)"]
        Interactive["interactive.py<br/>advanced_cli.py"]
    end
    
    subgraph "Runtime Dependencies"
        WS["websockets>=12.0<br/>WebSocket Protocol"]
        PW["playwright>=1.40.0<br/>Browser Automation"]
        AIO["aiohttp>=3.9.0<br/>HTTP Client"]
        YAML["PyYAML>=6.0<br/>Config Parser"]
    end
    
    subgraph "Development Dependencies"
        Pytest["pytest>=7.4.0<br/>Test Framework"]
        PytestAsync["pytest-asyncio>=0.21.0<br/>Async Testing"]
        Colorama["colorama>=0.4.6<br/>Terminal Colors"]
    end
    
    Scanner --> WS
    Scanner --> PW
    Scanner --> AIO
    Scanner --> YAML
    
    Defensive --> WS
    Defensive --> AIO
    Defensive --> YAML
    
    Interactive --> YAML
    
    Scanner -.testing.-> Pytest
    Scanner -.testing.-> PytestAsync
    Scanner -.optional.-> Colorama

Sources: pyproject.toml:29-34, setup.py:9-14, requirements.txt:1-19

Runtime Dependencies

websockets >= 12.0

The websockets library provides the core WebSocket protocol implementation used throughout WSHawk for establishing connections, sending messages, and receiving responses.

Purpose:

  • WebSocket client protocol implementation
  • Connection lifecycle management
  • Message framing and parsing
  • TLS/SSL support for wss:// connections

Usage in Codebase:

| Component | Purpose | Key Functions | |-----------|---------|---------------| | WSHawkV2 scanner | Primary connection handler | websockets.connect() | | DefensiveValidationModule | TLS/SSL validation | Connection with SSL context | | All CLI tools | WebSocket communication | Async context managers |

Key Features Utilized:

  • Async/await support: All WSHawk operations use async with websockets.connect() for non-blocking I/O
  • Custom headers: Used for Origin header manipulation in CSWSH tests
  • SSL context: Custom SSL contexts for certificate validation in defensive tests
  • Connection parameters: Timeout configuration, ping/pong handling
  • Exception handling: websockets.exceptions for connection errors

Version Rationale:

  • Version 12.0+ provides improved async performance
  • Better error messages for debugging
  • Enhanced SSL/TLS handling for defensive validation

Sources: pyproject.toml:30, setup.py:10, requirements.txt:4

playwright >= 1.40.0

Playwright provides real browser automation for XSS verification, eliminating false positives by executing JavaScript payloads in actual browser contexts.

Purpose:

  • XSS payload verification in real browsers
  • Screenshot capture for proof-of-concept
  • JavaScript execution environment
  • DOM manipulation detection

Usage in Codebase:

flowchart LR
    VV["VulnerabilityVerifier<br/>verify_xss()"]
    PW["playwright library"]
    Chromium["Chromium Browser<br/>Headless"]
    Page["Page Context"]
    Screenshot["Screenshot File"]
    
    VV --> PW
    PW --> Chromium
    Chromium --> Page
    Page --> Screenshot
    
    VV -.alert detection.-> Page
    VV -.DOM monitoring.-> Page

Key Features Utilized:

  • Browser contexts: Isolated environments for each XSS test
  • Page navigation: Loading WebSocket-generated HTML/JavaScript
  • Alert detection: page.on('dialog') handlers for XSS proof
  • Screenshot capture: page.screenshot() for visual evidence
  • Headless mode: Runs without GUI for CI/CD integration
  • Multiple browser engines: Chromium support (Firefox/WebKit available)

Installation Note: After installing the Python package, browsers must be installed:

playwright install chromium

Usage Pattern:

# Typical usage in VulnerabilityVerifier
async with async_playwright() as p:
    browser = await p.chromium.launch(headless=True)
    page = await browser.new_page()
    # XSS verification logic

Version Rationale:

  • Version 1.40.0+ provides stable async API
  • Improved headless browser performance
  • Better screenshot quality and reliability

Sources: pyproject.toml:31, setup.py:11, requirements.txt:8

aiohttp >= 3.9.0

The aiohttp library provides asynchronous HTTP client functionality for Out-of-Band Application Security Testing (OAST) integration with interact.sh.

Purpose:

  • HTTP requests to OAST provider (interact.sh)
  • Polling for out-of-band callbacks
  • Blind XXE/SSRF detection
  • DNS exfiltration testing in defensive validation

Usage in Codebase:

| Component | OAST Operation | HTTP Method | |-----------|----------------|-------------| | WSHawkV2.test_xxe() | Generate OAST URL, poll callbacks | GET | | WSHawkV2.test_ssrf() | OAST integration | GET | | DefensiveValidationModule.test_dns_exfiltration() | DNS callback verification | GET |

Key Features Utilized:

  • Async HTTP client: Non-blocking requests via aiohttp.ClientSession()
  • Connection pooling: Efficient multiple request handling
  • Timeout management: Configurable request timeouts
  • JSON parsing: Automatic JSON response handling
  • SSL verification: Certificate validation for HTTPS

OAST Integration Pattern:

# Typical OAST workflow
async with aiohttp.ClientSession() as session:
    # 1. Generate unique OAST URL
    async with session.get("https://interact.sh/register") as resp:
        oast_url = await resp.json()
    
    # 2. Inject payload with OAST URL
    payload = f"<!ENTITY xxe SYSTEM 'http://{oast_url}'>..."
    
    # 3. Poll for callbacks
    async with session.get(f"https://interact.sh/poll/{oast_url}") as resp:
        callbacks = await resp.json()

Version Rationale:

  • Version 3.9.0+ provides security fixes
  • Improved connection pooling
  • Better async/await integration

Sources: pyproject.toml:32, setup.py:12, requirements.txt:11

PyYAML >= 6.0

PyYAML provides YAML parsing for configuration files, authentication sequences, and custom payload definitions.

Purpose:

  • Parse YAML configuration files
  • Load authentication sequences
  • Process custom payload definitions
  • Configuration-driven scanning

Usage in Codebase:

| Component | Configuration Type | Example | |-----------|-------------------|---------| | WSHawkV2.__init__() | Authentication config | Login sequences | | WSHawkV2._load_config() | Scan parameters | Rate limits, timeouts | | CLI tools | User-provided configs | Custom test selection |

Key Features Utilized:

  • Safe loading: yaml.safe_load() for security
  • Python object mapping: Automatic dict/list conversion
  • Multi-document support: Multiple YAML documents in one file
  • UTF-8 support: International characters in configs

Configuration File Structure:

# Example authentication config
authentication:
  sequence:
    - send: '{"type": "auth", "token": "abc123"}'
      expect: '{"status": "authenticated"}'
    - send: '{"type": "subscribe", "channel": "test"}'
      
scan_options:
  rate_limit: 10
  timeout: 30
  verify_xss: true

Security Consideration: WSHawk always uses yaml.safe_load() to prevent arbitrary code execution vulnerabilities from untrusted YAML files.

Version Rationale:

  • Version 6.0+ provides security fixes for CVE-2020-14343
  • Better error messages for malformed YAML
  • Improved performance for large files

Sources: pyproject.toml:33, setup.py:13, requirements.txt:5

Development Dependencies

pytest >= 7.4.0 and pytest-asyncio >= 0.21.0

Testing framework for WSHawk's 90+ test suite covering all vulnerability detection modules.

Purpose:

  • Unit testing framework
  • Async test support
  • Test fixtures and mocking
  • Coverage reporting

Usage in Testing:

graph LR
    subgraph "Test Suite"
        TestFile["tests/test_modules_quick.py<br/>90+ tests"]
    end
    
    subgraph "Test Dependencies"
        Pytest["pytest<br/>Test Runner"]
        AsyncIO["pytest-asyncio<br/>Async Support"]
    end
    
    subgraph "Test Targets"
        Scanner["WSHawkV2"]
        Analyzer["MessageAnalyzer"]
        Verifier["VulnerabilityVerifier"]
        Mutator["PayloadMutator"]
    end
    
    TestFile --> Pytest
    TestFile --> AsyncIO
    
    Pytest --> Scanner
    Pytest --> Analyzer
    Pytest --> Verifier
    Pytest --> Mutator

Key Features Utilized:

  • Async test support: @pytest.mark.asyncio decorator for async functions
  • Fixtures: Reusable test setup and teardown
  • Parametrization: @pytest.mark.parametrize for multiple test cases
  • Mocking: Mock WebSocket connections and responses
  • Test discovery: Automatic test file detection

Test Execution:

# Run all tests
pytest tests/

# Run specific test file
pytest tests/test_modules_quick.py

# Run with coverage
pytest --cov=wshawk tests/

Test Statistics:

  • Total tests: 90+
  • Execution time: ~0.15 seconds
  • Coverage: Core modules covered

Version Rationale:

  • pytest 7.4.0+ provides better async test support
  • pytest-asyncio 0.21.0+ fixes async fixture issues

Sources: requirements.txt:14-15

colorama >= 0.4.6 (Optional)

Terminal color support for enhanced CLI output readability.

Purpose:

  • Colored terminal output
  • Cross-platform color support (Windows, Linux, macOS)
  • Enhanced log readability
  • Severity-based color coding

Usage Pattern:

  • Optional dependency: Not listed in pyproject.toml or setup.py
  • Graceful degradation: CLI works without colorama, just without colors
  • Logging integration: Color-coded severity levels

Color Mapping: | Severity | Color | Use Case | |----------|-------|----------| | CRITICAL | Red | Critical vulnerabilities found | | ERROR | Red | Connection errors, failures | | WARNING | Yellow | WAF detection, rate limiting | | INFO | White | Normal scan progress | | SUCCESS | Green | Successful connections |

Installation:

pip install colorama  # Optional for colored output

Sources: requirements.txt:18

Dependency Version Matrix

The following table shows version compatibility across Python versions:

| Dependency | Minimum Version | Python 3.8 | Python 3.9 | Python 3.10 | Python 3.11 | Python 3.12 | Python 3.13 | |------------|-----------------|------------|------------|-------------|-------------|-------------|-------------| | websockets | 12.0 | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | playwright | 1.40.0 | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | aiohttp | 3.9.0 | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | PyYAML | 6.0 | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |

Python Version Requirements:

  • Minimum: Python 3.8
  • Recommended: Python 3.11+ for best performance
  • Maximum tested: Python 3.13

Sources: pyproject.toml:13, 21-26, setup.py:39

Installation Verification

Verifying Runtime Dependencies

After installing WSHawk, verify all dependencies are correctly installed:

# Check Python version
python --version  # Should be >= 3.8

# Check installed packages
pip show websockets playwright aiohttp pyyaml

# Verify WSHawk imports
python -c "import wshawk; print(wshawk.__version__)"

# Verify Playwright browsers
playwright install --help

Dependency Size and Installation Time

| Dependency | Approximate Size | Installation Time | |------------|-----------------|-------------------| | websockets | ~200 KB | < 5 seconds | | playwright | ~300 MB (with browser) | 30-60 seconds | | aiohttp | ~1 MB | < 10 seconds | | PyYAML | ~200 KB | < 5 seconds |

Note: Playwright requires separate browser installation via playwright install chromium, which downloads the Chromium browser binary (~150 MB).

Sources: pyproject.toml:29-34

Dependency Update Policy

WSHawk follows these principles for dependency management:

  1. Minimum versions specified: Uses >= to allow newer versions
  2. Major version pinning: Prevents breaking changes (e.g., websockets>=12.0)
  3. Security updates: Dependencies updated for CVEs
  4. Compatibility testing: All versions tested in CI/CD

Checking for Updates

# Check outdated packages
pip list --outdated

# Update all dependencies
pip install --upgrade websockets playwright aiohttp pyyaml

Known Compatibility Issues

| Dependency | Issue | Workaround | |------------|-------|------------| | playwright < 1.40.0 | Async API instability | Upgrade to 1.40.0+ | | PyYAML < 6.0 | Security vulnerability CVE-2020-14343 | Upgrade to 6.0+ | | aiohttp < 3.9.0 | SSL verification issues | Upgrade to 3.9.0+ |

Sources: pyproject.toml:29-34, requirements.txt:1-19

Dependency Graph

The following diagram shows the complete dependency hierarchy including transitive dependencies:

graph TB
    WSHawk["wshawk package"]
    
    subgraph "Direct Dependencies"
        WS["websockets>=12.0"]
        PW["playwright>=1.40.0"]
        AIO["aiohttp>=3.9.0"]
        YAML["PyYAML>=6.0"]
    end
    
    subgraph "Transitive Dependencies"
        WSTransitive["websockets transitive:<br/>No additional deps"]
        
        PWTransitive["playwright transitive:<br/>- greenlet<br/>- pyee"]
        
        AIOTransitive["aiohttp transitive:<br/>- aiosignal<br/>- attrs<br/>- frozenlist<br/>- multidict<br/>- yarl<br/>- async-timeout"]
        
        YAMLTransitive["PyYAML transitive:<br/>No additional deps"]
    end
    
    WSHawk --> WS
    WSHawk --> PW
    WSHawk --> AIO
    WSHawk --> YAML
    
    WS --> WSTransitive
    PW --> PWTransitive
    AIO --> AIOTransitive
    YAML --> YAMLTransitive

Sources: pyproject.toml:29-34, setup.py:9-14

Docker Image Dependencies

When using WSHawk via Docker, additional system-level dependencies are included:

Base Image Dependencies

FROM python:3.11-slim
# Includes: Python 3.11, pip, system libraries

System Packages

| Package | Purpose | Required For | |---------|---------|--------------| | libnss3 | Network Security Services | Playwright Chromium | | libatk-bridge2.0-0 | Accessibility | Playwright Chromium | | libcups2 | Printing support | Playwright Chromium | | libxcomposite1 | X11 compositing | Playwright Chromium | | ca-certificates | SSL/TLS certificates | HTTPS connections |

These dependencies are automatically included in the Docker image and do not require manual installation.

Sources: Based on common Dockerfile patterns for Playwright (actual Dockerfile not provided in files)

Troubleshooting Dependency Issues

Common Issues and Solutions

Issue: Playwright browser not found

# Solution: Install Chromium browser
playwright install chromium

Issue: SSL certificate verification fails

# Solution: Update ca-certificates
pip install --upgrade certifi

Issue: Import error for websockets

# Solution: Reinstall websockets
pip uninstall websockets
pip install websockets>=12.0

Issue: PyYAML C extension build fails

# Solution: Install without C extension
pip install --no-build-isolation pyyaml

Dependency Conflict Resolution

If dependency conflicts occur during installation:

  1. Create fresh virtual environment:
python -m venv venv
source venv/bin/activate  # Linux/macOS
venv\Scripts\activate     # Windows
  1. Install with pip resolver:
pip install --upgrade pip
pip install wshawk
  1. Check for conflicts:
pip check

Sources: requirements.txt:1-19

Summary

WSHawk relies on four core runtime dependencies that provide distinct capabilities:

| Dependency | Role | Critical Features | |------------|------|-------------------| | websockets | WebSocket protocol | Connection management, TLS/SSL support | | playwright | Browser automation | XSS verification, screenshot capture | | aiohttp | HTTP client | OAST integration, out-of-band testing | | PyYAML | Configuration | YAML parsing, auth sequences |

All dependencies use minimum version constraints (>=) to allow updates while ensuring compatibility. The system requires Python 3.8+ and has been tested across Python 3.8-3.13.

Sources: pyproject.toml:13, 29-34, setup.py:9-14, 39, requirements.txt:1-19