Development and Contributing

Development and Contributing

Relevant source files

Purpose and Scope

This document provides technical guidance for contributing to the WSHawk project. It covers the development workflow, coding standards, quality gates, and extension architecture for adding new capabilities to the framework. This page serves as the entry point for contributors—child pages provide detailed instructions for environment setup, project architecture, and adding specific extensions.

For information about reporting security vulnerabilities, see Security Policy and Vulnerability Disclosure. For community behavioral standards, see Code of Conduct. For bug reporting and feature requests, see Issue Reporting and Templates.

Contribution Pathways

WSHawk accepts contributions across multiple domains. The project distinguishes between content contributions (payloads, documentation), feature contributions (new modules, mutators), and maintenance contributions (bug fixes, refactoring).

| Contribution Type | Scope | Files Modified | Review Complexity | | --- | --- | --- | --- | | Bug Fixes | Fix defects in existing code | Various .py files | Low - Medium | | Vulnerability Modules | Add new attack detection capabilities | wshawk/<module_name>.py, wshawk/scanner_v2.py | Medium - High | | Mutation Strategies | Add WAF bypass techniques | wshawk/mutators/<name>.py, wshawk/mutators/__init__.py | Medium | | Payload Collections | Add attack vectors | payloads/*.txt or payloads/**/*.json, wshawk/__main__.py | Low | | Documentation | Improve guides and examples | *.md files, docs/ | Low | | CLI Features | Add command-line options | wshawk/__main__.py, wshawk/interactive.py, etc. | Medium | | Testing | Add test coverage | tests/*.py | Low - Medium |

Sources: CONTRIBUTING.md L6-L13

Development Workflow

Overview Diagram: Fork to Merge Pipeline

Sources: CONTRIBUTING.md L15-L42

CONTRIBUTING.md L70-L84

Git Workflow Details

The standard Git workflow follows these commands:

Sources: CONTRIBUTING.md L18-L39

CONTRIBUTING.md L72-L80

Code Standards and Quality Requirements

Code Style Guidelines

WSHawk enforces strict code quality standards aligned with Python best practices:

| Standard | Requirement | Enforcement | | --- | --- | --- | | PEP 8 Compliance | All code must follow PEP 8 style guidelines | Manual review | | Type Hints | Use type hints for function parameters and return values | Manual review | | Docstrings | All functions and classes require docstrings | Manual review | | Modularity | Functions should be focused with single responsibility | Code review | | Error Handling | Proper exception handling with informative messages | Code review |

Sources: CONTRIBUTING.md L43-L48

Commit Message Format

Commit messages use prefixed categorization:

  • Add: - New feature or capability
  • Fix: - Bug fix or correction
  • Update: - Modification to existing feature
  • Docs: - Documentation changes only

Example: Add: NoSQL injection detection for MongoDB

Sources: CONTRIBUTING.md L62-L68

Testing Requirements

Before submitting a pull request, contributors must:

  1. Run the existing test suite: python tests/test_modules_quick.py
  2. Ensure all tests pass without errors
  3. Add new tests for new features to maintain coverage

Sources: CONTRIBUTING.md L50-L60

Extension Architecture

Extension Points and Code Integration

Sources: CONTRIBUTING.md L92-L113

setup.py L49-L55

Extension Point 1: Vulnerability Detection Modules

To add a new vulnerability detection module:

  1. Create module file: wshawk/<module_name>.py
  2. Implement detection logic: Add vulnerability scanning methods with proper error handling
  3. Include CVSS scoring: Calculate CVSS v3.1 scores for discovered vulnerabilities
  4. Integrate with scanner: Modify wshawk/scanner_v2.py to invoke the new module
  5. Add tests: Create test cases in tests/ directory

The module should follow the existing pattern seen in modules like sql_injection_tester.py, xss_tester.py, and other vulnerability detection modules.

Sources: CONTRIBUTING.md L94-L100

Extension Point 2: Mutation Strategies

To add a new WAF bypass mutation strategy:

  1. Create mutator file: wshawk/mutators/<name>.py
  2. Inherit from BaseMutator: Use the base class interface
  3. Implement mutate() method: Add transformation logic
  4. Register mutator: Add to create_default_mutators() in wshawk/mutators/__init__.py

Example structure:

Then register in wshawk/mutators/__init__.py:

Sources: CONTRIBUTING.md L102-L107

Extension Point 3: Payload Collections

To add new attack payloads:

  1. Create payload file: payloads/<name>.txt (one payload per line) or payloads/**/<name>.json (structured format)
  2. Update WSPayloads class: Modify wshawk/__main__.py to load the new payload collection
  3. Verify packaging: Ensure setup.py includes the payload files in package_data

