Configuration and Integration

Configuration and Integration

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

This document covers WSHawk's hierarchical configuration system and its integration capabilities with external platforms. Configuration in WSHawk v3.0.0 follows a precedence hierarchy that allows flexible deployment across different environments, while integrations enable automated workflow incorporation with tools like Jira, DefectDojo, and communication platforms.

For detailed CLI configuration options, see Advanced CLI Options. For programmatic configuration via the Python API, see Python API. For web dashboard authentication and API access, see Authentication and API Keys.

Configuration System Architecture

WSHawk's configuration system supports three sources with defined precedence:

  1. CLI Arguments (highest priority)
  2. Environment Variables
  3. Configuration File (wshawk.yaml) (lowest priority)

The system resolves secrets dynamically from environment variables or file paths using prefix notation.

Configuration Precedence Flow

graph TB
    CLI["CLI Arguments<br/>--rate, --playwright, etc"]
    ENV["Environment Variables<br/>WSHAWK_*, JIRA_*, DD_*"]
    YAML["wshawk.yaml<br/>Configuration File"]
    
    Config["WSHawkConfig<br/>Configuration Manager"]
    
    SecretResolver["Secret Resolver<br/>env: prefix<br/>file: prefix"]
    
    Scanner["WSHawkV2<br/>Scanner Instance"]
    WebGUI["Web Dashboard<br/>Flask Application"]
    Integrations["Integration Modules<br/>Jira, DefectDojo, Webhooks"]
    
    CLI --> Config
    ENV --> Config
    YAML --> Config
    
    Config --> SecretResolver
    
    SecretResolver --> Scanner
    SecretResolver --> WebGUI
    SecretResolver --> Integrations
    
    Config -.->|"1. CLI overrides all"| Scanner
    Config -.->|"2. ENV overrides YAML"| Scanner
    Config -.->|"3. YAML is default"| Scanner

Sources: README.md:137-150, README.md:29

Configuration File Structure

WSHawk uses wshawk.yaml for persistent configuration. Generate a template with:

python3 -m wshawk.config --generate

This creates wshawk.yaml.example which should be renamed to wshawk.yaml.

Configuration File Schema

graph LR
    subgraph "wshawk.yaml Structure"
        Root["wshawk.yaml"]
        
        Scanning["scanning:<br/>rate_limit<br/>max_connections<br/>timeout"]
        
        Verification["verification:<br/>use_playwright<br/>use_oast<br/>oast_provider"]
        
        Integrations["integrations:<br/>jira<br/>defectdojo<br/>webhooks"]
        
        JiraConfig["jira:<br/>url<br/>project<br/>api_token<br/>auto_create"]
        
        DDConfig["defectdojo:<br/>url<br/>api_key<br/>engagement_id"]
        
        WebhookConfig["webhooks:<br/>slack_url<br/>discord_url<br/>teams_url"]
        
        Reports["reports:<br/>output_dir<br/>formats<br/>include_traffic"]
        
        Web["web:<br/>host<br/>port<br/>password<br/>api_key"]
    end
    
    Root --> Scanning
    Root --> Verification
    Root --> Integrations
    Root --> Reports
    Root --> Web
    
    Integrations --> JiraConfig
    Integrations --> DDConfig
    Integrations --> WebhookConfig

Sources: README.md:137-150, docs/V3_COMPLETE_GUIDE.md:336-348

Secret Resolution Mechanism

WSHawk supports two secret resolution methods to avoid hardcoding credentials:

Environment Variable Resolution

Use the env: prefix to reference environment variables:

integrations:
  jira:
    api_token: "env:JIRA_API_TOKEN"
  defectdojo:
    api_key: "env:DD_API_KEY"
web:
  password: "env:WSHAWK_WEB_PASSWORD"

File-Based Secret Resolution

Use the file: prefix to read secrets from files (useful for Docker secrets or Kubernetes mounted volumes):

integrations:
  jira:
    api_token: "file:/run/secrets/jira_token"
  defectdojo:
    api_key: "file:/run/secrets/dd_api_key"

