Issue Reporting and Templates

Issue Reporting and Templates

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

Purpose and Scope

This document describes the GitHub issue reporting system for WSHawk, including the three standardized issue templates for bug reports, feature requests, and questions. The templates provide structured formats that ensure sufficient information is collected for effective triage and resolution. For information about contributing code and documentation, see Contributing Guidelines. For security vulnerability disclosure, see Security Policy and Vulnerability Disclosure.

Issue Template Types Overview

WSHawk provides three GitHub issue templates located in .github/ISSUE_TEMPLATE/ to standardize community interaction:

| Template | File | Auto Label | Purpose | |----------|------|------------|---------| | Bug Report | bug_report.md | bug | Report functional defects or unexpected behavior | | Feature Request | feature_request.md | enhancement | Suggest new capabilities or improvements | | Question/Discussion | -question-or-discussion.md | question | Ask usage questions or start technical discussions |

graph TB
    User["User Encounters Issue"]
    
    subgraph "Issue Type Selection"
        Bug["Bug Report<br/>.github/ISSUE_TEMPLATE/bug_report.md"]
        Feature["Feature Request<br/>.github/ISSUE_TEMPLATE/feature_request.md"]
        Question["Question/Discussion<br/>.github/ISSUE_TEMPLATE/-question-or-discussion.md"]
    end
    
    subgraph "Required Information Collection"
        BugFields["Version + Description + Steps<br/>Expected + Actual + OS + Python"]
        FeatureFields["Problem Statement<br/>Proposed Solution"]
        QuestionFields["Your Question"]
    end
    
    subgraph "Auto-Applied Metadata"
        BugLabel["Label: bug<br/>Title Prefix: [BUG]"]
        FeatureLabel["Label: enhancement<br/>Title Prefix: [FEATURE]"]
        QuestionLabel["Label: question<br/>Title Prefix: [QUESTION]"]
    end
    
    subgraph "Optional Enrichment"
        BugOpt["Logs/Screenshots"]
        FeatureOpt["Alternatives + Examples<br/>Contribution Offer"]
        QuestionOpt["Context + Version"]
    end
    
    User --> Bug
    User --> Feature
    User --> Question
    
    Bug --> BugFields
    Feature --> FeatureFields
    Question --> QuestionFields
    
    BugFields --> BugLabel
    FeatureFields --> FeatureLabel
    QuestionFields --> QuestionLabel
    
    BugFields --> BugOpt
    FeatureFields --> FeatureOpt
    QuestionFields --> QuestionOpt
    
    BugLabel --> Triage["GitHub Issue Created<br/>Auto-Labeled for Triage"]
    FeatureLabel --> Triage
    QuestionLabel --> Triage
    
    BugOpt --> Triage
    FeatureOpt --> Triage
    QuestionOpt --> Triage

Sources: .github/ISSUE_TEMPLATE/bug_report.md, .github/ISSUE_TEMPLATE/feature_request.md, .github/ISSUE_TEMPLATE/-question-or-discussion.md

Bug Report Template

The bug report template (.github/ISSUE_TEMPLATE/bug_report.md) collects comprehensive diagnostic information for reproducing and fixing defects.

Template Structure

graph LR
    Template["bug_report.md"]
    
    subgraph "YAML Front Matter"
        Meta["name: Bug report<br/>about: Report a bug in wshawk<br/>labels: bug"]
    end
    
    subgraph "Required Fields"
        Version["version<br/>wshawk Version<br/>placeholder: 2.0.x"]
        Desc["description<br/>Bug Description<br/>What happened?"]
        Steps["steps<br/>Steps to Reproduce<br/>1. Run command..."]
        Expected["expected<br/>Expected Behavior<br/>What should happen?"]
        Actual["actual<br/>Actual Behavior<br/>What actually happened?"]
        OS["os<br/>Operating System<br/>dropdown: Linux/macOS/Windows/Docker"]
    end
    
    subgraph "Optional Fields"
        Logs["logs<br/>Logs/Screenshots<br/>render: shell"]
        Python["python<br/>Python Version<br/>placeholder: 3.11"]
    end
    
    Template --> Meta
    Template --> Version
    Template --> Desc
    Template --> Steps
    Template --> Expected
    Template --> Actual
    Template --> OS
    Template --> Logs
    Template --> Python

