Development Guide

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

This document provides technical guidance for developers who want to contribute to WSHawk, extend its functionality, or integrate it into their own tools. It covers the development environment setup, architectural patterns, extension points, and contribution workflow.

For installation and usage information, see Getting Started. For information about using the Python API programmatically, see Python API. For details on specific subsystems like adding vulnerability detection modules or mutation strategies, see the child pages of this section.

Purpose and Scope

This guide is intended for:

Contributors adding features, fixing bugs, or improving documentation
Plugin developers creating custom vulnerability detectors or mutation strategies
Security researchers extending WSHawk's capabilities for specialized testing
Integration developers embedding WSHawk into security pipelines or custom tools

The material covers development setup, codebase architecture, extension mechanisms, and contribution guidelines. Detailed instructions for specific tasks (adding modules, payloads, tests) are covered in sub-pages 8.1 through 8.6.

Development Workflow Overview

The typical development workflow follows this pattern:

flowchart LR
    Fork["Fork Repository<br/>GitHub"]
    Clone["Clone Locally<br/>git clone"]
    Setup["Setup Environment<br/>venv + dependencies"]
    Branch["Create Feature Branch<br/>git checkout -b"]
    Develop["Implement Changes<br/>Code + Tests"]
    Test["Run Test Suite<br/>test_modules_quick.py"]
    Commit["Commit Changes<br/>git commit"]
    Push["Push to Fork<br/>git push"]
    PR["Create Pull Request<br/>GitHub"]
    Review["Code Review<br/>Maintainer"]
    Merge["Merge to Main<br/>CI/CD publishes"]
    
    Fork --> Clone
    Clone --> Setup
    Setup --> Branch
    Branch --> Develop
    Develop --> Test
    Test --> Commit
    Commit --> Push
    Push --> PR
    PR --> Review
    Review -->|Changes needed| Develop
    Review -->|Approved| Merge

Sources: CONTRIBUTING.md:15-84

Package Structure and Entry Points

Understanding the package structure is essential for development. WSHawk uses a modular architecture with multiple CLI entry points and a programmatic API.

Package Organization Diagram

graph TB
    subgraph "Package: wshawk/"
        Init["__init__.py<br/>WSHawkV2 class<br/>WSPayloads class"]
        Main["__main__.py<br/>cli() function<br/>wshawk entry point"]
        Interactive["interactive.py<br/>cli() function<br/>wshawk-interactive"]
        Advanced["advanced_cli.py<br/>cli() function<br/>wshawk-advanced"]
        Defensive["defensive_cli.py<br/>cli() function<br/>wshawk-defensive"]
        DefModule["defensive_validation.py<br/>DefensiveValidationModule"]
        
        subgraph "Analysis Modules"
            MessageAnalyzer["MessageAnalyzer<br/>JSON/XML/Binary detection"]
            VulnVerifier["VulnerabilityVerifier<br/>Pattern matching"]
            ServerFinger["ServerFingerprinter<br/>Technology detection"]
        end
        
        subgraph "Testing Modules"
            SessionTest["SessionHijackingTester<br/>6 security tests"]
            PlaywrightXSS["Playwright integration<br/>Real browser XSS"]
            OASTClient["OAST integration<br/>interact.sh"]
        end
        
        subgraph "Mutation System"
            PayloadMutator["PayloadMutator<br/>8+ strategies"]
            BaseMutator["mutators/BaseMutator<br/>Abstract base class"]
            Encoders["mutators/<br/>Specific encoders"]
        end
        
        subgraph "Utilities"
            RateLimiter["TokenBucketRateLimiter<br/>Adaptive rate control"]
            SessionState["SessionStateMachine<br/>State tracking"]
            WAFDetector["WAFDetector<br/>12 signatures"]
            CVSSCalc["CVSSCalculator<br/>v3.1 scoring"]
        end
    end
    
    subgraph "Data Files"
        PayloadsTxt["payloads/*.txt<br/>Simple vectors"]
        PayloadsJSON["payloads/**/*.json<br/>Structured attacks"]
        MalOrigins["malicious_origins.txt<br/>216+ origins"]
    end
    
    subgraph "Configuration"
        PyProject["pyproject.toml<br/>Package metadata"]
        Setup["setup.py<br/>Build configuration"]
        Requirements["requirements.txt<br/>Dependencies"]
    end
    
    subgraph "Entry Points (CLI)"
        EP1["wshawk<br/>Quick scan"]
        EP2["wshawk-interactive<br/>Interactive mode"]
        EP3["wshawk-advanced<br/>Advanced features"]
        EP4["wshawk-defensive<br/>Blue team validation"]
    end
    
    PyProject -->|"defines"| EP1
    PyProject -->|"defines"| EP2
    PyProject -->|"defines"| EP3
    PyProject -->|"defines"| EP4
    
    EP1 --> Main
    EP2 --> Interactive
    EP3 --> Advanced
    EP4 --> Defensive
    
    Main --> Init
    Defensive --> DefModule
    
    Init --> MessageAnalyzer
    Init --> VulnVerifier
    Init --> ServerFinger
    Init --> SessionTest
    Init --> PayloadMutator
    Init --> RateLimiter
    
    PayloadMutator --> BaseMutator
    BaseMutator --> Encoders
    
    Init --> PayloadsTxt
    Init --> PayloadsJSON
    DefModule --> MalOrigins

