Skip to content

Scanning Engine v2 - Module - WebSocket

Overview

WebSocket (https://en.wikipedia.org/wiki/WebSocket) is a protocol providing full-duplex communication channels over a single TCP connection, commonly used for real-time web applications such as chat, live updates, and collaborative tools. It enables interactive communication between a client and server with lower overhead than traditional HTTP polling.

This module connects to a WebSocket service, performs the handshake, and attempts to exchange messages to verify protocol compliance and gather service metadata.

Targeting

This module targets TCP ports by IP address or hostname.

Configuration

Only the publicly-available configuration keys that can be set in a job's module invocations will be described below. Additional configuration keys may exist, but not be shown here because they are restricted to specific users or because they are permanently set as a static value. If no keys have (required) after their names then invocations of this module need not contain a config key.

Named Keys

addresses-only

Discard hostnames once they are resolved to addresses.

  • Type: boolean

blocklist-files (required)

File of addresses, hostnames, and CIDR blocks that are blocked.

  • Type: list(string)

connect-timeout

Timeout for each connection, in seconds.

  • Type: string
  • Default: 10s

data

Data to send.

  • Type: string

debug

Run module with a debugging configuration.

  • Type: boolean

handshake-timeout

Timeout for the handshake to complete, in seconds.

  • Type: string
  • Default: 3s

max-v4

Maximum number of resolved IPv4 addresses to use.

  • Type: integer

max-v6

Maximum number of resolved IPv6 addresses to use.

  • Type: integer

path

Connection path.

  • Type: string
  • Default: /

read-timeout

Timeout for the read to complete, in seconds.

  • Type: string
  • Default: 10s

request-timeout

Maximum timeout for each DNS request. (e.g., '10m', '1h', '1s', '1h10m')

  • Type: string

resolution-timeout

Maximum timeout for DNS resolution of each target. (e.g., '10m', '1h', '1s', '1h10m')

  • Type: string

resolver-address

Custom DNS resolver address to use.

  • Type: string

resolver-concurrency

Number of concurrent goroutines to use when resolving targets.

  • Type: integer

targeting-timeout

Maximum duration allowed for parsing and resolving all targets. (e.g., '10m', '1h', '1s', '1h10m')

  • Type: string

tls

Connect using SSL/TLS.

  • Type: boolean

Schemas

The schema for the body object of all results generated with .task.module_name equal to websocket can be found here. The schema for results is available both in standalone and bundled form.

Examples

These are examples of the .body object for results with .task.module_name equal to websocket.

WebSocket.org's Echo Service

This example was generated with WebSocket.org's Echo service.

{
  "banner": "Request served by d56832234ce08e",
  "url": "wss://echo.websocket.org/"
}

Live Host

This example was generated with a live host on the internet.

{
  "banner": "{\"Action\":\"authChallenge\",\"Challenge\":\"7251e44089523c9fdd1c6de9d2fe8a224e5311bcbc90a10688b8b3b54ddf966e\",\"Desc\":\"SUCCESS\",\"Error\":0,\"Result\":\"\",\"Version\":1}",
  "url": "ws://[REDACTED]:30002/"
}

Changelog

v2.0.0 (2025-08-01)

  • Complete rewrite from Python to Go for improved performance and maintainability.
  • Improved error handling and result processing with better logging and validation.

v1.0.0 (2025-07-08)

  • Initial release of versioning for each module. All modules are being tagged with version number 1.0.0. Going forward:
  • Major version should be changed when there are changes that impact consumers or clients of the modules.
  • Minor version should be changed when there are additions which enrich or enhance the module but shouldn't affect consumers or clients.
  • Patch version should be changed when there are bugfixes.