Report Format and Output

Relevant source files

• README.md
• RELEASE_SUMMARY.md
• wshawk/init.py
• wshawk/logger.py
• wshawk/scanner_v2.py
• wshawk/session_hijacking_tester.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 TD

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)"]
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"]
Reporter["EnhancedHTMLReporter<br>(enhanced_reporter.py)"]
ReportGen["generate_report()<br>scanner_v2.py:662-666"]
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"]

VulnTests -.-> Vulns
Scanner -.-> TrafficLogs
Browser -.-> Screenshots
Scanner -.-> Fingerprint
Scanner -.-> ScanInfo
Vulns -.-> Reporter
TrafficLogs -.-> Reporter
Screenshots -.-> Reporter
Fingerprint -.-> Reporter
ScanInfo -.-> Reporter
ReportGen -.-> HTMLFile

subgraph subGraph3 ["Output Artifacts"]
    HTMLFile
    HostFS
    CI
    HTMLFile -.-> HostFS
    HTMLFile -.-> CI
end

subgraph subGraph2 ["Report Generation"]
    Reporter
    ReportGen
    Reporter -.-> ReportGen
end

subgraph subGraph1 ["Data Collection"]
    Vulns
    TrafficLogs
    Screenshots
    Fingerprint
    ScanInfo
end

subgraph subGraph0 ["Scan Execution"]
    Scanner
    VulnTests
    SessionTests
    Browser
    Scanner -.-> VulnTests
    Scanner -.-> SessionTests
    VulnTests -.-> Browser
end

Sources: wshawk/scanner_v2.py L545-L680

wshawk/enhanced_reporter.py

wshawk/session_hijacking_tester.py L515-L540

---

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 L193-L201

wshawk/scanner_v2.py L273-L283

wshawk/session_hijacking_tester.py L182-L193

Report Filename Convention

Reports follow a timestamped naming convention:

wshawk_report_YYYYMMDD_HHMMSS.html

Generated at: wshawk/scanner_v2.py L669

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 TD

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

Scanner -.-> RootLogger
Vuln -.-> ModuleLogger
Session -.-> ModuleLogger
Defensive -.-> ModuleLogger
RootLogger -.-> ConsoleHandler
RootLogger -.-> FileHandler
ConsoleHandler -.-> ColorFormatter
FileHandler -.-> PlainFormatter
ColorFormatter -.-> Terminal
PlainFormatter -.-> LogFile

subgraph Output ["Output"]
    Terminal
    LogFile
end

subgraph Formatters ["Formatters"]
    ColorFormatter
    PlainFormatter
end

subgraph Handlers ["Handlers"]
    ConsoleHandler
    FileHandler
end

subgraph subGraph1 ["Logger System"]
    RootLogger
    ModuleLogger
end

subgraph subGraph0 ["Log Sources"]
    Scanner
    Vuln
    Session
    Defensive
end

Sources: wshawk/logger.py L1-L71

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 L25 | | INFO | Blue | General informational messages | wshawk/logger.py L26 | | WARNING | Yellow | Non-critical issues | wshawk/logger.py L27 | | ERROR | Red | Error conditions | wshawk/logger.py L28 | | CRITICAL | Red + Bold | Critical failures | wshawk/logger.py L29 |

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 L37-L66

---

Screenshot Capture System

Browser-Based XSS Verification

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

flowchart TD

PayloadTest["test_xss_v2()<br>scanner_v2.py:215-293"]
Verifier["VulnerabilityVerifier<br>verify_xss()"]
Confidence["confidence == HIGH"]
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"]
InjectHTML["Inject payload into HTML<br>headless_xss_verifier.py"]
NavigatePage["page.goto()"]
CaptureScreen["page.screenshot()"]
Evidence["Evidence: screenshot bytes"]
AddToVuln["vulnerabilities.append()<br>browser_verified: True<br>scanner_v2.py:280"]
Screenshot["Screenshot embedded<br>in HTML report"]

Confidence -.-> HeadlessCheck
VerifyExec -.-> InjectHTML
Evidence -.-> AddToVuln

subgraph subGraph3 ["Report Integration"]
    AddToVuln
    Screenshot
    AddToVuln -.-> Screenshot
end

subgraph subGraph2 ["Screenshot Capture"]
    InjectHTML
    NavigatePage
    CaptureScreen
    Evidence
    InjectHTML -.-> NavigatePage
    NavigatePage -.-> CaptureScreen
    CaptureScreen -.-> Evidence
end

subgraph subGraph1 ["Browser Verification"]
    HeadlessCheck
    InitBrowser
    VerifyExec
    HeadlessCheck -.-> InitBrowser
    InitBrowser -.-> VerifyExec
end

subgraph subGraph0 ["XSS Detection Flow"]
    PayloadTest
    Verifier
    Confidence
    PayloadTest -.-> Verifier
    Verifier -.-> Confidence
end

Sources: wshawk/scanner_v2.py L215-L293

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 L263-L272

---

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 L634-L640

wshawk/scanner_v2.py L652-L658

---

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 L48-L62

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 L186-L239

---

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 L28-L76

wshawk/scanner_v2.py L545-L680

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 L662-L673

---

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 L643-L649

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 L189-L201

---

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 L515-L540

Integrated into main report at: wshawk/scanner_v2.py L593-L616

Sources: wshawk/session_hijacking_tester.py L515-L540

wshawk/scanner_v2.py L593-L616

---

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 L143-L183

---

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 L676-L678

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 L545-L680

wshawk/enhanced_reporter.py

wshawk/logger.py L1-L71

README.md L119-L129