Sources: pyproject.toml:41-45, pyproject.toml:50-51, CONTRIBUTING.md:96-113

Entry Point Configuration

The pyproject.toml file defines four CLI entry points using the [project.scripts] section:

| Entry Point | Module | Function | Purpose | |-------------|--------|----------|---------| | wshawk | wshawk.__main__ | cli() | Quick scan mode | | wshawk-interactive | wshawk.interactive | cli() | Interactive prompt mode | | wshawk-advanced | wshawk.advanced_cli | cli() | Advanced features (mutation, OAST) | | wshawk-defensive | wshawk.defensive_cli | cli() | Defensive validation mode |

Sources: pyproject.toml:41-45

Core Extension Points

WSHawk provides several extension points for customization. Understanding these is crucial for adding new functionality.

Extension Points Architecture

graph TB
    subgraph "Vulnerability Detection"
        BaseDetector["Base Pattern:<br/>Pattern matching in<br/>VulnerabilityVerifier"]
        CustomDetector["Custom Detector:<br/>New verify_* method<br/>in WSHawkV2"]
        PayloadFile["Payload File:<br/>payloads/<vuln_type>.txt"]
        
        CustomDetector -->|"uses"| PayloadFile
        CustomDetector -->|"extends"| BaseDetector
    end
    
    subgraph "Mutation Strategies"
        BaseMutatorClass["mutators/BaseMutator<br/>Abstract base class"]
        CustomMutator["Custom Mutator:<br/>Inherit from BaseMutator<br/>Implement mutate()"]
        MutatorRegistry["create_default_mutators()<br/>mutators/__init__.py"]
        
        CustomMutator -->|"inherits"| BaseMutatorClass
        CustomMutator -->|"registered in"| MutatorRegistry
    end
    
    subgraph "Payload Collections"
        PayloadLoader["WSPayloads class<br/>__init__.py"]
        NewPayloadTxt["New payload/*.txt<br/>One per line"]
        NewPayloadJSON["New payloads/**/*.json<br/>Structured format"]
        
        NewPayloadTxt -->|"loaded by"| PayloadLoader
        NewPayloadJSON -->|"loaded by"| PayloadLoader
    end
    
    subgraph "Defensive Tests"
        DefensiveModule["DefensiveValidationModule<br/>defensive_validation.py"]
        NewDefTest["New test method:<br/>test_*<br/>Returns TestResult"]
        
        NewDefTest -->|"added to"| DefensiveModule
    end
    
    subgraph "Verification Systems"
        PlaywrightInt["Playwright integration<br/>XSS verification"]
        OASTInt["OAST integration<br/>Blind vulnerabilities"]
        CustomVerifier["Custom Verifier:<br/>New verification logic"]
        
        CustomVerifier -->|"similar to"| PlaywrightInt
        CustomVerifier -->|"similar to"| OASTInt
    end
    
    Developer["Developer"] -->|"adds"| CustomDetector
    Developer -->|"creates"| CustomMutator
    Developer -->|"adds"| NewPayloadTxt
    Developer -->|"adds"| NewDefTest
    Developer -->|"implements"| CustomVerifier

Sources: CONTRIBUTING.md:92-113

Key Base Classes and Interfaces

| Component | Location | Base Class/Interface | Extension Method | |-----------|----------|---------------------|------------------| | Vulnerability Detector | wshawk/__init__.py | WSHawkV2 class | Add verify_* method | | Mutation Strategy | wshawk/mutators/ | BaseMutator | Inherit and implement mutate() | | Payload Collection | wshawk/payloads/ | N/A (file-based) | Add .txt or .json file | | Defensive Test | wshawk/defensive_validation.py | DefensiveValidationModule | Add test_* method | | Rate Limiter | wshawk/__init__.py | TokenBucketRateLimiter | Subclass for custom logic |

Sources: CONTRIBUTING.md:94-113

Development Environment Quick Start

A minimal setup for local development requires Python 3.8+ and the project dependencies.

Setup Steps

