Security Policy and Vulnerability Disclosure

Security Policy and Vulnerability Disclosure

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

Purpose and Scope

This document defines the security policy for WSHawk itself as a software tool, the process for reporting security vulnerabilities in WSHawk, and the legal requirements for using WSHawk responsibly. This policy covers:

  • Official distribution channels and protection against malicious versions
  • How to report security vulnerabilities in the WSHawk codebase
  • Responsible disclosure procedures
  • Legal disclaimers and authorization requirements for testing

For information about vulnerabilities that WSHawk detects in target applications, see Vulnerability Detection Overview. For defensive validation of security controls, see Defensive Mode Overview.

Sources: README.md:1-310

Critical Security Warning: Fake Versions and Malware

WSHawk has been repackaged and distributed through unauthorized channels with malicious code injected. Users must download only from official sources.

Official Distribution Channels

| Channel | URL/Command | Purpose | |---------|-------------|---------| | Official Website | https://wshawk.rothackers.com | Primary documentation and information | | GitHub Repository | https://github.com/regaan/wshawk | Source code, releases, and issue tracking | | PyPI | pip install wshawk | Python package installation | | Docker Hub | docker pull rothackers/wshawk | Public container registry | | GitHub Container Registry | docker pull ghcr.io/regaan/wshawk | GitHub-integrated registry |

Threat Model: Fake Distribution Vectors

graph TB
    subgraph "Legitimate Sources"
        GitHub["GitHub Repository<br/>github.com/regaan/wshawk"]
        PyPI["PyPI Registry<br/>pypi.org/project/wshawk"]
        DockerHub["Docker Hub<br/>rothackers/wshawk"]
        GHCR["GitHub Container Registry<br/>ghcr.io/regaan/wshawk"]
    end
    
    subgraph "Threat Vectors - DO NOT USE"
        ThirdParty["Third-Party Download Sites<br/>softonic.com, filehippo.com, etc"]
        Social["Social Media Links<br/>LinkedIn, Twitter Posts"]
        Torrents["Torrent Sites<br/>Peer-to-peer networks"]
        Mirrors["Unofficial Mirrors<br/>Repackaged versions"]
    end
    
    subgraph "Risk Categories"
        Malware["Malware Injection<br/>Backdoors, Keyloggers<br/>Data Exfiltration"]
        Trojan["Trojanized Code<br/>Modified scanner logic<br/>Credential theft"]
        Supply["Supply Chain Attack<br/>Compromised dependencies<br/>Malicious plugins"]
    end
    
    User[Security Professional]
    
    User -->|"SAFE"| GitHub
    User -->|"SAFE"| PyPI
    User -->|"SAFE"| DockerHub
    User -->|"SAFE"| GHCR
    
    User -.->|"DANGEROUS"| ThirdParty
    User -.->|"DANGEROUS"| Social
    User -.->|"DANGEROUS"| Torrents
    User -.->|"DANGEROUS"| Mirrors
    
    ThirdParty --> Malware
    Social --> Malware
    Torrents --> Trojan
    Mirrors --> Supply

Diagram: Official vs. Malicious Distribution Channels

Verification Procedures

PyPI Package Verification:

# Verify package source
pip show wshawk

# Expected output includes:
# Name: wshawk
# Location: /path/to/site-packages
# Home-page: https://github.com/regaan/wshawk
# Author: Regaan

Docker Image Verification:

# Verify image provenance
docker image inspect rothackers/wshawk:latest | grep -A 5 Labels

# Expected registry for official images:
# - Docker Hub: index.docker.io/rothackers/wshawk
# - GHCR: ghcr.io/regaan/wshawk

GitHub Release Verification: All official releases are tagged with version numbers (e.g., v3.0.0) and include:

  • Release notes with SHA-256 checksums
  • Signed commits (where available)
  • Official release announcements

Sources: README.md:3-14, README.md:53-81

WSHawk Security Policy

