Contributing Guidelines

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

• .github/ISSUE_TEMPLATE/-question-or-discussion.md
• .github/ISSUE_TEMPLATE/bug_report.md
• .github/ISSUE_TEMPLATE/feature_request.md
• .github/workflows/ghcr-publish.yml
• README.md
• setup.py

Purpose and Scope

This document outlines the contribution workflow, development standards, and submission process for WSHawk contributors. It covers how to set up a development environment, code style requirements, testing expectations, and the pull request process.

For detailed information about setting up your development environment, see Development Environment Setup. For adding specific feature types, see Adding Vulnerability Detection Modules, Adding Mutation Strategies, and Adding Payload Collections. For security vulnerability disclosure, see Security Policy and Vulnerability Disclosure.

---

Ways to Contribute

WSHawk welcomes contributions in multiple forms:

| Contribution Type | Description | Key Files | |------------------|-------------|-----------| | Bug Reports | Report defects or unexpected behavior | GitHub Issues | | Security Issues | Report vulnerabilities responsibly | security@rothackers.com | | Bug Fixes | Submit patches for existing issues | Any affected modules | | Vulnerability Modules | Add new vulnerability detection capabilities | wshawk/*.py | | Mutation Strategies | Add WAF evasion techniques | wshawk/mutators/*.py | | Payload Collections | Expand attack vector libraries | payloads/*.txt, payloads/**/*.json | | Documentation | Improve README, wiki, or inline docs | docs/, README.md | | Defensive Tests | Add blue team validation tests | wshawk/defensive_validation.py |

Sources: README.md:285-287, .github/ISSUE_TEMPLATE/bug_report.md, .github/ISSUE_TEMPLATE/feature_request.md

---

Development Environment Setup

Initial Setup Process

Follow these steps to prepare your local development environment:

# 1. Fork and clone the repository
git clone https://github.com/YOUR_USERNAME/wshawk.git
cd wshawk

# 2. Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# 3. Install dependencies
pip install -r requirements.txt
pip install -e .

# 4. Verify installation
wshawk --help
python tests/test_modules_quick.py

Development Environment Architecture

graph TB
    subgraph "Source Repository"
        Fork["GitHub Fork<br/>YOUR_USERNAME/wshawk"]
        Upstream["Upstream Repo<br/>regaan/wshawk"]
    end
    
    subgraph "Local Development"
        LocalClone["Local Clone<br/>wshawk/"]
        VirtualEnv["Virtual Environment<br/>venv/"]
        
        subgraph "Installed Packages"
            RequirementsTxt["requirements.txt<br/>websockets, playwright, aiohttp, PyYAML"]
            EditableInstall["pip install -e .<br/>WSHawk in development mode"]
        end
        
        subgraph "Development Files"
            SourceCode["wshawk/<br/>scanner_v2.py, mutators/, etc"]
            Tests["tests/<br/>test_modules_quick.py"]
            Payloads["payloads/<br/>*.txt, *.json"]
        end
    end
    
    subgraph "Verification"
        CLI["CLI Commands<br/>wshawk --help<br/>wshawk-defensive --help"]
        TestRunner["Test Execution<br/>python tests/test_modules_quick.py"]
    end
    
    Upstream -->|"fork"| Fork
    Fork -->|"git clone"| LocalClone
    LocalClone -->|"python -m venv"| VirtualEnv
    
    RequirementsTxt -->|"pip install"| VirtualEnv
    EditableInstall -->|"pip install -e ."| VirtualEnv
    
    VirtualEnv --> SourceCode
    VirtualEnv --> Tests
    VirtualEnv --> Payloads
    
    VirtualEnv --> CLI
    VirtualEnv --> TestRunner

Sources: setup.py:1-64, README.md:53-62

---

Development Guidelines

Code Style Standards

WSHawk follows Python best practices:

• PEP 8 Compliance: Follow standard Python style guidelines
• Type Hints: Add type annotations for function parameters and return values
• Docstrings: Document all classes and functions with descriptive docstrings
• Modularity: Keep functions focused on single responsibilities

