WSS Protocol Security Validation

WSS Protocol Security Validation

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

Purpose and Scope

This document describes the WSS (WebSocket Secure) Protocol Security Validation test, which is part of WSHawk's Defensive Validation Module. This test validates the TLS/SSL configuration of secure WebSocket endpoints to detect protocol-level vulnerabilities that could lead to man-in-the-middle (MITM) attacks, protocol downgrade attacks, and data interception.

Scope: This test focuses exclusively on the security of the transport layer (TLS/SSL) for wss:// connections. It does not test application-level vulnerabilities or authentication mechanisms.

For other defensive validation tests, see:

  • DNS Exfiltration Prevention: 5.2
  • Bot Detection Validation: 5.3
  • Cross-Site WebSocket Hijacking (CSWSH): 5.4
  • Defensive Mode Overview: 5.1

Sources: README.md:225-230, CHANGELOG.md:63-68

Security Rationale

WebSocket Secure (WSS) connections rely on TLS/SSL to provide confidentiality, integrity, and authentication. However, misconfigured TLS implementations can expose critical vulnerabilities:

| Vulnerability | Impact | Exploitation Vector | |--------------|--------|---------------------| | Deprecated TLS Versions | MITM, protocol downgrade | Attackers force SSLv3, TLS 1.0/1.1 to exploit POODLE, BEAST, etc. | | Weak Cipher Suites | Data decryption | RC4, DES, 3DES ciphers vulnerable to known attacks | | Certificate Issues | Impersonation, MITM | Expired, self-signed, or invalid chain allows spoofing | | No Forward Secrecy | Retroactive decryption | Compromised private key exposes all past traffic | | Insecure Renegotiation | MITM injection | Attacker injects commands during TLS renegotiation |

The WSS Protocol Security Validation test identifies these issues before attackers can exploit them, making it essential for:

  • Production deployment validation
  • Compliance requirements (PCI-DSS, HIPAA, SOC 2)
  • Blue team defensive posture assessment
  • Vulnerability management programs

Sources: README.md:225-230, CHANGELOG.md:63-68

Validation Tests Performed

1. TLS Version Validation

Test: Connects to the target WebSocket endpoint and examines the negotiated TLS protocol version.

Detects:

  • SSLv2 (completely insecure, deprecated since 1996)
  • SSLv3 (vulnerable to POODLE attack, deprecated since 2015)
  • TLS 1.0 (vulnerable to BEAST, deprecated since 2020)
  • TLS 1.1 (vulnerable to downgrade attacks, deprecated since 2020)

Expected: TLS 1.2 or TLS 1.3

CVSS Impact: Accepting deprecated protocols is typically rated HIGH severity (7.5+) due to MITM risk.

2. Weak Cipher Suite Detection

Test: Enumerates supported cipher suites and identifies cryptographically weak algorithms.

Detects:

  • RC4: Stream cipher vulnerable to multiple attacks (Bar Mitzvah, NOMORE)
  • DES/3DES: Block ciphers with insufficient key length, vulnerable to Sweet32
  • NULL ciphers: Provide no encryption (eNULL)
  • Export-grade ciphers: Intentionally weakened for historical export restrictions (EXPORT, EXP)
  • Anonymous Diffie-Hellman: No server authentication (ADH, AECDH)
  • MD5-based HMAC: Weak message authentication

Expected: Only AES-GCM, AES-CCM, or ChaCha20-Poly1305 with SHA-256+ HMAC.

CVSS Impact: Weak ciphers are rated MEDIUM to HIGH (5.0-7.5) depending on practical exploitability.

3. Certificate Validation

Test: Performs comprehensive X.509 certificate validation against the endpoint.

Validates:

  • Expiration: Certificate is currently valid (not expired, not not-yet-valid)
  • Self-Signed Detection: Certificate is not self-signed (missing CA signature)
  • Chain Integrity: Complete certificate chain validates to a trusted root CA
  • Hostname Verification: Certificate Common Name (CN) or Subject Alternative Name (SAN) matches the target hostname
  • Revocation Status: Certificate has not been revoked (via CRL/OCSP if available)

CVSS Impact: Certificate issues range from MEDIUM (self-signed in test environments) to CRITICAL (expired certificates in production, 9.0+).

4. Forward Secrecy Verification

Test: Checks if the negotiated cipher suite provides Perfect Forward Secrecy (PFS).

Validates:

  • ECDHE (Elliptic Curve Diffie-Hellman Ephemeral): Preferred for modern TLS
  • DHE (Diffie-Hellman Ephemeral): Legacy PFS support