This section addresses security vulnerabilities in WSHawk itself, not in target applications being scanned.

In-Scope Security Issues

The following security issues in WSHawk are in scope for responsible disclosure:

| Category | Examples | |----------|----------| | Authentication Bypass | Bypassing WSHAWK_WEB_PASSWORD protection in web dashboard | | Privilege Escalation | Gaining unauthorized access to scan history or reports | | Code Injection | Injecting malicious code through plugin system, configuration files, or user inputs | | Path Traversal | Accessing files outside intended directories through report paths or plugin loading | | SQL Injection | Exploiting database queries in scans.db persistence layer | | Credential Exposure | Leaking secrets from wshawk.yaml or environment variables | | Denial of Service | Causing WSHawk to crash or consume excessive resources | | Container Escape | Breaking out of Docker container isolation | | Dependency Vulnerabilities | Known CVEs in dependencies (websockets, playwright, flask, etc.) |

Out-of-Scope Issues

The following are NOT security vulnerabilities in WSHawk:

  • Expected functionality: WSHawk is designed to test WebSocket endpoints aggressively
  • Target application issues: Vulnerabilities found in scanned applications (these should be reported to those application owners)
  • Rate limiting: Servers blocking WSHawk due to aggressive scanning
  • Detection by WAFs/IDS: Security systems detecting WSHawk as an attack tool (this is expected)
  • Social engineering: User error in targeting unauthorized systems

WSHawk Security Architecture

graph TB
    subgraph "External Attack Surface"
        WebUI["Web Dashboard<br/>Flask App<br/>Port 5000/configurable"]
        API["REST API<br/>POST /api/scans<br/>GET /api/scans"]
        CLI["CLI Entrypoints<br/>wshawk, wshawk-advanced<br/>Command-line args"]
    end
    
    subgraph "Authentication Layer"
        PasswordAuth["Password Authentication<br/>WSHAWK_WEB_PASSWORD<br/>SHA-256 hashing<br/>wshawk/web/app.py"]
        APIKeyAuth["API Key Authentication<br/>WSHAWK_API_KEY<br/>Header-based auth"]
    end
    
    subgraph "Input Validation"
        URLVal["URL Validation<br/>ws:// or wss:// schemes<br/>scanner_v2.py"]
        ConfigVal["Config Validation<br/>wshawk.yaml parsing<br/>Secret resolution<br/>config.py"]
        PluginVal["Plugin Validation<br/>PluginManager<br/>Metadata checks<br/>plugins/plugin_manager.py"]
    end
    
    subgraph "Isolation Boundaries"
        Container["Docker Container<br/>Non-root user wshawk:1000<br/>--read-only support<br/>Dockerfile"]
        FS["Filesystem Isolation<br/>Restricted write paths<br/>/app/reports/<br/>/app/scans.db"]
        Network["Network Isolation<br/>Outbound only<br/>No listening services<br/>except web dashboard"]
    end
    
    subgraph "Data Protection"
        DB["SQLite Database<br/>scans.db<br/>WAL mode<br/>Local file only"]
        Reports["Report Files<br/>HTML/JSON/CSV/SARIF<br/>Restricted directory"]
        Secrets["Secret Storage<br/>Environment variables<br/>File-based secrets<br/>Never in plaintext logs"]
    end
    
    subgraph "Dependency Security"
        Deps["Python Dependencies<br/>websockets<br/>playwright<br/>flask<br/>aiohttp"]
        Updates["Version Pinning<br/>setup.py<br/>requirements.txt"]
    end
    
    WebUI --> PasswordAuth
    API --> APIKeyAuth
    API --> PasswordAuth
    CLI --> URLVal
    CLI --> ConfigVal
    
    PasswordAuth --> InputValidation
    APIKeyAuth --> InputValidation
    URLVal --> PluginVal
    ConfigVal --> PluginVal
    
    PluginVal --> Container
    Container --> FS
    Container --> Network
    
    InputValidation --> DB
    InputValidation --> Reports
    ConfigVal --> Secrets
    
    Container --> Deps
    Deps --> Updates

