Security Policy and Vulnerability Disclosure

Security Policy and Vulnerability Disclosure

Relevant source files

Purpose and Scope

This page documents WSHawk's security policy, including which versions receive security patches, the process for responsibly reporting security vulnerabilities, expected response timelines, and disclosure workflows. This policy applies to vulnerabilities discovered in the WSHawk codebase itself, not in target WebSocket applications being tested.

For general bug reporting (non-security issues), see Issue Reporting and Templates. For community behavioral standards when reporting issues, see Code of Conduct.

Sources: SECURITY.md L1-L56

Supported Versions

WSHawk maintains security patches for specific version branches. The project follows semantic versioning, with security support focused on recent major releases.

Version Support Matrix

| Version | Security Support | Status | | --- | --- | --- | | 2.0.x | ✅ Active support | Current stable branch receiving security patches | | < 1.0 | ❌ Unsupported | Legacy versions, no security patches provided |

Policy Details:

  • The current stable branch (2.0.x) receives all security patches
  • Legacy versions prior to 1.0 are no longer supported
  • When major version 3.0 is released, support policy for 2.0.x will be re-evaluated
  • Users should upgrade to the latest 2.0.x release to receive security fixes

Sources: SECURITY.md L3-L10

Vulnerability Reporting Process

WSHawk uses a private disclosure channel for security vulnerabilities to prevent exploitation before patches are available. Public issue trackers should not be used for security reports.

Communication Channel

Primary Contact: security@rothackers.com

This email address is monitored by project maintainers and is the exclusive channel for security vulnerability reports. Do not use GitHub Issues or Discussions for security-sensitive reports.

Required Information

When submitting a security report, include the following details to facilitate rapid triage and remediation:

| Field | Description | Example | | --- | --- | --- | | Description | Clear explanation of the vulnerability | "Command injection in payload mutation engine allows arbitrary code execution" | | Steps to Reproduce | Precise reproduction steps | "1. Run wshawk ws://target with custom config 2. Inject payload via..." | | Potential Impact | Security implications | "Remote code execution on scanner host, CVSS 9.8" | | Suggested Fix | Optional remediation approach | "Sanitize user input in wshawk/mutators/base.py:45-60" | | WSHawk Version | Affected version(s) | "2.0.5" or "2.0.x branch" | | Environment | OS, Python version, deployment | "Ubuntu 22.04, Python 3.11, Docker container" |

Sources: SECURITY.md L12-L24

CONTRIBUTING.md L129-L133

Response Timeline and Process

Expected Response Timeline