Secret Resolution Data Flow

graph LR
    YAML["wshawk.yaml<br/>api_token: env:JIRA_TOKEN"]
    
    Resolver["SecretResolver"]
    
    EnvCheck{"Prefix?"}
    EnvVar["os.environ.get<br/>JIRA_TOKEN"]
    FileRead["open<br/>/run/secrets/jira_token"]
    Literal["Return literal value"]
    
    ResolvedValue["Resolved Secret"]
    
    YAML --> Resolver
    Resolver --> EnvCheck
    
    EnvCheck -->|"env:"| EnvVar
    EnvCheck -->|"file:"| FileRead
    EnvCheck -->|"none"| Literal
    
    EnvVar --> ResolvedValue
    FileRead --> ResolvedValue
    Literal --> ResolvedValue

Sources: README.md:137-150

Integration Architecture

WSHawk's integration system operates independently from the core scanning engine via the "Integration Collaboration Plane." This decoupling ensures that integration failures do not impact scan execution.

Integration Data Flow

graph TB
    Scanner["WSHawkV2<br/>Scanner Engine"]
    
    VulnQueue["Vulnerability Queue<br/>In-Memory FIFO"]
    
    IntegrationManager["IntegrationManager<br/>Async Dispatcher"]
    
    ResilientSession["ResilientSession<br/>HTTP Wrapper<br/>Circuit Breakers"]
    
    JiraClient["JiraIntegration<br/>create_issue"]
    DDClient["DefectDojoIntegration<br/>push_findings"]
    WebhookClient["WebhookNotifier<br/>send_notification"]
    
    JiraAPI["Jira REST API<br/>/rest/api/2/issue"]
    DDAPI["DefectDojo API<br/>/api/v2/findings"]
    SlackAPI["Slack Webhook<br/>POST webhook_url"]
    
    Scanner -->|"HIGH/CRITICAL vuln"| VulnQueue
    VulnQueue --> IntegrationManager
    
    IntegrationManager --> ResilientSession
    
    ResilientSession --> JiraClient
    ResilientSession --> DDClient
    ResilientSession --> WebhookClient
    
    JiraClient --> JiraAPI
    DDClient --> DDAPI
    WebhookClient --> SlackAPI
    
    ResilientSession -.->|"Retry on failure<br/>Exponential backoff"| JiraClient
    ResilientSession -.->|"Circuit breaker<br/>if service down"| DDClient

Sources: RELEASE_SUMMARY.md:30-34, docs/V3_COMPLETE_GUIDE.md:129-131

Jira Integration

WSHawk automatically creates Jira tickets for HIGH and CRITICAL severity vulnerabilities.

Configuration

integrations:
  jira:
    enabled: true
    url: "https://your-domain.atlassian.net"
    username: "your-email@domain.com"
    api_token: "env:JIRA_API_TOKEN"
    project: "SEC"
    auto_create_issue: true
    severity_threshold: "HIGH"  # HIGH or CRITICAL

Ticket Content

Each Jira ticket includes:

  • Summary: Vulnerability type and target URL
  • Description: Detailed finding with CVSS v3.1 vector
  • Priority: Mapped from CVSS severity (CRITICAL → Highest, HIGH → High)
  • Labels: websocket, security, vulnerability type
  • Attachments: Proof-of-concept payload, response snippet

Sources: README.md:31, docs/V3_COMPLETE_GUIDE.md:336-341

DefectDojo Integration

DefectDojo integration enables centralized vulnerability management across multiple WSHawk scans.

Configuration

integrations:
  defectdojo:
    enabled: true
    url: "https://defectdojo.your-domain.com"
    api_key: "env:DD_API_KEY"
    product_name: "WebSocket Services"
    engagement_name: "Q4 2024 Security Audit"
    auto_create_engagement: true
    test_type: "WebSocket Security Scan"

Data Mapping

| WSHawk Field | DefectDojo Field | |--------------|------------------| | vulnerability.type | title | | vulnerability.cvss_score | severity | | vulnerability.confidence | severity (modifies score) | | vulnerability.payload | description | | vulnerability.evidence | mitigation | | scan.target | endpoints |