Example of proper code style:

# Good: Type hints, docstring, focused function
async def detect_sql_injection(
    message: str, 
    response: str, 
    payload: str
) -> Optional[Dict[str, Any]]:
    """
    Detect SQL injection vulnerabilities in WebSocket responses.
    
    Args:
        message: Original message sent
        response: Server response received
        payload: SQL injection payload used
        
    Returns:
        Dictionary with vulnerability details if detected, None otherwise
    """
    # Implementation

Package Structure Compliance

When adding new modules, ensure they are properly included in package metadata:

In setup.py:24:

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

In setup.py:49-57 for data files:

include_package_data=True,
package_data={
    "wshawk": [
        "payloads/*.txt",
        "payloads/**/*.json",
        "web/templates/*.html",
        "web/static/*",
    ],
}

Testing Requirements

All contributions must pass the existing test suite and include new tests for added functionality:

# Run quick test suite (90+ tests, ~0.15s)
python tests/test_modules_quick.py

# Verify all tests pass before submitting PR

Test coverage expectations:

• Bug Fixes: Add regression test to prevent recurrence
• New Features: Add unit tests for core functionality
• Vulnerability Modules: Test detection logic with known vulnerable patterns
• Mutation Strategies: Test mutation output variations

Sources: setup.py:16-64, README.md:251-265

---

Contribution Workflow

Git Branching and Commit Strategy

graph LR
    subgraph "Your Fork"
        Main["main branch<br/>(synced with upstream)"]
        FeatureBranch["feature/your-feature-name<br/>or fix/bug-description"]
    end
    
    subgraph "Development Cycle"
        Code["Write Code<br/>Follow PEP 8<br/>Add Type Hints"]
        Test["Run Tests<br/>python tests/test_modules_quick.py"]
        Commit["Git Commit<br/>Clear message format"]
    end
    
    subgraph "Upstream Repository"
        UpstreamMain["regaan/wshawk<br/>main branch"]
        PullRequest["Pull Request<br/>Review Process"]
    end
    
    Main -->|"git checkout -b"| FeatureBranch
    FeatureBranch --> Code
    Code --> Test
    Test --> Commit
    Commit -->|"git push origin"| FeatureBranch
    FeatureBranch -->|"Create PR"| PullRequest
    PullRequest -->|"Merged"| UpstreamMain
    UpstreamMain -->|"git pull upstream"| Main

Commit Message Format

Use clear, prefixed commit messages for easy changelog generation:

| Prefix | Usage | Example | |--------|-------|---------| | Add: | New features or capabilities | Add: SQLi blind detection module | | Fix: | Bug fixes | Fix: Rate limiter token calculation | | Update: | Modifications to existing code | Update: CVSS scoring algorithm | | Docs: | Documentation changes | Docs: Clarify mutation strategy usage | | Test: | Test additions or fixes | Test: Add XSS verification tests | | Refactor: | Code restructuring | Refactor: Extract payload loading logic |

Example commit workflow:

# 1. Create feature branch
git checkout -b feature/add-nosql-payloads

# 2. Make changes
# ... edit files ...

# 3. Test changes
python tests/test_modules_quick.py

# 4. Commit with clear message
git add .
git commit -m "Add: NoSQL injection payloads for MongoDB"

# 5. Push to your fork
git push origin feature/add-nosql-payloads

Sources: README.md:285-287, .github/workflows/ghcr-publish.yml:1-50

---

Adding New Features

Extension Points Architecture

Diagram: Code Entity Extension Points

