Installation Methods

Relevant source files

• .github/workflows/ghcr-publish.yml
• Dockerfile
• README.md
• RELEASE_SUMMARY.md
• requirements.txt
• setup.py

Purpose and Scope

This document details the three official installation methods for WSHawk: pip (Python Package Index), Docker Hub, and GitHub Container Registry (GHCR). Each method provides the same WSHawk v2.0.5 functionality but targets different deployment scenarios. For information about using WSHawk after installation, see CLI Command Reference. For deployment in specific environments, see Docker Deployment and CI/CD Integration.

Sources: README.md L36-L62

setup.py L1-L62

Dockerfile L1-L66

---

Overview of Installation Options

WSHawk supports three distribution channels, each serving different use cases and organizational requirements. All methods deliver the same four CLI commands (wshawk, wshawk-interactive, wshawk-advanced, wshawk-defensive) and Python API.

Installation Method Comparison

| Feature | pip (PyPI) | Docker Hub | GitHub Container Registry | | --- | --- | --- | --- | | Target Audience | Python developers | DevOps teams, CI/CD | GitHub-native organizations | | Registry URL | pypi.org/project/wshawk | docker.io/rothackers/wshawk | ghcr.io/noobforanonymous/wshawk | | Installation Command | pip install wshawk | docker pull rothackers/wshawk | docker pull ghcr.io/noobforanonymous/wshawk | | Authentication | None (public package) | None (public image) | GitHub token (optional) | | System Dependencies | User manages Python | Bundled in container | Bundled in container | | Image Size | N/A (source/wheel) | ~150MB | ~150MB | | Multi-Architecture | N/A | ✓ (amd64, arm64) | ✓ (amd64, arm64) | | Version Pinning | pip install wshawk==2.0.5 | :2.0.5, :2.0, :2, :latest | :latest, :v* | | Auto-Updates | Manual (pip install --upgrade) | Manual pull | Manual pull | | Best For | Local development, Python integration | Production, CI/CD, isolation | GitHub Actions, GHCR-only orgs |

Sources: README.md L36-L62

RELEASE_SUMMARY.md L23-L38

setup.py L16-L48

---

Installation Flow Architecture

The following diagram illustrates how WSHawk artifacts flow from the source repository to end users through three parallel distribution channels.

flowchart TD

GitHubRepo["GitHub: noobforanonymous/wshawk"]
SetupPy["setup.py<br>version='2.0.5'<br>entry_points"]
Dockerfile["Dockerfile<br>python:3.11-slim<br>multi-stage build"]
PyProject["pyproject.toml<br>dependencies"]
GitPush["Git Push Event<br>main branch or tag"]
GHActions["GitHub Actions Workflows"]
PyBuild["Python Package Build<br>sdist + wheel"]
DockerBuild["Multi-Platform Docker Build<br>linux/amd64, linux/arm64"]
PyPI["PyPI Registry<br>pypi.org/project/wshawk"]
DockerHub["Docker Hub<br>docker.io/rothackers/wshawk"]
GHCR["GitHub Container Registry<br>ghcr.io/noobforanonymous/wshawk"]
PipUser["pip install wshawk==2.0.5"]
DockerUser["docker pull rothackers/wshawk:2.0.5"]
GHCRUser["docker pull ghcr.io/.../wshawk:latest"]
CLI["CLI Commands:<br>wshawk, wshawk-interactive<br>wshawk-advanced, wshawk-defensive"]
PythonAPI["Python API:<br>from wshawk.scanner_v2 import WSHawkV2"]

SetupPy -.-> GitPush
Dockerfile -.-> GitPush
PyProject -.-> GitPush
PyBuild -.-> PyPI
DockerBuild -.-> DockerHub
DockerBuild -.-> GHCR
PyPI -.-> PipUser
DockerHub -.-> DockerUser
GHCR -.-> GHCRUser
PipUser -.-> CLI
PipUser -.-> PythonAPI
DockerUser -.-> CLI
GHCRUser -.-> CLI

subgraph Runtime ["Runtime Artifacts"]
    CLI
    PythonAPI
end

