# How the Core Module of holehe Works: A Deep Dive into Email OSINT Architecture > Explore how holehe's core module orchestrates dynamic discovery executes concurrent email verification checks and aggregates results. Understand its email OSINT architecture. - Repository: [Palenath/holehe](https://github.com/megadose/holehe) - Tags: deep-dive - Published: 2026-08-21 --- **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`](https://github.com/megadose/holehe/blob/main/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`](https://github.com/megadose/holehe/blob/main/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: ```bash holehe user@example.com ``` Display only confirmed registrations (filtering out "not found" results): ```bash holehe user@example.com --only-used ``` Disable colored output for log file compatibility: ```bash holehe user@example.com --no-color ``` Export findings to CSV for spreadsheet analysis: ```bash holehe user@example.com --csv ``` Skip password recovery attempts for faster, less noisy scanning: ```bash 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`](https://github.com/megadose/holehe/blob/main/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.