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

> Learn how to register new protocol modules in Patator. Discover the automatic module loading system and how to create your own modules seamlessly without explicit registration.

- Repository: [lanjelot/patator](https://github.com/lanjelot/patator)
- Tags: how-to-guide
- Published: 2026-03-05

---

**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`](https://github.com/lanjelot/patator/blob/main/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:

   ```python
   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:

   ```python
   self.module = module_cls()
   ```

5. **Merge metadata into the controller**

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

   ```python
   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`](https://github.com/lanjelot/patator/blob/main/src/patator/modules/echo.py):

```python
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:

```bash
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`](https://github.com/lanjelot/patator/blob/main/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`](https://github.com/lanjelot/patator/blob/main/src/patator/__main__.py)** (lines 1-30): Entry point that parses command-line arguments and initializes the `Controller` class, triggering the module