Community and Support

Community and Support

Relevant source files

This page provides an overview of community interaction channels, support resources, and contribution pathways for WSHawk. It covers how to get help, report issues, contribute code, and engage with the development community.

For detailed security vulnerability disclosure procedures, see Security Policy and Vulnerability Disclosure. For comprehensive issue reporting templates and guidelines, see Issue Reporting and Templates. For community behavioral standards and enforcement, see Code of Conduct.

Purpose and Scope

WSHawk maintains a structured open-source ecosystem with multiple interaction channels designed for different purposes. This document explains where to get support, how to report issues, contribute improvements, and extend the framework's capabilities. The focus is on practical workflows and concrete integration points within the codebase.

Support and Communication Channels

WSHawk provides four distinct communication channels, each optimized for specific types of interaction:

Channel Overview

| Channel | Purpose | Response Time | Privacy | | --- | --- | --- | --- | | GitHub Issues | Bug reports, feature requests | 24-48 hours | Public | | GitHub Discussions | Questions, usage help, general discussion | 24-72 hours | Public | | Email (security@rothackers.com) | Security vulnerability disclosure | 48 hours (initial response) | Private | | Email (support@rothackers.com) | Code of Conduct violations | 48-72 hours | Private |

When to Use Each Channel

GitHub Issues - Use for:

  • Confirmed bugs with reproducible steps
  • Feature requests with clear use cases
  • Documentation improvements
  • Integration problems with specific environments

GitHub Discussions - Use for:

  • "How do I...?" questions
  • Sharing usage patterns and best practices
  • Discussing potential features before formal requests
  • Troubleshooting unclear error messages

Security Email - Use for:

  • Security vulnerabilities in WSHawk code
  • Authentication bypass mechanisms
  • Payload injection that could harm infrastructure
  • Any issue with potential security impact

See Security Policy and Vulnerability Disclosure for the complete responsible disclosure process.

Support Email - Use for:

  • Reporting Code of Conduct violations
  • Escalating harassment or abusive behavior
  • Private community concerns

See Code of Conduct for enforcement procedures.

Community Interaction Architecture

flowchart TD

User["User/Contributor"]
Issues["GitHub Issues<br>Template-driven reporting"]
Discussions["GitHub Discussions<br>Q&A and conversations"]
PRs["Pull Requests<br>Code contributions"]
SecurityEmail["security@rothackers.com<br>Vulnerability disclosure"]
SupportEmail["support@rothackers.com<br>CoC violations"]
README["README.md<br>Quick start guide"]
Contributing["CONTRIBUTING.md<br>Development guidelines"]
Security["SECURITY.md<br>Security policy"]
CoC["CODE_OF_CONDUCT.md<br>Behavioral standards"]
Triage["Issue Triage<br>Label assignment"]
Maintainer["Maintainer Review<br>Priority assessment"]
Response["Response/Fix<br>Code or documentation"]

User -.-> Issues
User -.->|"reads"| Discussions
User -.->|"reads"| PRs
User -.-> SecurityEmail
User -.-> SupportEmail
Issues -.-> Triage
PRs -.-> Maintainer
User -.->|"reads"| README
User -.-> Contributing
User -.-> Security
User -.-> CoC
SecurityEmail -.-> Maintainer
SupportEmail -.-> Maintainer

subgraph subGraph3 ["Issue Processing"]
    Triage
    Maintainer
    Response
    Triage -.-> Maintainer
    Maintainer -.-> Response
end

subgraph subGraph2 ["Documentation Resources"]
    README
    Contributing
    Security
    CoC
end

subgraph subGraph1 ["Private Channels"]
    SecurityEmail
    SupportEmail
end

subgraph subGraph0 ["Public Channels"]
    Issues
    Discussions
    PRs
end

Sources: CONTRIBUTING.md L143-L146

SECURITY.md L16-L18

CODE_OF_CONDUCT.md L61-L63