Diagram: WSHawk Internal Security Architecture

Sources: README.md:121-127, README.md:289-297

Vulnerability Disclosure Process

Reporting a Security Vulnerability

If you discover a security vulnerability in WSHawk itself, please follow this responsible disclosure process:

Step 1: Private Disclosure

  • DO NOT open a public GitHub issue
  • DO NOT disclose the vulnerability publicly until it has been addressed
  • Email: support@rothackers.com with subject: [SECURITY] WSHawk Vulnerability Report

Step 2: Include Required Information

Your report should include:

| Field | Description | |-------|-------------| | Vulnerability Type | (e.g., Authentication Bypass, SQL Injection, Path Traversal) | | Affected Component | (e.g., wshawk/web/app.py, wshawk/scanner_v2.py, Docker image) | | Affected Versions | (e.g., v3.0.0, v2.x, all versions) | | Attack Vector | How to trigger the vulnerability | | Impact | What an attacker could achieve | | Proof of Concept | Code or commands to reproduce | | CVSS Score | (optional but helpful) | | Suggested Fix | (optional but appreciated) |

Example Report Template:

Subject: [SECURITY] WSHawk Vulnerability Report

Vulnerability Type: SQL Injection in Scan History
Affected Component: wshawk/web/app.py, line 145
Affected Versions: v3.0.0
Attack Vector: Crafted scan ID parameter in GET /api/scans/{id}

Description:
The scan ID parameter is not properly sanitized before being used in
a SQL query, allowing an attacker to execute arbitrary SQL commands.

Proof of Concept:
curl -X GET "http://localhost:5000/api/scans/1' OR '1'='1"

Impact:
- Read all scan history data
- Potentially modify or delete database records
- Extract WSHAWK_WEB_PASSWORD hash

CVSS v3.1 Score: 8.1 (High)
Vector: CVSS:3.1/AV:N/AC:L/PR:L/UI:N/S:U/C:H/I:H/A:N

Suggested Fix:
Use parameterized queries or ORM instead of string concatenation.

Disclosure Timeline

graph LR
    Report["Day 0<br/>Security Report<br/>Received"]
    Ack["Day 1-2<br/>Acknowledgment<br/>Severity Assessment"]
    Triage["Day 3-7<br/>Triage & Validation<br/>PoC Verification"]
    Fix["Day 8-30<br/>Fix Development<br/>Testing"]
    Review["Day 31-45<br/>Security Review<br/>Beta Testing"]
    Release["Day 46-60<br/>Patched Release<br/>CVE Assignment"]
    Public["Day 61-90<br/>Public Disclosure<br/>Advisory Published"]
    
    Report --> Ack
    Ack --> Triage
    Triage --> Fix
    Fix --> Review
    Review --> Release
    Release --> Public

Diagram: Vulnerability Disclosure Timeline

Expected Response Times

| Severity | Acknowledgment | Initial Triage | Patch Release | Public Disclosure | |----------|----------------|----------------|---------------|-------------------| | Critical | 24 hours | 3 days | 14-30 days | 60 days | | High | 48 hours | 7 days | 30-45 days | 90 days | | Medium | 72 hours | 14 days | 45-60 days | 120 days | | Low | 1 week | 30 days | Next release | Next release |

Critical severity: Authentication bypass, remote code execution, credential theft, container escape

High severity: SQL injection, privilege escalation, sensitive data exposure

Medium severity: Denial of service, information disclosure (non-sensitive)

Low severity: Security configuration issues, dependency version updates

Coordinated Disclosure

  • Embargo Period: We request a 60-90 day embargo period to develop and release a patch
  • CVE Assignment: For vulnerabilities with CVSS >= 7.0, we will request a CVE identifier
  • Security Advisory: A public security advisory will be published after patch release
  • Credits: Researchers who follow responsible disclosure will be credited in release notes