subgraph Users ["User Installation"]
    PipUser
    DockerUser
    GHCRUser
end

subgraph Registries ["Distribution Registries"]
    PyPI
    DockerHub
    GHCR
end

subgraph CICD ["CI/CD Automation"]
    GitPush
    GHActions
    PyBuild
    DockerBuild
    GitPush -.-> GHActions
    GHActions -.-> PyBuild
    GHActions -.-> DockerBuild
end

subgraph Source ["Source Repository"]
    GitHubRepo
    SetupPy
    Dockerfile
    PyProject
    GitHubRepo -.-> SetupPy
    GitHubRepo -.-> Dockerfile
    GitHubRepo -.-> PyProject
end

Key Observations:

• A single push to the main branch triggers parallel builds for all three channels
• pip installation provides both CLI and Python API access
• Docker installations provide CLI access only (containers run commands directly)
• All installation methods deliver the same WSHawk v2.0.5 functionality

Sources: setup.py L1-L62

Dockerfile L1-L66

.github/workflows/ghcr-publish.yml L1-L50

---

Method 1: pip Installation (PyPI)

The pip installation method installs WSHawk as a Python package in the local Python environment. This method is recommended for developers integrating WSHawk into custom scripts or requiring Python API access.

Prerequisites

| Requirement | Minimum | Recommended | | --- | --- | --- | | Python | 3.8+ | 3.11+ | | pip | 20.0+ | Latest | | Operating System | Linux, macOS, Windows | Any | | Virtual Environment | Optional | Recommended |

Sources: setup.py L39

Dockerfile L4

Installation Commands

Basic Installation

# Install latest version
pip install wshawk

# Install specific version (recommended for production)
pip install wshawk==2.0.5

# Upgrade existing installation
pip install --upgrade wshawk

Installation with Virtual Environment (Recommended)

# Create virtual environment
python3 -m venv wshawk-env

# Activate virtual environment
source wshawk-env/bin/activate  # Linux/macOS
wshawk-env\Scripts\activate     # Windows

# Install WSHawk
pip install wshawk==2.0.5

Sources: README.md L37-L44

RELEASE_SUMMARY.md L78-L81

Core Dependencies

The pip installation automatically installs the following dependencies as defined in setup.py L9-L14

:

| Dependency | Minimum Version | Purpose | | --- | --- | --- | | websockets | 12.0 | WebSocket client implementation | | playwright | 1.40.0 | Browser-based XSS verification | | aiohttp | 3.9.0 | HTTP requests for OAST integration | | PyYAML | 6.0 | Configuration file parsing |

Sources: setup.py L9-L14

requirements.txt L1-L20

Optional: Playwright Browser Installation

For browser-based XSS verification functionality, install Playwright browsers after installing WSHawk:

# Install Chromium browser (recommended)
playwright install chromium

# Or install all browsers (larger download)
playwright install

This step downloads headless browser binaries (~300MB for Chromium). Omitting this step disables the --playwright option but does not affect other WSHawk functionality.

Sources: README.md L42-L44

Version Pinning Strategy

# Full version pinning (most restrictive)
pip install wshawk==2.0.5

# Allow patch updates only
pip install "wshawk>=2.0.5,<2.1.0"

# Allow minor updates (semver compatible)
pip install "wshawk>=2.0.5,<3.0.0"

# Always latest (not recommended for production)
pip install wshawk

Sources: setup.py L18

RELEASE_SUMMARY.md L1-L2

Entry Points and CLI Commands

The pip installation registers four console script entry points via setup.py L41-L48

:

entry_points={
    "console_scripts": [
        "wshawk=wshawk.__main__:cli",
        "wshawk-interactive=wshawk.interactive:cli",
        "wshawk-advanced=wshawk.advanced_cli:cli",
        "wshawk-defensive=wshawk.defensive_cli:cli",
    ],
}

After installation, these commands are available system-wide:

| Command | Entry Point Module | Description | | --- | --- | --- | | wshawk | wshawk.__main__:cli | Quick scan with all features | | wshawk-interactive | wshawk.interactive:cli | Menu-driven testing | | wshawk-advanced | wshawk.advanced_cli:cli | Full CLI control | | wshawk-defensive | wshawk.defensive_cli:cli | Blue team validation |