Reporting Issues

WSHawk uses template-driven issue reporting to ensure consistent information gathering. For detailed templates and required information, see Issue Reporting and Templates.

Bug Reports

When reporting bugs, include:

| Required Information | Example | | --- | --- | | WSHawk version | 2.0.5 (from pip show wshawk or wshawk --version) | | Python version | 3.11.4 (from python --version) | | Operating system | Ubuntu 22.04 LTS, macOS 13.2, Windows 11 | | Installation method | pip install, Docker, GitHub source | | Steps to reproduce | Numbered list with exact commands | | Expected behavior | What should happen | | Actual behavior | What actually happens | | Error messages | Full traceback from logs |

Example Bug Report Structure:

WSHawk Version: 2.0.5
Python Version: 3.11.4
OS: Ubuntu 22.04 LTS
Installation: pip install wshawk==2.0.5

Steps to Reproduce:
1. Run: wshawk-advanced ws://echo.websocket.org --playwright
2. Scanner completes learning phase
3. Error occurs during XSS testing

Expected: Playwright launches and captures screenshots
Actual: Error "Browser executable not found"

Error Message:
[Full traceback from terminal or log file]

Sources: CONTRIBUTING.md L115-L126

Feature Requests

Feature requests should include:

  • Use Case: Specific scenario that benefits from the feature
  • Current Limitation: What cannot be done currently
  • Proposed Solution: How the feature would work
  • Alternatives Considered: Other approaches evaluated
  • Implementation Suggestion: (Optional) Technical approach

Sources: CONTRIBUTING.md L7-L13

Contributing Code and Documentation

WSHawk welcomes contributions across multiple extension points. The contribution workflow follows standard Git practices with automated quality gates.

Contribution Workflow

flowchart TD

Fork["Fork Repository<br>github.com/noobforanonymous/wshawk"]
Clone["Clone Fork<br>git clone https://github.com/YOUR_USERNAME/wshawk.git"]
Venv["Create Virtual Environment<br>python -m venv venv<br>source venv/bin/activate"]
Install["Install Dependencies<br>pip install -r requirements.txt<br>pip install -e ."]
Branch["Create Feature Branch<br>git checkout -b feature/name"]
Code["Write Code<br>Follow PEP 8<br>Add type hints<br>Write docstrings"]
Test["Run Tests<br>python tests/test_modules_quick.py"]
Commit["Commit Changes<br>git commit -m 'Add: Description'"]
Push["Push to Fork<br>git push origin feature/name"]
PR["Create Pull Request<br>On GitHub"]
Review["Code Review<br>Maintainer approval"]
CI["CI/CD Checks<br>Build + Test + Docker"]
Style["PEP 8 Validation<br>Type hints check"]
Tests["Test Execution<br>pytest suite"]
Merge["Merge to main<br>Automated release"]

Fork -.-> Clone
Clone -.-> Venv
Venv -.-> Install
Install -.-> Branch
Branch -.-> Code
Commit -.-> Push
Push -.-> PR
PR -.-> Review
PR -.-> CI
PR -.-> Style
PR -.-> Tests
Review -.-> Merge
CI -.-> Merge
Style -.-> Merge
Tests -.-> Merge

subgraph subGraph1 ["Quality Gates"]
    Review
    CI
    Style
    Tests
end

subgraph subGraph0 ["Development Phase"]
    Code
    Test
    Commit
    Code -.-> Test
    Test -.-> Commit
end

Sources: CONTRIBUTING.md L15-L39

CONTRIBUTING.md L70-L91

Setting Up Development Environment

Step 1: Fork and Clone

# Fork repository on GitHub, then:
git clone https://github.com/YOUR_USERNAME/wshawk.git
cd wshawk

Step 2: Virtual Environment

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

Step 3: Install Dependencies

pip install -r requirements.txt
pip install -e .  # Editable install for development

Step 4: Verify Installation

