Project Structure

Project Structure

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

Purpose and Scope

This document explains the file and directory organization of the WSHawk codebase, including package structure, configuration files, entry point definitions, and build artifacts. It is intended for developers who need to understand how the project is organized to contribute code, add features, or build from source.

For information about setting up a development environment, see Development Environment Setup. For building the package or Docker images, see Building from Source.

Package Organization Overview

WSHawk follows a standard Python package structure with the main application code in the wshawk/ directory. The project uses both modern (pyproject.toml) and legacy (setup.py) build configuration to ensure compatibility across Python packaging tools.

The package is structured as a multi-module Python application with distinct entry points for different operational modes (quick scan, interactive, advanced, defensive) and a web dashboard component with Flask-based assets.

Sources: pyproject.toml:1-58, setup.py:1-65

Directory Structure

graph TD
    Root["wshawk/ (root)"]
    
    Root --> Config["Configuration Files"]
    Root --> Package["wshawk/ (package)"]
    Root --> Docs["docs/"]
    Root --> Tests["tests/"]
    Root --> Build["Build Artifacts"]
    
    Config --> PyProject["pyproject.toml"]
    Config --> SetupPy["setup.py"]
    Config --> Manifest["MANIFEST.in"]
    Config --> GitIgnore[".gitignore"]
    Config --> License["LICENSE"]
    Config --> Readme["README.md"]
    
    Package --> Init["__init__.py"]
    Package --> Main["__main__.py"]
    Package --> ScannerV2["scanner_v2.py"]
    Package --> Interactive["interactive.py"]
    Package --> AdvCLI["advanced_cli.py"]
    Package --> DefCLI["defensive_cli.py"]
    Package --> Payloads["payloads/"]
    Package --> Web["web/"]
    Package --> OtherModules["Other Core Modules"]
    
    Payloads --> PayloadTxt["*.txt files"]
    Payloads --> PayloadJSON["*.json files"]
    
    Web --> Templates["templates/"]
    Web --> Static["static/"]
    
    Templates --> HTML["*.html files"]
    Static --> CSS["CSS/JS/Images"]
    
    Build --> Dist["dist/"]
    Build --> BuildDir["build/"]
    Build --> EggInfo["*.egg-info/"]
    Build --> Pycache["__pycache__/"]

Diagram: WSHawk Repository Directory Structure

This diagram shows the high-level organization of files and directories in the WSHawk repository. Configuration files at the root define package metadata and build behavior. The wshawk/ package contains all application code, with dedicated directories for payloads and web assets. Build artifacts are generated during packaging but excluded from version control.

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

Core Configuration Files

pyproject.toml

The primary build configuration file following PEP 621 standards. Defines project metadata, dependencies, and entry points.

| Section | Purpose | Key Contents | |---------|---------|--------------| | [build-system] | Build backend configuration | Uses setuptools>=61.0 with wheel | | [project] | Core metadata | Name, version (3.0.0), description, Python >=3.8 | | [project.dependencies] | Runtime dependencies | websockets, playwright, aiohttp, PyYAML, flask | | [project.scripts] | CLI entry points | 4 commands: wshawk, wshawk-interactive, wshawk-advanced, wshawk-defensive | | [tool.setuptools.package-data] | Packaged assets | Payload files, web templates, static files |

Sources: pyproject.toml:1-58

setup.py

Legacy setuptools configuration maintained for backward compatibility with older pip versions and build tools. Mirrors the configuration from pyproject.toml.

Key elements:

Sources: setup.py:1-65

MANIFEST.in

Controls which non-Python files are included in source distributions (sdist). This ensures that payload files, templates, and documentation are bundled with the package.

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

Sources: MANIFEST.in:1-7

Entry Points and CLI Commands

