wsrepl is a powerful and interactive WebSocket REPL (Read-Eval-Print Loop) tailored for penetration testers, enabling them to seamlessly send and receive WebSocket messages during assessments. Its intuitive interface allows users to observe incoming messages and automate communication, making WebSocket testing more efficient and effective.

Key Features

• Interactive Messaging: Easily send and receive WebSocket messages in real-time.
• Customizable Options: Set headers, ping/pong messages, and other parameters to tailor your interactions.
• SSL Support: Manage SSL verification and handle reconnections effortlessly.
• Plugin Architecture: Extend functionality with plugins for automating complex interaction sequences.
• Comprehensive Logging: Keep track of all interactions and message history for thorough analysis.
• Familiar Command-Line Interface: Supports curl command line arguments for quick adaptation from Developer Tools or Burp Suite, enabling penetration testers to hit the ground running.

Getting Started with wsrepl

To initiate the WebSocket client, run the command:

wsrepl -u URL

Substitute URL with your target WebSocket address (e.g., wss://echo.websocket.org). For additional options, users can access help using:

wsrepl -h

Extending Functionality with Plugins

Enhance your WebSocket interactions by creating Python plugins. By extending the Plugin class, you can define custom hooks that execute during various stages of the WebSocket lifecycle.

Example of implementing a simple plugin:

class MyPlugin(Plugin):
    messages = ["message1", "message2"]

    def init(self):
        # Initial settings here
        pass

    async def on_connect(self):
        # Actions upon connection
        pass

    async def on_message_received(self, message: WSMessage):
        # Process received messages
        pass

Example Authentication Plugin

Here’s an example plugin that sends an authentication message when connecting:

from wsrepl import Plugin
import json

class AuthPlugin(Plugin):
    def init(self):
        auth_message = {
            "messageType": "auth",
            "auth": {
                "user": "user-1234",
                "password": "password-1234"
            }
        }
        self.messages = [json.dumps(auth_message)]

Integrate this plugin by specifying it during the execution of wsrepl:

wsrepl -u URL -P auth_plugin.py

Refer to the documentation for additional plugin examples and integration guidance.

Join Our Community

We encourage contributions to wsrepl. If you have ideas, insights, or improvements, please create an issue or submit a pull request. Contributions, particularly those adding more plugin examples, are greatly appreciated.

Acknowledgments

This project is supported by Doyensec LLC, committed to enhancing the security landscape.