How to Configure Custom HTTP Timeouts with the `--timeout` Argument in holehe

Pass --timeout <seconds> to override the 10-second default for all HTTP requests made during OSINT reconnaissance.

holehe is an open-source OSINT tool for email reconnaissance that checks hundreds of websites for account existence. When scanning large target lists or operating on unstable networks, controlling HTTP timeout behavior becomes critical for reliable results. The --timeout argument, implemented in holehe/core.py, lets you adjust how long the tool waits for each remote server response.

How the --timeout Argument Works in holehe

The timeout configuration flows through two core components: the command-line interface parser and the HTTP request helper.

CLI Argument Definition in core.py

In holehe/core.py, the argument parser defines the --timeout option with a default value of 10 seconds:

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

The type=int enforcement ensures only integer values are accepted. The -T short form provides a quick alternative for frequent use.

Timeout Propagation to HTTP Requests

After parsing, args.timeout passes through to the request instrumentation in holehe/instruments.py. The request helper forwards this value directly to Python's requests library:

# Simplified from holehe/instruments.py

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

This design means every HTTP request made by holehe modules uses your specified timeout consistently.

Practical Usage Examples

Basic Timeout Override

Increase timeout for slow residential connections:

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

Aggressive Fast Scanning

Reduce timeout for rapid reconnaissance on responsive networks:

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

Using the Short Form

holehe -u target@example.com -T 15

Timeout Behavior and Error Handling

When a request exceeds the configured timeout, holehe raises requests.exceptions.Timeout. The tool catches these exceptions per-module and continues scanning remaining services rather than failing entirely.

According to the holehe source code, modules handle timeout exceptions gracefully:

• The specific service check returns None or error status
• Execution proceeds to the next target module
• Final output indicates which checks timed out

This design ensures partial results are preserved even when some services are unresponsive.

Performance Considerations

Timeout Value	Use Case	Trade-off
3-5 seconds	Fast scanning, reliable networks	Higher false-negative rate for slow services
10 seconds (default)	Balanced operation	Standard reliability
30-60 seconds	Slow VPNs, Tor, high-latency targets	Much slower overall scan time

Increasing timeout linearly impacts total scan duration. With 300+ services checked, a 60-second timeout creates a worst-case 5-minute delay per email address.

Summary

• holehe uses --timeout with a 10-second default, defined in holehe/core.py
• Values pass through holehe/instruments.py to Python's requests library
• Accepts integer seconds via -T short form or --timeout long form
• Timeouts are per-request, not per-email or per-scan
• Failed timeouts skip individual modules without crashing the full scan

Frequently Asked Questions

What happens if I don't specify a timeout?

holehe defaults to 10 seconds per HTTP request. This value is hardcoded in holehe/core.py as default=10 in the argument parser definition.

Can I set different timeouts for different services?

No. The holehe architecture uses a global timeout value passed to all request calls through holehe/instruments.py. Per-service timeout configuration would require modifying individual module files.

Why does my scan hang even with a short timeout?

Some modules may use separate connection pools or DNS resolution that isn't covered by the requests timeout. The --timeout parameter specifically controls the requests.get/requests.post timeout parameter, not underlying TCP connection establishment in all edge cases.

Does timeout affect rate limiting or retry behavior?

No. The timeout parameter only controls single request duration. holehe does not implement automatic retries; each service check makes one attempt with your specified timeout, then proceeds.

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