Project Metadata and Citation

Project Metadata and Citation

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

This page documents the technical metadata for the WSHawk project, including version identification, authorship, citation formats, licensing, and distribution metadata. This information is essential for proper attribution, dependency management, package distribution, and academic citation.

For information about the complete version history and feature evolution, see Version History and Changelog. For details about runtime dependencies and their rationale, see Dependency Reference.

Project Identification

WSHawk's core project metadata is defined in pyproject.toml:5-27 and follows the PEP 621 standard for Python package metadata.

Core Metadata

| Attribute | Value | Source | |-----------|-------|--------| | Name | wshawk | pyproject.toml:6 | | Version | 3.0.0 | pyproject.toml:7 | | Author | Regaan | pyproject.toml:8-10 | | Status | Production/Stable | pyproject.toml:15 | | License | MIT License | pyproject.toml:19 | | Python Version | >=3.8 | pyproject.toml:13 |

Description

The official project description is defined as:

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

Source: pyproject.toml:11

This description appears on PyPI, GitHub Container Registry, and all official distribution channels.

Sources: pyproject.toml:1-27, README.md:1

Citation Information

WSHawk provides a machine-readable citation file following the Citation File Format (CFF) v1.2.0 standard for academic and research citation.

CITATION.cff Structure

graph TB
    CFF["CITATION.cff<br/>Citation File Format v1.2.0"]
    
    subgraph "Author Metadata"
        Author["family-names: Regaan<br/>given-names: Regaan<br/>alias: regaan"]
    end
    
    subgraph "Project Metadata"
        Title["title: WSHawk"]
        Version["version: 3.0.0"]
        Date["date-released: 2026-02-18"]
    end
    
    subgraph "Repository Information"
        URL["url: github.com/regaan/wshawk"]
        RepoCode["repository-code: github.com/regaan/wshawk"]
    end
    
    subgraph "Classification"
        Keywords["keywords:<br/>- websocket<br/>- security<br/>- scanner<br/>- penetration-testing<br/>- vulnerability-scanning"]
        License["license: MIT"]
    end
    
    CFF --> Author
    CFF --> Title
    CFF --> Version
    CFF --> Date
    CFF --> URL
    CFF --> RepoCode
    CFF --> Keywords
    CFF --> License

Citation Format

When citing WSHawk in academic papers, security reports, or research publications:

BibTeX Format:

@software{Regaan_WSHawk_2026,
  author = {Regaan},
  title = {WSHawk},
  version = {3.0.0},
  date = {2026-02-18},
  url = {https://github.com/regaan/wshawk},
  license = {MIT}
}

APA Format:

Regaan. (2026). WSHawk (Version 3.0.0) [Computer software]. 
https://github.com/regaan/wshawk

Chicago Format:

Regaan. WSHawk. Version 3.0.0. Computer software. February 18, 2026.
https://github.com/regaan/wshawk

The citation metadata is stored in CITATION.cff:1-19 and is automatically indexed by GitHub's citation feature and research databases like Zenodo.

Sources: CITATION.cff:1-19

Licensing

License Type

WSHawk is distributed under the MIT License, one of the most permissive open-source licenses.

| Permission | Description | |------------|-------------| | Commercial Use | Permitted for commercial applications | | Modification | Permitted to modify and create derivatives | | Distribution | Permitted to distribute original or modified versions | | Private Use | Permitted for private/internal use | | Sublicense | Permitted to grant sublicenses |

Conditions

| Condition | Requirement | |-----------|-------------| | License and Copyright Notice | Must include license and copyright notice in distributions | | Attribution | Must credit original author (Regaan) |

Limitations

| Limitation | Details | |------------|---------| | Liability | No warranty; author not liable for damages | | Warranty | No warranty provided (AS-IS) |

The full license text is available in the LICENSE file at the repository root and is included in all distribution packages via MANIFEST.in:2.

Legal Notice from README:

The author explicitly disclaims liability for misuse:

The author (Regaan) is NOT responsible for any damage caused 
by the misuse of this tool. Always obtain proper authorization 
before testing.

Source: README.md:290-298

Sources: pyproject.toml:19, CITATION.cff:18, README.md:277-279, MANIFEST.in:2

Distribution Metadata

PyPI Classifiers

WSHawk declares comprehensive PyPI classifiers for discoverability and compatibility information:

graph LR
    subgraph "Development Status"
        Status["Development Status :: 5<br/>Production/Stable"]
    end
    
    subgraph "Intended Audience"
        IT["Intended Audience ::<br/>Information Technology"]
        Dev["Intended Audience ::<br/>Developers"]
    end
    
    subgraph "Topic"
        Topic["Topic :: Security"]
    end
    
    subgraph "License Classifier"
        LicClass["License :: OSI Approved ::<br/>MIT License"]
    end
    
    subgraph "Python Versions"
        Py38["Python :: 3.8"]
        Py39["Python :: 3.9"]
        Py310["Python :: 3.10"]
        Py311["Python :: 3.11"]
        Py312["Python :: 3.12"]
        Py313["Python :: 3.13"]
    end
    
    PyPI[PyPI Package Index]
    
    PyPI --> Status
    PyPI --> IT
    PyPI --> Dev
    PyPI --> Topic
    PyPI --> LicClass
    PyPI --> Py38
    PyPI --> Py39
    PyPI --> Py310
    PyPI --> Py311
    PyPI --> Py312
    PyPI --> Py313

Full classifier list defined in pyproject.toml:14-27.

Keywords

WSHawk uses the following keywords for search engine optimization and discoverability:

| Category | Keywords | |----------|----------| | Technology | websocket | | Domain | security, penetration-testing, bug-bounty, vulnerability | | Vulnerability Types | xss, sqli, session-hijacking | | Features | cvss, playwright, oast, waf-bypass | | Tool Type | scanner |

Source: pyproject.toml:28

These keywords are identical in both pyproject.toml and CITATION.cff for consistency across distribution channels.

Sources: pyproject.toml:14-28, CITATION.cff:12-17

Repository and Distribution URLs

Official Distribution Channels

graph TB
    Source["Source Repository<br/>github.com/regaan/wshawk"]
    
    subgraph "Python Distribution"
        PyPI["PyPI<br/>pypi.org/project/wshawk"]
        PipInstall["pip install wshawk"]
    end
    
    subgraph "Container Distribution"
        DockerHub["Docker Hub<br/>rothackers/wshawk"]
        GHCR["GitHub Container Registry<br/>ghcr.io/regaan/wshawk"]
    end
    
    subgraph "Documentation"
        Homepage["Homepage<br/>github.com/regaan/wshawk"]
        Issues["Bug Reports<br/>github.com/regaan/wshawk/issues"]
    end
    
    Source --> PyPI
    Source --> DockerHub
    Source --> GHCR
    
    PyPI --> PipInstall
    
    Source --> Homepage
    Source --> Issues

URL Mapping

| URL Type | Value | Defined In | |----------|-------|------------| | Homepage | https://github.com/regaan/wshawk | pyproject.toml:38 | | Bug Reports | https://github.com/regaan/wshawk/issues | pyproject.toml:39 | | Source Repository | https://github.com/regaan/wshawk | pyproject.toml:40 | | Official Website | https://wshawk.rothackers.com | README.md:9 | | PyPI Package | https://pypi.org/project/wshawk | (implicit) | | Docker Hub | https://hub.docker.com/r/rothackers/wshawk | README.md:12 | | GHCR | https://ghcr.io/regaan/wshawk | README.md:12, .github/workflows/ghcr-publish.yml:12-13 |

Sources: pyproject.toml:37-40, README.md:8-14, .github/workflows/ghcr-publish.yml:12-13

Package Configuration

Dependencies

WSHawk declares five core runtime dependencies:

| Dependency | Minimum Version | Purpose | |------------|-----------------|---------| | websockets | 12.0 | WebSocket protocol implementation | | playwright | 1.40.0 | Browser automation 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 backend |

Source: pyproject.toml:29-35

For detailed dependency rationale and version constraints, see Dependency Reference.

CLI Entry Points

WSHawk registers four CLI commands as console scripts:

graph LR
    subgraph "pyproject.toml[project.scripts]"
        EP1["wshawk =<br/>wshawk.__main__:cli"]
        EP2["wshawk-interactive =<br/>wshawk.interactive:cli"]
        EP3["wshawk-advanced =<br/>wshawk.advanced_cli:cli"]
        EP4["wshawk-defensive =<br/>wshawk.defensive_cli:cli"]
    end
    
    subgraph "Installed Commands"
        CMD1["/usr/local/bin/wshawk"]
        CMD2["/usr/local/bin/wshawk-interactive"]
        CMD3["/usr/local/bin/wshawk-advanced"]
        CMD4["/usr/local/bin/wshawk-defensive"]
    end
    
    EP1 --> CMD1
    EP2 --> CMD2
    EP3 --> CMD3
    EP4 --> CMD4
    
    CMD1 --> Quick["Quick Scan + Web Dashboard"]
    CMD2 --> Interactive["Menu-Driven Interface"]
    CMD3 --> Advanced["Full-Featured Scanner"]
    CMD4 --> Defensive["Blue Team Validation"]

Entry point definitions in pyproject.toml:42-46 map to executable functions in the codebase:

| Command | Module Path | Function | |---------|-------------|----------| | wshawk | wshawk.__main__ | cli() | | wshawk-interactive | wshawk.interactive | cli() | | wshawk-advanced | wshawk.advanced_cli | cli() | | wshawk-defensive | wshawk.defensive_cli | cli() |

Package Data

WSHawk includes non-Python assets in the distribution package:

graph TB
    Package["wshawk package<br/>[tool.setuptools.package-data]"]
    
    subgraph "Payload Collections"
        PayloadTxt["payloads/*.txt<br/>22,000+ static vectors"]
        PayloadJSON["payloads/**/*.json<br/>Structured payloads"]
    end
    
    subgraph "Web Dashboard Assets"
        Templates["web/templates/*.html<br/>Jinja2 templates"]
        Static["web/static/*<br/>CSS, JS, images"]
    end
    
    Package --> PayloadTxt
    Package --> PayloadJSON
    Package --> Templates
    Package --> Static

Package data specification in pyproject.toml:51-57 ensures these assets are included in:

  • PyPI wheel distributions
  • Source distributions (sdist)
  • Docker container images

The MANIFEST.in file at MANIFEST.in:1-7 provides redundant inclusion rules for compatibility with older build systems.

Sources: pyproject.toml:29-57, MANIFEST.in:1-7

Publishing and Distribution

Multi-Channel Distribution Architecture

graph TB
    subgraph "Source Control"
        GitHub["GitHub Repository<br/>regaan/wshawk<br/>Tags: v3.0.0"]
    end
    
    subgraph "Build Metadata"
        PyProject["pyproject.toml<br/>version: 3.0.0<br/>name: wshawk"]
        Manifest["MANIFEST.in<br/>Asset inclusion"]
        Citation["CITATION.cff<br/>date-released: 2026-02-18"]
    end
    
    subgraph "CI/CD Pipeline"
        GHCRWorkflow[".github/workflows/<br/>ghcr-publish.yml<br/>Triggers: push, tags, workflow_dispatch"]
    end
    
    subgraph "Distribution Registries"
        PyPIReg["PyPI Registry<br/>pip install wshawk<br/>Version: 3.0.0"]
        DockerHubReg["Docker Hub<br/>rothackers/wshawk:3.0.0<br/>rothackers/wshawk:latest"]
        GHCRReg["GitHub Container Registry<br/>ghcr.io/regaan/wshawk:3.0.0<br/>ghcr.io/regaan/wshawk:latest"]
    end
    
    GitHub --> PyProject
    GitHub --> Manifest
    GitHub --> Citation
    GitHub --> GHCRWorkflow
    
    PyProject --> PyPIReg
    Manifest --> PyPIReg
    
    GHCRWorkflow --> GHCRReg
    GHCRWorkflow --> DockerHubReg
    
    PyProject -.->|"version metadata"| GHCRWorkflow

GitHub Container Registry Publishing

The GHCR publishing workflow is defined in .github/workflows/ghcr-publish.yml:1-50.

Trigger Conditions:

  • Push to main branch
  • Tag creation matching v* pattern
  • Manual workflow_dispatch trigger

Tag Generation Strategy:

| Input Tag | Generated Tags | Example | |-----------|---------------|---------| | v3.0.0 | 3.0.0, 3.0, latest | Semantic version release | | Push to main | latest | Continuous deployment | | Other branches | (none) | Development branches ignored |

Tag pattern logic defined in .github/workflows/ghcr-publish.yml:38-41:

tags: |
  type=raw,value=latest,enable={{is_default_branch}}
  type=semver,pattern={{version}}
  type=semver,pattern={{major}}.{{minor}}

Registry Authentication:

  • Registry: ghcr.io (.github/workflows/ghcr-publish.yml:12)
  • Image Name: ${{ github.repository }} → regaan/wshawk
  • Username: ${{ github.actor }} (GitHub Actions bot)
  • Password: ${{ secrets.GITHUB_TOKEN }} (automatic GitHub token)

Permissions:

  • contents: read - Read repository source code
  • packages: write - Push to GitHub Container Registry

Source: .github/workflows/ghcr-publish.yml:18-20

Version Synchronization

All distribution channels use the same version number sourced from pyproject.toml:7:

| Distribution Channel | Version Source | Format | |---------------------|----------------|--------| | PyPI | pyproject.toml version field | 3.0.0 | | Docker Hub | Git tag (v*) via metadata extraction | 3.0.0, 3.0, latest | | GHCR | Git tag (v*) via metadata extraction | 3.0.0, 3.0, latest | | CITATION.cff | Manual synchronization | 3.0.0 |

Sources: pyproject.toml:7, CITATION.cff:8, .github/workflows/ghcr-publish.yml:34-41

Metadata Files Cross-Reference

File Relationships

graph TB
    subgraph "Build Configuration"
        PyProject["pyproject.toml<br/>[project] metadata<br/>[tool.setuptools] config"]
        Manifest["MANIFEST.in<br/>Asset inclusion rules"]
    end
    
    subgraph "Citation & Documentation"
        Citation["CITATION.cff<br/>Academic citation format"]
        README["README.md<br/>Human-readable docs"]
    end
    
    subgraph "CI/CD"
        GHCR["ghcr-publish.yml<br/>Container publishing"]
    end
    
    subgraph "Output Artifacts"
        Wheel["wshawk-3.0.0-py3-none-any.whl<br/>Python wheel"]
        Tarball["wshawk-3.0.0.tar.gz<br/>Source distribution"]
        Container["ghcr.io/regaan/wshawk:3.0.0<br/>Container image"]
    end
    
    PyProject -->|"setuptools build"| Wheel
    PyProject -->|"setuptools sdist"| Tarball
    Manifest -->|"asset inclusion"| Wheel
    Manifest -->|"asset inclusion"| Tarball
    
    GHCR -->|"docker build"| Container
    PyProject -.->|"metadata reference"| GHCR
    
    Citation -.->|"sync version"| PyProject
    README -.->|"documents"| PyProject

Metadata Consistency Table

| Attribute | pyproject.toml | CITATION.cff | README.md | |-----------|----------------|--------------|-----------| | Version | 3.0.0 | 3.0.0 | v3.0.0 | | Author | Regaan | Regaan (alias: regaan) | Regaan (@regaan) | | License | MIT License | MIT | MIT License | | Repository | github.com/.../wshawk | github.com/.../wshawk | github.com/.../wshawk | | Keywords | 13 keywords | 5 keywords | Embedded in features |

Sources: pyproject.toml:1-57, CITATION.cff:1-19, README.md:1-311, MANIFEST.in:1-7, .github/workflows/ghcr-publish.yml:1-50