wshawk --version  # Should show current version
python tests/test_modules_quick.py  # Run quick tests

Sources: CONTRIBUTING.md L18-L39

Extension Points and Code Integration

WSHawk provides three primary extension mechanisms, each with documented integration procedures:

Extension Point Architecture

flowchart TD

VulnPath["wshawk/.py"]
VulnClass["Class inheriting base patterns"]
CVSSImpl["CVSS scoring implementation"]
ScannerInteg["Integration with WSHawkV2"]
MutatorPath["wshawk/mutators/.py"]
BaseMutator["Inherit BaseMutator"]
MutateMethod["Implement mutate method"]
Registration["Add to create_default_mutators"]
InitFile["wshawk/mutators/init.py"]
PayloadFile["payloads/.txt<br>or payloads/**/.json"]
FileFormat["One payload per line<br>or JSON structure"]
WSPayloads["Update WSPayloads class"]
MainFile["wshawk/main.py"]
PEP8["PEP 8 compliance"]
TypeHints["Type hints"]
Docstrings["Comprehensive docstrings"]
Tests["Test coverage"]

ScannerInteg -.-> PEP8
InitFile -.-> PEP8
MainFile -.-> PEP8

subgraph subGraph3 ["Shared Requirements"]
    PEP8
    TypeHints
    Docstrings
    Tests
    PEP8 -.-> TypeHints
    TypeHints -.-> Docstrings
    Docstrings -.-> Tests
end

subgraph subGraph2 ["Extension Point 3: Payload Collections"]
    PayloadFile
    FileFormat
    WSPayloads
    MainFile
    PayloadFile -.-> FileFormat
    FileFormat -.-> WSPayloads
    WSPayloads -.-> MainFile
end

subgraph subGraph1 ["Extension Point 2: Mutation Strategies"]
    MutatorPath
    BaseMutator
    MutateMethod
    Registration
    InitFile
    MutatorPath -.-> BaseMutator
    BaseMutator -.-> MutateMethod
    MutateMethod -.-> Registration
    Registration -.-> InitFile
end

subgraph subGraph0 ["Extension Point 1: Vulnerability Modules"]
    VulnPath
    VulnClass
    CVSSImpl
    ScannerInteg
    VulnPath -.-> VulnClass
    VulnClass -.-> CVSSImpl
    CVSSImpl -.-> ScannerInteg
end

Sources: CONTRIBUTING.md L92-L113

Adding a Vulnerability Detection Module

Location: wshawk/<module_name>.py

Required Elements:

  1. Detection logic with error handling
  2. CVSS v3.1 scoring implementation
  3. Integration hooks for WSHawkV2 scanner
  4. Type hints and docstrings
  5. Test coverage

Example Structure Reference:

  • See wshawk/sql_injection_tester.py for SQL injection patterns
  • See wshawk/xss_tester.py for browser integration patterns
  • See wshawk/ssrf_tester.py for OAST integration patterns

Sources: CONTRIBUTING.md L94-L100

Adding a Mutation Strategy

Location: wshawk/mutators/<strategy>.py

Required Elements:

  1. Inherit from BaseMutator class
  2. Implement mutate(payload: str, context: dict) -> List[str] method
  3. Register in create_default_mutators() function
  4. Add to exports in wshawk/mutators/__init__.py

Registration Example:

# In wshawk/mutators/__init__.py
from .your_strategy import YourMutator

def create_default_mutators() -> List[BaseMutator]:
    return [
        # ... existing mutators ...
        YourMutator(),
    ]

Sources: CONTRIBUTING.md L102-L107

Adding Payload Collections

Location: payloads/<category>/<name>.txt or payloads/<category>/<name>.json

Text Format (.txt):

  • One payload per line
  • No empty lines
  • UTF-8 encoding
  • Example: payloads/sql_injection/postgresql.txt

JSON Format (.json):

  • Structured payload definitions
  • Example: payloads/xss/dom_contexts.json

