How to Run user‑scanner in a Docker Container: Complete Setup Guide

To run user‑scanner in a Docker container, build an image from python:3.12-slim, install dependencies via requirements.txt, and execute python -m user_scanner as the container ENTRYPOINT with your desired CLI arguments.

The user-scanner repository by kaifcodec is a pure‑Python OSINT aggregation framework that executes parallel username and email probes across hundreds of platforms. Its modular architecture—anchored by user_scanner/__main__.py and the orchestrator in user_scanner/core/orchestrator.py—requires only a standard Python runtime, making it ideal for containerized deployments without external binaries or system dependencies.

Architecture Overview for Containerization

Before building the image, understand how the codebase initializes inside a container:

• user_scanner/__main__.py – The CLI entry point that parses arguments and boots the core engine (user_scanner/core/engine.py).
• user_scanner/core/orchestrator.py – Loads every scan module located under user_scanner/user_scan/ and user_scanner/email_scan/, then dispatches concurrent requests using httpx and curl_cffi impersonation.
• user_scanner/core/result.py – Aggregates output from each module into a standardized result object.
• pyproject.toml and requirements.txt – Declare the package metadata and frozen dependency tree needed for pip installation.

Because the tool is installable from PyPI as a library, the container simply needs to import the package and invoke the module.

Creating the Dockerfile

Use a multi-stage build to minimize the final image size while ensuring compilation tools are available for dependencies like curl_cffi.

# Dockerfile

FROM python:3.12-slim AS builder

# Install build-time dependencies

RUN apt-get update && apt-get install -y --no-install-recommends \
    gcc libc-dev && rm -rf /var/lib/apt/lists/*

# Copy metadata for pip installation

WORKDIR /app
COPY pyproject.toml .
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Runtime stage – minimal image

FROM python:3.12-slim
WORKDIR /app
COPY --from=builder /usr/local/lib/python3.12/site-packages /usr/local/lib/python3.12/site-packages

# Optional: expose a default working directory for scan outputs

VOLUME /output
ENTRYPOINT ["python", "-m", "user_scanner"]

This configuration installs the full dependency tree—including the orchestrator and all scan modules—into /usr/local/lib/python3.12/site-packages, making them available to the Python interpreter at runtime.

Building the Docker Image

Execute the build command from the repository root:

docker build -t user-scanner .

The resulting image contains the complete user-scanner package, ready to execute scans without any host Python installation.

Running Scans in Containers

Pass CLI flags directly after the image name; the ENTRYPOINT forwards them to user_scanner/__main__.py.

Basic Execution with Volume Mounting

Mount a host directory to /output to persist results generated by the Result abstraction:

docker run --rm -v "$(pwd)/output:/output" user-scanner example@example.com

Email Scan with JSON Output

Specify an output path inside the mounted volume:

docker run --rm -v "$(pwd)/output:/output" user-scanner \
    -o /output/result.json example@example.com

Interactive Terminal Session

For debugging or manual inspection:

docker run -it --rm user-scanner --help

Advanced Configuration and Volume Management

When you run user‑scanner in a Docker container, consider these optimization patterns:

1. Multi-stage builds – The example above uses a builder stage with gcc and libc-dev to compile curl_cffi, then copies only the installed packages to the runtime stage. This eliminates build tools from the final image, reducing attack surface and image size.
2. Output persistence – The orchestrator writes data through the abstraction in user_scanner/core/result.py. Always mount a host volume to /output (or your custom path) when using the -o flag to prevent data loss when the container exits.
3. CI/CD integration – Because the container exits with the CLI’s return code, you can drop it into GitHub Actions or GitLab CI pipelines to automate OSINT workflows without installing Python on the runner.

Summary

• Base image – Use python:3.12-slim to run user‑scanner in a Docker container with minimal overhead.
• Entry point – The python -m user_scanner command triggers user_scanner/__main__.py, which initializes the core engine and orchestrator.
• Dependency management – Copy requirements.txt (generated from pyproject.toml) during the build to install httpx, curl_cffi, and scan modules.
• Data persistence – Mount host directories to the container’s /output path to capture JSON or text reports generated by the Result abstraction.
• Concurrency model – The orchestrator spawns parallel workers from user_scanner/user_scan/ and user_scanner/email_scan/ modules without requiring privileged container access.

Frequently Asked Questions

Does user‑scanner require external binaries inside the container?

No. According to the kaifcodec/user-scanner source code, the tool relies entirely on Python libraries. The orchestrator in user_scanner/core/orchestrator.py uses httpx and curl_cffi for HTTP impersonation, eliminating the need for external cURL binaries or system packages in the final image.

How do I pass custom CLI flags when running the container?

Append flags after the image name in your docker run command. The Dockerfile ENTRYPOINT array passes all arguments directly to user_scanner/__main__.py, which parses them via the CLI handler and passes them to the core engine.

Where does the container load scan modules from?

The orchestrator dynamically imports Python modules located under user_scanner/user_scan/ and user_scanner/email_scan/ within the installed package directory (/usr/local/lib/python3.12/site-packages). These paths are hardcoded in user_scanner/core/orchestrator.py and execute automatically when the container starts.

Can I deploy user‑scanner in Kubernetes?

Yes. The containerized design—using a standard Python ENTRYPOINT and no persistent state—makes it compatible with Kubernetes pods, Docker Compose stacks, and serverless container platforms. Simply mount a PersistentVolumeClaim to /output if you need to retain scan results.

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