#mermaid-yt9v8jesn8d{font-family:ui-sans-serif,-apple-system,system-ui,Segoe UI,Helvetica;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-yt9v8jesn8d .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-yt9v8jesn8d .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-yt9v8jesn8d .error-icon{fill:#dddddd;}#mermaid-yt9v8jesn8d .error-text{fill:#222222;stroke:#222222;}#mermaid-yt9v8jesn8d .edge-thickness-normal{stroke-width:1px;}#mermaid-yt9v8jesn8d .edge-thickness-thick{stroke-width:3.5px;}#mermaid-yt9v8jesn8d .edge-pattern-solid{stroke-dasharray:0;}#mermaid-yt9v8jesn8d .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-yt9v8jesn8d .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-yt9v8jesn8d .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-yt9v8jesn8d .marker{fill:#999;stroke:#999;}#mermaid-yt9v8jesn8d .marker.cross{stroke:#999;}#mermaid-yt9v8jesn8d svg{font-family:ui-sans-serif,-apple-system,system-ui,Segoe UI,Helvetica;font-size:16px;}#mermaid-yt9v8jesn8d p{margin:0;}#mermaid-yt9v8jesn8d .mermaid-main-font{font-family:ui-sans-serif,-apple-system,system-ui,Segoe UI,Helvetica;}#mermaid-yt9v8jesn8d .exclude-range{fill:#eeeeee;}#mermaid-yt9v8jesn8d .section{stroke:none;opacity:0.2;}#mermaid-yt9v8jesn8d .section0{fill:#dddddd;}#mermaid-yt9v8jesn8d .section2{fill:#eaeaea;}#mermaid-yt9v8jesn8d .section1,#mermaid-yt9v8jesn8d .section3{fill:white;opacity:0.2;}#mermaid-yt9v8jesn8d .sectionTitle0{fill:#444;}#mermaid-yt9v8jesn8d .sectionTitle1{fill:#444;}#mermaid-yt9v8jesn8d .sectionTitle2{fill:#444;}#mermaid-yt9v8jesn8d .sectionTitle3{fill:#444;}#mermaid-yt9v8jesn8d .sectionTitle{text-anchor:start;font-family:ui-sans-serif,-apple-system,system-ui,Segoe UI,Helvetica;}#mermaid-yt9v8jesn8d .grid .tick{stroke:lightgrey;opacity:0.8;shape-rendering:crispEdges;}#mermaid-yt9v8jesn8d .grid .tick text{font-family:ui-sans-serif,-apple-system,system-ui,Segoe UI,Helvetica;fill:#333;}#mermaid-yt9v8jesn8d .grid path{stroke-width:0;}#mermaid-yt9v8jesn8d .today{fill:none;stroke:red;stroke-width:2px;}#mermaid-yt9v8jesn8d .task{stroke-width:2;}#mermaid-yt9v8jesn8d .taskText{text-anchor:middle;font-family:ui-sans-serif,-apple-system,system-ui,Segoe UI,Helvetica;}#mermaid-yt9v8jesn8d .taskTextOutsideRight{fill:#333;text-anchor:start;font-family:ui-sans-serif,-apple-system,system-ui,Segoe UI,Helvetica;}#mermaid-yt9v8jesn8d .taskTextOutsideLeft{fill:#333;text-anchor:end;}#mermaid-yt9v8jesn8d .task.clickable{cursor:pointer;}#mermaid-yt9v8jesn8d .taskText.clickable{cursor:pointer;fill:#003163!important;font-weight:bold;}#mermaid-yt9v8jesn8d .taskTextOutsideLeft.clickable{cursor:pointer;fill:#003163!important;font-weight:bold;}#mermaid-yt9v8jesn8d .taskTextOutsideRight.clickable{cursor:pointer;fill:#003163!important;font-weight:bold;}#mermaid-yt9v8jesn8d .taskText0,#mermaid-yt9v8jesn8d .taskText1,#mermaid-yt9v8jesn8d .taskText2,#mermaid-yt9v8jesn8d .taskText3{fill:#333;}#mermaid-yt9v8jesn8d .task0,#mermaid-yt9v8jesn8d .task1,#mermaid-yt9v8jesn8d .task2,#mermaid-yt9v8jesn8d .task3{fill:#eaeaea;stroke:#ccc;}#mermaid-yt9v8jesn8d .taskTextOutside0,#mermaid-yt9v8jesn8d .taskTextOutside2{fill:#333;}#mermaid-yt9v8jesn8d .taskTextOutside1,#mermaid-yt9v8jesn8d .taskTextOutside3{fill:#333;}#mermaid-yt9v8jesn8d .active0,#mermaid-yt9v8jesn8d .active1,#mermaid-yt9v8jesn8d .active2,#mermaid-yt9v8jesn8d .active3{fill:hsl(0, 0%, 100%);stroke:#eaeaea;}#mermaid-yt9v8jesn8d .activeText0,#mermaid-yt9v8jesn8d .activeText1,#mermaid-yt9v8jesn8d .activeText2,#mermaid-yt9v8jesn8d .activeText3{fill:#333!important;}#mermaid-yt9v8jesn8d .done0,#mermaid-yt9v8jesn8d .done1,#mermaid-yt9v8jesn8d .done2,#mermaid-yt9v8jesn8d .done3{stroke:grey;fill:lightgrey;stroke-width:2;}#mermaid-yt9v8jesn8d .doneText0,#mermaid-yt9v8jesn8d .doneText1,#mermaid-yt9v8jesn8d .doneText2,#mermaid-yt9v8jesn8d .doneText3{fill:#333!important;}#mermaid-yt9v8jesn8d .crit0,#mermaid-yt9v8jesn8d .crit1,#mermaid-yt9v8jesn8d .crit2,#mermaid-yt9v8jesn8d .crit3{stroke:#ff8888;fill:red;stroke-width:2;}#mermaid-yt9v8jesn8d .activeCrit0,#mermaid-yt9v8jesn8d .activeCrit1,#mermaid-yt9v8jesn8d .activeCrit2,#mermaid-yt9v8jesn8d .activeCrit3{stroke:#ff8888;fill:hsl(0, 0%, 100%);stroke-width:2;}#mermaid-yt9v8jesn8d .doneCrit0,#mermaid-yt9v8jesn8d .doneCrit1,#mermaid-yt9v8jesn8d .doneCrit2,#mermaid-yt9v8jesn8d .doneCrit3{stroke:#ff8888;fill:lightgrey;stroke-width:2;cursor:pointer;shape-rendering:crispEdges;}#mermaid-yt9v8jesn8d .milestone{transform:rotate(45deg) scale(0.8,0.8);}#mermaid-yt9v8jesn8d .milestoneText{font-style:italic;}#mermaid-yt9v8jesn8d .doneCritText0,#mermaid-yt9v8jesn8d .doneCritText1,#mermaid-yt9v8jesn8d .doneCritText2,#mermaid-yt9v8jesn8d .doneCritText3{fill:#333!important;}#mermaid-yt9v8jesn8d .vert{stroke:navy;}#mermaid-yt9v8jesn8d .vertText{font-size:15px;text-anchor:middle;fill:navy!important;}#mermaid-yt9v8jesn8d .activeCritText0,#mermaid-yt9v8jesn8d .activeCritText1,#mermaid-yt9v8jesn8d .activeCritText2,#mermaid-yt9v8jesn8d .activeCritText3{fill:#333!important;}#mermaid-yt9v8jesn8d .titleText{text-anchor:middle;font-size:18px;fill:#444;font-family:ui-sans-serif,-apple-system,system-ui,Segoe UI,Helvetica;}#mermaid-yt9v8jesn8d :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;}00000000000000000000000000000000Acknowledgment within 48 hours Critical fix (within 7 days) Non-critical fix (within 30 days) Validate and triage issue Status update every 5-7 days Release patch and credit Initial ResponseInvestigationRemediationDisclosureVulnerability Report Response Timeline