Sources: setup.py L41-L48

pip Installation Flow Diagram

flowchart TD

User["User Terminal"]
PipCommand["pip install wshawk==2.0.5"]
PyPI["PyPI Registry<br>Download Package"]
Resolve["Resolve Dependencies:<br>websockets>=12.0<br>playwright>=1.40.0<br>aiohttp>=3.9.0<br>PyYAML>=6.0"]
Install["Install Package:<br>site-packages/wshawk/<br>Include payloads/.txtInclude payloads/**/.json"]
RegisterEntryPoints["Register Entry Points:<br>wshawk -> main:cli<br>wshawk-interactive -> interactive:cli<br>wshawk-advanced -> advanced_cli:cli<br>wshawk-defensive -> defensive_cli:cli"]
Verify["Verify Installation:<br>wshawk --help"]
Optional["Optional: playwright install chromium"]
Ready["Ready to Use:<br>CLI + Python API"]

User -.-> PipCommand
PipCommand -.-> PyPI
PyPI -.-> Resolve
Resolve -.-> Install
Install -.-> RegisterEntryPoints
RegisterEntryPoints -.-> Verify
Verify -.-> Optional
Optional -.-> Ready
Verify -.-> Ready

Sources: setup.py L1-L62

README.md L37-L44

---

Method 2: Docker Hub

Docker Hub provides pre-built, multi-architecture container images at docker.io/rothackers/wshawk. This method is recommended for production deployments, CI/CD pipelines, and environments requiring dependency isolation.

Prerequisites

| Requirement | Minimum | Notes | | --- | --- | --- | | Docker Engine | 20.10+ | Or Docker Desktop | | Docker Compose | 1.29+ (optional) | For multi-container setups | | Architecture | amd64 or arm64 | Both supported | | Internet Access | Required for pull | Can cache locally after pull |

Sources: Dockerfile L1-L66

RELEASE_SUMMARY.md L118-L123

Image Repository Structure

The Docker Hub repository rothackers/wshawk uses semantic versioning with multiple tag strategies:

| Tag | Example | Description | Stability | | --- | --- | --- | --- | | Full Version | 2.0.5 | Exact release version | Immutable | | Major.Minor | 2.0 | Latest patch in 2.0.x | Updates with patches | | Major | 2 | Latest minor in 2.x.x | Updates with minor releases | | Latest | latest | Latest stable release | Updates with any release |

Sources: Dockerfile L58

RELEASE_SUMMARY.md L30-L32

Pulling Images

# Pull latest version (rolling tag)
docker pull rothackers/wshawk:latest

# Pull specific version (recommended for production)
docker pull rothackers/wshawk:2.0.5

# Pull major.minor version (allow patches)
docker pull rothackers/wshawk:2.0

# Pull major version (allow minor updates)
docker pull rothackers/wshawk:2

Sources: README.md L49-L56

RELEASE_SUMMARY.md L84-L87

Running Containers

Basic Scan

# Quick scan (default wshawk command)
docker run --rm rothackers/wshawk:2.0.5 ws://target.com

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

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

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

Sources: README.md L56-L60

Dockerfile L52-L53

Volume Mounting for Reports

HTML reports are saved to /app inside the container. Mount a host directory to persist reports:

# Mount current directory for reports
docker run --rm \
  -v $(pwd)/reports:/app \
  rothackers/wshawk:2.0.5 \
  wshawk ws://target.com

# Reports saved to ./reports/wshawk_report_YYYYMMDD_HHMMSS.html

Sources: Dockerfile L26

Network Configuration

For testing internal services, use Docker network modes:

# Test service on host machine
docker run --rm --network host \
  rothackers/wshawk:2.0.5 \
  wshawk ws://localhost:8080

# Test service in Docker network
docker run --rm --network my-network \
  rothackers/wshawk:2.0.5 \
  wshawk ws://service-name:8080

Sources: Dockerfile L1-L66

Docker Image Architecture

The Docker image is built using a multi-stage process defined in Dockerfile L1-L66