Risk: Without forward secrecy, compromising the server's private key allows decryption of all previously captured traffic.

CVSS Impact: Lack of forward secrecy is rated MEDIUM (5.5-6.5) as it requires long-term key compromise.

5. TLS Renegotiation Security

Test: Validates that the server implements RFC 5746 (Secure Renegotiation Indication).

Detects:

  • Support for insecure legacy renegotiation
  • Missing Secure Renegotiation extension

Risk: Insecure renegotiation allows attackers to inject plaintext prefixes into the TLS stream, enabling request smuggling and session hijacking.

CVSS Impact: Rated HIGH (7.5+) if exploitable in the application context.

Sources: README.md:225-230, CHANGELOG.md:63-68

WSS Validation Architecture

Test Execution Flow

graph TB
    CLI["wshawk-defensive CLI"]
    DefensiveMode["Defensive Validation Module"]
    WSSValidator["WSS Protocol Security Validator"]
    
    subgraph "TLS Connection Establishment"
        TCPConnect["TCP Connection<br/>wss://target:443"]
        TLSHandshake["TLS Handshake<br/>ClientHello → ServerHello"]
        Extract["Extract TLS Parameters<br/>version, cipher, certificate"]
    end
    
    subgraph "Validation Tests"
        VersionCheck["TLS Version Check<br/>SSLv2/v3, TLS 1.0/1.1"]
        CipherCheck["Weak Cipher Detection<br/>RC4, DES, 3DES, NULL"]
        CertValidation["Certificate Validation<br/>expiry, chain, hostname"]
        FSCheck["Forward Secrecy Check<br/>ECDHE/DHE presence"]
        RenegCheck["Renegotiation Security<br/>RFC 5746 compliance"]
    end
    
    subgraph "Result Processing"
        CVSS["CVSS v3.1 Scoring<br/>Severity Assignment"]
        Report["Defensive Report<br/>Findings + Remediation"]
        Database[("scans.db<br/>SQLite Storage")]
    end
    
    CLI --> DefensiveMode
    DefensiveMode --> WSSValidator
    
    WSSValidator --> TCPConnect
    TCPConnect --> TLSHandshake
    TLSHandshake --> Extract
    
    Extract --> VersionCheck
    Extract --> CipherCheck
    Extract --> CertValidation
    Extract --> FSCheck
    Extract --> RenegCheck
    
    VersionCheck --> CVSS
    CipherCheck --> CVSS
    CertValidation --> CVSS
    FSCheck --> CVSS
    RenegCheck --> CVSS
    
    CVSS --> Report
    Report --> Database

Diagram: WSS Protocol Security Validation Execution Pipeline

This diagram shows how the WSS validation test integrates into the defensive validation workflow. The test establishes a TLS connection, extracts protocol parameters during the handshake, performs five independent validation checks, and generates a comprehensive report with CVSS scoring.

Sources: README.md:199-239, CHANGELOG.md:59-73

Running WSS Protocol Security Validation

Basic Usage

# Run all defensive validation tests (includes WSS validation)
wshawk-defensive wss://your-server.com

