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

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, 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 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 within the lanjelot/patator repository, with the core caching logic implemented between lines 1735 and 1777 according to the current master branch.

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