Holehe Main Execution Engine Location: Inside core.py

The main execution engine of Holehe resides in holehe/core.py, which orchestrates the entire asynchronous email-scanning workflow through the main() and maincore() functions.

Holehe is an open-source email enumeration tool developed by megadose that checks if an email address exists across hundreds of platforms. Understanding the main execution engine is essential for developers who want to extend the tool or integrate its capabilities into custom workflows.

Core Execution Architecture

The execution flow centers on holehe/core.py, which serves as the command-line interface and asynchronous task orchestrator. This file bridges user input with the modular site-checking system located in holehe/modules/.

Console Script Entry Point

The setup.cfg file registers the CLI command by pointing to holehe.core:main:

holehe = holehe.core:main

When you type holehe <email> in the terminal, Python invokes the main() function defined in holehe/core.py. This function immediately delegates to the Trio event loop:

def main():
    trio.run(maincore)

Asynchronous Workflow Orchestration

The maincore() function (implemented at lines 79-131 in holehe/core.py) handles the heavy lifting. It constructs the argument parser, dynamically imports every submodule in holehe.modules, and launches concurrent site checks using Trio for structured concurrency.

Key responsibilities include:

• Parsing command-line arguments such as --only-used and --csv
• Loading site-check implementations from the modules directory
• Executing checks as concurrent tasks
• Aggregating results
• Formatting output and optionally writing CSV files

Key Functions in core.py

Understanding the two primary functions clarifies how Holehe processes requests.

main() Function

The main() function acts as a thin wrapper that initializes the Trio runtime. It contains a single line that starts the async event loop:

def main():
    trio.run(maincore)

This design separates synchronous entry-point concerns from the asynchronous implementation, following Python best practices for CLI tools.

maincore() Function

The maincore() coroutine contains the actual execution logic. According to the source code in holehe/core.py, this function:

1. Builds the argparse configuration
2. Discovers and imports all site-check modules in holehe/modules/
3. Creates a Trio nursery to launch concurrent email verification tasks
4. Gathers results from each service module
5. Prints formatted output to stdout
6. Optionally exports data to CSV when the --csv flag is provided

The implementation leverages Trio's structured concurrency model to handle hundreds of simultaneous HTTP requests without blocking.

Command-Line Usage Examples

The core engine supports several execution modes via command-line flags:

# Basic email scan

holehe alice@example.com

# Filter results to show only registered accounts

holehe alice@example.com --only-used

# Export enumeration results to CSV

holehe alice@example.com --csv

These flags are parsed within maincore() and affect how results are filtered and persisted.

Programmatic Integration

You can bypass the CLI and invoke the engine directly from Python code. Import the entry point to replicate terminal behavior:

from holehe.core import main

# Executes the full workflow using sys.argv for arguments

main()

For advanced use cases requiring manual event loop management, import the async coroutine directly:

import asyncio
from holehe.core import maincore

# Run the async workflow inside an existing asyncio loop

asyncio.run(maincore())

Note that maincore() uses Trio internally, so running it inside asyncio.run() requires compatibility layers or direct Trio usage in production environments.

Supporting Infrastructure

Several adjacent files support the execution engine:

• holehe/instruments.py: Implements the Trio-compatible progress bar displayed during scans
• holehe/localuseragent.py: Provides static user-agent strings for HTTP requests to avoid detection
• holehe/modules/*.py: Individual platform implementations (e.g., facebook.py, twitter.py) that core.py dynamically discovers and executes
• holehe/__init__.py: Package initialization containing version metadata

Summary

• The main execution engine of Holehe lives in holehe/core.py, which serves as both the CLI entry point and async orchestrator.
• The main() function initializes the Trio event loop and immediately calls maincore().
• maincore() (lines 79-131) handles argument parsing, module discovery, concurrent execution via Trio, and result formatting.
• Command-line flags like --only-used and --csv are processed within the core engine to filter output and control export behavior.
• Programmatic access is available by importing main or maincore from holehe.core.

Frequently Asked Questions

What file contains the main execution engine of Holehe?

The main execution engine resides in holehe/core.py. This file contains the main() and maincore() functions that drive the entire email enumeration process, handle command-line arguments, and coordinate asynchronous site checks across hundreds of platforms.

How does Holehe manage concurrent site checks?

Holehe uses Trio for structured concurrency. The maincore() function in holehe/core.py creates a Trio nursery that launches each site-check module as a separate concurrent task, allowing hundreds of HTTP requests to execute simultaneously without blocking the main thread.

Can I run Holehe programmatically without using the command line?

Yes. Import the main() function from holehe.core to execute the full CLI workflow, or import maincore() to run the async logic directly within your own event loop. Note that maincore() is a Trio coroutine, so you should use trio.run() or an asyncio compatibility layer for proper execution.

Where is the holehe command registered?

The holehe command is registered in setup.cfg as a console script pointing to holehe.core:main. This entry point tells Python to execute the main() function from holehe/core.py whenever the holehe command is invoked from the terminal.

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