Sources: README.md:31, docs/V3_COMPLETE_GUIDE.md:342-344

Webhook Notifications

WSHawk supports real-time notifications to Slack, Discord, and Microsoft Teams.

Slack Configuration

integrations:
  webhooks:
    slack:
      enabled: true
      webhook_url: "env:SLACK_WEBHOOK_URL"
      channel: "#security-alerts"
      notify_on: ["CRITICAL", "HIGH"]
      include_cvss: true

Discord Configuration

integrations:
  webhooks:
    discord:
      enabled: true
      webhook_url: "env:DISCORD_WEBHOOK_URL"
      notify_on: ["CRITICAL", "HIGH", "MEDIUM"]

Microsoft Teams Configuration

integrations:
  webhooks:
    teams:
      enabled: true
      webhook_url: "env:TEAMS_WEBHOOK_URL"
      notify_on: ["CRITICAL", "HIGH"]

Notification Content

Webhook messages include:

  • Vulnerability type and severity
  • CVSS v3.1 score and vector
  • Target WebSocket URL
  • Timestamp and scan ID
  • Link to full HTML report (if web dashboard enabled)

Sources: README.md:31, RELEASE_SUMMARY.md:34, docs/V3_COMPLETE_GUIDE.md:345-349

Report Formats and Export

WSHawk generates reports in multiple formats for different consumption scenarios.

Report Generation Pipeline

graph LR
    Scanner["WSHawkV2<br/>scan_results"]
    
    ReportGenerator["ReportGenerator"]
    
    HTMLGen["HTMLReportGenerator<br/>generate_html_report"]
    JSONGen["JSONReportGenerator<br/>generate_json_report"]
    CSVGen["CSVReportGenerator<br/>generate_csv_report"]
    SARIFGen["SARIFReportGenerator<br/>generate_sarif_report"]
    
    HTMLFile["wshawk_report_*.html<br/>Human-readable"]
    JSONFile["wshawk_report_*.json<br/>Machine-readable"]
    CSVFile["wshawk_report_*.csv<br/>Spreadsheet"]
    SARIFFile["wshawk_report_*.sarif<br/>GitHub Security"]
    
    Scanner --> ReportGenerator
    
    ReportGenerator --> HTMLGen
    ReportGenerator --> JSONGen
    ReportGenerator --> CSVGen
    ReportGenerator --> SARIFGen
    
    HTMLGen --> HTMLFile
    JSONGen --> JSONFile
    CSVGen --> CSVFile
    SARIFGen --> SARIFFile

HTML Reports

Default format for human consumption. Includes:

  • Executive summary with CVSS distribution
  • Vulnerability details with syntax-highlighted payloads
  • Screenshots (if Playwright verification used)
  • Raw WebSocket traffic logs
  • Remediation recommendations

File naming: wshawk_report_YYYYMMDD_HHMMSS.html

JSON Reports

Structured data format for programmatic processing:

{
  "scan_metadata": {
    "target": "ws://example.com",
    "timestamp": "2024-01-01T12:00:00Z",
    "scanner_version": "3.0.0"
  },
  "vulnerabilities": [
    {
      "type": "SQL Injection",
      "severity": "HIGH",
      "cvss_score": 8.1,
      "cvss_vector": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:N",
      "confidence": "HIGH",
      "payload": "' OR '1'='1",
      "evidence": { "response": "...", "timing": 1234 }
    }
  ]
}

CSV Reports

Tabular format for spreadsheet analysis:

| Type | Severity | CVSS | Confidence | Payload | Evidence | |------|----------|------|------------|---------|----------| | SQL Injection | HIGH | 8.1 | HIGH | ' OR '1'='1 | {...} |

SARIF Reports

Standardized format for CI/CD integration and GitHub Security tab:

{
  "$schema": "https://raw.githubusercontent.com/oasis-tcs/sarif-spec/master/Schemata/sarif-schema-2.1.0.json",
  "version": "2.1.0",
  "runs": [
    {
      "tool": {
        "driver": {
          "name": "WSHawk",
          "version": "3.0.0"
        }
      },
      "results": [...]
    }
  ]
}

