Package Distribution

Package Distribution

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

This page documents WSHawk's distribution as a Python package on PyPI. It covers the package metadata, build system configuration, versioning strategy, included files, and the installation process via pip.

For Docker-based distribution, see Docker Images and Registries. For CI/CD integration patterns, see CI/CD Integration.

PyPI Distribution Overview

WSHawk is distributed on the Python Package Index (PyPI) under the package name wshawk. The package supports Python 3.8 through 3.13 and is classified as "Production/Stable" with MIT licensing.

Official PyPI Page: https://pypi.org/project/wshawk/

Installation Command:

pip install wshawk

Sources: README.md:55-62, pyproject.toml:5-7

Build System Architecture

WSHawk uses a dual configuration approach for maximum compatibility with both modern and legacy Python tooling:

Modern Configuration: pyproject.toml

The primary package metadata is defined in pyproject.toml:1-58 following PEP 621 standards:

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

This configuration uses the setuptools build backend with the modern pyproject.toml format, enabling compatibility with PEP 517-compliant build tools like build, pip, and poetry.

Legacy Configuration: setup.py

The setup.py:1-65 file provides backward compatibility for older tooling and CI/CD systems that expect traditional setup() calls. Both files maintain synchronized metadata to prevent version drift.

| Configuration | Purpose | Primary Use Case | |---------------|---------|------------------| | pyproject.toml | Modern declarative metadata | PEP 517+ tools, GitHub Actions, modern IDEs | | setup.py | Traditional setuptools API | Legacy CI/CD, editable installs, custom build scripts |

Sources: pyproject.toml:1-4, setup.py:1-17

Package Metadata

Identification and Authorship

name = "wshawk"
version = "3.0.0"
author = "Regaan"

Defined in pyproject.toml:6-10 and setup.py:17-19. The version follows semantic versioning (SemVer) with MAJOR.MINOR.PATCH format.

Description and Classification

Short Description (pyproject.toml:11):

"Professional WebSocket security scanner with real vulnerability verification, session hijacking tests, and CVSS scoring"

PyPI Trove Classifiers (pyproject.toml:14-27):

classifiers = [
    "Development Status :: 5 - Production/Stable",
    "Intended Audience :: Information Technology",
    "Intended Audience :: Developers",
    "Topic :: Security",
    "License :: OSI Approved :: MIT License",
    "Programming Language :: Python :: 3.8",
    "Programming Language :: Python :: 3.9",
    "Programming Language :: Python :: 3.10",
    "Programming Language :: Python :: 3.11",
    "Programming Language :: Python :: 3.12",
    "Programming Language :: Python :: 3.13",
]

These classifiers enable PyPI users to filter packages by maturity, intended audience, and Python version compatibility.

Search Keywords

SEO Keywords (pyproject.toml:28, setup.py:58):

websocket, security, scanner, penetration-testing, bug-bounty, 
vulnerability, xss, sqli, session-hijacking, cvss, playwright, 
oast, waf-bypass

These keywords optimize discoverability in PyPI and package manager searches.

Sources: pyproject.toml:5-28, setup.py:16-38

Package Structure and File Inclusion

Diagram: Package Build Flow

graph TB
    subgraph "Source Repository"
        PyProject["pyproject.toml<br/>Package Metadata"]
        Setup["setup.py<br/>Legacy Config"]
        Manifest["MANIFEST.in<br/>File Inclusion Rules"]
        SourceCode["wshawk/<br/>Source Code"]
        Payloads["wshawk/payloads/<br/>*.txt, *.json"]
        Web["wshawk/web/<br/>templates/, static/"]
        README["README.md<br/>Long Description"]
    end
    
    subgraph "Build Process"
        FindPackages["setuptools.find_packages()<br/>Exclude: tests, examples, docs"]
        IncludeData["Package Data:<br/>payloads/**/*<br/>web/**/*"]
        BuildWheel["python -m build<br/>Wheel Generation"]
    end
    
    subgraph "Distribution Artifact"
        WheelFile["wshawk-3.0.0-py3-none-any.whl"]
        TarFile["wshawk-3.0.0.tar.gz"]
    end
    
    subgraph "PyPI Registry"
        PyPIUpload["twine upload<br/>dist/*"]
        PyPIPackage["pypi.org/project/wshawk"]
    end
    
    PyProject --> FindPackages
    Setup --> FindPackages
    Manifest --> IncludeData
    SourceCode --> FindPackages
    Payloads --> IncludeData
    Web --> IncludeData
    README --> FindPackages
    
    FindPackages --> BuildWheel
    IncludeData --> BuildWheel
    
    BuildWheel --> WheelFile
    BuildWheel --> TarFile
    
    WheelFile --> PyPIUpload
    TarFile --> PyPIUpload
    
    PyPIUpload --> PyPIPackage