# 1. Fork and clone repository
git clone https://github.com/YOUR_USERNAME/wshawk.git
cd wshawk

# 2. Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# 3. Install dependencies
pip install -r requirements.txt

# 4. Install package in editable mode
pip install -e .

# 5. Install Playwright browsers (required for XSS verification)
playwright install chromium

# 6. Verify installation
wshawk --help
python tests/test_modules_quick.py

Sources: CONTRIBUTING.md:18-34, requirements.txt:1-18

Dependency Overview

The project has four core dependencies defined in both requirements.txt and pyproject.toml:

| Dependency | Version | Purpose | Module Usage | |------------|---------|---------|--------------| | websockets | ≥12.0 | WebSocket protocol implementation | All scanner modules | | playwright | ≥1.40.0 | Browser automation for XSS verification | verify_xss() in WSHawkV2 | | aiohttp | ≥3.9.0 | HTTP client for OAST requests | OAST integration methods | | PyYAML | ≥6.0 | Configuration file parsing | Config loading in CLI modules |

Optional dependencies:

pytest ≥7.4.0 - Test runner
pytest-asyncio ≥0.21.0 - Async test support
colorama ≥0.4.6 - Cross-platform colored terminal output

Sources: requirements.txt:4-18, pyproject.toml:29-34

Code Style and Standards

WSHawk follows Python best practices for maintainability and readability.

Coding Standards

From CONTRIBUTING.md:43-48:

PEP 8 compliance - Follow Python style guidelines
Type hints - Use type annotations where applicable
Docstrings - Document all functions and classes
Modular design - Keep functions focused and single-purpose

Commit Message Convention

From CONTRIBUTING.md:64-68:

| Prefix | Usage | Example | |--------|-------|---------| | Add: | New features | Add: XML entity injection detection | | Fix: | Bug fixes | Fix: Rate limiter overflow on rapid requests | | Update: | Improvements to existing code | Update: Enhanced WAF detection signatures | | Docs: | Documentation changes | Docs: Clarify mutation strategy usage |

Sources: CONTRIBUTING.md:41-68

Building and Testing

Before submitting changes, ensure all tests pass and the package builds correctly.

Running Tests

The test suite is located in tests/test_modules_quick.py and executes in ~0.15 seconds:

# Run all tests
python tests/test_modules_quick.py

# Expected output: 90+ tests pass

For new features:

Add tests in the tests/ directory
Ensure new code is covered by tests
Verify all existing tests still pass

Sources: CONTRIBUTING.md:52-60

Building the Package

# Build source and wheel distributions
python -m build

# Output: dist/wshawk-2.0.6.tar.gz and dist/wshawk-2.0.6-*.whl

Testing Docker Image

# Build Docker image
docker build -t wshawk:dev .

# Test CLI entry points
docker run --rm wshawk:dev wshawk --help
docker run --rm wshawk:dev wshawk-defensive --help

Sources: CONTRIBUTING.md:52-60

Pull Request Process

The contribution workflow follows GitHub's standard pull request model.

Submission Steps

From CONTRIBUTING.md:70-91:

Commit changes with descriptive messages
Push to your fork on a feature branch
Create Pull Request on GitHub
Include in PR description:
- Clear description of changes
- Reference to related issues (e.g., "Fixes #123")
- Test results if applicable
- Documentation updates

Review Criteria

Maintainers will review for:

Code quality and style compliance
Test coverage for new features
Documentation completeness
Breaking change assessment
Security implications

Sources: CONTRIBUTING.md:70-91

Security Considerations

Reporting Security Issues

Do not report security vulnerabilities in public GitHub issues.

Instead, use responsible disclosure:

Email: security@rothackers.com
Include WSHawk version, Python version, and reproduction steps

Sources: CONTRIBUTING.md:129-133

Security Testing Guidelines

When developing security testing features:

Use safe defaults - Limit rate, payload size, and test scope by default
Implement kill switches - Allow users to abort scans cleanly
Respect scope - Only test user-authorized targets
Validate inputs - Sanitize all user-provided data
Log responsibly - Avoid logging sensitive data (tokens, credentials)

Next Steps

For detailed information on specific development tasks:

Development Environment Setup - Complete environment configuration
Project Structure - Detailed directory layout and module organization
Adding Vulnerability Detection Modules - Create custom vulnerability detectors
Adding Mutation Strategies - Implement custom payload mutators
Adding Payload Collections - Expand the payload database
Testing Infrastructure - Test suite architecture and coverage

For contribution guidelines and community standards, see Contributing Guidelines and Code of Conduct.

Document Sources: pyproject.toml:1-52, CONTRIBUTING.md:1-154, requirements.txt:1-18