:

flowchart TD

BuildDeps["Install Build Dependencies:<br>gcc"]
CopySource["Copy Source Files:<br>setup.py, pyproject.toml<br>wshawk/ directory"]
PipInstall["pip install --no-cache-dir ."]
BuildArtifacts["Build Artifacts:<br>/usr/local/lib/python3.11/site-packages<br>/usr/local/bin/wshawk*"]
RuntimeDeps["Install Runtime Dependencies:<br>ca-certificates"]
CopyFromBuilder["Copy from Builder:<br>Python packages<br>CLI binaries"]
CreateUser["Create Non-Root User:<br>wshawk:1000"]
SetEnv["Set Environment:<br>PYTHONUNBUFFERED=1<br>PYTHONDONTWRITEBYTECODE=1"]
Entrypoint["ENTRYPOINT: wshawk<br>CMD: --help"]
Version["version=2.0.5"]
Source["source=github.com/noobforanonymous/wshawk"]
Description["description=Professional WebSocket scanner"]
License["licenses=MIT"]

BuildArtifacts -.-> CopyFromBuilder
Entrypoint -.-> Version
Entrypoint -.-> Source
Entrypoint -.-> Description
Entrypoint -.-> License

subgraph ImageMetadata ["Image Metadata (Labels)"]
    Version
    Source
    Description
    License
end

subgraph FinalStage ["Final Stage (python:3.11-slim)"]
    RuntimeDeps
    CopyFromBuilder
    CreateUser
    SetEnv
    Entrypoint
    RuntimeDeps -.-> CopyFromBuilder
    CopyFromBuilder -.-> CreateUser
    CreateUser -.-> SetEnv
    SetEnv -.-> Entrypoint
end

subgraph BuilderStage ["Builder Stage (python:3.11-slim)"]
    BuildDeps
    CopySource
    PipInstall
    BuildArtifacts
    BuildDeps -.-> CopySource
    CopySource -.-> PipInstall
    PipInstall -.-> BuildArtifacts
end

Image Characteristics:

• Base Image: python:3.11-slim (Dockerfile L4 Dockerfile L23 )
• Final Size: ~150MB (optimized via multi-stage build)
• User Context: Non-root user wshawk with UID 1000 (Dockerfile L38-L41 )
• Entry Point: wshawk command with --help as default (Dockerfile L52-L53 )
• Health Check: Runs wshawk --help every 30 seconds (Dockerfile L48-L49 )

Sources: Dockerfile L1-L66

RELEASE_SUMMARY.md L118-L123

---

Method 3: GitHub Container Registry (GHCR)

GitHub Container Registry provides an alternative Docker registry integrated with GitHub's ecosystem. Images are automatically published on every push to the main branch via GitHub Actions.

Prerequisites

Same as Docker Hub (Docker Engine 20.10+, amd64/arm64 architecture).

Sources: .github/workflows/ghcr-publish.yml L1-L50

Registry Authentication (Optional)

GHCR images from the wshawk repository are publicly accessible without authentication. For private registries or higher rate limits, authenticate using a GitHub Personal Access Token:

# Authenticate with GHCR
echo $GITHUB_TOKEN | docker login ghcr.io -u USERNAME --password-stdin

Sources: .github/workflows/ghcr-publish.yml L26-L31

Pulling Images

# Pull latest version
docker pull ghcr.io/noobforanonymous/wshawk:latest

# Pull specific version (if tagged with semver)
docker pull ghcr.io/noobforanonymous/wshawk:2.0.5

Sources: README.md L52-L53

RELEASE_SUMMARY.md L35-L36

Running Containers

GHCR images use the same interface as Docker Hub images:

# Basic scan
docker run --rm ghcr.io/noobforanonymous/wshawk:latest ws://target.com

# Defensive validation
docker run --rm ghcr.io/noobforanonymous/wshawk:latest wshawk-defensive ws://target.com

# With volume mounting
docker run --rm \
  -v $(pwd)/reports:/app \
  ghcr.io/noobforanonymous/wshawk:latest \
  wshawk ws://target.com

