Installation Methods

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

• .dockerignore
• .github/workflows/docker-build.yml
• .github/workflows/ghcr-publish.yml
• Dockerfile
• MANIFEST.in
• README.md
• docker-compose.yml
• pyproject.toml
• setup.py

Purpose and Scope

This page documents the three primary methods for installing WSHawk: pip installation from PyPI, Docker container deployment, and building from source. Each method is suitable for different use cases and deployment environments. For guidance on running your first scan after installation, see Quick Start Examples. For detailed information about the package distribution infrastructure, see Package Distribution and Docker Images.

---

Installation Method Overview

graph TB
    subgraph "Installation Methods"
        PIP["Method 1: pip install<br/>PyPI Registry"]
        Docker["Method 2: Docker<br/>Pre-built Images"]
        Source["Method 3: Build from Source<br/>GitHub Repository"]
    end
    
    subgraph "PyPI Installation"
        PyPIReg["PyPI Registry<br/>pypi.org/project/wshawk"]
        PipCmd["pip install wshawk"]
        PlaywrightSetup["playwright install chromium<br/>(Optional)"]
    end
    
    subgraph "Docker Sources"
        DockerHub["Docker Hub<br/>rothackers/wshawk"]
        GHCR["GitHub Container Registry<br/>ghcr.io/regaan/wshawk"]
    end
    
    subgraph "Source Build"
        GitRepo["git clone<br/>github.com/regaan/wshawk"]
        SetupPy["setup.py"]
        PyprojectToml["pyproject.toml"]
    end
    
    subgraph "Installed Components"
        WshawkPkg["wshawk Python package"]
        CLI1["wshawk CLI"]
        CLI2["wshawk-interactive CLI"]
        CLI3["wshawk-advanced CLI"]
        CLI4["wshawk-defensive CLI"]
        Payloads["Payload files<br/>*.txt, *.json"]
    end
    
    PIP --> PyPIReg
    PyPIReg --> PipCmd
    PipCmd --> WshawkPkg
    PipCmd --> PlaywrightSetup
    
    Docker --> DockerHub
    Docker --> GHCR
    DockerHub --> WshawkPkg
    GHCR --> WshawkPkg
    
    Source --> GitRepo
    GitRepo --> SetupPy
    GitRepo --> PyprojectToml
    SetupPy --> WshawkPkg
    PyprojectToml --> WshawkPkg
    
    WshawkPkg --> CLI1
    WshawkPkg --> CLI2
    WshawkPkg --> CLI3
    WshawkPkg --> CLI4
    WshawkPkg --> Payloads

Sources: README.md:49-77, pyproject.toml:1-52, setup.py:1-62, Dockerfile:1-66

---

Method 1: pip Installation (Recommended)

Installing from PyPI

The simplest installation method uses Python's package manager. The package is published to PyPI as wshawk and can be installed with a single command:

pip install wshawk

This installs the wshawk package along with all required dependencies defined in pyproject.toml:29-34:

• websockets>=12.0 - WebSocket protocol implementation
• playwright>=1.40.0 - Browser automation for XSS verification
• aiohttp>=3.9.0 - HTTP client for OAST integration
• PyYAML>=6.0 - YAML configuration parsing

Python Version Requirements

WSHawk requires Python 3.8 or higher, as specified in pyproject.toml:13 and setup.py:39. The package is tested against Python 3.8 through 3.13, as documented in the classifiers at pyproject.toml:21-26.

Optional: Playwright Browser Setup

For browser-based XSS verification (see Playwright XSS Verification), install the Chromium browser after installing WSHawk:

playwright install chromium

This downloads the Playwright-managed Chromium binary (~200MB). Omitting this step disables browser-based XSS verification but leaves all other functionality intact.

Entry Points Created

The pip installation creates four CLI entry points defined in pyproject.toml:41-45:

| Entry Point | Module | Purpose | |-------------|--------|---------| | wshawk | wshawk.__main__:cli | Quick scan mode | | wshawk-interactive | wshawk.interactive:cli | Interactive menu mode | | wshawk-advanced | wshawk.advanced_cli:cli | Advanced CLI with flags | | wshawk-defensive | wshawk.defensive_cli:cli | Defensive validation |

Package Data Inclusion

The installation includes payload files through package data configuration at pyproject.toml:50-51 and setup.py:50-54:

• payloads/*.txt - Simple text-based payload collections
• payloads/**/*.json - Structured JSON payload definitions

Sources: README.md:51-58, pyproject.toml:5-52, setup.py:8-62, requirements.txt:1-19

---

Method 2: Docker Deployment

Available Registries

WSHawk Docker images are published to two container registries:

| Registry | Image Path | Use Case | |----------|-----------|----------| | Docker Hub | rothackers/wshawk | General use, public access | | GitHub Container Registry | ghcr.io/regaan/wshawk | CI/CD integration, GitHub Actions |

Pulling Images

# From Docker Hub (recommended for most users)
docker pull rothackers/wshawk:latest