Integration: Update WSPayloads class in wshawk/__main__.py to load new payload files.

Sources: CONTRIBUTING.md L109-L113

Code Quality Standards

All contributions must meet the following quality standards before merge:

Code Style Requirements

| Requirement | Tool/Method | Reference | | --- | --- | --- | | PEP 8 Compliance | Manual review / linter | Python Enhancement Proposal 8 | | Type Hints | mypy-compatible annotations | All function signatures | | Docstrings | Google/NumPy style | All public functions and classes | | Modular Functions | Single responsibility principle | Keep functions focused |

Example Type Hint Pattern:

async def test_vulnerability(
    self,
    websocket: WebSocket,
    payload: str,
    context: Dict[str, Any]
) -> Optional[VulnerabilityFinding]:
    """
    Test for specific vulnerability using provided payload.
    
    Args:
        websocket: Active WebSocket connection
        payload: Test payload string
        context: Testing context with message structure
        
    Returns:
        VulnerabilityFinding if detected, None otherwise
    """

Sources: CONTRIBUTING.md L43-L48

Testing Requirements

Primary Test Suite: tests/test_modules_quick.py

Pre-Submission Checklist:

# 1. Run all tests
python tests/test_modules_quick.py

# 2. Verify no regressions
# All existing tests must pass

# 3. Add tests for new features
# New functionality requires test coverage

Test Categories:

  • Unit tests for individual functions
  • Integration tests for module interactions
  • End-to-end tests for complete workflows

Sources: CONTRIBUTING.md L50-L60

Quality Gate Process

flowchart TD

PR["Pull Request<br>Submitted"]
Build["Build Verification<br>Package builds successfully"]
TestRun["Test Execution<br>pytest suite passes"]
Docker["Docker Build<br>Multi-platform images"]
CodeReview["Code Review<br>Maintainer approval"]
StyleCheck["Style Check<br>PEP 8 compliance"]
DocCheck["Documentation<br>Completeness check"]
Merge["Merge to main<br>Automated release"]

PR -.-> Build
PR -.-> TestRun
PR -.-> Docker
PR -.-> CodeReview
PR -.-> StyleCheck
PR -.-> DocCheck
Build -.-> Merge
TestRun -.-> Merge
Docker -.-> Merge
CodeReview -.-> Merge
StyleCheck -.-> Merge
DocCheck -.-> Merge

subgraph subGraph1 ["Manual Review"]
    CodeReview
    StyleCheck
    DocCheck
end

subgraph subGraph0 ["Automated Checks"]
    Build
    TestRun
    Docker
end

Sources: CONTRIBUTING.md L85-L90

Commit and Pull Request Guidelines

Commit Message Format

Use descriptive prefixes to categorize changes:

| Prefix | Purpose | Example | | --- | --- | --- | | Add: | New feature or capability | Add: LDAP injection detection module | | Fix: | Bug fix | Fix: Playwright timeout on slow connections | | Update: | Modification to existing feature | Update: CVSS scoring for XXE vulnerabilities | | Docs: | Documentation changes | Docs: Add Docker deployment examples | | Refactor: | Code restructuring without behavior change | Refactor: Extract mutation logic to base class | | Test: | Test additions or modifications | Test: Add session hijacking test cases |

Sources: CONTRIBUTING.md L62-L68

Pull Request Requirements

Description Template:

## Description
[Clear description of changes]

## Related Issues
Fixes #123
Related to #456

## Testing
- [ ] All existing tests pass
- [ ] New tests added for new functionality
- [ ] Manual testing completed

## Documentation
- [ ] README updated (if applicable)
- [ ] Docstrings added/updated
- [ ] CHANGELOG.md updated

Required Elements:

  • Clear description of changes and motivation
  • References to related GitHub issues
  • Test results and coverage information
  • Documentation updates if needed

Sources: CONTRIBUTING.md L85-L90

Documentation Resources

