Defensive Validation

Defensive Validation

Relevant source files

Purpose and Scope

This document provides an overview of WSHawk's Defensive Validation module, a security control validation framework designed for blue teams. This page covers the module's purpose, architecture, test categories, and usage patterns. For detailed information about specific tests, see:

For offensive vulnerability testing capabilities, see Offensive Testing.

Overview

The Defensive Validation module inverts WSHawk's typical offensive testing model to serve blue team needs. While the core scanner (documented in Scanner Engine) focuses on discovering vulnerabilities, the defensive validation module tests whether security controls are properly configured to prevent those vulnerabilities from being exploited.

Design Philosophy

The module validates four critical security control categories:

| Control Category | Purpose | Risk if Misconfigured | | --- | --- | --- | | DNS Exfiltration Prevention | Blocks DNS-based data exfiltration | APT-style data theft | | Bot Detection | Detects automated browsers | Credential stuffing, scraping | | CSWSH Prevention | Validates Origin header enforcement | Session hijacking | | WSS Security | Enforces secure WebSocket protocols | MITM attacks |

Each test produces findings with CVSS v3.1 scores ranging from 5.3 (MEDIUM) to 9.8 (CRITICAL), enabling prioritized remediation.

Sources: docs/DEFENSIVE_VALIDATION.md L1-L15

README.md L143-L183

CHANGELOG.md L14-L27

Architecture and System Integration

Position in WSHawk Ecosystem

Diagram: Defensive Validation Module Position in WSHawk

The wshawk-defensive CLI command bypasses the offensive scanner engine entirely, invoking run_defensive_validation() directly. This architectural separation ensures defensive tests remain independent from offensive testing logic, while sharing common infrastructure (payload management, CVSS scoring, reporting).

Sources: docs/DEFENSIVE_VALIDATION.md L120-L157

README.md L143-L148

Module Structure

Diagram: Defensive Validation Module Internal Structure

Each test class maintains its own findings list and implements a run_all_tests() method that returns results. The run_defensive_validation() function orchestrates execution and aggregates findings.

Sources: docs/DEFENSIVE_VALIDATION.md L159-L189

Test Categories

1. DNS Exfiltration Prevention Test

Class: DNSExfiltrationTest

Purpose: Validates that the target network blocks DNS-based data exfiltration attempts through XXE and SSRF vectors.

Attack Scenario: Attackers encode stolen data in DNS queries (e.g., stolen-data.attacker.com), bypassing traditional firewalls. This technique is common in APT attacks and malware C2 communications.

Test Vectors:

  • XXE payload with external entity resolving to DNS callback
  • SSRF payload triggering DNS resolution

CVSS Score: 7.5-8.2 (HIGH) if vulnerable

Detailed information: See DNS Exfiltration Prevention Test

Sources: docs/DEFENSIVE_VALIDATION.md L17-L37

CHANGELOG.md L15-L16

2. Bot Detection Validation Test

Class: BotDetectionValidator

Purpose: Tests whether anti-bot measures can detect and block headless browsers used in automated attacks.

Attack Scenario: Automated attacks (credential stuffing, scraping, account takeover) rely on headless browsers. Effective bot detection should identify these tools through fingerprinting techniques.

Test Levels:

  1. Basic Detection: Tests if navigator.webdriver and other basic signals are checked
  2. Evasion Resistance: Tests if advanced evasion techniques (e.g., Playwright stealth mode) bypass detection

CVSS Scores:

  • 5.3 (MEDIUM) for basic detection failure
  • 7.8 (HIGH) for evasion resistance failure

Detailed information: See Bot Detection Validation Test

Sources: docs/DEFENSIVE_VALIDATION.md L40-L61

CHANGELOG.md L16

3. CSWSH Test (Cross-Site WebSocket Hijacking)

Class: CSWSHValidator

Purpose: Validates that WebSocket connections properly enforce Origin header validation to prevent cross-site attacks.

Attack Scenario: An attacker hosts a malicious page that establishes a WebSocket connection to the victim application, leveraging the victim's authenticated session to perform unauthorized actions.

Test Methodology:

  • Attempts connections with 216+ malicious origins loaded from payloads/malicious_origins.txt
  • Tests include: https://evil-attacker.com, http://localhost:666, null, empty strings, and various obfuscation techniques

CVSS Scores:

  • 9.1 (CRITICAL) for Origin validation failure
  • 7.5 (HIGH) for missing CSRF tokens

Detailed information: See CSWSH Test

Sources: docs/DEFENSIVE_VALIDATION.md L64-L85

CHANGELOG.md L17-L25

docs/DEFENSIVE_VALIDATION.md L270-L273

4. WSS Protocol Security Validation

Class: WSSSecurityValidator

