Python API Usage

Python API Usage

Relevant source files

Purpose and Scope

This page documents the programmatic Python API for WSHawk, enabling integration into custom security testing workflows, automated pipelines, and third-party tools. For command-line usage, see CLI Command Reference. For CI/CD integration examples, see CI/CD Integration.

The Python API provides direct access to the WSHawkV2 class and its underlying intelligence modules, allowing fine-grained control over scanning behavior, custom message injection, and programmatic result processing.

Core API Architecture

The following diagram illustrates the primary classes and methods exposed by the Python API:

Sources: wshawk/scanner_v2.py L28-L76

README.md L195-L209

Basic Import and Initialization

Importing the Scanner

The WSHawkV2 class is the primary entry point for programmatic scanning. It orchestrates all intelligence modules, vulnerability tests, and reporting.

Sources: wshawk/scanner_v2.py L1-L27

README.md L199-L201

Simple Initialization

Sources: wshawk/scanner_v2.py L33-L76

Configuration Options

The WSHawkV2 class exposes several configuration attributes and initialization parameters:

Initialization Parameters

| Parameter | Type | Default | Description | | --- | --- | --- | --- | | url | str | Required | Target WebSocket URL (ws:// or wss://) | | headers | Optional[Dict] | None | Custom HTTP headers for WebSocket handshake | | auth_sequence | Optional[str] | None | Path to YAML file containing authentication message sequence | | max_rps | int | 10 | Maximum requests per second for rate limiting |

Sources: wshawk/scanner_v2.py L33-L35

Runtime Configuration Attributes

| Attribute | Type | Default | Description | | --- | --- | --- | --- | | use_headless_browser | bool | True | Enable Playwright browser for XSS verification | | use_oast | bool | True | Enable OAST provider for blind vulnerability detection (XXE, SSRF) | | vulnerabilities | List[Dict] | [] | List of detected vulnerabilities (populated after scan) | | messages_sent | int | 0 | Counter for sent messages | | messages_received | int | 0 | Counter for received messages |

Sources: wshawk/scanner_v2.py L38-L76

Configuration Example

Sources: wshawk/scanner_v2.py L53-L62

Running Scans

Full Intelligent Scan Workflow

The following diagram illustrates the execution flow of the run_intelligent_scan() method:

Sources: wshawk/scanner_v2.py L545-L680

Basic Scan Execution

Sources: README.md L199-L207

Scan with All Features Enabled

Sources: wshawk/scanner_v2.py L545-L680

wshawk/scanner_v2.py L64-L76

Processing Results

Vulnerability Data Structure

Each vulnerability in the scanner.vulnerabilities list is a dictionary with the following structure:

| Key | Type | Description | | --- | --- | --- | | type | str | Vulnerability type (e.g., "SQL Injection", "Cross-Site Scripting (XSS)") | | severity | str | CVSS severity level: CRITICAL, HIGH, MEDIUM, LOW | | confidence | str | Confidence level: CRITICAL, HIGH, MEDIUM, LOW | | description | str | Human-readable vulnerability description | | payload | str | Attack payload that triggered the vulnerability | | response_snippet | str | First 200 characters of server response | | recommendation | str | Remediation guidance | | browser_verified | bool | (XSS only) Whether payload executed in real browser | | cvss_score | float | (Session tests only) Numeric CVSS v3.1 score |

Sources: wshawk/scanner_v2.py L193-L202

wshawk/scanner_v2.py L273-L283

wshawk/scanner_v2.py L602-L612

Result Processing Examples

Sources: wshawk/scanner_v2.py L640-L650

Accessing Intelligence Data

Sources: wshawk/scanner_v2.py L126-L136

wshawk/scanner_v2.py L660-L661

wshawk/scanner_v2.py L676-L678

Advanced Usage Patterns

Custom Test Execution

Instead of running the full scan, individual test methods can be called directly:

Available Test Methods:

Sources: wshawk/scanner_v2.py L545-L590

Integration with Custom Reporting

Sources: wshawk/scanner_v2.py L633-L678

Batch Scanning Multiple Targets

Sources: wshawk/scanner_v2.py L28-L76

API Class Reference

The following diagram maps the key classes accessible through the Python API:

Sources: wshawk/scanner_v2.py L28-L76

wshawk/scanner_v2.py L14-L23

Integration Examples

CI/CD Pipeline Integration

Sources: wshawk/scanner_v2.py L545-L680

Custom Payload Injection

Sources: wshawk/scanner_v2.py L87-L141

wshawk/scanner_v2.py L166-L169

Webhook Notification Integration

Sources: wshawk/scanner_v2.py L633-L641

Async Context Manager Pattern

The scanner can be used as an async context manager for automatic resource cleanup:

Sources: wshawk/scanner_v2.py L618-L631

Error Handling

Sources: wshawk/scanner_v2.py L77-L85

wshawk/scanner_v2.py L618-L631

Performance Considerations

Rate Limiting Configuration

Sources: wshawk/scanner_v2.py L45-L49

wshawk/scanner_v2.py L676-L678

Disabling Expensive Features

Sources: wshawk/scanner_v2.py L53-L58

Learning Phase Duration

Sources: wshawk/scanner_v2.py L87-L141

API Summary Table

| Component | Import Path | Primary Methods | Purpose | | --- | --- | --- | --- | | WSHawkV2 | wshawk.scanner_v2 | run_intelligent_scan(), connect(), learning_phase() | Main scanner orchestrator | | MessageIntelligence | wshawk.message_intelligence | learn_from_messages(), inject_payload_into_message() | Message format detection and injection | | VulnerabilityVerifier | wshawk.vulnerability_verifier | verify_sql_injection(), verify_xss(), verify_command_injection() | Real vulnerability verification | | ServerFingerprinter | wshawk.server_fingerprint | add_response(), fingerprint(), get_recommended_payloads() | Server technology detection | | HeadlessBrowserXSSVerifier | wshawk.headless_xss_verifier | verify_xss_execution(), start(), stop() | Browser-based XSS verification | | OASTProvider | wshawk.oast_provider | generate_payload(), check_interactions() | Out-of-band testing | | SessionHijackingTester | wshawk.session_hijacking_tester | run_all_tests() | Session security testing |

Sources: wshawk/scanner_v2.py L14-L23

setup.py L16-L48