Bug Bounty

WSHawk is an open-source project without a formal bug bounty program. However:

  • We deeply appreciate responsible disclosure
  • Researchers will be credited in SECURITY.md and release notes
  • Significant findings may be highlighted in project documentation

Sources: .github/ISSUE_TEMPLATE/bug_report.md:1-88

Responsible Use Policy

WSHawk is a security testing tool designed for authorized use only. Users must comply with all applicable laws and regulations.

Authorization Requirements

| Requirement | Description | |-------------|-------------| | Written Permission | Obtain explicit written authorization from the system owner before scanning | | Scope Definition | Clearly define what systems, IP ranges, and domains are authorized for testing | | Time Windows | Respect agreed-upon testing time windows and maintenance schedules | | Rate Limits | Configure appropriate rate limits to avoid service disruption | | Data Handling | Follow data protection regulations for any sensitive data encountered |

Authorized Use Cases

WSHawk is designed for:

1. Authorized Penetration Testing

  • Contracted security assessments with written authorization
  • Internal security testing of your own infrastructure
  • Red team exercises with documented approval

2. Bug Bounty Programs

  • Testing within published bug bounty program scope
  • Following platform-specific rules (HackerOne, Bugcrowd, etc.)
  • Respecting out-of-scope domains and vulnerability types

3. Security Research

  • Academic research with IRB approval
  • Responsible disclosure to affected vendors
  • Educational purposes with lab environments

4. Development and Testing

  • Testing your own WebSocket applications during development
  • Security validation in CI/CD pipelines
  • Defensive validation of your own production systems

Prohibited Activities

WSHawk must NOT be used for:

  • Unauthorized testing of third-party systems
  • Malicious attacks or data theft
  • Competitive intelligence gathering
  • Disruption of services (DoS attacks)
  • Violation of computer fraud and abuse laws (e.g., CFAA, Computer Misuse Act)

Defensive Validation Mode

The wshawk-defensive command is specifically designed for blue teams to validate their own security controls. This mode:

  • Tests DNS exfiltration prevention
  • Validates bot detection effectiveness
  • Checks CSWSH protections
  • Verifies WSS protocol security

Defensive mode should only be used against your own infrastructure.

Sources: README.md:267-297

Legal Disclaimer

Liability and Disclaimer

WSHawk is provided "AS IS" without warranty of any kind, express or implied.

  • Authorization: Users must obtain explicit permission before scanning any system
  • Liability: The author (Regaan) and contributors are NOT responsible for any damage, legal consequences, or misuse of this tool
  • Compliance: Users are responsible for complying with all applicable laws, regulations, and organizational policies
  • Third-Party Systems: Scanning systems without authorization may violate computer fraud and abuse laws in your jurisdiction

Not Malware

WSHawk is a legitimate security testing tool, not malware. Key distinctions:

| Characteristic | WSHawk (Legitimate Tool) | Malware | |----------------|--------------------------|---------| | Purpose | Security testing with authorization | Unauthorized malicious activity | | Distribution | Official channels (PyPI, GitHub, Docker Hub) | Third-party sites, email attachments | | Code Visibility | Open source, auditable | Obfuscated, hidden functionality | | Installation | Standard package managers | Drive-by downloads, exploits | | Behavior | Transparent scanning with logs and reports | Covert data exfiltration |

Any repackaged version of WSHawk containing malicious code is NOT associated with this project.

Terms of Use

By using WSHawk, you agree to:

  1. Obtain proper authorization before testing any system
  2. Use responsibly within legal and ethical boundaries
  3. Not modify the tool to bypass security controls or hide malicious activity
  4. Not redistribute modified versions without clear attribution and licensing compliance
  5. Accept full responsibility for your actions and any consequences

Sources: README.md:289-297

Contact Information

Security Contact