Sources: README.md L59-L60

RELEASE_SUMMARY.md L89-L93

GHCR Publishing Pipeline

The following diagram shows the automated GHCR publishing workflow:

flowchart TD

GitPush["Git Push Event<br>main branch or v* tag"]
Trigger["GitHub Actions Trigger<br>.github/workflows/ghcr-publish.yml"]
Checkout["Checkout Repository<br>actions/checkout@v4"]
Login["Login to GHCR<br>docker/login-action@v3<br>username: github.actor<br>password: GITHUB_TOKEN"]
ExtractMeta["Extract Metadata<br>docker/metadata-action@v5<br>tags: latest, semver"]
BuildPush["Build and Push<br>docker/build-push-action@v5<br>registry: ghcr.io<br>image: noobforanonymous/wshawk"]
GHCRRegistry["GHCR Public Registry<br>ghcr.io/noobforanonymous/wshawk"]

GitPush -.-> Trigger
Trigger -.-> Checkout
Checkout -.-> Login
Login -.-> ExtractMeta
ExtractMeta -.-> BuildPush
BuildPush -.-> GHCRRegistry

Key Workflow Properties:

• Trigger: Push to main branch or tags matching v* (.github/workflows/ghcr-publish.yml L3-L9 )
• Authentication: Uses GITHUB_TOKEN (no external secrets) (.github/workflows/ghcr-publish.yml L31 )
• Permissions: Requires contents: read and packages: write (.github/workflows/ghcr-publish.yml L18-L20 )
• Tagging: Generates latest for default branch and semver tags for version tags (.github/workflows/ghcr-publish.yml L38-L41 )

Sources: .github/workflows/ghcr-publish.yml L1-L50

GHCR vs Docker Hub Comparison

| Feature | GHCR | Docker Hub | | --- | --- | --- | | Registry URL | ghcr.io/noobforanonymous/wshawk | docker.io/rothackers/wshawk | | Authentication | GitHub token | Docker Hub credentials | | Auto-Publishing | GitHub Actions (automated) | GitHub Actions (automated) | | Tag Strategy | latest, semver | latest, 2, 2.0, 2.0.5 | | Image Linking | Links to GitHub repo | Manual documentation | | Rate Limits | GitHub limits | Docker Hub limits | | Best Use Case | GitHub-centric workflows | General Docker usage |

Sources: .github/workflows/ghcr-publish.yml L12-L13

RELEASE_SUMMARY.md L29-L38

---

System Requirements

Common Requirements (All Methods)

| Component | Requirement | Notes | | --- | --- | --- | | Operating System | Linux, macOS, Windows | WSL2 for Windows (Docker) | | RAM | 512MB minimum, 1GB recommended | For basic scans without Playwright | | RAM (with Playwright) | 2GB minimum, 4GB recommended | Browser automation requires more memory | | Disk Space (pip) | 100MB | + 300MB for Playwright browsers | | Disk Space (Docker) | 150MB per image | Multi-stage build optimization | | Network Access | Internet for installation | Can work offline after setup |

Sources: Dockerfile L1-L66

setup.py L39

Python Version Support Matrix

The following Python versions are officially supported per setup.py L32-L37

:

Python 3.8  ✓
Python 3.9  ✓
Python 3.10 ✓
Python 3.11 ✓ (Recommended, used in Docker images)
Python 3.12 ✓
Python 3.13 ✓

Sources: setup.py L32-L37

Dockerfile L4

Dockerfile L23

---

Verifying Installation

pip Installation Verification

# Verify CLI commands are accessible
wshawk --help
wshawk-interactive --help
wshawk-advanced --help
wshawk-defensive --help

# Check installed version
pip show wshawk

# Verify Python API
python3 -c "from wshawk.scanner_v2 import WSHawkV2; print('Import successful')"

Expected output:

Name: wshawk
Version: 2.0.5
Summary: Professional WebSocket security scanner...
Home-page: https://github.com/noobforanonymous/wshawk
Author: Regaan
License: MIT
Location: /path/to/site-packages
Requires: websockets, playwright, aiohttp, PyYAML

Sources: setup.py L16-L23