Sources: .github/ISSUE_TEMPLATE/bug_report.md:1-88

Required Fields

All fields marked with validations.required: true must be completed before issue submission:

| Field ID | Label | Input Type | Validation | Purpose | |----------|-------|------------|------------|---------| | version | wshawk Version | text input | required | Identifies affected release (e.g., "2.0.x", "3.0.0") | | description | Bug Description | textarea | required | Clear description of unexpected behavior | | steps | Steps to Reproduce | textarea | required | Numbered reproduction steps starting with command invocation | | expected | Expected Behavior | textarea | required | What the system should do in the scenario | | actual | Actual Behavior | textarea | required | What the system actually does instead | | os | Operating System | dropdown | required | Environment: Linux, macOS, Windows, or Docker |

Sources: .github/ISSUE_TEMPLATE/bug_report.md:18-81

Optional Fields

Additional diagnostic information that aids in troubleshooting:

| Field ID | Label | Input Type | Rendering | Purpose | |----------|-------|------------|-----------|---------| | logs | Logs/Screenshots | textarea | shell | Paste terminal output, stack traces, or screenshots showing the error | | python | Python Version | text input | - | Python interpreter version (e.g., "3.11", "3.12") for environment context |

Sources: .github/ISSUE_TEMPLATE/bug_report.md:64-87

Example Bug Report Fields

version: "3.0.0"
description: "WSHawkV2 crashes when using --playwright flag with invalid URL"
steps: |
  1. Run: wshawk-advanced ws://invalid..url --playwright
  2. Scanner initializes HeadlessBrowserXSSVerifier
  3. Playwright attempts connection
  4. See traceback
expected: "Scanner should validate URL before browser launch, show error message"
actual: "Unhandled exception in playwright_async_api._impl._errors.Error"
os: "Docker"
logs: |
  Traceback (most recent call last):
    File "/app/wshawk/scanner_v2.py", line 234, in run_heuristic_scan
    ...
python: "3.11"

Sources: .github/ISSUE_TEMPLATE/bug_report.md:38-69

Feature Request Template

The feature request template (.github/ISSUE_TEMPLATE/feature_request.md) captures enhancement proposals with structured justification.

Template Structure and Fields

graph TB
    Template["feature_request.md"]
    
    subgraph "YAML Metadata"
        Meta["name: Feature request<br/>labels: enhancement<br/>title prefix: [FEATURE]"]
    end
    
    subgraph "Required Sections"
        Problem["problem<br/>Problem Statement<br/>What problem does this solve?<br/>required: true"]
        Solution["solution<br/>Proposed Solution<br/>How should this work?<br/>required: true"]
    end
    
    subgraph "Optional Sections"
        Alternatives["alternatives<br/>Alternatives Considered<br/>What other solutions?"]
        Examples["examples<br/>Examples<br/>render: shell<br/>Code/CLI examples"]
        Contribute["contribution<br/>Contribution checkbox<br/>I'm willing to implement this"]
    end
    
    Template --> Meta
    Template --> Problem
    Template --> Solution
    Template --> Alternatives
    Template --> Examples
    Template --> Contribute
    
    Problem --> Triage["Feature Evaluation"]
    Solution --> Triage
    Alternatives --> Triage
    Examples --> Triage
    Contribute --> Priority["Higher Priority if<br/>Contributor Available"]

Sources: .github/ISSUE_TEMPLATE/feature_request.md:1-55

Required Information

| Field ID | Label | Purpose | Example Content | |----------|-------|---------|-----------------| | problem | Problem Statement | Articulate the user need or pain point | "I'm frustrated when scanning large WebSocket applications because there's no way to pause and resume scans" | | solution | Proposed Solution | Describe the desired feature behavior | "I'd like to see a scan checkpoint system that saves state to SQLite and allows wshawk --resume <scan_id>" |

Sources: .github/ISSUE_TEMPLATE/feature_request.md:18-34

Optional Enrichment

