Development Environment Setup

Development Environment Setup

Relevant source files

Purpose and Scope

This guide provides step-by-step instructions for setting up a local development environment for WSHawk. It covers prerequisites, repository cloning, dependency installation, and verification procedures necessary to begin contributing code.

For information about the project's architecture and module organization, see Project Structure and Architecture. For guidance on implementing specific extensions (vulnerability modules, mutators, payloads), see Adding Extensions.

Prerequisites

System Requirements

WSHawk requires the following base system components:

| Component | Requirement | Notes | | --- | --- | --- | | Python | >=3.8 | Supports versions 3.8, 3.9, 3.10, 3.11, 3.12, 3.13 | | Git | Any recent version | For repository cloning and version control | | Operating System | Linux, macOS, Windows | Playwright supports all major platforms | | Disk Space | ~500MB | Includes Playwright browser binaries | | Internet Access | Required | For dependency downloads and OAST testing |

The Python version range is defined in setup.py L39

which specifies python_requires=">=3.8". The classifiers in setup.py L32-L36

enumerate all officially supported Python versions.

Required Knowledge

Contributors should be familiar with:

  • Python async/await programming patterns
  • WebSocket protocol basics
  • Git workflow (fork, branch, pull request)
  • Command-line operations

Sources: setup.py L32-L39

CONTRIBUTING.md L15-L40

Development Environment Setup Workflow

Development Environment Setup Workflow Diagram: This flowchart illustrates the complete sequence from initial repository fork through development readiness. Each step references specific commands and files that will be detailed in subsequent sections.

Sources: CONTRIBUTING.md L18-L40

requirements.txt L1-L20

Repository Setup

Forking the Repository

  1. Navigate to https://github.com/noobforanonymous/wshawk
  2. Click the "Fork" button in the top-right corner
  3. Select your GitHub account as the fork destination

Cloning Your Fork

Replace YOUR_USERNAME with your actual GitHub username. This creates a local copy of your fork.

Adding Upstream Remote

Configure the original repository as an upstream remote to sync future changes:

This should display four remotes: origin (your fork) and upstream (original repository), each with fetch and push URLs.

Sources: CONTRIBUTING.md L18-L22

Virtual Environment Creation

Python virtual environments isolate project dependencies from system-wide packages, preventing version conflicts.

Creating the Environment

This creates a venv/ directory containing an isolated Python installation. The directory is excluded from version control via .gitignore L25-L28

Platform-Specific Activation

Linux/macOS:

Windows (Command Prompt):

Windows (PowerShell):

After activation, your shell prompt should be prefixed with (venv), indicating the active environment.

Deactivation

To deactivate the environment when finished:

Sources: CONTRIBUTING.md L24-L28

.gitignore L25-L28

Dependency Installation

WSHawk has two dependency categories: runtime dependencies and development dependencies.

Dependency Categories

Dependency Architecture Diagram: Maps external dependencies to their primary consumers in the codebase. Runtime dependencies support core functionality, while development dependencies enable testing and quality assurance.

Installing All Dependencies

This installs all packages listed in requirements.txt L1-L20

The file includes:

| Dependency | Version | Purpose | | --- | --- | --- | | websockets | >=12.0 | Core WebSocket protocol implementation | | playwright | >=1.40.0 | Headless browser for XSS verification | | aiohttp | >=3.9.0 | Async HTTP client for OAST callbacks | | PyYAML | >=6.0 | YAML configuration file parsing | | asyncio-mqtt | >=0.16.0 | MQTT protocol support | | pytest | >=7.4.0 | Test framework | | pytest-asyncio | >=0.21.0 | Async test support | | colorama | >=0.4.6 | Cross-platform terminal colors (optional) |

Note that setup.py L9-L14

defines a minimal runtime subset (excludes dev dependencies like pytest).

Sources: requirements.txt L1-L20

setup.py L9-L14

Development Installation

Install WSHawk in editable mode to enable live code changes without reinstallation:

The -e (editable) flag creates a symbolic link between the installation directory and your local source code. This allows modifications to .py files to take immediate effect.

What Gets Installed

This command processes setup.py L1-L62

to:

  1. Register CLI entry points (setup.py L41-L48 ): * wshawk → wshawk.__main__:cli * wshawk-interactive → wshawk.interactive:cli * wshawk-advanced → wshawk.advanced_cli:cli * wshawk-defensive → wshawk.defensive_cli:cli
  2. Include payload data files (setup.py L50-L55 ): * payloads/*.txt * payloads/**/*.json
  3. Install runtime dependencies (setup.py L40 ): * Uses the minimal dependency list (excludes dev tools)

After installation, the CLI commands become globally available in the virtual environment.

Sources: CONTRIBUTING.md L31-L34

setup.py L41-L55

Playwright Browser Installation

Playwright requires browser binaries for headless testing. Install Chromium (used for XSS verification):

Browser Installation Details