Purpose: Validates TLS/SSL configuration for secure WebSocket (wss://) connections to prevent protocol downgrade attacks and MITM.

Attack Scenarios:

  • Protocol downgrade attacks (POODLE, BEAST)
  • Weak cipher exploitation
  • Man-in-the-Middle via certificate forgery

Validation Checks:

  1. TLS Version: Detects deprecated SSLv2, SSLv3, TLS 1.0, TLS 1.1
  2. Cipher Suites: Identifies weak ciphers (RC4, DES, 3DES, MD5, NULL, EXPORT)
  3. Certificate Validation: Checks expiration, self-signed status, chain integrity
  4. Forward Secrecy: Verifies ECDHE or DHE key exchange
  5. TLS Renegotiation: Tests for insecure renegotiation
  6. Signature Algorithms: Detects weak algorithms (MD5, SHA1)

CVSS Scores:

  • 9.8 (CRITICAL) for deprecated TLS versions
  • 7.5 (HIGH) for weak ciphers or certificate issues
  • 5.3 (MEDIUM) for missing forward secrecy

Detailed information: See WSS Protocol Security Validation

Sources: docs/DEFENSIVE_VALIDATION.md L88-L116

CHANGELOG.md L18-L23

Usage Patterns

Command Line Interface

The wshawk-defensive command provides the primary CLI interface:

The command exits with non-zero status if CRITICAL or HIGH findings are detected, enabling CI/CD integration with failure thresholds.

Sources: docs/DEFENSIVE_VALIDATION.md L139-L147

README.md L147-L149

Python API

Running All Tests

The run_defensive_validation() function returns a list of findings dictionaries and prints a summary report to stdout.

Sources: docs/DEFENSIVE_VALIDATION.md L149-L157

Running Individual Tests

Each test class exposes a findings attribute containing the results list.

Sources: docs/DEFENSIVE_VALIDATION.md L160-L190

Findings Structure and Reporting

Finding Dictionary Schema

Each test produces findings with the following structure:

Sources: docs/DEFENSIVE_VALIDATION.md L238-L252

CVSS Severity Mapping

| Severity | CVSS Range | Interpretation | Action Required | | --- | --- | --- | --- | | CRITICAL | 9.0-10.0 | Immediate exploitation risk | Fix immediately | | HIGH | 7.0-8.9 | Significant security gap | Urgent remediation | | MEDIUM | 4.0-6.9 | Moderate risk | Address soon | | LOW | 0.1-3.9 | Minor concern | Schedule fix | | INFO | 0.0 | Informational only | No action required |

The CVSS scoring follows v3.1 methodology as documented in CVSS Scoring System.

Sources: docs/DEFENSIVE_VALIDATION.md L256-L265

Console Output Example

======================================================================
WSHawk Defensive Validation Suite
======================================================================

WARNING: AUTHORIZED TESTING ONLY
These tests validate defensive security controls.
Only use with explicit written authorization.

======================================================================

[*] Testing DNS Exfiltration Prevention...
[*] Validating Bot Detection Effectiveness...
[*] Testing CSWSH Prevention...
[*] Testing WSS Protocol Security...

======================================================================
DEFENSIVE VALIDATION SUMMARY
======================================================================

Findings:
  CRITICAL: 1
  HIGH: 2
  MEDIUM: 1

[CRITICAL] CSWSH - Origin Header Validation
  Description: Server accepts WebSocket connections from untrusted origins
  CVSS: 9.1
  Recommendation: Implement Origin header validation immediately

Sources: docs/DEFENSIVE_VALIDATION.md L194-L234

CI/CD Integration Example

The command returns non-zero exit codes on CRITICAL/HIGH findings, causing the workflow to fail and alert security teams.

Sources: docs/DEFENSIVE_VALIDATION.md L376-L411

Payload Management

The CSWSH test uses an external payload file containing 216+ malicious origins:

File: payloads/malicious_origins.txt

Format: One origin per line

https://evil-attacker.com
http://localhost:666
null
data:text/html,<script>alert(1)</script>

The CSWSHValidator.load_malicious_origins() method reads this file at runtime, enabling easy payload updates without code changes.

Sources: docs/DEFENSIVE_VALIDATION.md L268-L274

CHANGELOG.md L25-L30

Relationship to Offensive Testing

Diagram: Offensive vs Defensive Testing Paradigms

Offensive testing (documented in Offensive Testing) discovers vulnerabilities by exploiting weaknesses. Defensive validation tests whether security controls are properly configured to prevent those same vulnerabilities. Both modes leverage shared infrastructure but serve opposite roles in the security lifecycle.

Sources: README.md L143-L183

CHANGELOG.md L29-L31

Extension Points

To add new defensive tests:

  1. Create a class inheriting from DefensiveValidationModule base class
  2. Implement run_all_tests() method
  3. Populate self.findings list with finding dictionaries
  4. Register the test in run_defensive_validation() function
  5. Add payload files to payloads/ directory if needed
  6. Update documentation

See Adding Extensions for detailed contribution guidelines.

Sources: docs/DEFENSIVE_VALIDATION.md L433-L443