How to Register New Protocol Modules in Patator: A Complete Guide

Patator registers new protocol modules automatically by dynamically importing Python files from the patator/modules/ directory and instantiating the Module class they contain, requiring no explicit registration code.

Patator is a modular brute-forcing tool that treats each supported protocol as a pluggable Python module. Understanding how to register new protocol modules in Patator's module loading system is essential for extending its capabilities to custom protocols or authentication mechanisms. The registration process relies on Python's dynamic import capabilities to discover and load module classes at runtime.

Understanding Patator's Module Interface Contract

Before a new protocol can be registered, it must implement the standard module interface that Patator expects. This contract ensures the core engine can interact with any protocol uniformly.

Required Class Attributes

Every protocol module must define a Module class containing these class-level tuples:

• available_actions: Defines user-triggerable actions like login or ignore
• available_options: Defines configuration parameters like host, port, or user

Required Instance Methods

The Module class must implement specific methods that the Patator controller calls during execution:

• execute(self, **payload): Contains the core protocol logic and returns a Response_Base object
• available_keys(self): Returns a tuple telling Patator how to expand keywords for brute-forcing
• __init__(self): Initializes default values for module options

How Patator Registers New Protocol Modules at Runtime

The registration mechanism operates through a five-step dynamic import process defined in src/patator/patator.py (approximately lines 590-620). When you invoke Patator with a command like python -m patator ssh.host=127.0.0.1, the following occurs:

1. Parse the module name from arguments

   The controller extracts the protocol identifier from the first positional argument. In ssh.host=..., the module name is ssh.

2. Construct the import path

   Patator builds the fully qualified module path as patator.modules.{module_name}. All protocol modules must reside in the src/patator/modules/ directory.

3. Dynamic import using __import__

   The engine calls Python's built-in __import__ function (or importlib.import_module in newer implementations) to load the module file at runtime:

   module_cls = __import__(f'patator.modules.{module_name}', fromlist=[''])

4. Instantiate the module class

   Patator creates a single instance of the imported Module class and stores it in the controller:

   self.module = module_cls()

5. Merge metadata into the controller

   The registration completes by exposing the module's capabilities to the user interface:

   self.available_actions = self.builtin_actions + self.module.available_actions
   self.available_options = self.module.available_options

Because this import happens exactly once during controller initialization, no additional registration code, configuration files, or decorators are required to register new protocol modules.

Step-by-Step Guide: Creating a Custom Protocol Module

To register a new protocol module, you only need to create a Python file in the correct directory with the proper class structure. Here is a complete example implementing a dummy "echo" protocol.

Create the file src/patator/modules/echo.py:

class Module:
    # Define available actions for this protocol

    available_actions = (
        ('ignore', 'ignore a hit'),
    )

    # Define configuration options users can set

    available_options = (
        ('message', 'text to send'),
    )

    def __init__(self):
        self.message = ''

    # Tell Patator how to expand keywords for brute-forcing

    def available_keys(self):
        return (('message', self.message),)

    # Core execution logic

    def execute(self, **payload):
        from patator.patator import Response_Base
        
        # Simulate a protocol response

        return Response_Base(
            code=200,
            mesg=payload.get('message', ''),
            timing=0
        )

Use the new module immediately without restarting or recompiling:

python -m patator echo.message='Hello, world!' -x ignore:code=200

Patator automatically registers the echo module when it detects the echo.message argument, imports patator.modules.echo, instantiates the Module class, and exposes the ignore action and message option to the command-line interface.

Key Source Files and Implementation Details

Understanding the exact locations of the registration logic helps when debugging or extending Patator's module system:

• src/patator/patator.py (lines 590-620): Contains the dynamic import logic and controller initialization where __import__ loads protocol modules and their metadata is merged into the available actions and options.

• src/patator/modules/: Directory containing all protocol implementations. Each file named <protocol>.py must contain a Module class following the interface contract described above.

• src/patator/__main__.py (lines 1-30): Entry point that parses command-line arguments and initializes the Controller class, triggering the module

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}