# How Patator's TCP_Cache Class Optimizes TCP Connections for Brute-Force Speed

> Discover how Patator's TCP_Cache class speeds up brute-force attacks by reusing active TCP connections and eliminating redundant handshakes. Learn more about optimized connections.

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

---

**The `TCP_Cache` class eliminates redundant TCP handshakes by storing active connections in a dictionary keyed by `host:port`, allowing Patator to reuse sockets across brute-force attempts unless explicitly reset via the `persistent` option.**

Patator is a multi-protocol brute-force framework that requires rapid, repeated network connections to test credentials. Opening a new TCP socket for every authentication attempt introduces significant latency and resource overhead, particularly for TLS-encrypted services. The `TCP_Cache` class, implemented in [`src/patator/patator.py`](https://github.com/lanjelot/patator/blob/main/src/patator/patator.py), solves this by managing an intelligent connection pool that persists sockets across multiple authentication trials.

## The Architecture of TCP_Cache

### Connection Storage and Keying

At the core of the optimization is a simple but effective caching mechanism. Inside [`src/patator/patator.py`](https://github.com/lanjelot/patator/blob/main/src/patator/patator.py) at lines 1735–1738, the `TCP_Cache.__init__` method initializes `self.cache` as an empty dictionary. This cache maps unique `host:port` strings to tuples containing a connection key and a `TCP_Connection` object. The key is constructed not only from the destination address but also from critical connection parameters such as TLS settings and timeout values, ensuring that a cached connection matches the exact requirements of the current brute-force attempt.

## The Connection Lifecycle: bind() and reset()

### Reusing Sockets with bind()

The primary method driving the optimization is `bind()`, located at lines 1744–1769. When a protocol module requests a connection, `bind()` constructs a host-port identifier (`hp`) and a unique `key` based on the provided arguments. It then queries `self.cache` for an existing entry:

- **Cache Hit:** If `hp` exists and the stored `key` matches the current parameters, the existing `TCP_Connection` is returned immediately. This bypasses the entire socket creation, TCP three-way handshake, and TLS negotiation process.
- **Key Mismatch:** If `hp` exists but the stored `key` differs, the stale connection is explicitly closed and removed from the cache (lines 1756–1759) to prevent file descriptor leaks before a new connection is established.
- **Cache Miss:** If no entry exists, `bind()` creates a new connection via the module-specific `connect` method, stores the `(key, connection)` pair in the cache, and returns the fresh socket.

### Explicit Cleanup with reset()

For scenarios requiring a clean slate—such as after a failed authentication or when the user forces fresh connections—the `reset()` method (lines 1770–1777) closes the currently cached socket for the active `host:port` and deletes the entry from `self.cache`. This forces the subsequent `bind()` call to establish a brand-new TCP connection.

## Controlling Persistence Across Attempts

Every protocol module inheriting from `TCP_Cache` exposes a `persistent` parameter that defaults to `'1'`. When set to `'0'`, the module invokes `self.reset()` after each authentication attempt, effectively disabling the cache for that specific thread. This behavior is clearly demonstrated in the `FTP_login` module at lines 1841–1843, where the code checks the parameter and resets the connection when persistence is disabled. This design gives operators granular control: enable persistence for maximum speed, or disable it when services enforce single-attempt limits or require pristine sessions.

## Performance Impact of Connection Caching

By reusing connections through `TCP_Cache`, Patator achieves measurable performance gains:

- **Eliminated TCP Handshake Latency:** Avoids the round-trip time of the three-way handshake for every credential attempt.
- **TLS Session Reuse:** For encrypted protocols, cached connections skip expensive TLS renegotiations, drastically reducing CPU overhead.
- **Conserved System Resources:** Minimizes the number of open file descriptors, preventing resource exhaustion during high-concurrency scans against large target lists.

## Summary

- The `TCP_Cache` class maintains a dictionary of active connections keyed by `host:port` and connection-specific parameters.
- The `bind()` method returns cached sockets when keys match, closing mismatched entries to prevent connection leaks.
- The `reset()` method purges specific cache entries, allowing fresh connections on demand for protocol compliance or user preference.
- The `persistent` option (default `'1'`) controls whether connections survive across attempts or are recycled per trial.
- This architecture significantly reduces TCP handshake and TLS overhead, accelerating brute-force attacks while conserving system resources.

## Frequently Asked Questions

### What is the default value of the persistent option in Patator?

The default value is `'1'` (enabled). This means TCP connections are cached and reused across multiple brute-force attempts unless the user explicitly sets `persistent='0'` to force a new connection for every trial.

### How does TCP_Cache prevent connection leaks?

When the `bind()` method detects a cached connection for a `host:port` that exists but has a mismatched key, it explicitly calls `close()` on the stale socket and removes the entry from `self.cache` before creating a new connection, ensuring no orphaned sockets remain open.

### Can I disable TCP connection caching for specific protocols?

Yes. By providing `persistent='0'` as an argument to any protocol module that inherits from `TCP_Cache`, you instruct the module to call `self.reset()` after each attempt, ensuring every credential trial uses a fresh TCP connection regardless of the target host.

### Where is the TCP_Cache class defined in the Patator source code?

The class is defined in [`src/patator/patator.py`](https://github.com/lanjelot/patator/blob/main/src/patator/patator.py) within the lanjelot/patator repository, with the core caching logic implemented between lines 1735 and 1777 according to the current master branch.