How to Set a Custom HTTP Timeout for Holehe: CLI Configuration Guide

Use the --timeout or -T flag followed by the duration in seconds (e.g., --timeout 30) to override the default 10-second HTTP request timeout when running holehe from the command line.

The megadose/holehe email reconnaissance framework provides configurable HTTP timeout settings to accommodate varying network conditions and target response times. Setting a custom HTTP timeout for Holehe prevents premature termination of OSINT modules when investigating slow or rate-limited services. This configuration is implemented through Python's argparse module in the core CLI and propagates through the request handling stack to the underlying HTTP client.

Configuring the --timeout Argument in holehe/core.py

The command-line interface definition in holehe/core.py exposes timeout control via the -T/--timeout argument. This parameter accepts an integer value representing the maximum seconds to wait for server responses before raising a timeout exception.

The argument is registered in theArgumentParser instance as follows:

# From holehe/core.py

parser.add_argument(
    "-T", "--timeout",
    type=int,
    default=10,
    required=False,
    dest="timeout",
    help="HTTP request timeout in seconds (default: 10)",
)

When parsing completes, the value is stored in args.timeout and passed throughout the application lifecycle.

Practical Command Line Examples

You can specify custom timeout values using either the long or short flag format. The default value of 10 seconds applies when the flag is omitted.

Set a 30-second timeout for slow networks or Tor connections:

holehe -u target@example.com --timeout 30

Use the short flag for aggressive scanning with reduced wait times:

holehe -u target@example.com -T 5

Run with the library default for standard broadband connections:

holehe -u target@example.com

Timeout Propagation Through the Codebase

The timeout value flows from CLI parsing to HTTP execution through two primary source files.

Argument Parsing in core.py

After parsing, args.timeout contains the integer value specified by the user (or the default 10). This value is forwarded to the asynchronous execution context and eventually reaches the network layer.

# Simplified flow in holehe/core.py

args = parser.parse_args()

# args.timeout now contains the configured value (int)

# This value is passed to the module execution context

HTTP Request Execution in instruments.py

The actual HTTP request implementation resides in holehe/instruments.py. The request helper function receives the timeout parameter and passes it directly to Python's requests library.

# From holehe/instruments.py

def request(url, timeout, **kwargs):
    return requests.get(url, timeout=timeout, **kwargs)

This ensures that every HTTP request made by holehe modules respects the user-defined timeout threshold.

Best Practices for Timeout Configuration

Adjust timeout values based on your specific operational environment:

• Increase to 30-60 seconds when operating over Tor, VPNs, or high-latency networks to prevent false negatives from slow routing.
• Decrease to 3-5 seconds for aggressive scanning on fast, stable connections where you prioritize speed over comprehensive coverage.
• Maintain default 10 seconds for standard broadband investigations where target services typically respond within standard HTTP timeframes.

Summary

• The --timeout argument in holehe/core.py accepts integer values representing seconds.
• The default HTTP timeout is 10 seconds when no flag is provided.
• Configuration values propagate from the CLI parser to holehe/instruments.py and the underlying requests library.
• Use -T as a shorthand alias for --timeout in command line operations.

Frequently Asked Questions

What is the default HTTP timeout in Holehe?

The default timeout is 10 seconds, hardcoded in the argparse configuration within holehe/core.py. This value applies to all HTTP requests unless overridden via command line arguments.

How do I increase the timeout for slow connections?

Append --timeout 30 (or higher) to your holehe command. This is particularly useful when routing traffic through Tor or investigating geographically distant servers that exhibit high latency.

Where is the timeout parameter processed in the source code?

The value is initially parsed in holehe/core.py by the ArgumentParser, then passed to the request helper function in holehe/instruments.py, which forwards the parameter to requests.get() or requests.post() calls.

Can I set different timeouts for different websites?

No. The --timeout flag sets a global value that applies uniformly to all HTTP requests made during a single holehe execution. For varying timeout requirements per target, you must run separate holehe instances with different timeout configurations.

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