Diagram: Timeline for Security Vulnerability Handling

Response Stages

| Stage | Timeframe | Activities | | --- | --- | --- | | Initial Response | Within 48 hours | Acknowledge receipt of report via email | | Status Updates | Every 5-7 days | Provide investigation progress updates | | Critical Fix | Within 7 days | Patch development and testing for CVSS ≥ 9.0 issues | | Standard Fix | Within 30 days | Patch development and testing for lower severity issues |

Sources: SECURITY.md L26-L30

Disclosure Process Workflow

The vulnerability lifecycle follows a four-stage coordinated disclosure process designed to protect users while crediting security researchers.

flowchart TD

Report["Report Received<br>security@rothackers.com"]
Ack["Acknowledgment Sent<br>(within 48 hours)"]
Investigate["Investigation Phase<br>- Validate vulnerability<br>- Assess severity (CVSS)<br>- Identify affected versions"]
Triage["Severity<br>Classification?"]
CriticalFix["Critical Path<br>Target: 7 days<br>CVSS ≥ 9.0"]
StandardFix["Standard Path<br>Target: 30 days<br>CVSS < 9.0"]
Develop["Fix Development<br>- Code changes<br>- Test coverage<br>- Regression testing"]
Release["Patch Release<br>- Version bump (2.0.x)<br>- GitHub Release<br>- PyPI/Docker publish"]
Credit["Public Disclosure<br>- Security advisory<br>- Credit researcher<br>- CVE assignment (if applicable)"]

Report -.-> Ack
Ack -.-> Investigate
Investigate -.->|"CVSS ≥ 9.0"| Triage
Triage -.->|"CVSS < 9.0"| CriticalFix
Triage -.-> StandardFix
CriticalFix -.-> Develop
StandardFix -.-> Develop
Develop -.-> Release
Release -.-> Credit

Diagram: Security Vulnerability Disclosure Workflow

Process Stages Detail

Stage 1: Report Received

  • Reporter submits vulnerability details to security@rothackers.com
  • Maintainers receive notification
  • Internal tracking ticket created

Stage 2: Investigation

  • Validate the vulnerability is reproducible
  • Assess severity using CVSS v3.1 scoring (same methodology as CVSS Scoring System)
  • Identify all affected versions and code paths
  • Determine if issue exists in dependencies or core WSHawk code

Stage 3: Fix Development

  • Develop patch in private branch
  • Add test coverage in tests/ to prevent regression
  • Perform security-focused code review
  • Test against all supported versions (2.0.x)