Sources: pyproject.toml:48-57, setup.py:24,49-57, MANIFEST.in:1-7

Included Files via MANIFEST.in

The MANIFEST.in:1-7 file specifies additional files to include in the source distribution beyond Python code:

include README.md
include LICENSE
include requirements.txt
recursive-include wshawk/payloads *
recursive-include wshawk/web/templates *
recursive-include wshawk/web/static *

| Pattern | Purpose | File Count | |---------|---------|------------| | README.md | PyPI long description | 1 | | LICENSE | MIT license text | 1 | | requirements.txt | Dependency list | 1 | | wshawk/payloads/* | 22,000+ attack payloads | ~50 files | | wshawk/web/templates/* | Flask HTML templates | ~5 files | | wshawk/web/static/* | CSS/JS assets | ~10 files |

Sources: MANIFEST.in:1-7

Package Data Specification

Both pyproject.toml:51-57 and setup.py:50-57 declare package data to include in wheel distributions:

package_data = {
    "wshawk": [
        "payloads/*.txt",
        "payloads/**/*.json",
        "web/templates/*.html",
        "web/static/*",
    ],
}

This ensures that non-Python assets are accessible at runtime via importlib.resources or pkg_resources.

Sources: pyproject.toml:51-57, setup.py:50-57

Excluded Directories

The setup.py:24 configuration explicitly excludes development artifacts:

packages = find_packages(exclude=["tests", "tests.*", "examples", "examples.*", "docs"])

This prevents test code, example scripts, and documentation from bloating the distribution package.

Sources: setup.py:24

Entry Points and CLI Commands

Diagram: Entry Point Mapping

graph LR
    subgraph "PyPI Package: wshawk"
        EP1["[console_scripts]<br/>wshawk"]
        EP2["[console_scripts]<br/>wshawk-interactive"]
        EP3["[console_scripts]<br/>wshawk-advanced"]
        EP4["[console_scripts]<br/>wshawk-defensive"]
    end
    
    subgraph "Python Modules"
        Main["wshawk.__main__:cli"]
        Interactive["wshawk.interactive:cli"]
        Advanced["wshawk.advanced_cli:cli"]
        Defensive["wshawk.defensive_cli:cli"]
    end
    
    subgraph "Installed Commands"
        CMD1["$ wshawk"]
        CMD2["$ wshawk-interactive"]
        CMD3["$ wshawk-advanced"]
        CMD4["$ wshawk-defensive"]
    end
    
    EP1 --> Main
    EP2 --> Interactive
    EP3 --> Advanced
    EP4 --> Defensive
    
    Main --> CMD1
    Interactive --> CMD2
    Advanced --> CMD3
    Defensive --> CMD4

Sources: pyproject.toml:42-46, setup.py:41-47

Entry Point Definitions

From pyproject.toml (pyproject.toml:42-46):

[project.scripts]
wshawk = "wshawk.__main__:cli"
wshawk-interactive = "wshawk.interactive:cli"
wshawk-advanced = "wshawk.advanced_cli:cli"
wshawk-defensive = "wshawk.defensive_cli:cli"

From setup.py (setup.py:41-47):

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",
    ],
}

These entry points create executable scripts in bin/ (Unix) or Scripts/ (Windows) during installation, making the CLI commands globally available.

| Command | Module | Function | Purpose | |---------|--------|----------|---------| | wshawk | wshawk.__main__ | cli() | Quick scan mode or web dashboard launch | | wshawk-interactive | wshawk.interactive | cli() | Menu-driven interface | | wshawk-advanced | wshawk.advanced_cli | cli() | Full-featured CLI with all options | | wshawk-defensive | wshawk.defensive_cli | cli() | Blue team validation tests |

Sources: pyproject.toml:42-46, setup.py:41-47

Dependency Management

Core Dependencies

Defined in both pyproject.toml:29-35 and setup.py:9-14:

dependencies = [
    "websockets>=12.0",      # WebSocket protocol implementation
    "playwright>=1.40.0",    # Browser automation for XSS verification
    "aiohttp>=3.9.0",        # Async HTTP for OAST and integrations
    "PyYAML>=6.0",           # Configuration file parsing
    "flask>=3.0.0",          # Web dashboard framework
]

