Report Format and Output

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

• .github/workflows/ghcr-publish.yml
• README.md
• RELEASE_3.0.0.md
• RELEASE_SUMMARY.md
• docs/V3_COMPLETE_GUIDE.md
• wshawk/main.py

This page documents WSHawk's output artifacts: HTML report structure, logging formats, screenshot capture mechanisms, and customization options. For information about CVSS scoring methodology that appears in reports, see CVSS Scoring System. For configuration options that affect report generation, see Configuration and Authentication.

---

Purpose and Scope

WSHawk generates comprehensive security test reports containing vulnerability findings, evidence, and remediation guidance. This document covers:

• HTML Report Structure: Professional reports with CVSS scores, screenshots, and traffic logs
• Log Output Formats: Console and file logging with colored output
• Screenshot Capture: Browser-based XSS verification evidence
• Traffic Logs: WebSocket message request/response pairs
• Report Customization: Filename conventions and persistence options

All WSHawk execution modes (standard, interactive, advanced, defensive) generate the same report format for consistency.

---

Report Generation Pipeline

Data Flow from Scan to Report

flowchart TB
    subgraph "Scan Execution"
        Scanner["WSHawkV2<br/>(scanner_v2.py)"]
        VulnTests["Vulnerability Tests<br/>test_sql_injection_v2()<br/>test_xss_v2()<br/>test_command_injection_v2()"]
        SessionTests["SessionHijackingTester<br/>(session_hijacking_tester.py)"]
        Browser["HeadlessBrowserXSSVerifier<br/>(headless_xss_verifier.py)"]
    end
    
    subgraph "Data Collection"
        Vulns["vulnerabilities: List[Dict]<br/>scanner_v2.py:38"]
        TrafficLogs["traffic_logs: List<br/>scanner_v2.py:75"]
        Screenshots["screenshots: bytes<br/>Playwright captures"]
        Fingerprint["ServerFingerprinter<br/>fingerprint_info: Dict"]
        ScanInfo["scan_info: Dict<br/>target/duration/messages"]
    end
    
    subgraph "Report Generation"
        Reporter["EnhancedHTMLReporter<br/>(enhanced_reporter.py)"]
        ReportGen["generate_report()<br/>scanner_v2.py:662-666"]
    end
    
    subgraph "Output Artifacts"
        HTMLFile["wshawk_report_YYYYMMDD_HHMMSS.html<br/>scanner_v2.py:669"]
        HostFS["./reports/<br/>Volume mount in Docker"]
        CI["CI/CD Artifacts<br/>GitHub Actions upload"]
    end
    
    Scanner --> VulnTests
    Scanner --> SessionTests
    VulnTests --> Browser
    
    VulnTests --> Vulns
    Scanner --> TrafficLogs
    Browser --> Screenshots
    Scanner --> Fingerprint
    Scanner --> ScanInfo
    
    Vulns --> Reporter
    TrafficLogs --> Reporter
    Screenshots --> Reporter
    Fingerprint --> Reporter
    ScanInfo --> Reporter
    
    Reporter --> ReportGen
    ReportGen --> HTMLFile
    
    HTMLFile --> HostFS
    HTMLFile --> CI
    
    style Reporter fill:#f9f
    style HTMLFile fill:#9f9

Sources: wshawk/scanner_v2.py:545-680, wshawk/enhanced_reporter.py, wshawk/session_hijacking_tester.py:515-540

---

HTML Report Structure

Report Components

The HTML report generated by EnhancedHTMLReporter.generate_report() includes:

| Section | Content | Data Source | |---------|---------|-------------| | Summary Header | Target URL, scan duration, message counts, vulnerability totals | scan_info dict | | Risk Assessment | Overall risk level, CVSS distribution, severity breakdown | vulnerabilities list | | Server Fingerprint | Detected language, framework, database, technology stack | fingerprint_info dict | | Vulnerability Findings | Individual vulnerability details with CVSS scores | vulnerabilities list | | Evidence | Payload, response snippet, browser verification status | Per-vulnerability data | | Screenshots | XSS execution proof from Playwright | browser_verified flag | | Remediation | Actionable fix recommendations | Per-vulnerability recommendation | | Traffic Logs | Request/response pairs with timestamps | traffic_logs list |

Vulnerability Entry Format

Each vulnerability in the report contains the following fields:

{
    'type': 'SQL Injection',                    # Vulnerability category
    'severity': 'HIGH',                         # CVSS severity level
    'confidence': 'HIGH',                       # Verification confidence
    'description': 'SQL error-based injection', # Technical description
    'payload': "' OR '1'='1",                   # Attack vector used
    'response_snippet': 'SQL syntax error...',  # Evidence from response
    'browser_verified': True,                   # XSS browser execution flag
    'recommendation': 'Use parameterized queries', # Fix guidance
    'cvss_score': 7.5                          # Optional numeric score
}

Sources: wshawk/scanner_v2.py:193-201, wshawk/scanner_v2.py:273-283, wshawk/session_hijacking_tester.py:182-193

Report Filename Convention

Reports follow a timestamped naming convention:

wshawk_report_YYYYMMDD_HHMMSS.html

Generated at: wshawk/scanner_v2.py:669

Example: wshawk_report_20240315_143022.html

This enables:

• Historical tracking: Multiple scans produce uniquely named reports
• Chronological ordering: Filesystem sorting by creation time
• Audit compliance: Clear scan timestamp in filename

---

Log Output System

Console Logging Architecture

flowchart LR
    subgraph "Log Sources"
        Scanner["Scanner Modules"]
        Vuln["Vulnerability Tests"]
        Session["Session Tests"]
        Defensive["Defensive Validation"]
    end
    
    subgraph "Logger System"
        RootLogger["Root Logger<br/>logging.getLogger('wshawk')<br/>logger.py:48"]
        ModuleLogger["Module Loggers<br/>get_logger(name)<br/>logger.py:68-70"]
    end
    
    subgraph "Handlers"
        ConsoleHandler["StreamHandler<br/>sys.stdout<br/>logger.py:52"]
        FileHandler["FileHandler<br/>Optional log file<br/>logger.py:58-64"]
    end
    
    subgraph "Formatters"
        ColorFormatter["ColoredFormatter<br/>Terminal colors<br/>logger.py:21-35"]
        PlainFormatter["Standard Formatter<br/>Timestamp + level + message<br/>logger.py:62"]
    end
    
    subgraph "Output"
        Terminal["Colored Terminal Output"]
        LogFile["Plain Text Log File<br/>wshawk.log"]
    end
    
    Scanner --> RootLogger
    Vuln --> ModuleLogger
    Session --> ModuleLogger
    Defensive --> ModuleLogger
    
    RootLogger --> ConsoleHandler
    RootLogger --> FileHandler
    
    ConsoleHandler --> ColorFormatter
    FileHandler --> PlainFormatter
    
    ColorFormatter --> Terminal
    PlainFormatter --> LogFile

Sources: wshawk/logger.py:1-71, wshawk/main.py

Log Levels and Colors

The ColoredFormatter class provides color-coded console output:

| Level | Color | Usage | Code Location | |-------|-------|-------|---------------| | DEBUG | Cyan | Verbose debugging information | wshawk/logger.py:25 | | INFO | Blue | General informational messages | wshawk/logger.py:26 | | WARNING | Yellow | Non-critical issues | wshawk/logger.py:27 | | ERROR | Red | Error conditions | wshawk/logger.py:28 | | CRITICAL | Red + Bold | Critical failures | wshawk/logger.py:29 |

Specialized Logger Methods

WSHawk provides convenience logging methods in the Logger class:

Logger.info(message)      # Blue informational output
Logger.success(message)   # Green success messages
Logger.warning(message)   # Yellow warnings
Logger.error(message)     # Red errors
Logger.vuln(message)      # Red vulnerability findings
Logger.banner()           # ASCII art banner

Sources: wshawk/main.py

File Logging Configuration

Enable file logging via setup_logging():

setup_logging(verbose=True, log_file='wshawk.log')

File log format:

2024-03-15 14:30:22 - wshawk.scanner - INFO - Starting intelligent scan...
2024-03-15 14:30:25 - wshawk.verifier - WARNING - Low confidence detection
2024-03-15 14:30:30 - wshawk.scanner - ERROR - Connection timeout

Sources: wshawk/logger.py:37-66

---

Screenshot Capture System

Browser-Based XSS Verification

WSHawk uses Playwright to capture screenshots as proof of XSS execution:

flowchart TB
    subgraph "XSS Detection Flow"
        PayloadTest["test_xss_v2()<br/>scanner_v2.py:215-293"]
        Verifier["VulnerabilityVerifier<br/>verify_xss()"]
        Confidence["confidence == HIGH"]
    end
    
    subgraph "Browser Verification"
        HeadlessCheck["use_headless_browser<br/>scanner_v2.py:53"]
        InitBrowser["HeadlessBrowserXSSVerifier<br/>start()<br/>scanner_v2.py:254-256"]
        VerifyExec["verify_xss_execution()<br/>scanner_v2.py:257-260"]
    end
    
    subgraph "Screenshot Capture"
        InjectHTML["Inject payload into HTML<br/>headless_xss_verifier.py"]
        NavigatePage["page.goto()"]
        CaptureScreen["page.screenshot()"]
        Evidence["Evidence: screenshot bytes"]
    end
    
    subgraph "Report Integration"
        AddToVuln["vulnerabilities.append()<br/>browser_verified: True<br/>scanner_v2.py:280"]
        Screenshot["Screenshot embedded<br/>in HTML report"]
    end
    
    PayloadTest --> Verifier
    Verifier --> Confidence
    Confidence --> HeadlessCheck
    HeadlessCheck --> InitBrowser
    InitBrowser --> VerifyExec
    
    VerifyExec --> InjectHTML
    InjectHTML --> NavigatePage
    NavigatePage --> CaptureScreen
    CaptureScreen --> Evidence
    
    Evidence --> AddToVuln
    AddToVuln --> Screenshot
    
    style Screenshot fill:#9f9

Sources: wshawk/scanner_v2.py:215-293, wshawk/headless_xss_verifier.py

Screenshot Evidence Structure

When browser verification succeeds, the vulnerability entry includes:

{
    'type': 'Cross-Site Scripting (XSS)',
    'severity': 'CRITICAL',                     # Upgraded from HIGH
    'confidence': 'CRITICAL',                   # Browser verification confirms
    'description': 'REAL EXECUTION: Alert triggered in browser',
    'browser_verified': True,                   # Screenshot available
    'payload': '<script>alert(1)</script>',
    # ... additional fields
}

Console output indicates browser verification:

[VULN] XSS [CRITICAL]: REAL EXECUTION: Alert triggered in browser
[VULN] Payload: <script>alert(1)</script>
[VULN]   [BROWSER VERIFIED] Payload executed in real browser!

Sources: wshawk/scanner_v2.py:263-272

---

Traffic Logs

WebSocket Message Logging

The traffic_logs list captures all WebSocket communication:

# Structure (conceptual - actual implementation in enhanced_reporter.py)
traffic_logs = [
    {
        'timestamp': '2024-03-15 14:30:22',
        'direction': 'SENT',
        'message': '{"action": "test", "payload": "..."}',
        'size': 256
    },
    {
        'timestamp': '2024-03-15 14:30:23',
        'direction': 'RECEIVED',
        'message': '{"status": "error", "data": "SQL syntax..."}',
        'size': 512
    }
]

Message Statistics

Scan summary includes message counts:

scan_info = {
    'target': 'ws://target.com',
    'duration': 45.2,                # seconds
    'messages_sent': 1523,           # scanner_v2.py:68
    'messages_received': 1498        # scanner_v2.py:69
}

Console output:

[INFO] Scan complete in 45.20s
[INFO] Messages sent: 1523
[INFO] Messages received: 1498
[INFO] Vulnerabilities found: 7

Sources: wshawk/scanner_v2.py:634-640, wshawk/scanner_v2.py:652-658

---

Report Persistence and Distribution

File System Storage

Local Execution

Reports saved to current working directory:

$ wshawk ws://target.com
# Generates: ./wshawk_report_20240315_143022.html

Docker Volume Mounting

Mount host directory to persist reports:

docker run --rm \
  -v $(pwd)/reports:/app/reports \
  rothackers/wshawk ws://target.com

Reports appear in ./reports/wshawk_report_*.html on host.

Sources: README.md:48-62, Docker deployment documentation

CI/CD Artifact Upload

GitHub Actions example:

- name: Run WSHawk Scan
  run: wshawk ws://target.com

- name: Upload Report
  uses: actions/upload-artifact@v3
  with:
    name: security-report
    path: wshawk_report_*.html

Sources: CI/CD integration patterns from README.md:186-239

---

Report Customization Options

Programmatic Report Access

Using the Python API to access report data:

from wshawk.scanner_v2 import WSHawkV2
import asyncio

scanner = WSHawkV2("ws://target.com")
await scanner.run_intelligent_scan()

# Access vulnerabilities programmatically
for vuln in scanner.vulnerabilities:
    print(f"{vuln['type']}: {vuln['severity']}")
    print(f"  CVSS: {vuln.get('cvss_score', 'N/A')}")
    print(f"  Fix: {vuln['recommendation']}")

