# Patator Performance Tuning: Optimizing Thread Count, Timeout, and Execution Parameters

> Optimize Patator performance by tuning thread count, timeout, rate limit, and max retries. Discover key execution parameters for faster, more reliable results.

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

---

**Patator's performance is governed by the `Controller` class in [`src/patator/patator.py`](https://github.com/lanjelot/patator/blob/main/src/patator/patator.py), where the command-line options `--threads`, `--timeout`, `--rate-limit`, and `--max-retries` configure parallelism, request duration limits, throttling delays, and failure recovery behavior.**

The lanjelot/patator repository provides a modular brute-force framework with configurable concurrency controls implemented in its central execution engine. These performance tuning parameters allow operators to balance scan speed against resource consumption and target stability. This article examines the key configuration flags and their implementation within the `Controller` class.

## Core Performance Parameters

Patator exposes five critical flags that directly impact execution speed and reliability. These options are parsed in `Controller.__init__` (approximately lines 248-257 in [`src/patator/patator.py`](https://github.com/lanjelot/patator/blob/main/src/patator/patator.py)) and stored as instance attributes.

### Thread Count (`-t`, `--threads`)

The `--threads` parameter controls the size of the worker pool, defaulting to **10** concurrent processes. Each thread runs a `Consumer` process that pulls payloads from the producer queue and executes the module's `execute()` method. Increasing this value raises parallelism but consumes additional CPU and memory resources.

### Request Timeout (`--timeout`)

By default set to **0** (disabled), this parameter specifies the maximum duration in seconds for any single request attempt. When enabled, Patator uses `enable_alarm(self.timeout)` within `Controller.consume()` (lines 1406-1412) to interrupt stalled connections. If the alarm fires, a `TimeoutError` is raised, triggering the retry mechanism.

### Rate Limiting (`--rate-limit`)

This flag inserts a deliberate delay (in seconds) between consecutive attempts, defaulting to **0** for maximum speed. The controller checks this value in the consumer loop and calls `sleep(self.rate_limit)` before each request (line 1496), providing a simple mechanism to avoid overwhelming targets or triggering intrusion detection systems.

### Maximum Retries (`--max-retries`)

Defaulting to **4**, this setting determines how many times Patator re-issues a payload after failures such as network errors, timeouts, or module-defined retry conditions. Setting this to **-1** enables unlimited retries, while **0** disables retry logic entirely. The retry counter is evaluated in `Controller.consume()` (lines 1499-1505 and 1512-1519).

### Auto-Progress Reporting (`--auto-progress`)

While not affecting raw performance, this option prints status summaries every *N* seconds without requiring user interaction. Disabled by default (0), it helps monitor long-running scans with high thread counts.

## Internal Implementation Mechanics

Understanding how these parameters function within the `Controller` class helps diagnose performance bottlenecks.

### Worker Process Creation

In `Controller.start_threads()` (lines 1444-1452), the controller spawns `multiprocessing.Process` instances based on `self.num_threads`. Each worker initializes a dedicated task queue with a maximum size of 10,000 entries:

```python
task_queues = [multiprocessing.Queue(maxsize=10000) for _ in range(self.num_threads)]
for num in range(self.num_threads):
    # Process initialization

```

These processes execute `Controller.consume()`, which contains the main request handling loop.

### Timeout Enforcement

The timeout mechanism wraps each module execution with alarm signals. In `Controller.consume()` (lines 1406-1412), the code enables the alarm before calling the module and disables it immediately after:

```python
enable_alarm(self.timeout)
resp = module.execute(**payload)
disable_alarm()

```

If execution exceeds the specified duration, the alarm triggers a `TimeoutError`, which is caught and logged before the retry logic evaluates whether to reattempt the payload.

### Retry Logic Flow

The consumer loop tracks attempt counts via `try_count`, comparing against `self.max_retries`. When retries are exhausted, the action set is forced to `{'fail': None}`, terminating further attempts on that payload (lines 1512-1519).

## Practical Configuration Examples

### High-Concurrency SSH Scanning with Timeouts

Run 30 parallel threads against a network range, aborting connections exceeding 5 seconds, with 200ms delays between attempts:

```bash
patator ssh_login host=NET0 user=FILE0 password=FILE1 \
        0=10.0.0.0/24 1=users.txt 2=passwords.txt \
        -t 30 --timeout 5 --rate-limit 0.2

```

This configuration prevents hung SSH daemons from stalling the scan while maintaining a polite request rate.

### Zero-Retry HTTP Fuzzing

For quick reconnaissance where connection failures should be skipped immediately:

```bash
patator http_fuzz url=FILE0 method=GET \
        0=paths.txt \
        --max-retries 0

```

Setting `--max-retries 0` ensures Patator moves to the next payload on the first failure, maximizing speed when accuracy is less critical than coverage.

### Large-Scale FTP Auditing with Progress Monitoring

Deploy 50 threads across a broad network with automatic status updates every 30 seconds:

```bash
patator ftp_login host=NET0 user=FILE0 password=FILE1 \
        0=10.0.0.0/24 1=users.txt 2=pass.txt \
        -t 50 --auto-progress 30

```

This setup suits long-duration scans where manual progress checks are impractical.

## Summary

- **Thread count** (`-t`) controls the `multiprocessing.Process` pool size in `Controller.start_threads()`, defaulting to 10 workers.
- **Timeout** (`--timeout`) uses alarm signals in `Controller.consume()` to abort slow requests, defaulting to disabled (0).
- **Rate limiting** (`--rate-limit`) adds deliberate delays via `sleep()` calls to throttle request velocity.
- **Max retries** (`--max-retries`) caps reattempts per payload within the consumer loop, defaulting to 4.
- All parameters are parsed in `Controller.__init__` in [`src/patator/patator.py`](https://github.com/lanjelot/patator/blob/main/src/patator/patator.py) and propagate to concurrent workers.

## Frequently Asked Questions

### How do I determine the optimal thread count for a Patator scan?

Start with the default of 10 threads and monitor CPU utilization and network bandwidth. For I/O-bound protocols like HTTP or SSH against remote targets, you can often increase this to 50-100 threads, but avoid exceeding your system's file descriptor limits or the target's connection capacity. Each thread spawns a separate process, so memory usage scales linearly with the thread count.

### What happens when a request exceeds the specified timeout?

When `--timeout` is set to a positive integer, `Controller.consume()` enables a signal alarm before executing the module. If the alarm fires before `module.execute()` returns, Patator catches the resulting `TimeoutError`, logs the failure, and subjects the payload to the retry logic according to `--max-retries`. The default timeout of 0 disables this protection entirely.

### Can I disable retry attempts completely to speed up scanning?

Yes, set `--max-retries 0` to prevent any reattempts after failures. By default, Patator retries failed payloads up to 4 times. Setting the value to -1 enables unlimited retries, which is useful for unreliable networks but can stall indefinitely on persistent failures.

### What is the difference between `--rate-limit` and `--timeout`?

`--rate-limit` controls the *interval* between requests, adding a sleep delay before each attempt to reduce load on the target. `--timeout` controls the *maximum duration* of an individual request, killing connections that hang or respond too slowly. Use rate limiting to avoid detection or service degradation, and use timeouts to prevent slow targets from blocking your worker pool.