| Dependency | Minimum Version | Purpose | |------------|----------------|---------| | websockets | 12.0 | WebSocket client/server library | | playwright | 1.40.0 | Chromium automation for XSS verification | | aiohttp | 3.9.0 | Async HTTP client for OAST and API integrations | | PyYAML | 6.0 | YAML parser for wshawk.yaml configuration | | flask | 3.0.0 | Web framework for dashboard |

Optional Post-Install Step

The Playwright browser binary requires a separate installation step after package installation:

pip install wshawk
playwright install chromium

This two-step process keeps the base package size minimal (~5MB) while allowing users who need browser verification to opt-in to the larger (~200MB) Chromium download.

Sources: pyproject.toml:29-35, setup.py:9-14, README.md:60-62

Installation Process

Diagram: Installation Flow

graph TB
    User["User Terminal"]
    
    subgraph "Installation Command"
        PipCmd["$ pip install wshawk"]
    end
    
    subgraph "PyPI Resolution"
        PyPIFetch["PyPI API:<br/>pypi.org/pypi/wshawk/json"]
        VersionSelect["Version Selection:<br/>Latest (3.0.0)"]
        WheelDownload["Download:<br/>wshawk-3.0.0-py3-none-any.whl"]
    end
    
    subgraph "Dependency Resolution"
        DepCheck["Check dependencies:<br/>websockets>=12.0<br/>playwright>=1.40.0<br/>aiohttp>=3.9.0<br/>PyYAML>=6.0<br/>flask>=3.0.0"]
        DepInstall["Install missing<br/>dependencies"]
    end
    
    subgraph "Package Installation"
        ExtractWheel["Extract wheel to<br/>site-packages/wshawk/"]
        CreateScripts["Create entry points:<br/>bin/wshawk<br/>bin/wshawk-interactive<br/>bin/wshawk-advanced<br/>bin/wshawk-defensive"]
        InstallMeta["Install metadata:<br/>wshawk-3.0.0.dist-info/"]
    end
    
    subgraph "Optional Step"
        PlaywrightInstall["$ playwright install chromium"]
        BrowserDownload["Download Chromium (~200MB)"]
    end
    
    subgraph "Verification"
        TestCmd["$ wshawk --version"]
        Output["wshawk 3.0.0"]
    end
    
    User --> PipCmd
    PipCmd --> PyPIFetch
    PyPIFetch --> VersionSelect
    VersionSelect --> WheelDownload
    WheelDownload --> DepCheck
    DepCheck --> DepInstall
    DepInstall --> ExtractWheel
    ExtractWheel --> CreateScripts
    CreateScripts --> InstallMeta
    InstallMeta --> PlaywrightInstall
    PlaywrightInstall --> BrowserDownload
    BrowserDownload --> TestCmd
    TestCmd --> Output

Sources: README.md:55-62, pyproject.toml:29-35

Installation Methods

Standard Installation:

pip install wshawk

With Browser Verification Support:

pip install wshawk
playwright install chromium

Specific Version:

pip install wshawk==3.0.0

Development/Editable Install (from source):

git clone https://github.com/regaan/wshawk.git
cd wshawk
pip install -e .

Sources: README.md:55-62

Version Management

Current Version

The package version is declared in three locations to ensure consistency:

  1. pyproject.toml: pyproject.toml:7 → version = "3.0.0"
  2. setup.py: setup.py:18 → version = "3.0.0"
  3. CITATION.cff: CITATION.cff:8 → version: 3.0.0

Semantic Versioning

WSHawk follows semantic versioning (SemVer 2.0.0):

| Version Component | Meaning | Example Change | |------------------|---------|----------------| | MAJOR (3) | Breaking changes | Scanner API redesign | | MINOR (0) | New features, backward compatible | Added defensive mode | | PATCH (0) | Bug fixes, backward compatible | Fixed rate limiting bug |

Release Date

The release date is documented in CITATION.cff:9:

date-released: 2026-02-18

Sources: pyproject.toml:7, setup.py:18, CITATION.cff:8-9

Project URLs and Metadata

Configured URLs

From pyproject.toml (pyproject.toml:37-40):

[project.urls]
Homepage = "https://github.com/regaan/wshawk"
"Bug Reports" = "https://github.com/regaan/wshawk/issues"
Source = "https://github.com/regaan/wshawk"

From setup.py (setup.py:59-63):

project_urls = {
    "Bug Reports": "https://github.com/regaan/wshawk/issues",
    "Source": "https://github.com/regaan/wshawk",
    "Documentation": "https://github.com/regaan/wshawk/blob/main/README.md",
}

