Issue Reporting and Templates

Relevant source files

• .github/ISSUE_TEMPLATE/-question-or-discussion.md
• .github/ISSUE_TEMPLATE/bug_report.md
• .github/ISSUE_TEMPLATE/feature_request.md
• CONTRIBUTING.md

Purpose and Scope

This document explains how to report bugs, request features, and ask questions in the WSHawk project using GitHub's structured issue templates. It covers the three issue templates available in the repository, their required fields, and the appropriate scenarios for each template type.

For reporting security vulnerabilities, see Security Policy and Vulnerability Disclosure, which describes the private disclosure process via email rather than public GitHub issues.

For broader contribution guidelines including code contributions and pull requests, see the CONTRIBUTING.md documentation referenced throughout this page.

---

GitHub Issue Template System

WSHawk implements a structured issue reporting system through GitHub's issue template feature. The project provides three distinct templates, each designed for specific interaction types:

| Template | File Location | Labels | Use Case | | --- | --- | --- | --- | | Bug Report | .github/ISSUE_TEMPLATE/bug_report.md | bug | Software defects, errors, unexpected behavior | | Feature Request | .github/ISSUE_TEMPLATE/feature_request.md | enhancement | New capabilities, improvements, functionality additions | | Question/Discussion | .github/ISSUE_TEMPLATE/-question-or-discussion.md | question | Usage questions, clarifications, general discussion |

All templates are YAML front-matter formatted Markdown files that render as interactive forms in GitHub's issue creation interface. This structure ensures consistent information gathering across all community interactions.

Sources: .github/ISSUE_TEMPLATE/bug_report.md L1-L88

.github/ISSUE_TEMPLATE/feature_request.md L1-L55

.github/ISSUE_TEMPLATE/-question-or-discussion.md L1-L37

---

Bug Report Template Structure

The bug report template is the most comprehensive, collecting eight categories of information to enable efficient debugging and reproduction.

Template Fields and Validation

flowchart TD

User["User Encounters Bug"]
GitHub["GitHub Issue Creation"]
Template["bug_report.md Template"]
Version["wshawk Version<br>type: input<br>required: true<br>placeholder: 2.0.x"]
Description["Bug Description<br>type: textarea<br>required: true<br>clear description"]
Steps["Steps to Reproduce<br>type: textarea<br>required: true<br>numbered steps"]
Expected["Expected Behavior<br>type: textarea<br>required: true"]
Actual["Actual Behavior<br>type: textarea<br>required: true"]
Logs["Logs/Screenshots<br>type: textarea<br>optional<br>render: shell"]
OS["Operating System<br>type: dropdown<br>required: true<br>options: Linux/macOS/Windows/Docker"]
Python["Python Version<br>type: input<br>optional<br>placeholder: 3.11"]
Validation["Validation Pass"]
Issue["GitHub Issue Created<br>Title: [BUG]<br>Label: bug"]

Template -.-> Version
Template -.-> Description
Template -.-> Steps
Template -.-> Expected
Template -.-> Actual
Template -.-> Logs
Template -.-> OS
Template -.-> Python
Version -.-> Validation
Description -.-> Validation
Steps -.-> Validation
Expected -.-> Validation
Actual -.-> Validation
OS -.-> Validation
Logs -.-> Validation
Python -.-> Validation
Validation -.-> Issue
User -.-> GitHub
GitHub -.-> Template

Diagram: Bug Report Template Field Structure and Validation Flow

Required vs Optional Fields

The template enforces five mandatory fields through GitHub's validation system:

Required Fields:

• wshawk Version [line 19-25](https://github.com/noobforanonymous/wshawk/blob/0eebedf4/line 19-25) - Version identification for reproducibility
• Bug Description [line 27-34](https://github.com/noobforanonymous/wshawk/blob/0eebedf4/line 27-34) - Clear problem statement
• Steps to Reproduce [line 36-46](https://github.com/noobforanonymous/wshawk/blob/0eebedf4/line 36-46) - Actionable reproduction steps
• Expected Behavior [line 48-54](https://github.com/noobforanonymous/wshawk/blob/0eebedf4/line 48-54) - Expected outcome
• Actual Behavior [line 56-62](https://github.com/noobforanonymous/wshawk/blob/0eebedf4/line 56-62) - Observed outcome
• Operating System [line 71-81](https://github.com/noobforanonymous/wshawk/blob/0eebedf4/line 71-81) - Environment context via dropdown (Linux/macOS/Windows/Docker)

Optional Fields:

• Logs/Screenshots [line 64-69](https://github.com/noobforanonymous/wshawk/blob/0eebedf4/line 64-69) - Supporting evidence with shell rendering
• Python Version [line 83-87](https://github.com/noobforanonymous/wshawk/blob/0eebedf4/line 83-87) - Interpreter version

Field Type Specifications

The template uses three GitHub form field types:

| Field Type | Usage | Validation Capability | | --- | --- | --- | | input | Single-line text entry | required: true/false, placeholder | | textarea | Multi-line text entry | required: true/false, placeholder, render | | dropdown | Pre-defined options | required: true/false, options: [] |

The render: shell attribute on the Logs/Screenshots field [line 69](https://github.com/noobforanonymous/wshawk/blob/0eebedf4/line 69)

enables syntax highlighting for pasted terminal output.

Sources: .github/ISSUE_TEMPLATE/bug_report.md L1-L88

---

Feature Request Template Structure

The feature request template focuses on problem-solution articulation and implementation willingness assessment.

Template Field Hierarchy

flowchart TD

User["User Identifies Need"]
Template["feature_request.md Template"]
Problem["Problem Statement<br>type: textarea<br>required: true<br>What problem does this solve?"]
Solution["Proposed Solution<br>type: textarea<br>required: true<br>How should this work?"]
Alternatives["Alternatives Considered<br>type: textarea<br>optional<br>Other solutions?"]
Examples["Examples<br>type: textarea<br>optional<br>render: shell"]
Contribution["Contribution Checkbox<br>type: checkboxes<br>optional<br>Willing to implement?"]
CoreInfo["Core Information Complete"]
EnhancedInfo["Enhanced Context"]
Issue["GitHub Issue Created<br>Title: [FEATURE]<br>Label: enhancement"]

Template -.-> Problem
Template -.-> Solution
Template -.-> Alternatives
Template -.-> Examples
Template -.-> Contribution
Problem -.-> CoreInfo
Solution -.-> CoreInfo
Alternatives -.-> EnhancedInfo
Examples -.-> EnhancedInfo
Contribution -.-> EnhancedInfo
CoreInfo -.-> Issue
EnhancedInfo -.-> Issue
User -.-> Template

Diagram: Feature Request Template Structure and Information Flow

Required Components

Mandatory Fields:

• Problem Statement [line 18-25](https://github.com/noobforanonymous/wshawk/blob/0eebedf4/line 18-25) - Describes the user pain point or limitation
• Proposed Solution [line 27-34](https://github.com/noobforanonymous/wshawk/blob/0eebedf4/line 27-34) - Articulates the desired functionality

Optional Enhancements:

• Alternatives Considered [line 36-41](https://github.com/noobforanonymous/wshawk/blob/0eebedf4/line 36-41) - Shows exploration of other approaches
• Examples [line 43-47](https://github.com/noobforanonymous/wshawk/blob/0eebedf4/line 43-47) - Provides concrete usage examples with shell rendering
• Contribution Checkbox [line 49-54](https://github.com/noobforanonymous/wshawk/blob/0eebedf4/line 49-54) - Indicates contributor willingness

Contribution Signaling

The template includes a unique checkboxes field type [line 49-54](https://github.com/noobforanonymous/wshawk/blob/0eebedf4/line 49-54)

that allows feature requesters to signal implementation interest:

- type: checkboxes
  id: contribution
  attributes:
    label: Contribution
    options:
      - label: I'm willing to implement this feature

This checkbox serves dual purposes:

1. Prioritization signal - Maintainers can prioritize features with committed implementers
2. Contribution funnel - Converts feature requests into potential pull requests

Sources: .github/ISSUE_TEMPLATE/feature_request.md L1-L55

---

Question and Discussion Template

The simplest template, designed for open-ended inquiries and discussions.

Minimal Field Structure

flowchart TD

User["User Has Question"]
Template["-question-or-discussion.md"]
Question["Your Question<br>type: textarea<br>required: true<br>What would you like to know?"]
Context["Context<br>type: textarea<br>optional<br>Additional context?"]
Version["wshawk Version<br>type: input<br>optional<br>placeholder: 2.0.x"]
Issue["GitHub Issue Created<br>Title: [QUESTION]<br>Label: question"]

Template -.-> Question
Template -.-> Context
Template -.-> Version
Question -.-> Issue
Context -.-> Issue
Version -.-> Issue
User -.-> Template

Diagram: Question/Discussion Template Minimal Structure

Field Specifications

Required:

• Your Question [line 18-24](https://github.com/noobforanonymous/wshawk/blob/0eebedf4/line 18-24) - The core inquiry

Optional:

• Context [line 26-31](https://github.com/noobforanonymous/wshawk/blob/0eebedf4/line 26-31) - Situational background
• wshawk Version [line 32-36](https://github.com/noobforanonymous/wshawk/blob/0eebedf4/line 32-36) - Version context for usage questions

This template intentionally minimizes friction for community engagement. Unlike the bug report template's mandatory environment fields, questions only require the question text itself, acknowledging that many inquiries are conceptual rather than environment-specific.

Sources: .github/ISSUE_TEMPLATE/-question-or-discussion.md L1-L37

---

Issue Template File Structure

All three templates follow GitHub's YAML-based issue form specification:

flowchart TD

FrontMatter["YAML Front Matter<br>---<br>name: Template Name<br>about: Description<br>title: Prefix<br>labels: [label]<br>assignees: ''<br>---"]
FormBody["Form Body<br>body: array of field definitions"]
Field1["Field Definition<br>- type: markdown/input/textarea/dropdown/checkboxes<br>  id: unique_id<br>  attributes:<br>    label: Field Label<br>    description: Help text<br>    placeholder: Example<br>  validations:<br>    required: true/false"]
UIForm["Interactive Web Form<br>Field validation<br>Auto-labeling<br>Title prefixing"]

Field1 -.-> UIForm

subgraph subGraph1 ["Rendered in GitHub"]
    UIForm
end

subgraph subGraph0 ["Template File Structure"]
    FrontMatter
    FormBody
    Field1
    FrontMatter -.-> FormBody
    FormBody -.-> Field1
end

Diagram: GitHub Issue Template File Structure to Rendered Form

Common Template Elements

All templates share structural patterns:

Front Matter Structure (Lines 1-8 in each file):

name: Display Name
about: Description
title: '[PREFIX] '
labels: label_name
assignees: ''

Body Array Pattern:

• Starts with body: key after front matter
• Contains array of field objects
• Each field has type, id, attributes, and optional validations

Field Type Distribution:

| Field Type | Bug Report | Feature Request | Question | | --- | --- | --- | --- | | markdown | 1 | 1 | 1 | | input | 2 | 0 | 1 | | textarea | 5 | 4 | 2 | | dropdown | 1 | 0 | 0 | | checkboxes | 0 | 1 | 0 |

Sources: .github/ISSUE_TEMPLATE/bug_report.md L1-L12

.github/ISSUE_TEMPLATE/feature_request.md L1-L12

.github/ISSUE_TEMPLATE/-question-or-discussion.md L1-L12

---

Issue Reporting Workflow

Complete Issue Lifecycle

flowchart TD

Start["User Identifies Issue/Need"]
Decision["Issue Type?"]
BugPath["Select Bug Report Template"]
FeaturePath["Select Feature Request Template"]
QuestionPath["Select Question Template"]
SecurityPath["DO NOT USE GITHUB<br>Email security@rothackers.com<br>See SECURITY.md"]
BugForm["Complete Bug Report Form<br>- wshawk version (required)<br>- Description (required)<br>- Reproduction steps (required)<br>- Expected/Actual behavior (required)<br>- OS selection (required)<br>- Logs/screenshots (optional)<br>- Python version (optional)"]
FeatureForm["Complete Feature Request Form<br>- Problem statement (required)<br>- Proposed solution (required)<br>- Alternatives (optional)<br>- Examples (optional)<br>- Contribution willingness (optional)"]
QuestionForm["Complete Question Form<br>- Your question (required)<br>- Context (optional)<br>- Version (optional)"]
Submit["Submit Issue<br>Auto-labeled: bug<br>Title: [BUG] ..."]
Submit2["Submit Issue<br>Auto-labeled: enhancement<br>Title: [FEATURE] ..."]
Submit3["Submit Issue<br>Auto-labeled: question<br>Title: [QUESTION] ..."]
Triage["Maintainer Triage<br>- Validate reproducibility<br>- Assign priority<br>- Request additional info"]
Respond["Community Response<br>- Answer question<br>- Point to documentation<br>- Close or convert to discussion"]
Action["Action Taken<br>- Bug fix PR<br>- Feature implementation<br>- Documentation update<br>- Close as won't fix"]
SecureChannel["Private Email Channel<br>Responsible disclosure<br>See page 9.1"]

Start -.->|"Usage Question"| Decision
Decision -.->|"New Capability"| BugPath
Decision -.-> FeaturePath
Decision -.-> QuestionPath
Decision -.->|"Security Vulnerability"| SecurityPath
BugPath -.->|"Software Defect"| BugForm
FeaturePath -.-> FeatureForm
QuestionPath -.-> QuestionForm
BugForm -.-> Submit
FeatureForm -.-> Submit2
QuestionForm -.-> Submit3
Submit -.-> Triage
Submit2 -.-> Triage
Submit3 -.-> Respond
Triage -.-> Action
SecurityPath -.-> SecureChannel

Diagram: Complete Issue Reporting Workflow from Identification to Resolution

Template Selection Decision Tree

Use Bug Report Template when:

• WSHawk produces an error or exception
• Functionality works differently than documented
• Commands exit with unexpected codes
• Reports contain incorrect information
• Scanner fails to detect known vulnerabilities

Use Feature Request Template when:

• Requesting new vulnerability detection modules
• Suggesting new CLI options or commands
• Proposing new mutation strategies
• Requesting output format additions
• Suggesting payload collection expansions

Use Question Template when:

• Unclear about usage patterns
• Need clarification on documentation
• Want to discuss best practices
• Seeking guidance on configuration
• Exploring integration approaches

Never use public templates for:

• Security vulnerabilities in WSHawk itself
• Exploitable bugs that could harm users
• Authentication bypass issues
• Any vulnerability requiring responsible disclosure

Sources: CONTRIBUTING.md L115-L127

.github/ISSUE_TEMPLATE/bug_report.md

.github/ISSUE_TEMPLATE/feature_request.md

.github/ISSUE_TEMPLATE/-question-or-discussion.md

---

Best Practices for Issue Reporting

Bug Report Best Practices

Version Specification:

• Use exact version numbers (e.g., 2.0.5, not "latest")
• For Docker deployments, specify image tag: rothackers/wshawk:2.0.5
• Include commit hash if testing development builds

Reproduction Steps:

• Provide complete command line invocations
• Include all relevant CLI flags (--playwright, --rate, etc.)
• Specify target WebSocket URL format (ws:// vs wss://)
• Attach authentication configuration files if applicable
• Number steps sequentially for clarity

Log Inclusion:

• Use the render: shell field [bug_report.md L69](https://github.com/noobforanonymous/wshawk/blob/0eebedf4/bug_report.md#L69-L69) for proper formatting
• Include full stack traces, not truncated output
• Capture DEBUG level logs if available
• Include timestamps for timing-related issues

Environment Details:

• OS selection dropdown handles Linux/macOS/Windows/Docker [bug_report.md L72-L79](https://github.com/noobforanonymous/wshawk/blob/0eebedf4/bug_report.md#L72-L79)
• For Docker: specify host OS AND container environment
• Python version helps diagnose dependency issues [bug_report.md L84-L87](https://github.com/noobforanonymous/wshawk/blob/0eebedf4/bug_report.md#L84-L87)

Feature Request Best Practices

Problem Statement Articulation:

• Focus on the "why" before the "what"
• Describe user impact, not technical implementation
• Reference existing WSHawk capabilities that fall short
• Quantify problem scope when possible

Solution Proposal:

• Describe desired behavior, not code changes
• Provide example command invocations showing intended usage
• Consider integration with existing features
• Account for backward compatibility

Example Provision:

• Use the render: shell field [feature_request.md L47](https://github.com/noobforanonymous/wshawk/blob/0eebedf4/feature_request.md#L47-L47) for command examples
• Show before/after scenarios
• Include expected output formats
• Demonstrate edge cases

Contribution Signal:

• Check the contribution box [feature_request.md L50-L54](https://github.com/noobforanonymous/wshawk/blob/0eebedf4/feature_request.md#L50-L54) if willing to implement
• Increases likelihood of feature acceptance
• Maintainers can provide implementation guidance
• Streamlines pull request review process

Question Best Practices

Question Formulation:

• Be specific about the uncertain behavior
• Separate multiple distinct questions into separate issues
• Search existing issues/discussions before posting
• Include version context [-question-or-discussion.md L32-L36](https://github.com/noobforanonymous/wshawk/blob/0eebedf4/-question-or-discussion.md#L32-L36) for usage questions

Context Provision:

• Describe what you're trying to accomplish
• Explain what you've already tried
• Reference documentation sections that are unclear
• Include relevant configuration snippets

Sources: CONTRIBUTING.md L115-L127

---

Integration with CONTRIBUTING.md

The issue templates are one component of WSHawk's contribution system, which is comprehensively documented in CONTRIBUTING.md:

Relationship to Contribution Workflow

flowchart TD

IssueTemplates["Issue Templates<br>bug_report.md<br>feature_request.md<br>-question-or-discussion.md"]
Fork["Fork Repository<br>CONTRIBUTING.md:17-22"]
Branch["Create Branch<br>CONTRIBUTING.md:36-39"]
Develop["Code Changes<br>PEP 8, type hints, docstrings<br>CONTRIBUTING.md:42-48"]
Test["Run Tests<br>test_modules_quick.py<br>CONTRIBUTING.md:50-60"]
PR["Submit Pull Request<br>CONTRIBUTING.md:70-90"]
VulnModule["New Vulnerability Module<br>wshawk/*.py"]
Mutator["New Mutator<br>wshawk/mutators/"]
Payloads["New Payloads<br>payloads/*.txt"]
Closes["Closes Original Issue"]

IssueTemplates -.->|"Bug Report Leads To"| Fork
IssueTemplates -.->|"Feature Request With ContributionCheckbox Checked"| Fork
Develop -.-> VulnModule
Develop -.-> Mutator
Develop -.-> Payloads
VulnModule -.-> Test
Mutator -.-> Test
Payloads -.-> Test
PR -.-> Closes

subgraph subGraph2 ["Extension Points (CONTRIBUTING.md:92-114)"]
    VulnModule
    Mutator
    Payloads
end

subgraph subGraph1 ["Development Workflow (CONTRIBUTING.md)"]
    Fork
    Branch
    Develop
    Test
    PR
    Fork -.-> Branch
    Branch -.-> Develop
    Test -.->|"After Merge"| PR
end

subgraph subGraph0 ["Community Interaction (Page 9.2)"]
    IssueTemplates
end

Diagram: Issue Template Integration with Development Contribution Workflow

Contribution Path Matrix

| Starting Point | Next Steps | Documentation | | --- | --- | --- | | Bug Report Issue | 1. Issue triage2. Fork repo3. Create fix4. Submit PR | CONTRIBUTING.md L17-L90 | | Feature Request (Checkbox Unchecked) | 1. Community discussion2. Maintainer evaluation3. Roadmap consideration | Issue comments | | Feature Request (Checkbox Checked) | 1. Fork repo2. Follow extension guides3. Submit PR | CONTRIBUTING.md L92-L114 | | Question Issue | 1. Community answers2. Documentation improvement3. Issue closure | Issue comments |

Cross-Reference to CONTRIBUTING.md Sections

• Bug Reporting Details: CONTRIBUTING.md L115-L127
• Code Style Guidelines: CONTRIBUTING.md L42-L48
• Testing Requirements: CONTRIBUTING.md L50-L60
• Pull Request Guidelines: CONTRIBUTING.md L85-L90
• Extension Point Documentation: CONTRIBUTING.md L92-L114
• Security Issue Handling: CONTRIBUTING.md L129-L133

Sources: CONTRIBUTING.md L1-L155

---

Template Maintenance and Evolution

Template File Locations

flowchart TD

Root[".github/"]
IssueTemplate["ISSUE_TEMPLATE/"]
Bug["bug_report.md<br>Lines: 88<br>Fields: 8<br>Required: 5"]
Feature["feature_request.md<br>Lines: 55<br>Fields: 5<br>Required: 2"]
Question["-question-or-discussion.md<br>Lines: 37<br>Fields: 3<br>Required: 1"]
BugLabel["Auto-labels: bug<br>Title prefix: [BUG]"]
FeatureLabel["Auto-labels: enhancement<br>Title prefix: [FEATURE]"]
QuestionLabel["Auto-labels: question<br>Title prefix: [QUESTION]"]

Root -.-> IssueTemplate
IssueTemplate -.-> Bug
IssueTemplate -.-> Feature
IssueTemplate -.-> Question
Bug -.-> BugLabel
Feature -.-> FeatureLabel
Question -.-> QuestionLabel

Diagram: Issue Template File Organization and Metadata

GitHub Integration Points

The templates integrate with GitHub's issue system through several mechanisms:

1. Automatic Labeling: labels: ["label_name"] in front matter applies labels on issue creation
2. Title Prefixing: title: "[PREFIX] " prepends text to issue titles
3. Form Validation: validations: required: true enforces mandatory fields
4. Field Rendering: render: shell enables syntax highlighting for logs/code
5. Dropdown Options: options: [] restricts values to predefined choices

These integrations eliminate manual triage work and ensure consistent issue metadata.

Sources: .github/ISSUE_TEMPLATE/bug_report.md L1-L88

.github/ISSUE_TEMPLATE/feature_request.md L1-L55

.github/ISSUE_TEMPLATE/-question-or-discussion.md L1-L37

---

Summary

WSHawk's issue reporting system provides three structured pathways for community interaction:

| Template | Fields | Mandatory | Auto-Label | Use Case | | --- | --- | --- | --- | --- | | bug_report.md | 8 | 5 | bug | Software defects, errors | | feature_request.md | 5 | 2 | enhancement | New capabilities, improvements | | -question-or-discussion.md | 3 | 1 | question | Usage questions, clarifications |

All templates leverage GitHub's YAML form specification to enforce structured information gathering, reducing back-and-forth during issue triage. The bug report template is the most comprehensive, requiring version, reproduction steps, and environment details. The feature request template balances problem articulation with optional contribution signaling. The question template minimizes friction for community engagement.

Security vulnerabilities must never use these public templates; instead, they require private disclosure via email as documented in Security Policy and Vulnerability Disclosure.

For code contributions following issue creation, consult CONTRIBUTING.md for development workflow, coding standards, and extension point documentation.