WSS Protocol Security Validation

WSS Protocol Security Validation

Relevant source files

Purpose and Scope

This page documents the WSS (WebSocket Secure) Protocol Security Validator, a defensive validation module that tests server-side TLS/SSL configuration for secure WebSocket connections. This module is designed for blue teams to validate cryptographic security controls and identify protocol-level vulnerabilities that could enable man-in-the-middle attacks, protocol downgrade attacks, or weak encryption.

Scope: This page covers the cryptographic and certificate validation testing performed by WSSSecurityValidator. For information about other defensive validation tests, see Defensive Validation. For general WebSocket security testing, see Offensive Testing. For CSWSH (cross-site) attacks specifically, see CSWSH Test.

Note: WSS security validation only executes for wss:// URLs. Standard ws:// connections are unencrypted and cannot be tested for TLS/SSL security.

Overview

The WSS Protocol Security Validator performs comprehensive TLS/SSL security analysis on WebSocket Secure connections. It validates that servers implement current cryptographic best practices by testing for:

  • Deprecated protocol versions (SSLv2, SSLv3, TLS 1.0, TLS 1.1)
  • Weak cipher suites (RC4, DES, 3DES, MD5-based, NULL, EXPORT, anonymous)
  • Certificate validity (expiration, self-signed certificates, signature algorithms)
  • Certificate chain integrity (missing intermediates, untrusted roots)
  • Forward secrecy (ECDHE, DHE support)
  • Renegotiation security (insecure renegotiation vulnerabilities)

The validator assigns CVSS v3.1 scores ranging from 5.3 (MEDIUM) to 9.8 (CRITICAL) based on the severity of discovered issues.

Sources: wshawk/wss_security_validator.py L1-L14

docs/DEFENSIVE_VALIDATION.md L88-L116

README.md L169-L174

Architecture and Integration

Module Structure

The WSS security validator is implemented as an independent module that integrates into the broader defensive validation framework through conditional execution.

Diagram: WSS Security Validator Integration Flow

Sources: wshawk/defensive_validation.py L522-L532

wshawk/wss_security_validator.py L391-L422

wshawk/wss_security_validator.py L425-L462

Class Architecture

Diagram: WSSSecurityValidator Class Structure

Sources: wshawk/wss_security_validator.py L23-L73

wshawk/wss_security_validator.py L75-L88

Security Tests Performed

Test Execution Workflow

The run_all_tests() method orchestrates five independent security tests in sequence:

Diagram: WSS Security Test Execution Sequence

Sources: wshawk/wss_security_validator.py L391-L422

1. TLS Protocol Version Support Testing

Objective: Detect if server accepts deprecated or vulnerable TLS/SSL protocol versions.

Implementation: The test_tls_version_support() method attempts to establish connections using each deprecated protocol version defined in self.deprecated_protocols:

| Protocol | Vulnerability | CVSS | | --- | --- | --- | | SSLv2 | DROWN attack, completely broken | 9.8 | | SSLv3 | POODLE attack | 9.8 | | TLS 1.0 | BEAST attack, deprecated | 9.8 | | TLS 1.1 | Deprecated by RFC 8996 | 9.8 |

Test Logic:

FOR EACH deprecated_protocol IN [SSLv2, SSLv3, TLS1.0, TLS1.1]:
    CREATE SSLContext(protocol)
    DISABLE hostname checking and certificate verification
    ATTEMPT connection to (host, port)
    IF connection succeeds:
        RECORD as vulnerable
        ADD CRITICAL finding (CVSS 9.8)
    ELSE:
        Protocol properly rejected (good)

Finding Structure:

  • Vulnerable: Server accepts one or more deprecated protocols
  • Severity: CRITICAL
  • CVSS: 9.8
  • Description: Lists specific vulnerable versions accepted
  • Recommendation: Disable all TLS versions below 1.2

Sources: wshawk/wss_security_validator.py L90-L147

wshawk/wss_security_validator.py L44-L50

2. Cipher Suite Security Testing

Objective: Identify weak or deprecated cipher suites and verify forward secrecy support.

Weak Cipher Patterns Detected:

| Pattern | Issue | Examples | | --- | --- | --- | | RC4 | Broken stream cipher | RC4-SHA, RC4-MD5 | | DES/3DES | Weak/deprecated encryption | DES-CBC3-SHA | | MD5 | Broken hash function | RC4-MD5, NULL-MD5 | | NULL | No encryption | NULL-SHA, NULL-MD5 | | EXPORT | Intentionally weakened (40-bit) | EXP-RC4-MD5 | | anon/ADH/AECDH | No authentication (MITM vulnerable) | ADH-AES256-SHA |

Test Logic:

ESTABLISH connection with default SSL context
GET negotiated cipher: (name, version, bits)
IF cipher_name contains ANY weak_cipher_pattern:
    ADD HIGH finding (CVSS 7.5)
ELIF cipher_name does NOT contain forward_secrecy_pattern (ECDHE/DHE):
    ADD MEDIUM finding (CVSS 5.3)