graph TB
    subgraph ExtensionPoints["Extension Points"]
        VulnModules["Vulnerability Modules<br/>wshawk/scanner_v2.py<br/>detect_* async functions"]
        MutatorBase["Mutation Strategies<br/>wshawk/mutators/base_mutator.py<br/>BaseMutator class"]
        PayloadFiles["Payload Collections<br/>payloads/*.txt<br/>payloads/**/*.json"]
        DefensiveTests["Defensive Tests<br/>wshawk/defensive_validation.py<br/>DefensiveValidationModule"]
        Plugins["Plugin System<br/>wshawk/plugin_manager.py<br/>PayloadPlugin/DetectorPlugin"]
    end
    
    subgraph PackageConfig["Package Configuration"]
        SetupPy["setup.py<br/>find_packages()<br/>package_data"]
        EntryPoints["setup.py:41-48<br/>console_scripts:<br/>wshawk<br/>wshawk-interactive<br/>wshawk-advanced<br/>wshawk-defensive"]
    end
    
    subgraph CoreClasses["Core Integration Classes"]
        WSHawkV2["WSHawkV2<br/>wshawk/scanner_v2.py<br/>run_heuristic_scan()"]
        WSPayloads["WSPayloads<br/>wshawk/__main__.py<br/>load_payloads()"]
        MutatorFactory["create_default_mutators()<br/>wshawk/mutators/__init__.py"]
    end
    
    VulnModules -->|"called by"| WSHawkV2
    MutatorBase -->|"instantiated by"| MutatorFactory
    PayloadFiles -->|"loaded by"| WSPayloads
    DefensiveTests -->|"run via"| EntryPoints
    
    WSHawkV2 -->|"uses"| WSPayloads
    WSHawkV2 -->|"uses"| MutatorFactory
    
    PayloadFiles -.->|"must be in"| SetupPy
    VulnModules -.->|"module must be in"| SetupPy
    Plugins -.->|"directory must be in"| SetupPy

Adding a Vulnerability Detection Module

Create new vulnerability detectors in the wshawk/ directory following this pattern:

Required Components:

1. Detection function with signature: async def detect_<vuln_type>(...) -> Optional[Dict[str, Any]]
2. Error handling for malformed responses
3. CVSS v3.1 scoring calculation
4. Integration into scanner_v2.py:WSHawkV2.run_tests()

Example structure:

# File: wshawk/new_vuln_detector.py

async def detect_new_vulnerability(
    message: str,
    response: str, 
    payload: str,
    metadata: Dict[str, Any]
) -> Optional[Dict[str, Any]]:
    """
    Detect new vulnerability type.
    
    Returns:
        Dict with keys: type, severity, cvss_score, evidence
    """
    # 1. Check for vulnerability patterns
    # 2. Calculate CVSS score
    # 3. Return structured finding
    pass

Integration location: wshawk/scanner_v2.py in the run_tests() method

Entry Point Registration: New CLI commands must be added to setup.py:41-48:

entry_points={
    "console_scripts": [
        "wshawk=wshawk.__main__:cli",
        "wshawk-interactive=wshawk.interactive:cli",
        "wshawk-advanced=wshawk.advanced_cli:cli",
        "wshawk-defensive=wshawk.defensive_cli:cli",
        # Add your new command here
    ],
}

Sources: setup.py:41-48, README.md:38-52

Adding a Mutation Strategy

Create new mutators in wshawk/mutators/ by inheriting from BaseMutator:

Required Steps:

1. Create file: wshawk/mutators/your_mutator.py
2. Inherit from BaseMutator class
3. Implement mutate(payload: str) -> str method
4. Register in wshawk/mutators/__init__.py:create_default_mutators()

Example structure:

# File: wshawk/mutators/custom_mutator.py

from wshawk.mutators.base_mutator import BaseMutator

class CustomMutator(BaseMutator):
    """Custom mutation strategy for WAF evasion."""
    
    def mutate(self, payload: str) -> str:
        """
        Apply custom mutation logic.
        
        Args:
            payload: Original payload string
            
        Returns:
            Mutated payload
        """
        # Apply your mutation logic
        return mutated_payload

Registration location: wshawk/mutators/init.py in create_default_mutators() function

Sources: README.md:38-52, README.md:244-249

Adding Payload Collections

Add new payloads in the payloads/ directory:

File Formats:

• .txt files: One payload per line (simple vectors)
• .json files: Structured payloads with metadata

Example .txt format:

# File: payloads/nosql_injection.txt
{"$ne": null}
{"$gt": ""}
{"$where": "this.password.length > 0"}

Integration: Update WSPayloads class in wshawk/main.py to load new payload file in the load_payloads() method.

Ensure new payload files are included in package distribution via setup.py:50-57:

package_data={
    "wshawk": [
        "payloads/*.txt",          # Your new .txt file
        "payloads/**/*.json",      # Your new .json file
        "web/templates/*.html",
        "web/static/*",
    ],
}

Sources: setup.py:50-57, README.md:40

---

Pull Request Process

Pull Request Submission

sequenceDiagram
    participant Dev as "Developer"
    participant Fork as "Your Fork"
    participant GH as "GitHub"
    participant CI as "CI/CD (Actions)"
    participant Rev as "Maintainers"
    participant Main as "Upstream Main"
    
    Dev->>Fork: "git push origin feature-branch"
    Dev->>GH: "Create Pull Request"
    GH->>CI: "Trigger docker-build.yml"
    CI->>CI: "Build Docker Image"
    CI->>CI: "Run Tests"
    CI->>GH: "Report Status"
    
    GH->>Rev: "Notify for Review"
    Rev->>GH: "Review Code"
    
    alt "Changes Requested"
        Rev->>Dev: "Request Changes"
        Dev->>Fork: "Push Updates"
        Fork->>GH: "Update PR"
        GH->>CI: "Re-run CI"
    end
    
    Rev->>GH: "Approve PR"
    Rev->>Main: "Merge to main"
    Main->>CI: "Trigger docker-build.yml<br/>Publish to GHCR/Docker Hub"

Pull Request Guidelines

Your pull request should include:

| Requirement | Description | |------------|-------------| | Clear Description | Explain what changes were made and why | | Issue Reference | Link related GitHub issues with Fixes #123 or Closes #456 | | Test Results | Show that python tests/test_modules_quick.py passes | | Documentation Updates | Update README.md or docs/ if adding user-facing features | | Breaking Changes Notice | Clearly mark any breaking API changes | | Screenshots (if applicable) | For UI changes or report format modifications |

Automated CI Checks:

• Docker build validation (triggered by .github/workflows/ghcr-publish.yml:3-14)
• Image publishing to GitHub Container Registry (GHCR)
• Multi-platform compatibility verification

The CI workflow defined in .github/workflows/ghcr-publish.yml:15-50 automatically:

1. Triggers on push to main branch or version tags (v*)
2. Builds Docker image using Dockerfile
3. Pushes to ghcr.io/regaan/wshawk with semantic version tags
4. Generates latest, <major>.<minor>, and <major>.<minor>.<patch> tags

Sources: .github/workflows/ghcr-publish.yml:1-50, README.md:64-81

---

Code Standards and Best Practices

Project Structure Conventions

When adding files, follow the established directory structure:

wshawk/
├── scanner_v2.py              # Core scanner (WSHawkV2 class)
├── message_analyzer.py        # MessageAnalyzer class
├── vulnerability_verifier.py  # VulnerabilityVerifier class
├── server_fingerprinter.py    # ServerFingerprinter class
├── session_hijacking_tester.py # SessionHijackingTester class
├── defensive_validation.py    # DefensiveValidationModule class
├── mutators/
│   ├── __init__.py           # create_default_mutators()
│   ├── base_mutator.py       # BaseMutator abstract class
│   └── *.py                  # Concrete mutator implementations
└── __main__.py               # CLI entrypoints, WSPayloads class