Configuration

reports:
  output_dir: "./reports"
  formats: ["html", "json", "csv", "sarif"]
  include_traffic_logs: true
  include_screenshots: true
  compress_large_reports: true

Sources: README.md:175-185, RELEASE_SUMMARY.md:52-56, docs/V3_COMPLETE_GUIDE.md:363-376

Environment Variables Reference

| Variable | Purpose | Example | |----------|---------|---------| | WSHAWK_WEB_PASSWORD | Web dashboard authentication | strong_password_123 | | WSHAWK_API_KEY | API key for REST API access | wshawk_abc123def456 | | JIRA_API_TOKEN | Jira authentication token | ATB...xyz | | JIRA_URL | Jira instance URL | https://domain.atlassian.net | | DD_API_KEY | DefectDojo API key | Token abc...xyz | | DD_URL | DefectDojo instance URL | https://dd.domain.com | | SLACK_WEBHOOK_URL | Slack incoming webhook URL | https://hooks.slack.com/... | | DISCORD_WEBHOOK_URL | Discord webhook URL | https://discord.com/api/webhooks/... | | TEAMS_WEBHOOK_URL | Microsoft Teams webhook URL | https://outlook.office.com/webhook/... | | OAST_PROVIDER_URL | Custom OAST provider | https://interact.sh |

Sources: README.md:122-127, docs/V3_COMPLETE_GUIDE.md:300-302

Configuration Best Practices

Security

  1. Never commit secrets to version control. Use environment variables or file references.
  2. Use dedicated service accounts for integrations (not personal credentials).
  3. Rotate API keys regularly (quarterly recommended).
  4. Restrict API key permissions to minimum required scope.

Performance

  1. Set appropriate rate limits based on target capacity:

    scanning:
  rate_limit: 10  # requests per second

  2. Disable unused integrations to reduce overhead:

    integrations:
  jira:
    enabled: false

  3. Limit Playwright usage to HIGH/CRITICAL findings:

    verification:
  playwright_severity_threshold: "HIGH"

CI/CD Integration

  1. Use SARIF format for automatic GitHub Security tab integration:

    reports:
  formats: ["sarif"]

  2. Configure fail thresholds to break builds on critical findings:

    scanning:
  fail_on_severity: "CRITICAL"

  3. Enable headless mode for automated scanning:

    wshawk --no-interactive --output-format sarif ws://target.com

Sources: README.md:29, RELEASE_SUMMARY.md:9-14, docs/V3_COMPLETE_GUIDE.md:352-377

Docker Configuration

When running WSHawk in Docker, configuration can be provided via:

  1. Environment variables (recommended):

    docker run --rm \
  -e WSHAWK_WEB_PASSWORD=secret \
  -e JIRA_API_TOKEN=token \
  rothackers/wshawk ws://target.com

  2. Volume-mounted config file:

    docker run --rm \
  -v $(pwd)/wshawk.yaml:/app/wshawk.yaml \
  rothackers/wshawk ws://target.com

  3. Docker secrets (Swarm/Kubernetes):

    services:
  wshawk:
    image: rothackers/wshawk
    secrets:
      - jira_token
secrets:
  jira_token:
    external: true

Sources: README.md:64-78

Troubleshooting

"Secret not resolved" Error

Cause: Environment variable or file not found.

Solution: Verify the variable exists:

echo $JIRA_API_TOKEN

Integration Timeout

Cause: External service unreachable or rate-limited.

Solution: Check ResilientSession circuit breaker state. Increase timeout:

integrations:
  timeout: 30  # seconds

SARIF Upload Failed

Cause: Invalid SARIF format or GitHub token missing.

Solution: Validate SARIF with:

npm install -g @microsoft/sarif-multitool
sarif validate wshawk_report.sarif

Sources: RELEASE_SUMMARY.md:9-14, docs/V3_COMPLETE_GUIDE.md:413-421