Holehe HTTP Client Configuration: How to Customize the httpx AsyncClient

Holehe uses the httpx library for all HTTP requests, with only the timeout parameter exposed through the command-line interface; deeper customization requires modifying the source code or passing a pre-configured client manually.

Holehe is an OSINT email reconnaissance tool that checks for account registrations across hundreds of websites. Understanding its HTTP client configuration helps users optimize request behavior for different network conditions and operational requirements. This article examines exactly how Holehe configures its httpx.AsyncClient and what customization options are available.

What HTTP Client Does Holehe Use?

Holehe relies exclusively on httpx for HTTP communication. According to the source code in megadose/holehe, this dependency is declared in setup.py (line 11) and used throughout the application.

The core client instantiation occurs in holehe/core.py at line 213:

client = httpx.AsyncClient(timeout=timeout)

This creates an asynchronous HTTP client with httpx's default settings for:

• Connection pooling
• HTTP/1.1 and HTTP/2 support
• Standard headers
• No proxy configuration
• No retry logic

A synchronous variant appears only for the version-check request, which uses httpx.get with default parameters.

Configurable Options: Timeout Only

Command-Line Timeout Control

The only HTTP client setting exposed to end users is request timeout. This is controlled via:

holehe user@example.com --timeout 30

Or using the short flag:

holehe user@example.com -T 30

The argument is parsed in holehe/core.py at line 94 and defaults to 10 seconds if unspecified. This value passes directly to the httpx.AsyncClient constructor.

Why Timeout Matters for Holehe

Holehe performs hundreds of concurrent requests across disparate websites with varying response times. The default 10-second timeout balances:

• Completeness (catching slow-responding services)
• Speed (avoiding indefinite waits on unresponsive hosts)
• Resource efficiency (freeing connections for other checks)

Users on slower networks or those targeting geographically distant services may need to increase this value.

Customizing the HTTP Client

Limitations of the Public API

The current Holehe public API does not expose additional httpx configuration options. Users cannot directly set:

• Proxy servers
• Custom headers or User-Agent strings
• Connection pool limits
• Retry policies
• SSL/TLS verification settings
• HTTP/2 prioritization

These remain at httpx defaults as determined by the library's own AsyncClient initialization.

Method 1: Source Code Modification

To permanently change HTTP client behavior, edit holehe/core.py around line 213:

# Original

client = httpx.AsyncClient(timeout=timeout)

# Modified with proxy and connection limits

client = httpx.AsyncClient(
    timeout=timeout,
    proxies="http://proxy.example.com:8080",
    limits=httpx.Limits(max_connections=100, max_keepalive=20),
    headers={"User-Agent": "Custom-Agent/1.0"},
)

This approach requires maintaining a fork or local patch.

Method 2: Programmatic Client Injection

For programmatic usage, instantiate a custom client and pass it to Holehe's internal functions:

import httpx
from holehe.core import launch_module, get_functions, import_submodules

# Configure custom httpx.AsyncClient

custom_client = httpx.AsyncClient(
    timeout=20,
    proxies="http://myproxy:8080",
    limits=httpx.Limits(max_connections=10, max_keepalive=5),
    headers={"User-Agent": "Mozilla/5.0 (Custom)"},
)

# Load Holehe modules

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

# Use custom_client with launch_module calls

# (requires calling internal functions directly rather than CLI)

This method provides full httpx flexibility without modifying Holehe's source, though it bypasses the standard command-line interface.

Key Implementation Files

Understanding these source locations helps when customizing Holehe's HTTP behavior:

File	Line(s)	Purpose
holehe/core.py	213	httpx.AsyncClient instantiation with timeout
holehe/core.py	94	--timeout / -T argument parsing
setup.py	11	httpx dependency declaration

Summary

• Holehe uses httpx.AsyncClient for all asynchronous HTTP operations, with synchronous httpx.get only for version checks
• The timeout parameter (default 10s) is the only configurable option exposed through the CLI (--timeout / -T)
• All other HTTP client settings use httpx defaults with no proxy, custom headers, or retry logic
• Deeper customization requires either modifying holehe/core.py or programmatically injecting a pre-configured httpx.AsyncClient
• The version-check request uses separate synchronous httpx calls unaffected by the main client configuration

Frequently Asked Questions

Can I use a proxy with Holehe?

Not through the standard command-line interface. Holehe's httpx.AsyncClient is instantiated without proxy configuration. To route traffic through a proxy, either modify holehe/core.py line 213 to include a proxies parameter, or use the programmatic approach with a custom httpx.AsyncClient that includes proxy settings.

Does Holehe support custom User-Agent headers?

No, the public API does not expose User-Agent customization. The httpx library sends its default headers. To override this, modify the client creation in holehe/core.py to include a custom headers dictionary, or pass a pre-configured client with modified headers when calling Holehe functions programmatically.

Why does Holehe use httpx instead of requests or aiohttp?

The source code in setup.py specifies httpx as the HTTP dependency. This choice provides native async/await support with a requests-compatible API, HTTP/2 capability, and modern Python async patterns. The AsyncClient design aligns with Holehe's concurrent checking of multiple websites.

Can I increase the connection pool size for faster scanning?

The connection pool size is not exposed through CLI arguments. Httpx applies its default Limits configuration. To adjust connection limits, create a custom httpx.AsyncClient with explicit limits=httpx.Limits(max_connections=..., max_keepalive=...) and use it programmatically, or modify the instantiation in holehe/core.py.

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