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

Patator's performance is governed by the Controller class in 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) 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:

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:

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:

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:

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:

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 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.

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