How to Build a Holehe Docker Image: Complete Setup Guide

The Holehe project ships a minimal Dockerfile that builds a lightweight Python 3.11 container, copies the source into /opt/holehe, installs the package via setup.py, and exposes the holehe CLI for immediate execution.

Building a Holehe Docker image ensures consistent deployment of this email reconnaissance tool across any environment. The megadose/holehe repository includes an official Dockerfile that leverages Debian Bullseye with Python 3.11, packaging the tool and its dependencies into a portable container. This guide explains how to build the image from source and run the CLI inside a secure container environment.

Understanding the Holehe Dockerfile Structure

The Dockerfile at the repository root defines a streamlined build process optimized for security and minimal footprint. According to the megadose/holehe source code, the container configuration follows a four-step pattern: base image selection, source code integration, working directory configuration, and package installation.

Base Image Selection

Line 1 of the Dockerfile specifies python:3.11-slim-bullseye as the foundation. This official Python image provides a minimal Debian Bullseye runtime without unnecessary build tools, reducing both attack surface and final image size while maintaining compatibility with Holehe's async requirements.

Source Code Integration

Lines 2-3 copy the entire repository into /opt/holehe and establish that path as the working directory. This placement follows Linux filesystem conventions for third-party software installations, keeping the application isolated from system directories.

Package Installation and Dependencies

Lines 4-5 execute python setup.py install, which registers the holehe console entry point and installs required dependencies. As defined in setup.py at line 11, the installation pulls in termcolor, bs4, httpx, trio, tqdm, and colorama. The setup.py script maps the holehe command to the entry point implemented in holehe/core.py, ensuring the CLI behaves identically to a local pip installation.

Building the Holehe Docker Image

Execute the following command from the repository root to build the image:

docker build -t holehe-image .

This command processes the Dockerfile instructions sequentially, creating a tagged image named holehe-image that contains the fully configured environment.

Running Holehe Inside a Container

Once built, execute Holehe reconnaissance commands without installing Python locally:

docker run --rm holehe-image holehe test@example.com

The --rm flag automatically removes the container after execution, preventing persistent storage consumption and maintaining a clean host environment.

For interactive exploration or debugging, access the container shell directly:

docker run -it --rm holehe-image /bin/sh

From within the shell at /opt/holehe, invoke the tool normally:

holehe target@example.com

Key Files in the Docker Build Process

• Dockerfile – Defines the container build steps, specifying the base image as python:3.11-slim-bullseye and orchestrating the installation sequence.

• setup.py – Declares package metadata and dependency requirements at line 11; the Dockerfile invokes this file to install Holehe and register the console script.

• holehe/core.py – Implements the main CLI entry point that the holehe command executes when run inside the container.

Summary

• The Holehe Dockerfile uses python:3.11-slim-bullseye to provide a minimal, secure Python 3.11 runtime on Debian Bullseye.
• Source code is copied to /opt/holehe and dependencies are installed via setup.py, which references requirements at line 11.
• The holehe console entry point connects to the implementation in holehe/core.py.
• Build the image with docker build -t holehe-image .
• Execute reconnaissance with docker run --rm holehe-image holehe <email>

Frequently Asked Questions

What base image does Holehe use for Docker builds?

The Holehe Dockerfile uses python:3.11-slim-bullseye as specified in line 1 of the Dockerfile. This provides a Debian Bullseye-based Python 3.11 runtime with minimal packages, ensuring a lightweight and secure foundation for the email reconnaissance tool.

How are dependencies managed in the Holehe Docker image?

Dependencies are automatically installed during the image build process when the Dockerfile executes python setup.py install at lines 4-5. This command reads the requirements listed in setup.py at line 11, installing httpx, trio, bs4, termcolor, tqdm, and colorama permanently into the container image.

Can I run the Holehe Docker container interactively?

Yes, you can access an interactive shell by running docker run -it --rm holehe-image /bin/sh. This drops you into the container's shell at the /opt/holehe working directory, where you can execute holehe commands directly or inspect the installed package files.

Where is the Holehe CLI entry point defined?

The holehe command is registered as a console script in setup.py, which points to the main function in holehe/core.py. When you run holehe <email> inside the container, you are executing the Python code defined in that core module according to the megadose/holehe source implementation.

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