How CSV Export Works in Holehe: A Complete Technical Breakdown

Holehe's CSV export functionality generates timestamped CSV files containing all email investigation results when the -C flag is passed on the command line.

The CSV export capability in the Holehe OSINT tool allows security researchers and investigators to save email probe results in a structured, machine-readable format for further analysis. This feature is implemented directly in the core module and requires no external dependencies beyond Python's standard library.

Where the CSV Export Logic Lives

The entire export pipeline resides in holehe/core.py. This single file handles command-line parsing, result collection, and file generation.

When you invoke Holehe with the -C or --csv flag, the argparse configuration in core.py captures this preference and stores it in args.csvoutput as a boolean flag. This value determines whether the tool triggers file export after completing all site probes.

The Export Flow: Step by Step

Holehe processes CSV export through a tightly orchestrated four-step sequence inside the export_csv function (line 30 in holehe/core.py):

1. Timestamp and Filename Generation

The function first captures the current moment using datetime.now(), converts it to a Unix timestamp via datetime.timestamp(now), and rounds it to an integer. It then constructs a deterministic filename pattern:

holehe_<timestamp>_<email>_results.csv

This naming convention ensures chronological sorting and clear association between output files and target investigations.

2. CSV Writer Initialization

The export routine opens the target file with specific encoding parameters:

• encoding="utf8" — handles international characters in domain names and recovery emails
• newline="" — prevents platform-specific line-ending artifacts

It instantiates csv.DictWriter using the keys from the first result dictionary (data[0].keys()) as automatic column headers. This dynamic header extraction means the CSV structure adapts to whatever fields the probe modules return.

3. Data Writing

The writer executes two operations:

• writer.writeheader() — outputs column names
• writer.writerows(data) — batch-writes all result dictionaries

This approach preserves the exact data structure shown in console output—including fields like domain, exists, emailrecovery, phoneNumber, and others—while transforming it into tabular format.

4. Completion and Exit

After file operations complete, the function flushes buffers and terminates with a status message identifying the generated file path. The program exits cleanly without returning to interactive probing.

Practical Usage Examples

Basic Console Output

holehe user@example.com

CSV Export Mode

holehe user@example.com -C

# Output: All results have been exported to holehe_1725039200_user@example.com_results.csv

Recreating the Export Logic

This minimal Python snippet mirrors Holehe's internal implementation exactly:

import csv
from datetime import datetime

def export_csv(data, email):
    now = datetime.now()
    timestamp = datetime.timestamp(now)
    filename = f"holehe_{round(timestamp)}_{email}_results.csv"
    
    with open(filename, "w", encoding="utf8", newline="") as f:
        writer = csv.DictWriter(f, fieldnames=data[0].keys())
        writer.writeheader()
        writer.writerows(data)
    
    print(f"All results have been exported to {filename}")

# Example execution

export_csv(
    [
        {"domain": "github.com", "exists": True, "emailrecovery": None},
        {"domain": "twitter.com", "exists": False, "emailrecovery": None}
    ],
    "user@example.com",
)

Key Source Files

File	Purpose
holehe/core.py	Defines CLI parser, export_csv function, and post-probe export trigger
holehe/__init__.py	Exposes package entry point for the holehe command
holehe/modules/*	Site-specific check modules that populate the data structure consumed by export_csv

CSV Output Structure

The generated CSV export files contain one row per probed service with standardized columns. Typical fields include:

• domain — the service being checked
• exists — boolean indicating account presence
• emailrecovery — partial recovery email if exposed
• phoneNumber — partial recovery phone if exposed
• others — additional metadata from specific modules

Because headers derive dynamically from result dictionaries, column availability varies based on which services return data for a given email address.

Summary

• CSV export activates with -C or --csv flags parsed in holehe/core.py
• The export_csv function generates timestamped filenames and writes UTF-8 encoded CSV
• csv.DictWriter uses result dictionary keys as headers for flexible schema handling
• Output files land in the working directory with predictable naming for automation pipelines
• No external dependencies required—implementation uses only Python standard library

Frequently Asked Questions

How do I enable CSV export in Holehe?

Pass the -C or --csv flag when invoking the tool from the command line. Holehe will automatically generate a CSV file after completing all site probes.

Where does Holehe save the exported CSV file?

Files are saved to the current working directory with the naming pattern holehe_<timestamp>_<email>_results.csv. The timestamp uses Unix epoch seconds for chronological sorting.

What columns appear in the Holehe CSV export?

Columns match the keys of the result dictionaries returned by probe modules. Common fields include domain, exists, emailrecovery, phoneNumber, and others, though availability varies by target service.

Does CSV export require additional Python packages?

No. The implementation in holehe/core.py uses only standard library modules: csv, datetime, and built-in file I/O. No pip install steps are necessary beyond the base Holehe installation.

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