User Scanner

On Linux and macOS, you can use Nix to run the scanner without permanent installation, enter a temporary shell, or set up a development workspace.

# Run the scanner instantly without installing anything permanently
nix run github:kaifcodec/user-scanner/main -- --help

# Drop into a temporary shell where the 'user-scanner' command is active
nix shell github:kaifcodec/user-scanner/main

# (For Developers) Clone the repo and drop into an isolated workspace
nix develop .

It is recommended to use a virtual environment to manage dependencies. Create a .venv directory and activate it based on your operating system.

# create venv
python3 -m venv .venv

# Activate venv
# Linux / macOS
source .venv/bin/activate

# Windows (PowerShell)
.venv\Scripts\Activate.ps1

The pattern system allows you to generate multiple username or email variations from a single compact pattern definition using the -u (username) or -e (email) flags.

Quick Start Examples:

• Scan character sets: user-scanner -u "john[a-c]" (scans johna, johnb, johnc)
• Scan with length control: user-scanner -u "john[0-9]{0-2}" -s 50 (scans up to 50 permutations)
• Scan case variations: user-scanner -u "[jJ]ohn[0-9]{1-2}"
• Scan email variations: user-scanner -e "user[a-z]{0-1}@example.com"

# Scan "johna", "johnb", "johnc"
user-scanner -u "john[a-c]"

# Scan up to 50 permutations instead of default 100
user-scanner -u "john[0-9]{0-2}" -s 50

# Scan multiple variations with case differences
user-scanner -u "[jJ]ohn[0-9]{1-2}"

# With emails
user-scanner -e "user[a-z]{0-1}@example.com"

To install User Scanner using the standard Python setup, upgrade pip and then install the package. You can install it globally or within a virtual environment.

# Upgrade pip to the latest version
python3 -m pip install --upgrade pip

# Install the package globally or in your virtual environment
pip install user-scanner

To use proxies during a scan, provide a path to a file containing a list of proxies (one per line) using the --proxy-file flag.

If you use the --validate-proxies flag, the tool will test the proxies against gstatic.com/generate_204 before starting the scan to ensure they are working.

You can list all available modules for either username or email scanning to see which sites are supported and whether they are considered "loud" (sites that might trigger notifications like password resets).

• List username modules: user-scanner --list-user
• List email modules: user-scanner --list-email

Note: If --no-nsfw is used, NSFW sites will be excluded from the list.

When constructing patterns, adhere to these constraints:

• No Nesting: Do not nest brackets (e.g., [[a-z]] is invalid).
• Ascending Ranges: Ranges must go from lower to higher ASCII values (e.g., [a-z] is valid, but [z-a] is invalid).
• Purpose: The pattern engine is designed for generating variations, not for complex regex-like logic.

Scan multiple identifiers provided in a text file (one per line) using the -ef (email file) or -uf (username file) flags.

user-scanner -ef emails.txt     # bulk email scan
user-scanner -uf usernames.txt  # bulk username scan

Use the --hudson flag to check if a username or email has been exposed in infostealer malware logs.

user-scanner -e johndoe@gmail.com --hudson   # for email check
user-scanner -u johndoe --hudson             # for username check

To bypass rate-limiting, use a proxy list. It is recommended to validate them first using the --validate-proxies flag. This filters working proxies and saves them to validated_proxies.txt before starting the scan.

user-scanner -u johndoe -P proxies.txt --validate-proxies # recommended