| Field ID | Label | Purpose | |----------|-------|---------| | alternatives | Alternatives Considered | Show analysis of other approaches (e.g., external tools, workarounds) | | examples | Examples | Provide concrete CLI commands or code snippets showing usage (render: shell formatting) | | contribution | Contribution Checkbox | Indicate willingness to implement the feature via pull request |

The contribution checkbox (.github/ISSUE_TEMPLATE/feature_request.md:49-54) serves as a signal for maintainer prioritization—features with committed contributors often receive faster review.

Sources: .github/ISSUE_TEMPLATE/feature_request.md:36-54

Question and Discussion Template

The question template (.github/ISSUE_TEMPLATE/-question-or-discussion.md) provides a lightweight format for usage questions and technical discussions.

Template Structure

| Section | Field ID | Type | Required | Purpose | |---------|----------|------|----------|---------| | Question | question | textarea | Yes | The core question or discussion topic | | Context | context | textarea | No | Additional background, use case details, or configuration information | | Version | version | text input | No | WSHawk version for version-specific questions (placeholder: "2.0.x") |

graph LR
    User["User Has Question"]
    
    subgraph "Template Fields"
        Q["question field<br/>Your Question<br/>required: true"]
        C["context field<br/>Context<br/>optional"]
        V["version field<br/>wshawk Version<br/>optional"]
    end
    
    subgraph "Auto-Metadata"
        Label["Label: question<br/>Title: [QUESTION]"]
    end
    
    User --> Q
    Q --> C
    C --> V
    
    Q --> Label
    C --> Label
    V --> Label
    
    Label --> Discussion["GitHub Discussion Thread<br/>Community Answers"]

Sources: .github/ISSUE_TEMPLATE/-question-or-discussion.md:1-37

Minimal Required Information

Unlike bug reports and feature requests, questions only require the core question text (.github/ISSUE_TEMPLATE/-question-or-discussion.md:18-24). The context and version fields are optional but recommended for:

  • Configuration-specific questions (provide wshawk.yaml excerpt in context)
  • Deployment environment questions (Docker, Kubernetes setup details)
  • Integration questions (Jira, DefectDojo, webhook configurations)
  • Version-specific behavior queries (specify exact version)

Sources: .github/ISSUE_TEMPLATE/-question-or-discussion.md:26-36

Best Practices for Issue Reporting

Bug Reports

DO:

  • Include the exact command that triggered the bug (.github/ISSUE_TEMPLATE/bug_report.md:38-45)
  • Provide full stack traces in the logs field with shell rendering
  • Specify Docker image tag if using containers (e.g., rothackers/wshawk:3.0.0)
  • Test against the latest release before reporting
  • Sanitize sensitive information (credentials, internal URLs) from logs

DON'T:

  • Report usage questions as bugs (use question template instead)
  • Submit duplicate issues without searching existing reports
  • Omit version information—different releases have different behaviors

Feature Requests

DO:

DON'T:

  • Request features that contradict WSHawk's design (e.g., removing the resilience layer)
  • Propose features without use case justification
  • Submit feature requests for third-party integration bugs (report to that platform)

Questions

DO:

  • Search existing issues and documentation before asking
  • Provide version and context for configuration questions
  • Include relevant excerpts from wshawk.yaml or command output
  • Reference specific documentation pages that were unclear

DON'T:

  • Use the question template for bug reports
  • Ask multiple unrelated questions in a single issue
  • Request debugging help without providing logs or configuration

Sources: .github/ISSUE_TEMPLATE/bug_report.md, .github/ISSUE_TEMPLATE/feature_request.md, .github/ISSUE_TEMPLATE/-question-or-discussion.md

Issue Lifecycle and Triage Workflow