graph LR
    subgraph "Entry Point Definitions"
        PyProject["pyproject.toml<br/>[project.scripts]"]
        SetupPy["setup.py<br/>entry_points"]
    end
    
    subgraph "CLI Commands"
        CMD1["wshawk"]
        CMD2["wshawk-interactive"]
        CMD3["wshawk-advanced"]
        CMD4["wshawk-defensive"]
    end
    
    subgraph "Implementation Modules"
        Main["wshawk.__main__:cli"]
        Interactive["wshawk.interactive:cli"]
        Advanced["wshawk.advanced_cli:cli"]
        Defensive["wshawk.defensive_cli:cli"]
    end
    
    PyProject --> CMD1
    PyProject --> CMD2
    PyProject --> CMD3
    PyProject --> CMD4
    
    SetupPy --> CMD1
    SetupPy --> CMD2
    SetupPy --> CMD3
    SetupPy --> CMD4
    
    CMD1 --> Main
    CMD2 --> Interactive
    CMD3 --> Advanced
    CMD4 --> Defensive

Diagram: CLI Entry Points Mapping

This diagram shows how the four CLI commands exposed to users map to specific Python module functions. Both pyproject.toml and setup.py define identical entry points for compatibility.

Entry Point Definitions

| Command | Module Path | Function | Purpose | |---------|-------------|----------|---------| | wshawk | wshawk.__main__ | cli() | Quick scan mode with 22,000+ payloads | | wshawk-interactive | wshawk.interactive | cli() | Menu-driven interactive interface | | wshawk-advanced | wshawk.advanced_cli | cli() | Advanced features (smart payloads, Playwright) | | wshawk-defensive | wshawk.defensive_cli | cli() | Blue team validation mode |

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

Package Module Hierarchy

wshawk/init.py

The package initialization file that defines the public API and package metadata:

from .__main__ import *
from .interactive import *

__version__ = "3.0.0"
__author__ = "Regaan (@regaan)"

This imports core functionality from __main__.py and interactive.py, making them available when users import the wshawk package. The version and author metadata are accessible programmatically.

Sources: wshawk/init.py:1-10

Core Module Structure

Based on the entry point definitions and package structure, the main wshawk/ package contains:

| Module | Purpose | Entry Point | |--------|---------|-------------| | __init__.py | Package initialization, version info | - | | __main__.py | Legacy scanner, quick scan CLI | wshawk | | scanner_v2.py | WSHawkV2 core scanning engine | - | | interactive.py | Interactive menu interface | wshawk-interactive | | advanced_cli.py | Advanced mode with smart payloads | wshawk-advanced | | defensive_cli.py | Defensive validation mode | wshawk-defensive |

Additional modules (not shown in provided files but referenced in architecture diagrams):

  • resilient_session.py - ResilientSession, circuit breakers
  • rate_limiter.py - TokenBucketRateLimiter
  • payload_evolver.py - Smart payload evolution
  • vulnerability_verifier.py - Confidence scoring
  • web/app.py - Flask web dashboard
  • plugins/ - Plugin system components

Sources: wshawk/init.py:1-10, pyproject.toml:42-46

Package Data and Static Assets

graph TB
    subgraph "Package Data Configuration"
        PyProject["pyproject.toml<br/>[tool.setuptools.package-data]"]
        SetupPy["setup.py<br/>package_data"]
        Manifest["MANIFEST.in<br/>recursive-include"]
    end
    
    subgraph "Payload Files"
        PayloadDir["wshawk/payloads/"]
        PayloadTxt["*.txt files<br/>(22,000+ vectors)"]
        PayloadJSON["**/*.json files<br/>(structured payloads)"]
    end
    
    subgraph "Web Dashboard Assets"
        WebDir["wshawk/web/"]
        Templates["templates/*.html<br/>(Jinja2 templates)"]
        Static["static/*<br/>(CSS/JS/Images)"]
    end
    
    PyProject --> PayloadDir
    SetupPy --> PayloadDir
    Manifest --> PayloadDir
    
    PyProject --> WebDir
    SetupPy --> WebDir
    Manifest --> WebDir
    
    PayloadDir --> PayloadTxt
    PayloadDir --> PayloadJSON
    
    WebDir --> Templates
    WebDir --> Static