Stage 4: Disclosure

  • Publish patched version to PyPI and Docker registries
  • Create GitHub Release with security advisory
  • Credit researcher in release notes (if desired by reporter)
  • Coordinate CVE assignment for critical issues via MITRE or GitHub Security Advisories

Sources: SECURITY.md L32-L38

Responsible Disclosure Guidelines

Reporter Expectations

WSHawk follows coordinated disclosure principles, balancing public safety with researcher recognition:

Requirements for Reporters:

  1. Private Reporting: Use security@rothackers.com, not public channels (GitHub Issues, Twitter, blogs)
  2. Reasonable Embargo: Allow maintainers time to develop and release a patch before public disclosure
  3. Good Faith Testing: Do not exploit vulnerabilities in production systems or exfiltrate data
  4. Confidentiality: Do not share vulnerability details with third parties before public disclosure

Researcher Benefits:

  1. Credit: Public acknowledgment in release notes and security advisories (optional)
  2. Communication: Regular status updates throughout the process
  3. Coordinated Disclosure: Opportunity to publish detailed write-ups after patch release
  4. CVE Credit: Named as discoverer in CVE records (for qualifying vulnerabilities)

Example Embargo Timeline

For a hypothetical CVSS 8.5 vulnerability reported on Day 0:

| Day | Activity | | --- | --- | | 0 | Vulnerability report received | | 1 | Acknowledgment sent to reporter | | 3-7 | Investigation and validation complete | | 10-25 | Patch development and testing | | 28 | Patch released as version 2.0.6 | | 28 | Public security advisory published | | 28+ | Reporter may publish detailed analysis |

Sources: SECURITY.md L39-L41

Security Updates and Notifications

Staying Informed

Users can monitor for security patches through multiple channels:

flowchart TD

Security["Security Patch Released<br>Version: 2.0.x"]
GHRelease["GitHub Releases<br>github.com/noobforanonymous/wshawk/releases"]
GHWatch["GitHub Watch/Notifications<br>Repository watchers receive alerts"]
PyPI["PyPI Package Updates<br>pypi.org/project/wshawk"]
Docker["Docker Tag Updates<br>docker.io/rothackers/wshawk<br>ghcr.io/noobforanonymous/wshawk"]
User1["User: GitHub Watcher<br>Receives email notification"]
User2["User: pip install --upgrade wshawk<br>Pulls latest version"]
User3["User: docker pull rothackers/wshawk:latest<br>Gets updated image"]

Security -.-> GHRelease
Security -.-> PyPI
Security -.-> Docker
GHRelease -.-> GHWatch
GHWatch -.-> User1
PyPI -.-> User2
Docker -.-> User3

Diagram: Security Update Distribution Channels

Notification Mechanisms

| Channel | How to Subscribe | Update Frequency | | --- | --- | --- | | GitHub Releases | Navigate to repository click "Watch" → "Custom" → "Releases" | Immediate notification on release | | GitHub Security Advisories | Automatically available to watchers | Published with each security patch | | PyPI Version Feed | Monitor via pip list --outdated or dependency scanning tools | Updated within hours of release | | Docker Tags | Subscribe to Docker Hub notifications or use docker pull with :latest tag | Updated simultaneously with PyPI |

Version Pinning Recommendations

For production deployments, use explicit version pinning to control when security updates are applied:

pip installation:

# Recommended: Pin to specific patch version
pip install wshawk==2.0.5

# Alternative: Allow patch updates within 2.0.x
pip install 'wshawk>=2.0.0,<2.1.0'

Docker deployment:

# Recommended: Pin to specific version
docker pull rothackers/wshawk:2.0.5

# Alternative: Use major.minor tag (gets latest patch)
docker pull rothackers/wshawk:2.0

# Not recommended for production: Latest tag (uncontrolled updates)
docker pull rothackers/wshawk:latest

Sources: SECURITY.md L43-L47

Scope Boundaries

In Scope

The security policy covers vulnerabilities in WSHawk's codebase:

| Component | Examples | File Paths | | --- | --- | --- | | Core Scanner | Injection in scanner logic, authentication bypass | wshawk/scanner_v2.py | | Vulnerability Modules | Logic errors in detection, false negatives allowing exploits | wshawk/sql_injection.py wshawk/xss.py etc. | | Payload System | Unsafe payload loading, code execution via malicious payloads | wshawk/payloads.py payloads/ | | Intelligence Modules | Server fingerprinting bypass, message parsing vulnerabilities | wshawk/intelligence/ | | Mutation Engine | Unsafe mutation logic, mutator bypass | wshawk/mutators/ | | CLI Commands | Command injection via arguments, privilege escalation | wshawk/main.py wshawk/cli_*.py | | OAST Integration | Credential leakage, subdomain takeover | wshawk/oast_providers.py | | Playwright Integration | Browser automation exploits, XSS in report generation | wshawk/playwright_utils.py | | Report Generation | Template injection, XSS in HTML reports | Report generation code |

Out of Scope

The following are not covered by WSHawk's security policy:

| Category | Rationale | Alternative Action | | --- | --- | --- | | Dependency Vulnerabilities | WSHawk relies on third-party libraries (websockets, playwright, etc.) | Report to upstream maintainers; WSHawk will update dependencies | | Social Engineering | Attacks targeting WSHawk users (phishing, pretexting) | Outside project control | | Physical Security | Physical access to systems running WSHawk | Infrastructure security responsibility | | Findings in Target Systems | Vulnerabilities discovered by WSHawk in applications being tested | Report to the tested application's owner | | Theoretical Vulnerabilities | Issues requiring unrealistic preconditions or no impact | May be documented as informational |

Example Out-of-Scope Report:

"The websockets library version X.Y used by WSHawk has CVE-XXXX-YYYY"

Correct Action: This should be reported to the websockets maintainers. WSHawk maintainers will update requirements.txt once a patched version is available.

Sources: SECURITY.md L49-L53

Integration with Development Process

Security in the Development Lifecycle

Security considerations are integrated throughout WSHawk's development workflow:

flowchart TD

Contrib["Contributor<br>Submits PR"]
Review["Code Review<br>- Security implications<br>- Input validation<br>- Error handling"]
CI["CI/CD Checks<br>- pytest execution<br>- Build verification"]
Merge["Merge to main<br>Branch protection"]
Security["Security Team<br>Reviews security-sensitive changes"]
Release["Release Process<br>- Version tagging<br>- Distribution (PyPI/Docker)"]

Contrib -.-> Review
Review -.->|"Security-sensitivechanges"| CI
CI -.-> Merge
Review -.-> Security
Security -.-> Merge
Merge -.-> Release

Diagram: Security Integration in Development Workflow

Security-Sensitive Areas:

  • Input validation in CLI argument parsing: wshawk/main.py
  • User-controlled data in vulnerability modules
  • External data fetching (OAST, payloads)
  • Report generation with user-supplied content
  • Authentication handling and credential storage

Contributors modifying these areas should reference Adding Extensions for security best practices.

Sources: CONTRIBUTING.md L1-L154

SECURITY.md L1-L56

Contact Information

Security Contact

Email: security@rothackers.com

Response Time: Within 48 hours

Encryption: PGP/GPG encryption is accepted but not required. If you prefer encrypted communication, include your public key in the initial report and request the team's public key.

General Support

For non-security issues:

  • Bug Reports: [GitHub Issues](https://github.com/noobforanonymous/wshawk/blob/0eebedf4/GitHub Issues) with bug template
  • Feature Requests: [GitHub Issues](https://github.com/noobforanonymous/wshawk/blob/0eebedf4/GitHub Issues) with feature template
  • Questions: [GitHub Discussions](https://github.com/noobforanonymous/wshawk/blob/0eebedf4/GitHub Discussions)

See Issue Reporting and Templates for detailed guidance.

Sources: SECURITY.md L16-L18

CONTRIBUTING.md L127-L146

Summary

WSHawk's security policy prioritizes user safety through:

  1. Clear Support Boundaries: Security patches for 2.0.x only
  2. Private Disclosure Channel: security@rothackers.com for responsible reporting
  3. Defined Timelines: 48-hour acknowledgment, 7-day critical fixes, 30-day standard fixes
  4. Coordinated Disclosure: Collaboration with researchers for safe public disclosure
  5. Multiple Notification Channels: GitHub Releases, PyPI, Docker registries
  6. Defined Scope: Focus on WSHawk code, not dependencies or target systems

By following this policy, the project maintains a balance between rapid vulnerability remediation and responsible community engagement.

Sources: SECURITY.md L1-L56