These URLs appear on the PyPI package page, providing users with direct links to issue tracking, source code, and documentation.

README Integration

The README.md file serves as the PyPI long description, displaying formatted Markdown on the package page. This is configured in setup.py:5-6:

with open("README.md", "r", encoding="utf-8") as fh:
    long_description = fh.read()

And applied via setup.py:21-22:

long_description = long_description,
long_description_content_type = "text/markdown",

Sources: pyproject.toml:37-40, setup.py:5-6,59-63

Building the Package Locally

Build Command

Using modern Python build tools:

python -m build

This generates two artifacts in the dist/ directory:

  1. Wheel: wshawk-3.0.0-py3-none-any.whl (universal Python 3 wheel)
  2. Source Distribution: wshawk-3.0.0.tar.gz

Legacy Build Command

Using setuptools directly:

python setup.py sdist bdist_wheel

Diagram: Build System Components

graph TB
    subgraph "Configuration Files"
        PyProject["pyproject.toml<br/>[build-system]<br/>requires setuptools>=61.0"]
        Setup["setup.py<br/>setuptools.setup()"]
        Manifest["MANIFEST.in<br/>File inclusion rules"]
    end
    
    subgraph "Build Command"
        BuildCmd["python -m build"]
        BuildBackend["setuptools.build_meta"]
    end
    
    subgraph "Build Artifacts"
        Wheel["dist/wshawk-3.0.0-py3-none-any.whl<br/>Binary distribution"]
        SDist["dist/wshawk-3.0.0.tar.gz<br/>Source distribution"]
    end
    
    subgraph "Upload to PyPI"
        Twine["twine upload dist/*"]
        PyPI["pypi.org/project/wshawk"]
    end
    
    PyProject --> BuildBackend
    Setup --> BuildBackend
    Manifest --> BuildBackend
    BuildCmd --> BuildBackend
    
    BuildBackend --> Wheel
    BuildBackend --> SDist
    
    Wheel --> Twine
    SDist --> Twine
    
    Twine --> PyPI

Sources: pyproject.toml:1-4, setup.py:1-65, MANIFEST.in:1-7

Python Version Compatibility

WSHawk supports a wide range of Python versions to maximize compatibility across different environments:

Minimum Version Requirement

requires-python = ">=3.8"

Defined in pyproject.toml:13 and setup.py:39.

Tested Versions

The package explicitly declares support for:

  • Python 3.8
  • Python 3.9
  • Python 3.10
  • Python 3.11
  • Python 3.12
  • Python 3.13

This is reflected in the trove classifiers pyproject.toml:21-26 and setup.py:32-37.

Version Selection Rationale

| Python Version | Status | Rationale | |----------------|--------|-----------| | 3.8+ | Supported | Minimum for asyncio improvements and typing features | | 3.7 and below | Not supported | Missing required async features | | 3.13 | Supported | Latest stable version |

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

Security and Official Distribution

Official Source Warning

The README.md:3-14 contains a critical security notice about fake/malicious versions:

> **OFFICIAL SOURCES ONLY:**  
> - **Official Website:** `https://wshawk.rothackers.com`
> - **GitHub:** `https://github.com/regaan/wshawk`  
> - **PyPI:** `pip install wshawk`  
> - **Docker:** `docker pull rothackers/wshawk` or `ghcr.io/regaan/wshawk`

Verification Process

Users can verify authenticity by checking:

  1. PyPI Maintainer: Package maintainer should be the official GitHub account
  2. GitHub Source: Source code URL should point to github.com/regaan/wshawk
  3. Version Consistency: Version in pyproject.toml, setup.py, and CITATION.cff should match
  4. Signature: Future releases may include GPG signatures

Sources: README.md:3-14

Citation Metadata

WSHawk provides a CITATION.cff:1-19 file following the Citation File Format standard:

cff-version: 1.2.0
message: "If you use this software, please cite it as below."
authors:
- family-names: "Regaan"
  given-names: "Regaan"
  alias: "regaan"
title: "WSHawk"
version: 3.0.0
date-released: 2026-02-18
url: "https://github.com/regaan/wshawk"
repository-code: "https://github.com/regaan/wshawk"
keywords:
  - websocket
  - security
  - scanner
  - penetration-testing
  - vulnerability-scanning
license: MIT

This file enables automated citation generation for academic papers and security research referencing WSHawk.

Sources: CITATION.cff:1-19