Package: wsrepl
wsrepl- Websocket REPL for pentesterswsreplis an interactive websocket REPL designed specifically for penetration testing. It provides an interface for observing incoming websocket messages and sending new ones, with an easy-to-use framework for automating this communication.FeaturesInteractively send and receive websocket messagesCustomize headers, ping/pong messages, and other parametersHandle SSL verification and reconnectionsPlug-in support for automating complex interaction scenariosFull logging and message historySupports curl command line arguments for easy onboarding from Developer Tools or Burp Suite (use 'Copy as Curl' menu and replacecurlwithwsrepl)InstallationYou can download and install wsrepl using pip:pip install wsreplAlternatively, you can clone this repository and install it from source:git clone https://github.com/doyensec/wsrepl
cd wsrepl
pip install .UsageThe basic command for starting wsrepl is as follows:wsrepl -u URLReplace URL with your target websocket URL, e.g.wss://echo.websocket.org. For more options and settings, you can use the -h or --help option:usage: wsrepl [-h] [-u URL] [-i] [-s] [-k] [-X REQUEST] [-H HEADER]
              [-b COOKIE] [--compressed] [-S] [-A USER_AGENT] [-O ORIGIN]
              [-F HEADERS_FILE] [--no-native-ping]
              [--ping-interval PING_INTERVAL] [--hide-ping-pong]
              [--ping-0x1-interval PING_0X1_INTERVAL]
              [--ping-0x1-payload PING_0X1_PAYLOAD]
              [--pong-0x1-payload PONG_0X1_PAYLOAD] [--hide-0x1-ping-pong]
              [-t TTL] [-p HTTP_PROXY] [-r RECONNECT_INTERVAL]
              [-I INITIAL_MESSAGES] [-P PLUGIN] [-v VERBOSE]
              [url_positional]

Websocket Client

positional arguments:
  url_positional        Websocket URL (e.g. wss://echo.websocket.org)

options:
  -h, --help            show this help message and exit
  -u URL, --url URL     Websocket URL (e.g. wss://echo.websocket.org)
  -i, --include         No effect, just for curl compatibility
  -s, --silent          No effect, just for curl compatibility
  -k, --insecure        Disable SSL verification
  -X REQUEST, --request REQUEST
                        No effect, just for curl compatibility
  -H HEADER, --header HEADER
                        Additional header (e.g. "X-Header: value"), can be
                        used multiple times
  -b COOKIE, --cookie COOKIE
                        Cookie header (e.g. "name=value"), can be used
                        multiple times
  --compressed          No effect, just for curl compatibility
  -S, --small           Smaller UI
  -A USER_AGENT, --user-agent USER_AGENT
                        User-Agent header
  -O ORIGIN, --origin ORIGIN
                        Origin header
  -F HEADERS_FILE, --headers-file HEADERS_FILE
                        Additional headers file (e.g. "headers.txt")
  --no-native-ping      Disable native ping/pong messages
  --ping-interval PING_INTERVAL
                        Ping interval (seconds)
  --hide-ping-pong      Hide ping/pong messages
  --ping-0x1-interval PING_0X1_INTERVAL
                        Fake ping (0x1 opcode) interval (seconds)
  --ping-0x1-payload PING_0X1_PAYLOAD
                        Fake ping (0x1 opcode) payload
  --pong-0x1-payload PONG_0X1_PAYLOAD
                        Fake pong (0x1 opcode) payload
  --hide-0x1-ping-pong  Hide fake ping/pong messages
  -t TTL, --ttl TTL     Heartbeet interval (seconds)
  -p HTTP_PROXY, --http-proxy HTTP_PROXY
                        HTTP Proxy Address (e.g. 127.0.0.1:8080)
  -r RECONNECT_INTERVAL, --reconnect-interval RECONNECT_INTERVAL
                        Reconnect interval (seconds, default: 2)
  -I INITIAL_MESSAGES, --initial-messages INITIAL_MESSAGES
                        Send the messages from this file on connect
  -P PLUGIN, --plugin PLUGIN
                        Plugin file to load
  -v VERBOSE, --verbose VERBOSE
                        Verbosity level, 1-4 default: 3 (errors, warnings,
                        info), 4 adds debugAutomating with PluginsTo automate your websocket communication, you can create a Python plugin by extending thePluginclass in wsrepl. This class allows you to define various hooks that are triggered during different stages of the websocket communication.Here is an outline of how to define a plugin:classMyPlugin(Plugin):# Messages that will be sent to the server on (re-)connect.messages=["message1","message2","message3"]definit(self):# This method is called when the plugin is loaded.# Use it to set initial settings or generate self.messages dynamically.passasyncdefon_connect(self):# This method is called when the websocket connection is established.passasyncdefon_message_received(self,message:WSMessage):# This method is called when a message is received from the server.pass# ... Other hooks can be defined here.Refer to the source ofPlugin classfor the full list of hooks you can use and what they do:Example PluginHere is an example of a plugin that sends a predefined authentication message to a server:fromwsreplimportPluginimportjsonclassAuthPlugin(Plugin):definit(self):auth_message={"messageType":"auth","auth":{"user":"user-1234"","password":"password-1234"}}self.messages=[json.dumps(auth_message)]This plugin can be used by specifying it when running wsrepl:wsrepl -u URL -P auth_plugin.pyReplace URL with your target websocket URL and auth_plugin.py with the path to the Python file containing your plugin.docs/directory contains a few more example plugins.ContributingContributions to wsrepl are welcome! Please,create an issueor submit a pull request if you have any ideas or suggestions. In particular, adding more plugin examples would be very helpful.CreditsThis project has been sponsored byDoyensec LLC.