payloads/
├── *.txt                     # Simple payload lists
└── **/*.json                 # Structured payloads

tests/
└── test_modules_quick.py     # 90+ unit tests

Error Handling Patterns

All vulnerability detection functions should handle errors gracefully:

async def detect_vulnerability(...) -> Optional[Dict[str, Any]]:
    try:
        # Detection logic
        if vulnerability_found:
            return {
                'type': 'SQL_INJECTION',
                'severity': 'HIGH',
                'cvss_score': 8.5,
                'evidence': '...'
            }
    except Exception as e:
        logger.error(f"Detection error: {e}")
        return None
    
    return None  # No vulnerability found

CVSS Scoring Requirements

All vulnerability findings must include CVSS v3.1 scoring. Reference the existing scoring implementation in wshawk/scanner_v2.py or see CVSS Scoring System for details.

Sources: setup.py:1-64, README.md:38-52

---

Issue Reporting

Bug Report Requirements

WSHawk provides structured issue templates for consistent bug reporting. The bug report template at .github/ISSUE_TEMPLATE/bug_report.md:1-88 requires:

| Information | Template Field | Description | |------------|----------------|-------------| | Version | version | Output of wshawk --version or pip show wshawk | | Bug Description | description | Clear description of the bug | | Steps to Reproduce | steps | Exact commands and configuration used | | Expected Behavior | expected | What should have happened | | Actual Behavior | actual | What actually happened | | Logs/Screenshots | logs | Full traceback or error output (shell render) | | Operating System | os | Dropdown: Linux/macOS/Windows/Docker | | Python Version | python | python --version output |

Issue Templates Available:

• Bug Reports: .github/ISSUE_TEMPLATE/bug_report.md - For defects and unexpected behavior
• Feature Requests: .github/ISSUE_TEMPLATE/feature_request.md - For new capability proposals
• Questions: .github/ISSUE_TEMPLATE/-question-or-discussion.md - For help and discussions

Issue Tracker: https://github.com/regaan/wshawk/issues

For structured reporting guidance, see Issue Reporting and Templates.

Sources: .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, README.md:301

---

Security Vulnerability Disclosure

⚠️ IMPORTANT: Do NOT report security vulnerabilities in public GitHub issues.

For responsible disclosure of security vulnerabilities in WSHawk itself, follow the process documented in Security Policy and Vulnerability Disclosure.

Direct Security Contact: security@rothackers.com or support@rothackers.com

Sources: README.md:268-298, README.md:304

---

Community Standards

Code of Conduct

All contributors must adhere to these principles:

• Be Respectful: Professional communication at all times
• Welcome Newcomers: Help first-time contributors get started
• Constructive Feedback: Focus on improving code, not criticizing people
• Respect Viewpoints: Acknowledge different approaches and perspectives

For complete community standards and enforcement guidelines, see Code of Conduct.

Getting Help

If you have questions about contributing:

• GitHub Issues: Use .github/ISSUE_TEMPLATE/-question-or-discussion.md template for questions
• Existing Issues: Search closed issues at https://github.com/regaan/wshawk/issues
• Documentation: Review the docs/ folder (README.md:242-249 references guides)
• Email Support: support@rothackers.com (README.md:304)
• Official Sources: Only trust code from https://github.com/regaan/wshawk (README.md:3-14 security warning)

Sources: README.md:299-305, .github/ISSUE_TEMPLATE/-question-or-discussion.md:1-37

---

License Agreement

By contributing to WSHawk, you agree that your contributions will be licensed under the MIT License, the same license that covers the project.

All submitted code must be original work or properly attributed third-party code compatible with the MIT License.

License Information:

• README.md:19: [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)]
• README.md:277-279: Official MIT License declaration
• setup.py:26-30: Package classifier "License :: OSI Approved :: MIT License"

Sources: README.md:277-279, setup.py:26-30

---

Quick Reference Checklist

Before submitting your contribution:

• [ ] Code follows PEP 8 style guidelines
• [ ] Type hints added for new functions
• [ ] Docstrings added for new classes/functions
• [ ] Tests pass: python tests/test_modules_quick.py
• [ ] New tests added for new functionality
• [ ] Commit messages use clear prefixes (Add:, Fix:, etc.)
• [ ] Documentation updated if needed
• [ ] PR description is clear and references issues
• [ ] Changes tested in both pip and Docker installations (if applicable)
• [ ] Security implications considered
• [ ] No sensitive data in commits (credentials, private keys, etc.)

Sources: CONTRIBUTING.md:1-155