How the Password Recovery Detection Method Works in holehe

holehe leverages the password recovery detection method to verify email registration by invoking site-specific "forgot password" workflows and parsing server responses for account existence indicators.

The open-source OSINT tool holehe exploits public password reset APIs to determine if an email address is registered across hundreds of services without authenticating. By analyzing how different platforms respond to recovery requests, the tool extracts evidence of account existence and additional metadata like secondary emails or phone numbers. This technique is implemented consistently across service-specific modules in the megadose/holehe repository.

The Core Architecture of Password Recovery Detection

Module Flag Declaration

Every module implementing this technique defines a constant identifier that enables the core system to recognize its strategy. The modules explicitly declare:

method = "password recovery"

This flag appears across diverse implementations including holehe/modules/software/adobe.py, holehe/modules/social_media/odnoklassniki.py, holehe/modules/products/samsung.py, and holehe/modules/mails/mail_ru.py.

Orchestration in holehe.core

The central engine in holehe/core.py manages execution unless explicitly disabled. When users run scans without the --no-password-recovery flag, the core iterates over all loaded modules and invokes their coroutines asynchronously. Each module receives three critical parameters: an HTTP client instance for session persistence, the target email address, and a shared out list where results are appended.

Step-by-Step Workflow Implementation

Step 1: Initiating the Reset Process

The module constructs an HTTP request that mimics legitimate "forgot password" form submissions. This typically involves sending a POST or GET request to the service's recovery endpoint, passing the target email as a request parameter. The request headers and payload structure mirror genuine browser behavior to avoid detection.

Step 2: Response Analysis and Account Verification

After issuing the request, the module inspects server responses for account existence indicators:

• Negative indicators: Error codes or messages such as "email not found" trigger the module to record exists=False
• Positive indicators: Successful responses containing recovery tokens, secondary email addresses, or masked phone numbers confirm registration. The module sets exists=True and extracts available fields into the result dictionary

Step 3: Rate Limit Handling

Modules implement exception handling to catch HTTP 429 responses or connection timeouts. When rate limiting is detected, the module reports rateLimit=True to inform the user that the result may be inconclusive due to throttling rather than actual account absence.

Concrete Implementation: The Adobe Module

The holehe/modules/software/adobe.py file demonstrates sophisticated multi-request handling. The implementation executes:

1. A POST request to https://auth.services.adobe.com/signin/v1/authenticationstate to create an authentication state
2. Extracts the x-ims-authentication-state-encrypted header from the response
3. Performs a subsequent GET request to .../challenges?purpose=passwordRecovery using the encrypted state
4. Parses the JSON response: presence of errorCode indicates the email is absent, while valid responses yield secondaryEmail and securityPhoneNumber fields

Result Structure and Data Extraction

Each password recovery module appends a standardized dictionary to the results list:

{
    "name": service_name,
    "domain": service_domain,
    "method": "password recovery",
    "frequent_rate_limit": False,
    "rateLimit": False,
    "exists": True,
    "emailrecovery": secondary_email,
    "phoneNumber": phone,
    "others": None,
}

The exists boolean serves as the primary indicator, while emailrecovery and phoneNumber provide additional OSINT value when services expose partial recovery information.

Running holehe with Password Recovery Checks

Execute scans via CLI with default password recovery detection enabled:

holehe -e victim@example.com

Disable the checks to improve speed when account verification isn't required:

holehe -e victim@example.com --no-password-recovery

Programmatically process results in Python:

import asyncio
from holehe.core import run_modules

email = "victim@example.com"
results = asyncio.run(run_modules(email))
for r in results:
    if r["method"] == "password recovery" and r["exists"]:
        print(f"{r['name']} reports the account exists")
        if r["emailrecovery"]:
            print(f"  secondary email: {r['emailrecovery']}")
        if r["phoneNumber"]:
            print(f"  phone: {r['phoneNumber']}")

Summary

• holehe identifies account registration through the password recovery detection method by triggering "forgot password" workflows across hundreds of services
• Each module declares method = "password recovery" and implements service-specific HTTP request logic in files like adobe.py, samsung.py, and odnoklassniki.py
• The holehe/core.py orchestrator respects the --no-password-recovery flag and manages asynchronous execution across all modules
• Modules analyze API responses for error codes (indicating non-registration) or recovery metadata (confirming account existence)
• Results follow a standardized schema including exists, emailrecovery, and phoneNumber fields for consistent downstream processing

Frequently Asked Questions

What is the password recovery detection method in holehe?

The password recovery detection method is a reconnaissance technique where holehe modules simulate the "forgot password" workflow on target websites to determine if an email address is registered. By analyzing whether the server returns error messages like "email not found" or returns recovery tokens and secondary contact information, the tool can confirm account existence without authentication.

How does holehe handle rate limiting during password recovery checks?

When a module encounters HTTP 429 status codes or connection timeouts during recovery requests, it catches these exceptions and sets rateLimit=True in the result dictionary. This distinguishes between confirmed account absence and temporary blocking, ensuring users don't misinterpret throttling as proof that an email is unregistered.

Which file contains the core logic for running password recovery modules?

The holehe/core.py file contains the orchestration logic that loads all modules, checks for the --no-password-recovery CLI flag, and executes each module's coroutine asynchronously. It passes the HTTP client, target email, and results list to every module while aggregating their standardized output dictionaries.

Can password recovery modules extract additional information beyond account existence?

Yes, many modules extract supplementary OSINT data when available. For example, the Adobe module in holehe/modules/software/adobe.py retrieves secondaryEmail and securityPhoneNumber fields from successful recovery challenges, while other services may expose masked phone numbers or backup email domains in their API responses.

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