| Browser | Size | Purpose | | --- | --- | --- | | chromium | ~350MB | Primary browser for XSS verification | | firefox | ~400MB | Optional, not used by default | | webkit | ~300MB | Optional, not used by default |

Chromium is sufficient for WSHawk development. The binary installs to ~/.cache/ms-playwright/ (Linux/macOS) or %USERPROFILE%\AppData\Local\ms-playwright\ (Windows).

Verifying Installation

Expected output: Version 1.40.0 or higher.

The .playwright/ cache directory is excluded from version control via .gitignore L71

Sources: requirements.txt L9

.gitignore L71

Running Tests

WSHawk includes a quick test suite for development validation.

Test Execution

This test file validates core module functionality. The test suite uses pytest with async support (requirements.txt L15-L16

).

Test Coverage Areas

Test Coverage Diagram: Maps the test suite to code modules under validation. The quick test suite (test_modules_quick.py) provides fast feedback during development by testing core functionality without requiring live WebSocket endpoints.

Expected Test Output

Successful execution produces output similar to:

============================= test session starts ==============================
platform linux -- Python 3.11.0, pytest-7.4.0, pluggy-1.3.0
collected 15 items

tests/test_modules_quick.py ...............                              [100%]

============================== 15 passed in 2.45s ===============================

Test Artifacts

Tests generate temporary files excluded by .gitignore L50-L82

:

  • .pytest_cache/ - Pytest cache
  • test_results/ - Test output artifacts
  • wshawk_report_*.html - Generated scan reports

Sources: CONTRIBUTING.md L54-L60

.gitignore L38-L82

Installation Verification

Verify the complete installation by testing CLI commands and Python imports.

CLI Command Verification

Test all four entry points:

Each command should display its help text without errors. The entry points are registered via setup.py L42-L47

Python Import Verification

Test programmatic access:

Expected output: Import successful

Module Discovery Verification

Verify package data inclusion:

This confirms that payload files (setup.py L52-L54

) are correctly bundled and accessible.

Sources: setup.py L42-L54

CONTRIBUTING.md L54-L60

IDE Configuration (Optional)

Visual Studio Code

Create .vscode/settings.json (excluded via .gitignore L31

):

PyCharm

  1. Open project root directory
  2. Navigate to: File → Settings → Project → Python Interpreter
  3. Click gear icon → Add → Existing Environment
  4. Select venv/bin/python (Linux/macOS) or venv\Scripts\python.exe (Windows)

Sources: .gitignore L30-L36

Common Issues and Troubleshooting

Issue: playwright command not found

Cause: Playwright CLI not in PATH after installation.

Solution:

Ensure virtual environment is activated (venv/bin/activate).

Issue: Import errors for wshawk modules

Cause: Package not installed in editable mode.

Solution:

The -e flag is required for development to enable live code changes.

Issue: Missing payload files

Cause: Package data not included during installation.

Solution: Verify setup.py L49-L55

specifies include_package_data=True and package_data dictionary. Reinstall:

Issue: Test failures with WebSocket connection errors

Cause: Tests attempting to connect to non-existent WebSocket servers.

Solution: The test_modules_quick.py suite should not require live connections. If tests fail, check test isolation and mocking.

Issue: Permission errors on Windows during Playwright installation

Cause: Insufficient permissions for browser binary installation.

Solution: Run command prompt as Administrator or modify Playwright cache location:

Sources: requirements.txt L9

.gitignore L71

Next Steps

After completing environment setup:

  1. Review Project Structure: See Project Structure and Architecture for codebase organization
  2. Explore Extension Points: See Adding Extensions for contribution guidance
  3. Read Contribution Guidelines: Review CONTRIBUTING.md L1-L155 for code style and workflow
  4. Create Feature Branch: git checkout -b feature/descriptive-name
  5. Start Development: Modify code, run tests, commit changes

The development environment is now ready for contributions to vulnerability modules, mutators, payloads, or core functionality.

Sources: CONTRIBUTING.md L36-L91

setup.py L1-L62

Summary

This guide covered:

  • Prerequisites: Python 3.8+, Git, 500MB disk space
  • Repository Setup: Fork, clone, upstream configuration
  • Virtual Environment: Creation and platform-specific activation
  • Dependencies: Runtime (websockets, playwright, aiohttp, PyYAML) and development (pytest)
  • Development Installation: Editable mode (pip install -e .) for live code changes
  • Playwright: Browser binary installation for XSS verification
  • Testing: Running test_modules_quick.py for validation
  • Verification: CLI commands and Python imports
  • IDE Configuration: VSCode and PyCharm setup
  • Troubleshooting: Common installation issues

The complete workflow transforms a developer from zero to contribution-ready in approximately 10-15 minutes, assuming adequate internet bandwidth for dependency downloads.

Sources: CONTRIBUTING.md L15-L60

setup.py L1-L62

requirements.txt L1-L20

.gitignore L1-L93