The wshawk-defensive command executes all four defensive validation tests:

  1. DNS Exfiltration Prevention
  2. Bot Detection Validation
  3. Cross-Site WebSocket Hijacking (CSWSH)
  4. WSS Protocol Security Validation (if wss:// scheme is used)

Note: The WSS test only runs when the target URL uses the wss:// scheme. For ws:// (unencrypted) connections, the test is skipped with a warning that the connection is inherently insecure.

Docker Deployment

# Using Docker Hub
docker run --rm rothackers/wshawk:latest wshawk-defensive wss://target.com

# Using GitHub Container Registry
docker run --rm ghcr.io/regaan/wshawk:latest wshawk-defensive wss://target.com

Python API

import asyncio
from wshawk.defensive import DefensiveValidator

async def validate_wss():
    validator = DefensiveValidator("wss://your-server.com")
    results = await validator.run_wss_security_test()
    
    for finding in results:
        print(f"[{finding['severity']}] {finding['title']}")
        print(f"  CVSS: {finding['cvss_score']}")
        print(f"  Remediation: {finding['remediation']}")

asyncio.run(validate_wss())

Sources: README.md:203-206, README.md:64-78

Test Results and Findings

Finding Categories

The WSS validation test generates findings in the following categories:

| Category | Severity Range | Example Finding | |----------|---------------|-----------------| | Protocol Version | HIGH - CRITICAL | "Server accepts deprecated TLS 1.0" | | Cipher Suites | MEDIUM - HIGH | "Weak cipher RC4-SHA detected" | | Certificate Issues | MEDIUM - CRITICAL | "Certificate expired 30 days ago" | | Forward Secrecy | MEDIUM | "No forward secrecy (DHE/ECDHE missing)" | | Renegotiation | HIGH | "Insecure TLS renegotiation enabled" |

Sample Report Output

=== WSS Protocol Security Validation ===
Target: wss://api.example.com/ws

[CRITICAL] Deprecated TLS Version Detected
  Protocol: TLS 1.0
  CVSS: 9.1 (AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:N)
  Risk: Vulnerable to BEAST, CRIME attacks
  Remediation: Disable TLS 1.0/1.1, enforce TLS 1.2+

[HIGH] Weak Cipher Suite Supported
  Cipher: TLS_RSA_WITH_RC4_128_SHA
  CVSS: 7.5 (AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:N/A:N)
  Risk: RC4 stream cipher vulnerable to multiple attacks
  Remediation: Disable RC4, prefer AES-GCM or ChaCha20-Poly1305

[MEDIUM] Missing Forward Secrecy
  Negotiated: TLS_RSA_WITH_AES_128_CBC_SHA256
  CVSS: 5.9 (AV:N/AC:H/PR:N/UI:N/S:U/C:H/I:N/A:N)
  Risk: Past traffic can be decrypted if private key compromised
  Remediation: Enable ECDHE or DHE cipher suites

[PASS] Certificate Valid
  Issuer: Let's Encrypt Authority X3
  Expiration: 2026-06-15 (89 days remaining)
  Chain: Valid (trusted root CA)

CVSS Scoring for TLS Issues

The test applies CVSS v3.1 scoring based on industry standards:

graph LR
    Issue["TLS/SSL Issue"]
    
    subgraph "CVSS Calculation"
        AV["Attack Vector<br/>Network (AV:N)"]
        AC["Attack Complexity<br/>Low/High (AC:L/H)"]
        PR["Privileges Required<br/>None (PR:N)"]
        UI["User Interaction<br/>None (UI:N)"]
        C["Confidentiality Impact<br/>High/None (C:H/N)"]
        I["Integrity Impact<br/>High/None (I:H/N)"]
    end
    
    Score["CVSS Base Score"]
    Severity["Severity Rating"]
    
    Issue --> AV
    Issue --> AC
    Issue --> PR
    Issue --> UI
    Issue --> C
    Issue --> I
    
    AV --> Score
    AC --> Score
    PR --> Score
    UI --> Score
    C --> Score
    I --> Score
    
    Score --> Severity
    
    Score -->|"0.0-3.9"| Low["LOW"]
    Score -->|"4.0-6.9"| Medium["MEDIUM"]
    Score -->|"7.0-8.9"| High["HIGH"]
    Score -->|"9.0-10.0"| Critical["CRITICAL"]

Diagram: CVSS Scoring Logic for TLS Vulnerabilities

All findings include a CVSS vector string for integration with vulnerability management platforms.

Sources: README.md:46, README.md:225-230

Remediation Guidance

TLS Version Issues

Finding: Server accepts SSLv3, TLS 1.0, or TLS 1.1

Remediation:

# Nginx configuration
ssl_protocols TLSv1.2 TLSv1.3;
ssl_prefer_server_ciphers on;

# Apache configuration (mod_ssl)
SSLProtocol -all +TLSv1.2 +TLSv1.3

# Python ssl module (websockets library)
import ssl
ssl_context = ssl.SSLContext(ssl.PROTOCOL_TLS_SERVER)
ssl_context.minimum_version = ssl.TLSVersion.TLSv1_2

Weak Cipher Suites

Finding: RC4, DES, 3DES, or NULL ciphers detected

Remediation:

# Nginx - Modern cipher suite configuration
ssl_ciphers 'ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305';
ssl_prefer_server_ciphers off;

# Python websockets server with explicit cipher control
import ssl
ssl_context = ssl.SSLContext(ssl.PROTOCOL_TLS_SERVER)
ssl_context.set_ciphers('ECDHE+AESGCM:ECDHE+CHACHA20:DHE+AESGCM:!aNULL:!MD5:!DSS')

Recommended Cipher Suites (in priority order):

  1. TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 (forward secrecy + AEAD)
  2. TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 (forward secrecy + AEAD)
  3. TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256 (forward secrecy + AEAD)

Certificate Issues

Finding: Certificate expired, self-signed, or invalid chain

Remediation:

# Generate Let's Encrypt certificate with certbot
sudo certbot certonly --standalone -d your-server.com

# Update certificate paths in server configuration
ssl_certificate /etc/letsencrypt/live/your-server.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/your-server.com/privkey.pem;

# Setup automatic renewal
sudo certbot renew --dry-run

For internal services, use a private Certificate Authority:

  • Deploy certificates signed by your organizational CA
  • Ensure client applications trust your CA root certificate

Missing Forward Secrecy

Finding: Cipher suite lacks ECDHE or DHE key exchange

Remediation:

# Enforce forward secrecy by disabling RSA key exchange
ssl_ciphers 'EECDH+AESGCM:EDH+AESGCM';

Validation: After configuration changes, verify using:

# OpenSSL test for forward secrecy
openssl s_client -connect your-server.com:443 -cipher 'ECDHE'

Insecure Renegotiation

Finding: Server does not implement RFC 5746

Remediation:

# Nginx - Disable client-initiated renegotiation
ssl_prefer_server_ciphers on;

# Apache - Ensure mod_ssl 2.8.7+ with RFC 5746 support
# Typically enabled by default in modern versions
SSLInsecureRenegotiation off

Sources: README.md:225-239

Integration with Defensive Validation Suite

Multi-Test Execution Flow

graph TB
    Start["wshawk-defensive wss://target.com"]
    
    subgraph "Sequential Test Execution"
        DNS["1. DNS Exfiltration Test<br/>UDP egress validation"]
        Bot["2. Bot Detection Test<br/>Headless browser detection"]
        CSWSH["3. CSWSH Test<br/>Origin header validation"]
        WSS["4. WSS Protocol Test<br/>TLS/SSL security"]
    end
    
    subgraph "Result Aggregation"
        Combine["Aggregate Findings<br/>4 test results"]
        Priority["Priority Ranking<br/>CRITICAL → LOW"]
        CVSS["Calculate Overall Risk<br/>Weighted CVSS"]
    end
    
    subgraph "Reporting"
        HTMLReport["HTML Report<br/>wshawk_defensive_report_*.html"]
        JSONExport["JSON Export<br/>SIEM integration"]
        WebhookNotify["Webhook Notification<br/>Slack/Discord/Teams"]
    end
    
    Start --> DNS
    DNS --> Bot
    Bot --> CSWSH
    CSWSH --> WSS
    
    WSS --> Combine
    
    Combine --> Priority
    Priority --> CVSS
    
    CVSS --> HTMLReport
    CVSS --> JSONExport
    CVSS --> WebhookNotify

Diagram: Defensive Validation Multi-Test Execution Pipeline

The WSS Protocol Security Validation test runs as the fourth test in the defensive validation suite. Results are aggregated with findings from the other three tests to provide a comprehensive security posture assessment.

Sources: README.md:199-239

Technical Implementation Details

TLS Inspection Methodology

The WSS validation test uses Python's ssl module to inspect TLS parameters during the WebSocket connection handshake:

  1. Connection Establishment: Initiates a WebSocket connection using the wss:// scheme
  2. TLS Parameter Extraction: Captures SSLSocket.version(), SSLSocket.cipher(), and SSLSocket.getpeercert()
  3. Analysis: Compares extracted parameters against security baselines
  4. Finding Generation: Creates vulnerability records with CVSS scores

Code Entity Mapping

| Component | Purpose | Related Files | |-----------|---------|---------------| | DefensiveValidator | Orchestrates all defensive tests | Defensive validation module | | WSSSecurityTester | Implements TLS/SSL validation logic | Defensive validation module | | TLSInspector | Extracts TLS parameters from connections | Defensive validation module | | CVSSCalculator | Computes CVSS scores for TLS findings | Core scanning engine | | DefensiveReport | Generates remediation-focused reports | Reporting system |

Integration with Configuration System

The WSS validation test respects the hierarchical configuration system:

# wshawk.yaml - Defensive validation configuration
defensive:
  wss_security:
    min_tls_version: "TLSv1.2"
    allowed_ciphers:
      - "ECDHE-RSA-AES128-GCM-SHA256"
      - "ECDHE-RSA-AES256-GCM-SHA384"
    require_forward_secrecy: true
    strict_certificate_validation: true

Configuration can be overridden via environment variables:

export WSHAWK_DEFENSIVE_MIN_TLS_VERSION="TLSv1.3"
wshawk-defensive wss://target.com

Sources: README.md:137-150, README.md:225-230

Blue Team Use Cases

1. Pre-Production Security Validation

Scenario: Validate TLS configuration before deploying a new WebSocket service to production.

# Test staging environment
wshawk-defensive wss://staging-api.example.com/ws

# Verify all WSS findings are PASS
# If issues found, fix configuration and re-test

2. Continuous Compliance Monitoring

Scenario: Schedule regular TLS configuration audits for PCI-DSS or SOC 2 compliance.

# Kubernetes CronJob for weekly validation
apiVersion: batch/v1
kind: CronJob
metadata:
  name: wss-security-audit
spec:
  schedule: "0 2 * * 0"  # Every Sunday at 2 AM
  jobTemplate:
    spec:
      template:
        spec:
          containers:
          - name: wshawk
            image: rothackers/wshawk:latest
            command:
            - wshawk-defensive
            - wss://production-api.example.com/ws
            env:
            - name: WSHAWK_WEBHOOK_URL
              valueFrom:
                secretKeyRef:
                  name: wshawk-config
                  key: slack-webhook

3. Certificate Expiration Monitoring

Scenario: Detect certificates nearing expiration before they cause outages.

# Run WSS validation daily
# Alert on findings with "certificate expiration" in title
wshawk-defensive wss://api.example.com/ws --webhook https://hooks.slack.com/...

4. Post-Configuration Change Validation

Scenario: After updating TLS configuration (e.g., disabling TLS 1.1), verify the change was applied correctly.

# Before change
wshawk-defensive wss://api.example.com/ws > before.json

# Apply configuration change (Nginx, Apache, etc.)

# After change
wshawk-defensive wss://api.example.com/ws > after.json

# Compare results to confirm deprecated protocols are disabled
diff before.json after.json

Sources: README.md:232-238, README.md:199-206

Performance and Safety Considerations

Test Duration

The WSS Protocol Security Validation test is non-intrusive and fast:

  • Single Connection: Establishes one TLS connection to the target
  • No Payload Injection: Does not send application-level payloads
  • Read-Only: Only reads TLS parameters, does not modify server state
  • Typical Duration: 1-3 seconds per target

Production Safety

The test is safe for production environments:

  • No brute-force attempts or rate limiting concerns
  • No impact on application logic or business operations
  • No sensitive data transmission
  • Can be run during business hours without risk

Network Requirements

  • Outbound HTTPS (443): Required to connect to wss:// endpoints
  • No Special Permissions: Does not require elevated privileges
  • Firewall Friendly: Uses standard WebSocket handshake (HTTP Upgrade)

Sources: README.md:225-230

Comparison with External Tools

WSHawk's WSS validation differs from standalone TLS scanners:

| Feature | WSHawk WSS Validation | SSL Labs / testssl.sh | Nmap ssl-enum-ciphers | |---------|----------------------|----------------------|----------------------| | WebSocket-Specific | Yes (validates during WS handshake) | No (generic HTTPS) | No (generic TLS) | | Integrated Testing | Part of 4-test defensive suite | Standalone tool | Standalone script | | CVSS Scoring | Automatic for all findings | Manual interpretation | Manual interpretation | | Remediation Guidance | WebSocket server examples | Generic web server | None | | CI/CD Integration | Native (SARIF export) | Manual scripting required | Manual scripting required | | Report Persistence | SQLite-backed dashboard | None (web UI only) | None (terminal output) |

Key Advantage: WSHawk validates TLS security during an actual WebSocket connection, ensuring the TLS configuration applies to WebSocket traffic specifically (not just the initial HTTP/HTTPS endpoint).

Sources: README.md:23-37, README.md:225-230

Summary

The WSS Protocol Security Validation test provides blue teams with a comprehensive, automated solution for validating TLS/SSL security in WebSocket applications. By detecting deprecated protocols, weak ciphers, certificate issues, and missing security features, it enables organizations to prevent MITM attacks and maintain compliance with modern security standards.

Key Capabilities:

  • Detects 5 categories of TLS vulnerabilities
  • Provides CVSS-scored findings with remediation guidance
  • Integrates with existing defensive validation workflows
  • Safe for production environments
  • Supports CI/CD integration via SARIF export

Usage: Execute via wshawk-defensive wss://target.com to validate all defensive security controls, including WSS protocol security.

Sources: README.md:199-239, CHANGELOG.md:59-73