How the Timeout Parameter Controls Module Execution in Holehe

The -T/--timeout flag configures a global timeout value (default 10 seconds) for the shared httpx.AsyncClient, determining how long each module waits for HTTP responses before treating the request as a failure and marking the result with rateLimit: True.

Holehe is an open-source OSINT tool that checks email addresses against multiple services asynchronously. The timeout parameter directly governs the maximum duration each module spends awaiting network responses, creating a trade-off between scan speed and result accuracy.

CLI Argument Parsing in core.py

The timeout value originates in holehe/core.py, where the argument parser defines the -T and --timeout flags with a default of 10 seconds:

parser.add_argument("-T","--timeout", type=int , default=10, ...)

After parsing, the value is stored in args.timeout and used to instantiate the HTTP client between lines 108-114. This single configuration point ensures the timeout is applied consistently across the entire application.

Propagation to Modules via AsyncClient

Holehe creates one httpx.AsyncClient instance using the user-provided timeout, which is then injected into every module:

timeout = args.timeout
client = httpx.AsyncClient(timeout=timeout)

All module functions receive this client object as a required parameter (e.g., myspace(email, client, out)). Because modules share this single client instance, the timeout setting propagates to every HTTP request made during execution, ensuring uniform network behavior without manual configuration per service.

Execution Impact and Error Handling

When a request exceeds the configured duration, httpx raises a TimeoutException. Holehe catches generic exceptions within module logic and interprets them as rate-limit or timeout conditions, setting "rateLimit": True in the output dictionary.

For example, in holehe/modules/social_media/myspace.py, an initial GET request uses a hard-coded 2-second timeout, but subsequent requests respect the client-wide timeout passed from core.py. If the global timeout is reached, the module treats it as a rate limit and stops processing.

Short vs. Long Timeout Values

• Shorter timeouts (e.g., 3 seconds): Accelerate overall scan completion but increase the risk of false negatives, as slower services may be marked as rate-limited before responding.
• Longer timeouts (e.g., 30 seconds): Improve accuracy for slow or congested services but significantly extend total execution time, especially if multiple services are unresponsive.
• Default (10 seconds): The original author's balanced setting suitable for most network conditions.

Practical Configuration Examples

Run Holehe with custom timeout values via the CLI:

# Default 10-second timeout

holehe example@example.com

# Fast scan with 3-second timeout

holehe example@example.com -T 3

# Tolerant scan for slow networks (20 seconds)

holehe example@example.com --timeout 20

For programmatic usage, create the client with a custom timeout before invoking modules directly:

import httpx
from holehe.core import import_submodules, get_functions

modules = import_submodules("holehe.modules")
websites = get_functions(modules)

# Configure 5-second timeout

client = httpx.AsyncClient(timeout=5)

# Execute specific module

import holehe.modules.social_media.myspace as myspace_mod
await myspace_mod.myspace("example@example.com", client, [])

Summary

• The timeout parameter is defined in holehe/core.py with a default value of 10 seconds.
• A single httpx.AsyncClient instance shares the timeout setting across all modules.
• Exceeded timeouts result in TimeoutException, which modules catch and report as rateLimit: True.
• Adjusting the value trades off between scan speed (short timeouts) and reliability (long timeouts).

Frequently Asked Questions

What is the default timeout value in Holehe?

The default timeout is 10 seconds, defined in the argument parser within holehe/core.py. This value is used when the -T or --timeout flag is not specified.

How does Holehe handle requests that exceed the timeout limit?

When a request exceeds the configured timeout, httpx raises a TimeoutException. Holehe catches this exception in module code and marks the result with "rateLimit": True, indicating the check could not complete due to time constraints or rate limiting.

Can individual modules override the global timeout setting?

While modules generally use the shared client, some may implement specific timeouts for individual requests. For instance, myspace.py uses a hard-coded 2-second timeout for an initial GET request, but subsequent requests respect the global client timeout passed from the CLI.

Does increasing the timeout guarantee finding more accounts?

Not necessarily. A longer timeout only allows more time for slow servers to respond; it does not bypass rate limiting or authentication requirements. However, it can reduce false negatives caused by temporary network latency.

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