# Access scan statistics
print(f"Messages sent: {scanner.messages_sent}")
print(f"Duration: {(scanner.end_time - scanner.start_time).total_seconds()}s")

Sources: wshawk/scanner_v2.py:28-76, wshawk/scanner_v2.py:545-680

Custom Report Generation

Create custom reports using vulnerability data:

# After scan completes
vulnerabilities = scanner.vulnerabilities
scan_info = {
    'target': scanner.url,
    'duration': (scanner.end_time - scanner.start_time).total_seconds(),
    'messages_sent': scanner.messages_sent,
    'messages_received': scanner.messages_received
}

# Generate custom report
from wshawk.enhanced_reporter import EnhancedHTMLReporter
reporter = EnhancedHTMLReporter()
custom_html = reporter.generate_report(
    vulnerabilities,
    scan_info,
    scanner.fingerprinter.get_info()
)

# Save with custom filename
with open('custom_security_report.html', 'w') as f:
    f.write(custom_html)

Sources: wshawk/scanner_v2.py:662-673

---

Confidence Level Breakdown

Reports include a confidence distribution summary:

Confidence breakdown:
  CRITICAL: 2
  HIGH: 5
  MEDIUM: 3
  LOW: 1

Generated by: wshawk/scanner_v2.py:643-649

Confidence Levels Explained

| Level | Meaning | Example | |-------|---------|---------| | CRITICAL | Browser-verified execution | XSS with Playwright screenshot | | HIGH | Strong pattern match with context | SQL error messages with injection | | MEDIUM | Suspicious response patterns | Possible command output | | LOW | Reflection without exploitation proof | Payload echoed back unchanged |

Sources: wshawk/vulnerability_verifier.py (ConfidenceLevel enum), wshawk/scanner_v2.py:189-201

---

Session Security Report Format

Session hijacking tests generate structured results:

{
    'summary': {
        'total_tests': 6,
        'vulnerable': 3,
        'critical_vulnerabilities': 2,
        'risk_level': 'CRITICAL'
    },
    'vulnerabilities': [
        {
            'type': 'token_reuse',
            'vulnerable': True,
            'confidence': 'HIGH',
            'description': 'Session token can be reused after termination',
            'cvss_score': 7.5,
            'recommendation': 'Invalidate tokens on session close',
            'evidence': {...}
        }
    ]
}

Generated by: wshawk/session_hijacking_tester.py:515-540

Integrated into main report at: wshawk/scanner_v2.py:593-616

Sources: wshawk/session_hijacking_tester.py:515-540, wshawk/scanner_v2.py:593-616

---

Defensive Validation Report Format

Defensive validation tests produce specialized findings:

{
    'test': 'DNS Exfiltration Prevention',
    'status': 'VULNERABLE',
    'severity': 'HIGH',
    'cvss_score': 8.2,
    'description': 'Server performs DNS lookups to attacker-controlled domains',
    'evidence': {
        'dns_callback': True,
        'domain': 'attacker.oastify.com',
        'payload_type': 'XXE'
    },
    'recommendation': 'Implement egress filtering to block outbound DNS to untrusted domains'
}

Sources: Defensive validation modules (referenced in architecture diagrams), README.md:143-183

---

Report Generation Performance

Rate Limiter Statistics

Reports include rate limiting metrics:

Rate limiter: 1523 requests, 47 waits
  Current rate: 9.8, Adaptive adjustments: 12

Provides insights into:

• Total requests: Number of messages sent during scan
• Total waits: Number of times rate limiter delayed requests
• Current rate: Final requests-per-second rate
• Adaptive adjustments: Number of automatic rate adjustments

Sources: wshawk/scanner_v2.py:676-678, wshawk/rate_limiter.py

---

Summary

WSHawk generates comprehensive, professional HTML reports with:

• Structured vulnerability findings with CVSS v3.1 scores
• Browser-based screenshot evidence for XSS verification
• Complete traffic logs of WebSocket communication
• Server fingerprinting data for context-aware assessment
• Actionable remediation guidance for each finding
• Timestamped filenames for historical tracking
• Flexible persistence via local files, Docker volumes, or CI/CD artifacts
• Colored console logging with optional file output
• Programmatic access to scan results for custom workflows

Report filename: wshawk_report_YYYYMMDD_HHMMSS.html

Sources: wshawk/scanner_v2.py:545-680, wshawk/enhanced_reporter.py, wshawk/logger.py:1-71, README.md:119-129