ELSE:
    PASS (strong cipher with forward secrecy)

Recommended Ciphers: ECDHE-RSA-AES256-GCM-SHA384, ECDHE-RSA-AES128-GCM-SHA256, ECDHE-RSA-CHACHA20-POLY1305

Sources: wshawk/wss_security_validator.py L149-L227

wshawk/wss_security_validator.py L54-L73

3. Certificate Signature Algorithm Validation

Objective: Verify certificate validity, expiration, and detect self-signed certificates.

Checks Performed:

Diagram: Certificate Validation Decision Tree

Validation Steps:

  1. Expiration Check: Parse notAfter field, compare to current date
  2. Self-Signed Detection: Compare subject and issuer fields
  3. Hash Extraction: Generate SHA-256 hash of DER certificate for tracking

Sources: wshawk/wss_security_validator.py L229-L308

4. Certificate Chain Integrity Testing

Objective: Verify that the server provides a complete, valid certificate chain from a trusted root CA.

Test Logic:

CREATE SSLContext with check_hostname=True (strict validation)
ATTEMPT connection with certificate verification enabled
IF SSLCertVerificationError:
    ADD HIGH finding (CVSS 7.5)
    Common issues:
    - Missing intermediate certificates
    - Untrusted root CA
    - Certificate name mismatch
ELSE:
    ADD INFO finding (valid chain)

Common Certificate Chain Issues:

  • Incomplete chain: Server only sends leaf certificate, missing intermediates
  • Wrong order: Certificates not presented in correct chain order
  • Untrusted root: Chain terminates at non-trusted CA
  • Hostname mismatch: Certificate CN/SAN doesn't match server hostname

Sources: wshawk/wss_security_validator.py L310-L355

5. TLS Renegotiation Security Testing

Objective: Verify that TLS renegotiation is secure and not vulnerable to injection attacks.

Background: Insecure TLS renegotiation (CVE-2009-3555) allows attackers to inject data into established TLS sessions by exploiting the renegotiation handshake.

Test Approach:

  • Modern Python ssl module enforces secure renegotiation by default via OP_NO_RENEGOTIATION flag
  • Test establishes connection and verifies no renegotiation-related errors occur
  • If connection succeeds, renegotiation is secure

Finding: INFO severity (secure by default in modern TLS implementations)

Sources: wshawk/wss_security_validator.py L357-L389

Finding Structure and CVSS Scoring

Finding Data Model

Each security test generates a finding dictionary with standardized fields:

Diagram: Finding Dictionary Structure and Storage

Sources: wshawk/wss_security_validator.py L75-L88

CVSS Scoring Matrix

| Issue | Severity | CVSS Score | Rationale | | --- | --- | --- | --- | | Deprecated TLS (SSLv2/3, TLS 1.0/1.1) | CRITICAL | 9.8 | Enables protocol downgrade attacks, POODLE, BEAST | | Weak cipher suites (RC4, DES, NULL) | HIGH | 7.5 | Cryptographically broken, enables decryption | | Missing forward secrecy | MEDIUM | 5.3 | Past traffic decryptable if private key compromised | | Expired certificate | HIGH | 7.5 | Prevents legitimate client validation | | Self-signed certificate | MEDIUM | 5.3 | Bypasses trust model, enables MITM | | Invalid certificate chain | HIGH | 7.5 | Prevents proper certificate validation | | Secure renegotiation | INFO | 0.0 | No vulnerability (informational) |

CVSS v3.1 Severity Ranges:

  • CRITICAL: 9.0-10.0
  • HIGH: 7.0-8.9
  • MEDIUM: 4.0-6.9
  • LOW: 0.1-3.9
  • INFO: 0.0

Sources: docs/DEFENSIVE_VALIDATION.md L112-L116

wshawk/wss_security_validator.py L75-L88

Configuration and Validation Rules

Deprecated Protocol Definitions

The validator maintains a dictionary mapping deprecated protocol names to Python ssl module constants:

Note: PROTOCOL_SSLv23 is used for SSLv2/v3 testing but with options configured to test specific versions.

Sources: wshawk/wss_security_validator.py L44-L50

Weak Cipher Pattern Matching

Cipher suites are validated using string pattern matching against known-weak components:

Sources: wshawk/wss_security_validator.py L54-L64

Recommended Cipher Patterns

Forward secrecy is verified by checking for these patterns in the negotiated cipher name:

Preferred cipher suites (in order):

  1. ECDHE-RSA-AES256-GCM-SHA384
  2. ECDHE-RSA-AES128-GCM-SHA256
  3. ECDHE-RSA-CHACHA20-POLY1305

Sources: wshawk/wss_security_validator.py L66-L73

wshawk/wss_security_validator.py L189-L191

Usage and Integration

Command-Line Usage

The WSS security validator is automatically invoked when running defensive validation against a wss:// URL:

Conditional Execution: For ws:// URLs, WSS tests are skipped with an informational message:

[*] Skipping WSS security tests (requires wss:// URL)

Sources: wshawk/defensive_validation.py L522-L532

README.md L147-L149

Python API Usage

Direct usage of the validator class:

Async wrapper for integration with async codebases:

Sources: wshawk/wss_security_validator.py L425-L462

wshawk/wss_security_validator.py L465-L474

Integration with Defensive Validation Suite

The validator integrates into the broader defensive validation workflow:

Sources: wshawk/defensive_validation.py L522-L532

Output Format and Reporting

Console Output Structure

The validator produces structured console output during test execution:

[*] Testing WSS Protocol Security...
[*] Checking TLS protocol versions...
[*] Analyzing cipher suites...
[*] Validating certificate signature...
[*] Verifying certificate chain...
[*] Testing TLS renegotiation...

======================================================================
WSS SECURITY VALIDATION SUMMARY
======================================================================

Findings:
  CRITICAL: 1
  HIGH: 2
  MEDIUM: 1

[CRITICAL] TLS Protocol Downgrade Vulnerability
  Description: Server supports deprecated TLS/SSL versions: TLSv1.0, TLSv1.1
  Recommendation: Disable SSLv2, SSLv3, TLS 1.0, and TLS 1.1...
  CVSS: 9.8

[HIGH] Weak Cipher Suite
  Description: Server negotiated weak cipher: RC4-SHA (128 bits)
  Recommendation: Disable weak ciphers...
  CVSS: 7.5

Sources: wshawk/wss_security_validator.py L440-L461

Finding Integration with Report Generator

Findings from WSS validation are merged with other defensive validation findings and included in the HTML report generated by the main scanner:

all_findings = []
# ... other defensive tests ...
wss_test = WSSSecurityValidator(target_url)
wss_test.run_all_tests()
all_findings.extend(wss_test.findings)  # Merge with other findings

Each finding in all_findings includes:

  • Test name
  • Vulnerable status (boolean)
  • Severity (CRITICAL/HIGH/MEDIUM/LOW/INFO)
  • Description
  • Recommendation
  • CVSS score
  • Timestamp
  • Optional details dictionary

Sources: wshawk/defensive_validation.py L495-L556

docs/DEFENSIVE_VALIDATION.md L238-L252

Remediation Guidance

TLS Version Configuration

Issue: Server accepts deprecated TLS versions (SSLv2/3, TLS 1.0/1.1)

Remediation Steps:

  1. Nginx Configuration:
  1. Apache Configuration:
  1. Node.js (ws library):
  1. Python (websockets library):

Cipher Suite Hardening

Issue: Weak cipher suites enabled

Recommended Cipher Configuration:

Nginx:

Apache:

OpenSSL (command-line testing):

Certificate Issues

Issue: Expired or self-signed certificates

Remediation:

  1. Obtain valid certificate from trusted CA: * Let's Encrypt (free, automated) * Commercial CAs (DigiCert, Sectigo, etc.)
  2. Ensure complete certificate chain:
  1. Automate renewal (Let's Encrypt example):

Sources: docs/DEFENSIVE_VALIDATION.md L278-L373

Testing and Verification

Manual Verification Tools

OpenSSL Command-Line Testing:

Nmap TLS Scanning:

SSLyze (comprehensive TLS analyzer):

Automated Testing in CI/CD

Sources: docs/DEFENSIVE_VALIDATION.md L377-L411

Limitations and Considerations

Technical Limitations

  1. Python SSL Module Constraints: * Limited access to low-level TLS handshake details * Cannot directly test all cipher suites (only those negotiated) * Renegotiation testing relies on default secure behavior
  2. Protocol-Specific: * Only tests wss:// URLs (HTTPS/TLS-based WebSockets) * Cannot test ws:// (unencrypted WebSocket) connections * Requires network connectivity to target server
  3. Snapshot Testing: * Tests current TLS configuration at time of execution * Does not detect configuration changes over time * Requires periodic re-scanning for continuous validation

Sources: docs/DEFENSIVE_VALIDATION.md L427-L431

Security Considerations

  1. Authorized Testing Only: This tool performs active connection attempts and should only be used with explicit authorization
  2. Network Visibility: TLS tests generate network traffic that may trigger IDS/IPS alerts
  3. Certificate Privacy: Test output may include certificate details (subject, issuer)

Best Practices

  1. Regular Scanning: Schedule weekly or monthly scans to detect configuration drift
  2. Staging First: Test against staging environments before production
  3. Combine with Other Tools: Use alongside SSLyze, testssl.sh for comprehensive validation
  4. Document Baselines: Maintain historical scan results to track security posture changes

Sources: docs/DEFENSIVE_VALIDATION.md L415-L423

Extension and Customization

Adding New Tests

To extend the validator with additional TLS security tests:

  1. Add test method to WSSSecurityValidator class:
  1. Integrate into run_all_tests():

Custom Cipher/Protocol Lists

Modify validation rules by updating class attributes:

Sources: wshawk/wss_security_validator.py L391-L422

docs/DEFENSIVE_VALIDATION.md L434-L443