Diagram: Package Data Assets and Configuration

This diagram shows how non-Python assets are configured for inclusion in the distributed package. Three configuration files ensure these assets are bundled: pyproject.toml and setup.py for wheel distributions, and MANIFEST.in for source distributions.

Payload Collections

Located in wshawk/payloads/, these files contain the vulnerability testing vectors:

  • *.txt files: Plain text payload collections for various vulnerability types
  • **/*.json files: Structured payload definitions with metadata, potentially organized in subdirectories

The double-asterisk pattern (**/*.json) in the configuration indicates support for nested directory structures under payloads/.

Sources: pyproject.toml:52-54, setup.py:50-53, MANIFEST.in:4

Web Dashboard Assets

Located in wshawk/web/, these assets support the Flask-based management dashboard:

  • templates/*.html: Jinja2 templates for dashboard pages (scan history, reports)
  • static/*: CSS stylesheets, JavaScript, images, and other static content

Sources: pyproject.toml:55-56, setup.py:54-55, MANIFEST.in:5-6

Build System Configuration

Build Backend

WSHawk uses setuptools as the build backend with the following configuration:

[build-system]
requires = ["setuptools>=61.0", "wheel"]
build-backend = "setuptools.build_meta"
  • setuptools>=61.0: Required for pyproject.toml support (PEP 621)
  • wheel: Enables building wheel distributions (.whl files)
  • build-backend: Uses modern setuptools build interface

Sources: pyproject.toml:1-3

Package Discovery

Automatic package discovery finds all Python packages in the repository:

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

The empty find configuration uses default discovery rules, which automatically includes the wshawk/ package and any subpackages. The setup.py file explicitly excludes test directories:

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

Sources: pyproject.toml:48-49, setup.py:24

Dependency Management

Runtime Dependencies

All runtime dependencies are specified with minimum version requirements:

| Dependency | Minimum Version | Purpose | |------------|----------------|---------| | websockets | 12.0 | WebSocket protocol implementation | | playwright | 1.40.0 | Headless browser for XSS verification | | aiohttp | 3.9.0 | Async HTTP client for OAST and integrations | | PyYAML | 6.0 | Configuration file parsing | | flask | 3.0.0 | Web dashboard framework |

These dependencies are defined in both pyproject.toml and setup.py to ensure consistency.

Sources: pyproject.toml:29-35, setup.py:9-14

Python Version Compatibility

WSHawk supports Python 3.8 through 3.13:

requires-python = ">=3.8"

The classifiers in pyproject.toml explicitly list all supported minor versions: 3.8, 3.9, 3.10, 3.11, 3.12, and 3.13.

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

Ignored Artifacts and Generated Files

The .gitignore file defines patterns for files that should not be committed to version control. These fall into several categories:

Python Build Artifacts

__pycache__/
*.py[cod]
*$py.class
*.so
build/
dist/
*.egg-info/
wheels/

These are generated during package building and installation. The build/ and dist/ directories contain wheel and source distribution archives.

Sources: .gitignore:1-22

Development Environment

venv/
env/
.venv
.idea/
.vscode/

Virtual environment directories and IDE configuration folders are excluded to prevent conflicts between developers using different tools.

Sources: .gitignore:24-36

Testing Artifacts

.pytest_cache/
.coverage
htmlcov/
.tox/
.hypothesis/

Generated by testing frameworks (pytest, coverage.py, tox, hypothesis). The .hypothesis/ directory contains hypothesis testing state.

Sources: .gitignore:38-43

Runtime Artifacts

# Reports (generated during scans)
wshawk_report_*.html
reports/
!wshawk/web/templates/*.html

# Logs
*.log
logs/

# Plugin cache
.plugin_cache/

# OAST data
oast_data/
*.oast

# Session data
sessions/
*.session

# Playwright
.playwright/

These are generated during WSHawk operation:

  • Report files: HTML reports with pattern wshawk_report_*.html, but web templates are explicitly included (!wshawk/web/templates/*.html)
  • Logs: Application logs from scanning operations
  • Plugin cache: Cached plugin metadata for lazy loading
  • OAST data: Out-of-band testing data from interact.sh
  • Session data: WebSocket session state
  • Playwright: Browser automation cache and binaries

Sources: .gitignore:45-72

Sensitive Data

# Secrets (never commit)
*.key
*.pem
*.crt
secrets.json

# WSHawk Production
scans.db
scans.db-wal
scans.db-shm
wshawk.yaml
.env
.wshawk/

Critical exclusions to prevent credential leakage:

  • Cryptographic keys: Private keys and certificates
  • Database files: scans.db with WAL mode files (-wal, -shm)
  • Configuration: wshawk.yaml may contain API tokens and passwords
  • Environment files: .env with secrets
  • User directory: .wshawk/ for user-specific data

Sources: .gitignore:84-96

Export Formats

# Exported formats
*.json
*.csv
*.sarif
!pyproject.toml
!package.json

Scan exports in various formats are ignored, but project configuration files (pyproject.toml, package.json) are explicitly preserved using negation patterns.

Sources: .gitignore:98-103

Project Metadata

Package Classifiers

The package includes comprehensive PyPI classifiers for discoverability:

classifiers=[
    "Development Status :: 5 - Production/Stable",
    "Intended Audience :: Information Technology",
    "Intended Audience :: Developers",
    "Topic :: Security",
    "License :: OSI Approved :: MIT License",
    "Programming Language :: Python :: 3",
    # ... version-specific classifiers
]

These indicate production stability, target audience (security professionals, developers), and the security topic.

Sources: pyproject.toml:14-27, setup.py:25-37

Keywords and Search Terms

Keywords optimize package discoverability on PyPI:

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

These cover the tool's purpose (websocket scanner), techniques (penetration-testing, waf-bypass), vulnerability types (xss, sqli), and advanced features (playwright, oast, cvss).

Sources: pyproject.toml:28, setup.py:58

Project URLs

Three primary URLs are defined for external navigation:

| URL Type | Location | Purpose | |----------|----------|---------| | Homepage | https://github.com/regaan/wshawk | Main repository | | Bug Reports | https://github.com/regaan/wshawk/issues | Issue tracker | | Source | https://github.com/regaan/wshawk | Source code |

The setup.py file additionally links to documentation at the README.

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

Licensing

The project uses the MIT License with an additional security disclaimer:

MIT License
Copyright (c) 2025 Regaan (@regaan)

DISCLAIMER: This tool is for authorized security testing only. 
Unauthorized access to computer systems is illegal. The author 
is not responsible for any misuse of this software.

The disclaimer emphasizes that WSHawk is intended for authorized penetration testing only, limiting the author's liability for misuse.

Sources: LICENSE:1-26

Summary

The WSHawk project structure follows Python packaging best practices with:

  1. Dual configuration: Both pyproject.toml (modern) and setup.py (legacy) for maximum compatibility
  2. Multi-mode entry points: Four CLI commands for different operational modes
  3. Asset packaging: Payload files and web dashboard assets bundled with distribution
  4. Comprehensive exclusions: Extensive .gitignore prevents committing sensitive data, build artifacts, and runtime files
  5. Modern build system: Uses setuptools with automatic package discovery
  6. Production-ready metadata: Detailed classifiers, keywords, and URLs for PyPI distribution

Developers contributing to WSHawk should understand this structure to properly organize new modules, add payload files, or extend the CLI interface.

Sources: pyproject.toml:1-58, setup.py:1-65, MANIFEST.in:1-7, .gitignore:1-108, wshawk/init.py:1-10, LICENSE:1-26