WSHawk maintains comprehensive documentation across multiple files:

Core Documentation Files

| File | Purpose | Audience | | --- | --- | --- | | README.md | Quick start, features, basic usage | New users | | CONTRIBUTING.md | Development guidelines, contribution workflow | Contributors | | DOCKER.md | Container deployment, docker-compose | DevOps teams | | DEFENSIVE_VALIDATION.md | Blue team testing guide | Security teams | | SECURITY.md | Vulnerability disclosure policy | Security researchers | | CODE_OF_CONDUCT.md | Community behavioral standards | All participants | | CHANGELOG.md | Version history, breaking changes | All users |

Documentation Update Workflow

When contributing code that affects user-facing behavior:

  1. Update README.md if adding CLI flags or major features
  2. Update CONTRIBUTING.md if changing development workflow
  3. Update DOCKER.md if modifying Docker images or environment variables
  4. Update CHANGELOG.md with summary of changes
  5. Update inline docstrings for all modified functions

Sources: CONTRIBUTING.md L143-L146

Community Behavioral Standards

WSHawk follows the Contributor Covenant Code of Conduct v2.0. Key principles:

Core Principles

  • Empathy and Kindness: Demonstrate respect toward all participants
  • Constructive Feedback: Focus on improvement, not criticism
  • Responsibility: Accept accountability for mistakes and learn from them
  • Community Focus: Prioritize collective benefit over individual gain

Unacceptable Behavior

  • Sexualized language or imagery
  • Trolling, insulting comments, or personal attacks
  • Public or private harassment
  • Publishing private information without permission
  • Other unprofessional conduct

Enforcement

Violations should be reported to support@rothackers.com. Community leaders will:

  1. Review complaints promptly and fairly
  2. Maintain privacy of reporters
  3. Follow graduated enforcement guidelines (correction → warning → ban)

For complete enforcement procedures, see Code of Conduct.

Sources: CODE_OF_CONDUCT.md L1-L129

Security Vulnerability Disclosure

WSHawk takes security seriously and maintains a responsible disclosure policy.

Supported Versions

| Version | Security Support | | --- | --- | | 2.0.x | ✅ Active support | | < 1.0 | ❌ No support |

Disclosure Process

Private Reporting: Email security@rothackers.com (not GitHub Issues)

Timeline:

  • Initial response: 48 hours
  • Status updates: Every 5-7 days
  • Fix timeline: * Critical issues: 7 days * Other issues: 30 days

Process Stages:

  1. Report received → Acknowledgment within 48 hours
  2. Investigation → Validation of issue
  3. Fix development → Patch creation and testing
  4. Disclosure → Coordinated release with credit

For complete security policy and out-of-scope items, see Security Policy and Vulnerability Disclosure.

Sources: SECURITY.md L1-L56

Getting Started as a Contributor

Quick Start Checklist

  • Read CONTRIBUTING.md for development guidelines
  • Read CODE_OF_CONDUCT.md for community standards
  • Read SECURITY.md if reporting security issues
  • Fork the repository and set up development environment
  • Run python tests/test_modules_quick.py to verify setup
  • Create a feature branch for your changes
  • Write code following PEP 8 with type hints and docstrings
  • Test your changes thoroughly
  • Submit a pull request with clear description

Common First Contributions

Good first contributions for new contributors:

  1. Documentation Improvements: Fix typos, clarify explanations, add examples
  2. Payload Collections: Add new payload files for existing vulnerability types
  3. Test Coverage: Add test cases for existing functionality
  4. Bug Fixes: Address issues labeled "good first issue" on GitHub
  5. Code Examples: Add usage examples to documentation

Questions and Help

  • Usage Questions: GitHub Discussions
  • Development Help: Comment on related issues or open a discussion
  • Bug Reports: GitHub Issues with template
  • Security Issues: security@rothackers.com (private)

Sources: CONTRIBUTING.md L1-L155