How the Core Module of holehe Works: A Deep Dive into Email OSINT Architecture

The core module orchestrates dynamic discovery of service modules, executes concurrent email verification checks using Trio and httpx, and aggregates results into formatted reports.

The holehe tool by megadose/holehe is an open-source email OSINT (Open Source Intelligence) utility that checks where an email address is registered across hundreds of platforms. At the heart of this operation lies holehe/core.py, which serves as the central nervous system handling everything from module discovery to asynchronous network requests. Understanding how the core module of holehe works reveals the architectural patterns that enable rapid, parallelized email reconnaissance.

Dynamic Module Discovery and Loading

The core starts by dynamically discovering available service checks without hardcoding module names. The import_submodules function (lines 37-47) utilizes pkgutil.walk_packages to traverse the holehe.modules package tree, automatically importing every submodule it encounters.

This approach builds a dictionary of fully-qualified module objects at runtime, allowing the tool to recognize new platform modules immediately upon installation without modifying the core logic. The discovery mechanism ensures that adding support for a new website requires only dropping a Python file into the appropriate modules directory.

Service Function Selection and Filtering

Once modules are loaded, get_functions (lines 50-63) iterates through the imported packages to extract the specific callable that performs the email check for each website. It identifies the public function implementing the check—typically named after the last component of the module path—and compiles these into an executable list.

The selector also respects the --no-password-recovery flag, filtering out modules that specifically attempt password recovery flows when this option is specified. This allows users to skip slower or more intrusive checks while maintaining the core verification functionality.

Command-Line Interface and Email Validation

The maincore function defines the CLI interface using Python’s ArgumentParser (lines 80-96), exposing options including:

• --only-used – display only sites where the email is registered
• --no-color – disable ANSI color codes for logging pipelines
• --csv – export results to a CSV file
• --timeout – configure network request timeouts

Before initiating any network activity, the core validates the target through is_email (lines 94-104), which applies a regex pattern to guarantee the supplied argument conforms to email format standards. This prevents wasting resources on malformed inputs.

Asynchronous Execution Engine

The core leverages Trio for structured concurrency and httpx for HTTP operations. An httpx.AsyncClient instance is instantiated with the user-specified timeout (lines 12-14), enabling efficient connection pooling across hundreds of simultaneous requests.

To provide user feedback during execution, the core attaches a TrioProgress instrument (defined in holehe/instruments.py) to the Trio event loop (lines 16-18). This instrument renders a progress bar that tracks completion status across all modules.

Using trio.open_nursery() (lines 18-21), the core spawns one asynchronous task per website via the launch_module wrapper. Each task calls the website-specific check function with three arguments: the target email, the shared HTTP client, and a synchronized output list. The launch_module wrapper (lines 66-78) catches exceptions from individual modules, ensuring that a single failing website does not crash the entire reconnaissance run, and records standardized error entries instead.

Result Normalization and Reporting

Each service module returns a standardized dictionary containing:

• exists – boolean indicating if the email is registered
• rateLimit – whether the platform throttled the request
• emailrecovery – partial email addresses exposed by recovery flows
• phoneNumber – associated phone numbers if leaked
• others – additional platform-specific metadata

After all tasks complete, the core sorts results by module name and passes them to print_result for color-coded terminal display (lines 22-31). If the --csv flag was provided, export_csv (lines 54-65) serializes the dataset to disk. This dual-output system supports both human analysis and automated pipeline integration.

Self-Update Mechanism

The core includes an automatic update checker via check_update (lines 65-86). This function queries the Python Package Index (PyPI) for the latest holehe release and automatically upgrades the package when a newer version exists, ensuring users always operate with the latest platform modules and security patches.

Practical Usage Examples

Basic reconnaissance against a single target:

holehe user@example.com

Display only confirmed registrations (filtering out "not found" results):

holehe user@example.com --only-used

Disable colored output for log file compatibility:

holehe user@example.com --no-color

Export findings to CSV for spreadsheet analysis:

holehe user@example.com --csv

Skip password recovery attempts for faster, less noisy scanning:

holehe user@example.com --no-password-recovery

Summary

• Dynamic Discovery: The core uses pkgutil.walk_packages in import_submodules to auto-detect service modules without manual registration.
• Structured Concurrency: Trio’s nursery pattern enables parallel checking of hundreds of sites while isolating failures via launch_module exception handling.
• Standardized I/O: Results follow a consistent schema across all modules, supporting both terminal tables via print_result and CSV export via export_csv.
• Validation First: The is_email regex ensures syntactic correctness before any network requests occur.
• Auto-Maintenance: The check_update function keeps the tool current by querying PyPI and self-upgrading when necessary.

Frequently Asked Questions

What is the role of the holehe core module?

The core module in holehe/core.py serves as the orchestration engine that discovers available platform modules, validates input emails, manages concurrent HTTP sessions, and aggregates results into readable reports. It abstracts the complexity of async networking and error handling away from individual service implementations.

How does holehe check multiple websites simultaneously?

The core utilizes trio.open_nursery() to spawn asynchronous tasks for each service module, with each task running the platform-specific check function concurrently. An httpx.AsyncClient shares connection pools across these tasks, while a TrioProgress instrument tracks overall completion status in real time.

What happens when a specific website check fails?

Individual module failures are caught by the launch_module wrapper (lines 66-78), which records a standardized error entry containing the exception details rather than crashing the entire scan. This ensures that network timeouts, API changes, or site outages do not prevent the reconnaissance of other platforms from completing.

How does the core module validate email addresses before scanning?

Before executing any network requests, the core passes the input through is_email (lines 94-104), which applies a regular expression pattern to verify that the string conforms to standard email syntax. This validation step prevents unnecessary HTTP traffic for malformed or non-email inputs.

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