# From GitHub Container Registry
docker pull ghcr.io/regaan/wshawk:latest

# Specific version
docker pull rothackers/wshawk:2.0.6

Images are built and published automatically via GitHub Actions workflow at .github/workflows/ghcr-publish.yml:1-50.

Running Containers

The Docker image uses wshawk as the entrypoint (see Dockerfile:52):

# Display help
docker run --rm rothackers/wshawk --help

# Basic scan
docker run --rm rothackers/wshawk ws://target.com

# Interactive mode
docker run --rm -it rothackers/wshawk wshawk-interactive

# Advanced mode with options
docker run --rm rothackers/wshawk wshawk-advanced ws://target.com --playwright

# Defensive validation
docker run --rm rothackers/wshawk wshawk-defensive ws://target.com

Docker Image Architecture

graph TB
    subgraph "Multi-Stage Build"
        BuildStage["Builder Stage<br/>python:3.11-slim"]
        FinalStage["Final Stage<br/>python:3.11-slim"]
    end
    
    subgraph "Builder Stage Components"
        GCC["gcc compiler"]
        SetupFiles["setup.py<br/>pyproject.toml<br/>README.md"]
        WshawkSrc["wshawk/ source"]
        PipInstall["pip install ."]
    end
    
    subgraph "Final Stage Components"
        CACerts["ca-certificates"]
        PythonPkgs["/usr/local/lib/python3.11/site-packages"]
        CLIBins["/usr/local/bin/wshawk*"]
        NonRootUser["User: wshawk (UID 1000)"]
    end
    
    subgraph "Runtime Configuration"
        Entrypoint["ENTRYPOINT wshawk"]
        HealthCheck["HEALTHCHECK wshawk --help"]
        EnvVars["PYTHONUNBUFFERED=1<br/>PYTHONDONTWRITEBYTECODE=1"]
    end
    
    BuildStage --> GCC
    BuildStage --> SetupFiles
    BuildStage --> WshawkSrc
    SetupFiles --> PipInstall
    WshawkSrc --> PipInstall
    
    PipInstall --> PythonPkgs
    PipInstall --> CLIBins
    
    FinalStage --> CACerts
    FinalStage --> PythonPkgs
    FinalStage --> CLIBins
    FinalStage --> NonRootUser
    FinalStage --> Entrypoint
    FinalStage --> HealthCheck
    FinalStage --> EnvVars

The Docker image uses a multi-stage build defined in Dockerfile:4-23 to minimize final image size. The builder stage compiles dependencies, and the final stage contains only runtime components.

Multi-Platform Support

Docker images are built for multiple architectures through the GitHub Actions workflow, supporting both amd64 and arm64 platforms. This enables deployment on:

• x86_64 Linux servers (amd64)
• ARM-based servers and Apple Silicon Macs (arm64)

Image Metadata

The Docker image includes OpenContainers-compliant labels defined at Dockerfile:55-65 for integration with container registries and documentation systems.

Sources: README.md:60-76, Dockerfile:1-66, .github/workflows/ghcr-publish.yml:1-50

---

Method 3: Building from Source

Cloning the Repository

git clone https://github.com/regaan/wshawk.git
cd wshawk

Installing Dependencies

Create a virtual environment and install dependencies:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in editable mode for development
pip install -e .

# Or install normally
pip install .

The editable mode (-e) installs the package in development mode, allowing source code changes to take effect immediately without reinstallation.

Build System Configuration

WSHawk uses a PEP 517-compliant build system configured in pyproject.toml:1-3:

[build-system]
requires = ["setuptools>=61.0", "wheel"]
build-backend = "setuptools.build_meta"

The build process uses setuptools>=61.0 and wheel to create distribution packages.

Building Distribution Packages

To create distribution packages for publishing or local installation:

# Install build tools
pip install build

# Build wheel and source distribution
python -m build

# Output: dist/wshawk-2.0.6-py3-none-any.whl
#         dist/wshawk-2.0.6.tar.gz

The version is defined at pyproject.toml:7 and setup.py:18.

Package Discovery

The package discovery mechanism is configured at pyproject.toml:47-48:

[tool.setuptools]
packages = {find = {}}

This automatically discovers all Python packages in the project directory. The equivalent configuration exists in setup.py:24 using find_packages() with exclusions for test and documentation directories.

Development Dependencies

For testing and development, install additional dependencies from requirements.txt:13-18:

pip install pytest>=7.4.0 pytest-asyncio>=0.21.0

See Testing Infrastructure for details on running the test suite.

Sources: setup.py:1-62, pyproject.toml:1-52, requirements.txt:1-19

---

Installation Verification

Testing the Installation

Verify the installation by checking the version and help output:

# Check version
wshawk --help

# Verify all CLI entry points
wshawk-interactive --help
wshawk-advanced --help
wshawk-defensive --help

Entry Point Resolution