Docker Installation Verification

# Verify image exists locally
docker images | grep wshawk

# Expected output:
# rothackers/wshawk    2.0.5    <image-id>    <size>    <date>
# rothackers/wshawk    latest   <image-id>    <size>    <date>

# Verify CLI help
docker run --rm rothackers/wshawk:2.0.5 --help

# Verify all commands
docker run --rm rothackers/wshawk:2.0.5 wshawk --help
docker run --rm rothackers/wshawk:2.0.5 wshawk-defensive --help

# Check image metadata
docker inspect rothackers/wshawk:2.0.5 | grep -A 5 Labels

Expected labels include:

• version="2.0.5"
• org.opencontainers.image.source="https://github.com/noobforanonymous/wshawk"
• maintainer="Regaan"

Sources: Dockerfile L56-L66

Dockerfile L48-L49

GHCR Installation Verification

# Verify GHCR image
docker images | grep ghcr.io/noobforanonymous/wshawk

# Run health check equivalent
docker run --rm ghcr.io/noobforanonymous/wshawk:latest --help

Sources: .github/workflows/ghcr-publish.yml L1-L50

---

Version Pinning Best Practices

Production Deployments

For production environments, always pin to exact versions:

# pip: Use exact version
pip install wshawk==2.0.5

# Docker: Use full version tag
docker pull rothackers/wshawk:2.0.5

# requirements.txt
wshawk==2.0.5

Development Environments

For development, allow minor updates while preventing breaking changes:

# pip: Allow patch updates
pip install "wshawk>=2.0.5,<2.1.0"

# Docker: Use major.minor tag
docker pull rothackers/wshawk:2.0

CI/CD Pipelines

Use Dependabot or similar tools to track updates while maintaining explicit version control:

# Example Dependabot configuration
version: 2
updates:
  - package-ecosystem: "pip"
    directory: "/"
    schedule:
      interval: "weekly"
    target-branch: "develop"

Sources: setup.py L18

Dockerfile L58

---

Troubleshooting Installation Issues

pip Installation Issues

Issue: ModuleNotFoundError after installation

# Solution: Ensure virtual environment is activated
source venv/bin/activate

# Or reinstall with --force-reinstall
pip install --force-reinstall wshawk==2.0.5

Issue: Playwright installation fails

# Solution: Install system dependencies first (Ubuntu/Debian)
sudo apt-get install -y libnss3 libnspr4 libatk1.0-0 libatk-bridge2.0-0

# Then install Playwright browsers
playwright install chromium

Sources: setup.py L9-L14

requirements.txt L8-L9

Docker Installation Issues

Issue: Permission denied

# Solution: Add user to docker group
sudo usermod -aG docker $USER
# Then log out and back in

Issue: Cannot mount volume

# Solution: Use absolute path
docker run --rm \
  -v /absolute/path/to/reports:/app \
  rothackers/wshawk:2.0.5 ws://target.com

Issue: Network connectivity to host services

# Solution: Use host.docker.internal (Docker Desktop)
docker run --rm rothackers/wshawk:2.0.5 ws://host.docker.internal:8080

# Or use --network host (Linux)
docker run --rm --network host rothackers/wshawk:2.0.5 ws://localhost:8080

Sources: Dockerfile L1-L66

---

Summary

WSHawk v2.0.5 provides three installation methods targeting different deployment scenarios:

1. pip (PyPI): Best for Python developers, local development, and API integration. Provides both CLI and Python API access. Requires manual dependency management.
2. Docker Hub: Best for production deployments, CI/CD pipelines, and dependency isolation. Pre-built multi-architecture images with semantic versioning. Easy volume mounting for report persistence.
3. GitHub Container Registry: Best for GitHub-centric workflows and organizations standardizing on GHCR. Automated publishing via GitHub Actions with minimal authentication overhead.

All methods deliver identical WSHawk functionality including the four CLI commands, 22,000+ attack payloads, CVSS scoring, and professional HTML reporting.

Sources: README.md L36-L62

setup.py L1-L62

Dockerfile L1-L66

.github/workflows/ghcr-publish.yml L1-L50