graph TB
    subgraph "Issue Creation"
        Select["User Selects Template<br/>GitHub Issue Interface"]
        Fill["Fill Required Fields<br/>+ Optional Context"]
        Submit["Submit Issue<br/>Auto-labeled by template"]
    end
    
    subgraph "Auto-Processing"
        BugLabel["bug_report.md → bug label"]
        FeatureLabel["feature_request.md → enhancement label"]
        QuestionLabel["-question-or-discussion.md → question label"]
    end
    
    subgraph "Maintainer Triage"
        Review["Review for Completeness"]
        ValidBug{"Valid Bug?"}
        ValidFeature{"Aligned with Roadmap?"}
        ValidQuestion{"Answerable?"}
    end
    
    subgraph "Issue States"
        NeedsInfo["Label: needs-info<br/>Request more details"]
        Confirmed["Label: confirmed<br/>Bug reproduced"]
        Accepted["Label: accepted<br/>Feature planned"]
        Answered["Provide answer<br/>Close issue"]
        Duplicate["Close as duplicate<br/>Link to original"]
        WontFix["Close with explanation<br/>Label: wontfix"]
    end
    
    Select --> Fill
    Fill --> Submit
    
    Submit --> BugLabel
    Submit --> FeatureLabel
    Submit --> QuestionLabel
    
    BugLabel --> Review
    FeatureLabel --> Review
    QuestionLabel --> Review
    
    Review --> ValidBug
    Review --> ValidFeature
    Review --> ValidQuestion
    
    ValidBug -->|No| NeedsInfo
    ValidBug -->|Yes| Confirmed
    ValidBug -->|Duplicate| Duplicate
    
    ValidFeature -->|Needs Clarification| NeedsInfo
    ValidFeature -->|Yes| Accepted
    ValidFeature -->|Out of Scope| WontFix
    
    ValidQuestion -->|Incomplete| NeedsInfo
    ValidQuestion -->|Yes| Answered
    
    NeedsInfo -->|User Responds| Review
    
    Confirmed --> Dev["Development & PR"]
    Accepted --> Dev

Sources: .github/ISSUE_TEMPLATE/bug_report.md:1-12, .github/ISSUE_TEMPLATE/feature_request.md:1-11, .github/ISSUE_TEMPLATE/-question-or-discussion.md:1-11

Template Field Cross-Reference

The following table maps template fields to their technical implementation in the GitHub issue form schema:

| Template | Field ID | Attribute Path | Validation Rule | Line Reference | |----------|----------|----------------|-----------------|----------------| | bug_report.md | version | attributes.label | validations.required: true | .github/ISSUE_TEMPLATE/bug_report.md:19-25 | | bug_report.md | description | attributes.label | validations.required: true | .github/ISSUE_TEMPLATE/bug_report.md:28-34 | | bug_report.md | steps | attributes.label | validations.required: true | .github/ISSUE_TEMPLATE/bug_report.md:37-46 | | bug_report.md | os | attributes.options | validations.required: true | .github/ISSUE_TEMPLATE/bug_report.md:71-81 | | bug_report.md | logs | attributes.render | none (optional) | .github/ISSUE_TEMPLATE/bug_report.md:64-69 | | feature_request.md | problem | attributes.label | validations.required: true | .github/ISSUE_TEMPLATE/feature_request.md:19-24 | | feature_request.md | solution | attributes.label | validations.required: true | .github/ISSUE_TEMPLATE/feature_request.md:27-34 | | feature_request.md | contribution | attributes.options | none (optional) | .github/ISSUE_TEMPLATE/feature_request.md:49-54 | | -question-or-discussion.md | question | attributes.label | validations.required: true | .github/ISSUE_TEMPLATE/-question-or-discussion.md:19-24 | | -question-or-discussion.md | context | attributes.label | none (optional) | .github/ISSUE_TEMPLATE/-question-or-discussion.md:26-31 |

Sources: .github/ISSUE_TEMPLATE/bug_report.md, .github/ISSUE_TEMPLATE/feature_request.md, .github/ISSUE_TEMPLATE/-question-or-discussion.md

Integration with Development Workflow

Issues created from these templates integrate with the broader WSHawk development ecosystem:

  • Bug Reports link to pull requests via GitHub's issue-PR linking (e.g., "Fixes #123")
  • Feature Requests tagged enhancement appear in release planning milestones
  • Questions inform documentation improvements when common patterns emerge

For implementing fixes or features, see Contributing Guidelines. For local development and testing, see Development Environment Setup and Testing Infrastructure.

Sources: .github/ISSUE_TEMPLATE/bug_report.md, .github/ISSUE_TEMPLATE/feature_request.md