graph LR
    subgraph "Package Structure"
        WshawkPkg["wshawk package<br/>(site-packages)"]
        MainModule["wshawk/__main__.py"]
        InteractiveModule["wshawk/interactive.py"]
        AdvancedModule["wshawk/advanced_cli.py"]
        DefensiveModule["wshawk/defensive_cli.py"]
    end
    
    subgraph "Console Scripts"
        WshawkCmd["wshawk command"]
        InteractiveCmd["wshawk-interactive command"]
        AdvancedCmd["wshawk-advanced command"]
        DefensiveCmd["wshawk-defensive command"]
    end
    
    subgraph "Entry Point Functions"
        MainCli["__main__:cli()"]
        InteractiveCli["interactive:cli()"]
        AdvancedCli["advanced_cli:cli()"]
        DefensiveCli["defensive_cli:cli()"]
    end
    
    WshawkPkg --> MainModule
    WshawkPkg --> InteractiveModule
    WshawkPkg --> AdvancedModule
    WshawkPkg --> DefensiveModule
    
    MainModule --> MainCli
    InteractiveModule --> InteractiveCli
    AdvancedModule --> AdvancedCli
    DefensiveModule --> DefensiveCli
    
    WshawkCmd --> MainCli
    InteractiveCmd --> InteractiveCli
    AdvancedCmd --> AdvancedCli
    DefensiveCmd --> DefensiveCli

The entry points are defined in pyproject.toml:41-45 and setup.py:41-47, mapping CLI commands to Python module functions.

Checking Payload Files

Verify payload files are installed correctly:

python -c "import wshawk; import os; print(os.path.dirname(wshawk.__file__))"
# Output shows package installation directory

# List payload files
ls $(python -c "import wshawk; import os; print(os.path.dirname(wshawk.__file__))")/payloads/

The payload files are included through the package_data configuration at pyproject.toml:50-51 and setup.py:50-54.

Sources: pyproject.toml:41-51, setup.py:41-54

---

Dependency Management

Core Dependencies

WSHawk's core dependencies are declared consistently across pyproject.toml:29-34, setup.py:9-14, and requirements.txt:4-11:

| Dependency | Minimum Version | Purpose | |------------|----------------|---------| | websockets | 12.0 | WebSocket protocol implementation | | playwright | 1.40.0 | Browser automation for XSS verification | | aiohttp | 3.9.0 | HTTP client for OAST integration | | PyYAML | 6.0 | YAML configuration file parsing |

Dependency Resolution Flow

graph TB
    subgraph "Installation Method"
        PipInstall["pip install wshawk"]
        SourceInstall["pip install ."]
        DockerBuild["docker build"]
    end
    
    subgraph "Configuration Files"
        PyprojectToml["pyproject.toml<br/>dependencies list"]
        SetupPy["setup.py<br/>install_requires"]
        RequirementsTxt["requirements.txt<br/>(reference only)"]
    end
    
    subgraph "Resolved Dependencies"
        Websockets["websockets>=12.0"]
        Playwright["playwright>=1.40.0"]
        Aiohttp["aiohttp>=3.9.0"]
        PyYAML["PyYAML>=6.0"]
    end
    
    subgraph "Installed Components"
        WsLib["websockets library"]
        PwLib["playwright library"]
        HttpLib["aiohttp library"]
        YamlLib["PyYAML library"]
    end
    
    PipInstall --> PyprojectToml
    SourceInstall --> SetupPy
    DockerBuild --> SetupPy
    
    PyprojectToml --> Websockets
    PyprojectToml --> Playwright
    PyprojectToml --> Aiohttp
    PyprojectToml --> PyYAML
    
    SetupPy --> Websockets
    SetupPy --> Playwright
    SetupPy --> Aiohttp
    SetupPy --> PyYAML
    
    Websockets --> WsLib
    Playwright --> PwLib
    Aiohttp --> HttpLib
    PyYAML --> YamlLib

Optional Dependencies

Additional testing dependencies are specified in requirements.txt:14-18 but are not installed automatically:

• pytest>=7.4.0 - Test framework
• pytest-asyncio>=0.21.0 - Async test support
• colorama>=0.4.6 - Terminal color output (optional enhancement)

These are only needed for development and running the test suite (see Testing Infrastructure).

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

---

Installation Method Comparison

| Aspect | pip | Docker | Source Build | |--------|-----|--------|-------------| | Ease of Use | Highest | High | Medium | | Setup Time | < 1 minute | < 2 minutes | 2-5 minutes | | Python Required | Yes (3.8+) | No | Yes (3.8+) | | Isolation | Virtual env | Container | Virtual env | | Development | Editable mode | Not suitable | Best option | | CI/CD | Good | Excellent | Good | | Update Process | pip install --upgrade | docker pull | git pull + rebuild | | Size | ~50MB | ~400MB | ~50MB | | Configuration File | pyproject.toml:1-52 | Dockerfile:1-66 | setup.py:1-62 | | Distribution | PyPI | Docker Hub, GHCR | GitHub | | Multi-platform | Native | amd64, arm64 | Native |

Sources: README.md:49-77, pyproject.toml:1-52, Dockerfile:1-66, setup.py:1-62