How Holehe's CSV Export Functionality Works: A Technical Deep Dive

Holehe's CSV export functionality is implemented in the export_csv function in holehe/core.py, which generates timestamped UTF-8 CSV files containing OSINT scan results when the -C/--csv flag is provided.

Holehe is an open-source OSINT (Open Source Intelligence) tool by megadose that checks for account existence across hundreds of platforms using email addresses. When conducting investigations or automated reconnaissance, exporting results to CSV format enables further analysis in spreadsheet applications or data processing pipelines. Understanding how holehe's CSV export functionality works requires examining the core implementation, data structures, and command-line interface integration.

Understanding the CSV Export Architecture

The CSV export capability is centralized in holehe/core.py, where the export_csv function handles file generation and data serialization. This function integrates with the argument parser to respond to the -C or --csv flag supplied during command execution.

The export_csv Function Implementation

According to the megadose/holehe source code, the export_csv function performs three critical operations: filename generation, file handle configuration, and dictionary serialization.

First, the function constructs a timestamped filename using the format holehe_<timestamp>_<email>_results.csv at lines 58-60. This naming convention prevents file collisions and maintains chronological organization of scan results.

Second, the function opens the file with newline='' to prevent extra blank lines on Windows systems, as implemented at line 61. This ensures cross-platform compatibility for the output file.

Third, the function utilizes Python's csv.DictWriter to serialize the list of result dictionaries. The header row is automatically derived from the keys of the first result dictionary (data[0].keys()), guaranteeing that column order matches the internal data structure. The implementation writes all rows using fc.writerows(data) at lines 61-64.

CSV File Structure and Data Fields

Each row in the exported CSV represents a single module's outcome from the holehe scan. The columns correspond to specific fields returned by individual platform-checking modules.

The CSV contains the following seven fields:

• name: The internal identifier of the module (e.g., twitter, gmail, github)
• domain: The target website's domain (e.g., twitter.com, gmail.com)
• rateLimit: Boolean value (True/False) indicating whether the request encountered rate limiting
• exists: Boolean value (True/False) indicating whether an account linked to the email was found
• emailrecovery: Partially obfuscated recovery email returned by the service, or None if unavailable
• phoneNumber: Partially obfuscated recovery phone number returned by the service, or None if unavailable
• others: Miscellaneous additional data such as full names, account creation dates, or profile metadata, or None if unavailable

Command Line Usage

The CSV export functionality is triggered via the command-line interface using the -C or --csv flag. The argument parser in holehe/core.py (lines 192-194) defines this flag with dest="csvoutput", enabling the boolean check that triggers the export sequence.

To generate a CSV file during a standard holehe scan:

holehe victim@example.com -C

Upon completion, the tool outputs the file location:

All results have been exported to holehe_1723862123_victim@example.com_results.csv

The timestamp in the filename corresponds to the Unix timestamp at execution time, ensuring unique filenames for repeated scans of the same target.

Programmatic Implementation

Developers can also invoke the CSV export functionality programmatically when building custom tools around holehe's core modules. The following example demonstrates how to run an asynchronous scan and export results using the export_csv function:

import httpx
import trio
from holehe.core import export_csv, get_functions, import_submodules

async def run(email):
    # Import all holehe modules

    modules = import_submodules("holehe.modules")
    functions = get_functions(modules)
    
    # Collect results

    out = []
    async with httpx.AsyncClient(timeout=10) as client:
        for func in functions:
            await func(email, client, out)
    
    # Export to CSV using a mock args object

    class Args:
        csvoutput = True
    
    export_csv(out, Args(), email)

# Run the investigation

trio.run(run, "victim@example.com")

This approach allows integration into larger automation frameworks while maintaining the same file formatting and data structure as the CLI implementation.

Summary

• Holehe's CSV export functionality is centralized in the export_csv function within holehe/core.py, specifically lines 54-64.
• The system generates timestamped filenames using the pattern holehe_<timestamp>_<email>_results.csv to prevent overwrites.
• Data is serialized using Python's csv.DictWriter with headers dynamically extracted from result dictionary keys.
• The CSV contains seven standardized fields: name, domain, rateLimit, exists, emailrecovery, phoneNumber, and others.
• Cross-platform compatibility is ensured by opening files with newline='' to prevent Windows blank line artifacts.
• The functionality is accessible via CLI flag -C/--csv or programmatically through the core module.

Frequently Asked Questions

What file naming convention does holehe use for CSV exports?

Holehe generates filenames using the format holehe_<timestamp>_<email>_results.csv, where the timestamp represents the Unix epoch time at execution. This naming scheme, implemented in holehe/core.py lines 58-60, prevents file collisions when running multiple scans and maintains chronological organization of OSINT results.

Does the CSV export include rate limit information from holehe scans?

Yes, the CSV export includes a dedicated rateLimit column (boolean) that indicates whether the specific module encountered rate limiting during the request. This field allows analysts to distinguish between account non-existence and temporary blocking mechanisms implemented by target platforms.

How does holehe handle CSV formatting across different operating systems?

The export_csv function in holehe/core.py explicitly opens output files with newline='' (line 61) before passing the handle to csv.DictWriter. This parameter prevents the Windows-specific \r\r\n line ending artifacts that would otherwise create extra blank lines in the exported CSV file.

Can holehe export to CSV when used as a Python library rather than CLI?

Yes, developers can invoke export_csv(out, args, email) programmatically by importing the function from holehe.core. The function requires a list of result dictionaries (out), an arguments object with a csvoutput boolean attribute, and the target email string to construct the filename, enabling integration into custom automation workflows.

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