How to Set a Custom HTTP Timeout for Requests in Holehe

TLDR: You can configure a custom HTTP timeout in Holehe by passing the --timeout argument (or -T) followed by the number of seconds; this value is parsed in holehe/core.py and applied to all outgoing requests via the timeout parameter in holehe/instruments.py, with a default of 10 seconds.

Holehe, the open-source email OSINT tool by megadose, checks email address registration status across hundreds of websites using asynchronous HTTP requests. When network latency varies or target services respond slowly, adjusting the custom HTTP timeout prevents premature failures and ensures complete scans. The timeout configuration is implemented through Python's argparse module in the core CLI handler and enforced uniformly across all verification modules.

Locating the Timeout Configuration in holehe/core.py

The command-line interface defines the timeout parameter using argparse in holehe/core.py. The tool registers a -T/--timeout option that accepts integer values, defaulting to 10 seconds when unspecified.

# 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)",
)

After parsing command-line input, the value is stored in the args.timeout attribute. This variable is subsequently passed to the asynchronous request handlers that orchestrate module execution.

How holehe/instruments.py Applies the Timeout

The actual HTTP request implementation resides in holehe/instruments.py, which wraps Python's requests library. The helper functions receive the timeout value from the core module and inject it directly into every requests.get or requests.post call, ensuring consistent network behavior across all OSINT checks.

# Simplified from holehe/instruments.py

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

This architecture ensures that modifying the CLI argument propagates immediately to every website check without requiring changes to individual module code.

Practical Examples for Using Custom Timeouts

You can adjust the timeout based on your network conditions and target reliability.

• Default behavior (10 seconds):

  holehe -u test@example.com

• Extended timeout for slow networks (30 seconds):

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

• Aggressive fast scanning (5 seconds):

  holehe -u test@example.com -T 5

Setting a higher value is recommended when scanning through VPNs or Tor connections where latency fluctuates, while lower values accelerate scans against well-known, responsive APIs.

Summary

• Holehe accepts a custom HTTP timeout via the -T or --timeout CLI argument defined in holehe/core.py.
• The default timeout is 10 seconds, suitable for standard broadband connections.
• The integer value is parsed by argparse and stored in args.timeout.
• holehe/instruments.py applies this value to all requests library calls, ensuring uniform timeout behavior across every email verification module.
• Adjust this parameter when experiencing false negatives due to network latency or when optimizing scan duration.

Frequently Asked Questions

What is the default HTTP timeout in Holehe?

The default timeout is 10 seconds, as defined by the default=10 parameter in the argparse configuration within holehe/core.py. If you do not specify --timeout, every HTTP request will wait up to 10 seconds for a response before raising a timeout exception.

Can I set different timeouts for different verification modules?

No, the current implementation in megadose/holehe uses a global timeout value passed from args.timeout to the centralized request handler in holehe/instruments.py. All modules share the same timeout duration for consistency; you cannot configure per-module timeouts without modifying the source code.

Why does Holehe hang even when I set a high timeout value?

If the tool appears to hang despite a high custom HTTP timeout, the issue likely stems from connection-level timeouts outside the scope of the requests library's timeout parameter, such as DNS resolution delays or TCP connection timeouts at the operating system level. Ensure your system-level resolver settings are configured appropriately, or investigate potential proxy misconfigurations.

Is there a maximum limit for the timeout value?

There is no enforced upper limit in the Holehe source code; you can specify any positive integer accepted by Python's requests library (e.g., --timeout 300 for 5 minutes). However, excessively high values may cause the tool to run indefinitely if a target server never responds, so use practical limits based on your scanning requirements.

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