Primary Security Contact:

  • Email: support@rothackers.com
  • Subject Line: [SECURITY] WSHawk Vulnerability Report
  • Expected Response: 24-72 hours depending on severity

GitHub Security

For non-critical security issues that don't require confidentiality:

Community Support

General Questions:

Author:

Issue Templates

WSHawk provides structured issue templates for different report types:

Bug Reports: .github/ISSUE_TEMPLATE/bug_report.md

  • Version information
  • Steps to reproduce
  • Expected vs. actual behavior
  • System environment details

Feature Requests: .github/ISSUE_TEMPLATE/feature_request.md

  • Problem statement
  • Proposed solution
  • Use case examples

Questions/Discussions: .github/ISSUE_TEMPLATE/-question-or-discussion.md

  • General questions
  • Usage guidance
  • Best practices

Sources: README.md:299-304, .github/ISSUE_TEMPLATE/bug_report.md:1-88, .github/ISSUE_TEMPLATE/feature_request.md:1-55, .github/ISSUE_TEMPLATE/-question-or-discussion.md:1-37

Security Update Process

Receiving Security Updates

GitHub Watch/Notifications:

  • Watch the repository for release notifications
  • Star the project to receive updates in your feed
  • Subscribe to release notifications

Container Image Updates:

  • Docker Hub automatically tags new versions
  • Use :latest tag for automatic updates (not recommended for production)
  • Pin to specific versions (e.g., :3.0.0) for stability

PyPI Package Updates:

# Check for updates
pip list --outdated | grep wshawk

# Upgrade to latest version
pip install --upgrade wshawk

Security Patch Releases

Security patches follow semantic versioning:

  • Major vulnerabilities: Immediate patch release (e.g., 3.0.0 → 3.0.1)
  • Minor issues: Bundled into next minor release (e.g., 3.0.x → 3.1.0)
  • Backports: Critical patches may be backported to previous major versions

CI/CD Integration Security

The GitHub Actions workflows include security measures:

Docker Build Workflow: .github/workflows/ghcr-publish.yml

  • Automated builds on push and tags
  • Multi-registry publishing (Docker Hub, GHCR)
  • Semantic versioning tags

Image Signing (Future):

  • Planned: Cosign signatures for container images
  • Planned: SBOM (Software Bill of Materials) generation

Sources: .github/workflows/ghcr-publish.yml:1-50

Compliance and Certifications

Open Source License

WSHawk is released under the MIT License, which:

  • Permits commercial use
  • Allows modification and distribution
  • Requires attribution
  • Provides no warranty

License File: LICENSE

Dependency Security

WSHawk dependencies are regularly updated for security patches. Key dependencies:

| Dependency | Purpose | Security Considerations | |------------|---------|------------------------| | websockets | WebSocket client library | Transport layer security, protocol handling | | playwright | Browser automation | Sandbox isolation, chromium security | | flask | Web dashboard | Authentication, XSS prevention, CSRF tokens | | aiohttp | HTTP client for integrations | TLS verification, timeout handling | | pyyaml | Configuration parsing | Safe loading to prevent code execution | | cryptography | Password hashing | SHA-256 for password storage |

For a complete list of dependencies and their versions, see Dependency Reference.

Sources: README.md:17-21

Summary

This security policy establishes clear guidelines for:

  1. Downloading safely: Only use official distribution channels to avoid malware
  2. Reporting vulnerabilities: Follow responsible disclosure through support@rothackers.com
  3. Using responsibly: Obtain authorization before testing any system
  4. Understanding liability: Users accept full responsibility for their actions

WSHawk is a powerful security testing tool that must be used ethically and legally. The project maintainers are committed to:

  • Promptly addressing security vulnerabilities
  • Maintaining transparency through public advisories
  • Supporting the security community through responsible disclosure
  • Protecting users from malicious repackaged versions

For additional guidance on using WSHawk features, see:

Sources: README.md:1-310