The package configuration at setup.py L50-L55

specifies:

This ensures payload files are included in the distributed package.

Sources: CONTRIBUTING.md L109-L113

setup.py L50-L55

Package Structure and Entry Points

Console Script Registration

WSHawk registers four CLI commands through setuptools entry points:

The entry points are defined at setup.py L41-L47

:

When adding new CLI commands, register them in this section and create the corresponding module with a cli() function.

Sources: setup.py L41-L47

Dependency Management

Core Dependencies

WSHawk requires specific versions of core libraries as defined in requirements.txt L4-L12

and setup.py L9-L14

:

| Dependency | Minimum Version | Purpose | | --- | --- | --- | | websockets | 12.0 | WebSocket protocol implementation | | playwright | 1.40.0 | Browser automation for XSS verification | | aiohttp | 3.9.0 | HTTP client for OAST integration | | PyYAML | 6.0 | Configuration file parsing |

Development Dependencies

Additional dependencies for testing and development:

  • pytest >= 7.4.0 - Testing framework
  • pytest-asyncio >= 0.21.0 - Async test support
  • colorama >= 0.4.6 - Terminal color output (optional)

When adding new functionality that requires additional dependencies:

  1. Add to requirements.txt
  2. Add to install_requires in setup.py
  3. Document the dependency purpose in comments

Sources: requirements.txt L1-L19

setup.py L9-L14

Pull Request Requirements

PR Description Checklist

Pull requests must include:

  • Clear description: Explain what the PR changes and why
  • Related issues: Reference GitHub issues using #issue_number
  • Test results: Include output from python tests/test_modules_quick.py
  • Documentation updates: Update relevant .md files if behavior changes
  • Breaking changes: Clearly mark any breaking changes

Sources: CONTRIBUTING.md L85-L90

Quality Gates

Before merging, pull requests must pass:

All gates must pass before the PR can be merged. If any check fails, the contributor must address the issues and push updates to the PR branch.

Sources: CONTRIBUTING.md L85-L90

Bug Reporting Requirements

When reporting bugs through GitHub Issues, include:

| Information | Description | | --- | --- | | WSHawk version | Output of wshawk --version or package version | | Python version | Output of python --version | | Operating system | OS name and version | | Steps to reproduce | Numbered list of exact steps | | Expected behavior | What should happen | | Actual behavior | What actually happens | | Error messages | Full traceback or error output | | Logs | Relevant log files if available |

GitHub Issues: https://github.com/noobforanonymous/wshawk/issues

Sources: CONTRIBUTING.md L115-L127

Security Vulnerability Disclosure

Critical: Do not report security vulnerabilities in public GitHub Issues.

For security issues that could affect WSHawk users or the projects they scan, use the private disclosure channel:

Email: security@rothackers.com

This ensures responsible disclosure and allows the maintainers to patch vulnerabilities before public disclosure.

Sources: CONTRIBUTING.md L129-L133

File Exclusions and Ignored Artifacts

The .gitignore L1-L93

file specifies which files should not be committed to the repository:

| Category | Patterns | Rationale | | --- | --- | --- | | Python artifacts | __pycache__/, *.pyc, dist/, *.egg-info/ | Build artifacts | | Virtual environments | venv/, env/, ENV/, .venv | Local Python environments | | IDE files | .vscode/, .idea/, *.swp | Editor configurations | | Test artifacts | .pytest_cache/, .coverage, .tox/ | Testing outputs | | Reports | wshawk_report_*.html, *.html | Generated scan reports | | Secrets | *.key, *.pem, secrets.json | Never commit credentials | | Session data | sessions/, *.session | Runtime session files | | Playwright cache | .playwright/ | Browser automation cache |

Contributors should never commit:

  • Credentials, API keys, or secrets
  • Generated reports from local testing
  • IDE-specific configuration files
  • Temporary or cache files

Sources: .gitignore L1-L93

Community Interaction Channels

WSHawk provides multiple channels for different types of community interaction:

| Channel | Purpose | URL/Contact | | --- | --- | --- | | GitHub Issues | Bug reports, feature requests | https://github.com/noobforanonymous/wshawk/issues | | GitHub Discussions | Questions, general discussion | GitHub Discussions | | Email | Security vulnerabilities (private) | security@rothackers.com | | Pull Requests | Code contributions | GitHub PR system |

For detailed templates and guidelines, see Issue Reporting and Templates.

Sources: CONTRIBUTING.md L127-L144

License Agreement

By contributing to WSHawk, you agree that your contributions will be licensed under the MIT License. This is the same license used by the main project.

The project URLs and metadata are defined at setup.py L57-L61

:

Sources: CONTRIBUTING.md L148-L150

setup.py L57-L61