### CLI Example: Simple usernames with numbers

Source: https://github.com/kaifcodec/user-scanner/blob/main/docs/PATTERNS.md

Scan for usernames starting with 'johnny' followed by zero to two digits.

```bash
user-scanner -u "johnny[0-9]{0-2}"
```

--------------------------------

### Install User Scanner

Source: https://context7.com/kaifcodec/user-scanner/llms.txt

Installs the user-scanner package using pip. It's recommended to use a virtual environment.

```bash
python -m venv .venv
source .venv/bin/activate          # Linux/macOS
# .venv\Scripts\Activate.ps1       # Windows PowerShell

pip install user-scanner
```

--------------------------------

### Install User Scanner

Source: https://github.com/kaifcodec/user-scanner/blob/main/README.md

Installs the user-scanner package using pip. Ensure pip is up-to-date before installation.

```bash
python -m pip install --upgrade pip
```

```bash
pip install user-scanner
```

--------------------------------

### CLI Example: Multiple separators

Source: https://github.com/kaifcodec/user-scanner/blob/main/docs/PATTERNS.md

Scan for usernames with different separators between name parts.

```bash
user-scanner -u "john[._-]doe"
```

--------------------------------

### Check Installed Version

Source: https://context7.com/kaifcodec/user-scanner/llms.txt

Display the currently installed version of the user-scanner tool.

```bash
# Check the installed version
user-scanner --version
```

--------------------------------

### Create and Activate Virtual Environment

Source: https://github.com/kaifcodec/user-scanner/blob/main/README.md

Recommended setup for isolating project dependencies. Use 'source' on Linux/macOS and '.venv\Scripts\Activate.ps1' on Windows PowerShell.

```bash
python -m venv .venv
```

```bash
# Linux / macOS
source .venv/bin/activate
```

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

--------------------------------

### Library Mode Email Scan Example

Source: https://github.com/kaifcodec/user-scanner/blob/main/README.md

Python example demonstrating library usage for email scanning with the 'user-scanner' package (version 1.2.0+). Shows how to get JSON or CSV output.

```python
import asyncio
from user_scanner.core import engine
from user_scanner.email_scan.shopping import etsy

async def main():
    # Engine detects 'email_scan' path -> returns "Registered" status
    result = await engine.check(etsy, "test@gmail.com")
    json_data = result.to_json() # returns JSON output
    csv_data = result.to_csv()   # returns CSV output
    print(json_data)             # prints the json data

asyncio.run(main())
```

--------------------------------

### CLI Example: Combining with other flags

Source: https://github.com/kaifcodec/user-scanner/blob/main/docs/PATTERNS.md

Combine pattern scanning with verbose output, request delays, and specific categories.

```bash
user-scanner -u "admin[0-9]{1-2}" -v --delay 0.5 -s 25
```

```bash
user-scanner -u "user[a-c]" -c social -s 50
```

--------------------------------

### CLI Example: Complex pattern with limited scans

Source: https://github.com/kaifcodec/user-scanner/blob/main/docs/PATTERNS.md

Scan a complex username pattern with a limited number of results.

```bash
user-scanner -u "user[a-z]{0-1}[0-9]{0-2}" -s 50
```

--------------------------------

### Performance Tip: Start with Limits

Source: https://github.com/kaifcodec/user-scanner/blob/main/docs/PATTERNS.md

Always use the -s flag to limit the number of permutations scanned, especially during initial testing.

```bash
user-scanner -u "pattern[0-9]{0-3}" -s 25
```

--------------------------------

### Status Validate Helper Example (Launchpad)

Source: https://github.com/kaifcodec/user-scanner/blob/main/CONTRIBUTING.md

Demonstrates using status_validate for sites where availability is determined by HTTP status codes. This is suitable for sites that reliably return 404 for missing profiles.

```python
from user_scanner.core.orchestrator import status_validate


def validate_launchpad(user):
    url = f"https://launchpad.net/~{user}"
    show_url = "https://launchpad.net"

    headers = {
        'User-Agent': "Mozilla/5.0 (Linux; Android 10; K) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/141.0.0.0 Mobile Safari/537.36",
        'Accept': "text/html,application/xhtml+xml,application/xml;q=0.9",
        'Accept-Encoding': "gzip, deflate, br, zstd",
        'Upgrade-Insecure-Requests': "1",
    }

    return status_validate(url, 404, 200, show_url=show_url, headers=headers, follow_redirects=True)
```

--------------------------------

### Check installed version

Source: https://context7.com/kaifcodec/user-scanner/llms.txt

Displays the currently installed version of the user-scanner tool.

```APIDOC
## Check the installed version
user-scanner --version
```

--------------------------------

### CLI Example: Email pattern variations

Source: https://github.com/kaifcodec/user-scanner/blob/main/docs/PATTERNS.md

Scan for email addresses with case variations and separators in the local part.

```bash
user-scanner -e "[jJ]ohn[_.]doe@example.com"
```

--------------------------------

### Upgrade to latest release

Source: https://context7.com/kaifcodec/user-scanner/llms.txt

Initiates an upgrade process to install the latest available release of the user-scanner tool from PyPI.

```APIDOC
## Upgrade to the latest PyPI release
user-scanner -U
```

--------------------------------

### Character Set Examples

Source: https://github.com/kaifcodec/user-scanner/blob/main/docs/PATTERNS.md

Define character sets using square brackets. Each character within the brackets creates a separate variation.

```plaintext
john[abc]         → "johna", "johnb", "johnc"
user[0-9]         → "user0", "user1", ..., "user9"
test[a-zA-Z]      → "testa", "testb", ..., "testZ"
site[_.-]         → "site_", "site.", "site-"
```

--------------------------------

### Generic Validate Helper Example (GitHub)

Source: https://github.com/kaifcodec/user-scanner/blob/main/CONTRIBUTING.md

Demonstrates using generic_validate for sites requiring complex logic or response body parsing. Includes defining a processor function to inspect the response.

```python
from user_scanner.core.orchestrator import generic_validate, Result

def validate_github(user: str) -> Result:
    """
    Example of a 'generic_validate' module.
    Use this when the site requires complex logic or response body parsing.
    """
    url = f"https://github.com/signup_check/username?value={user}"

    # Define show_url for clean output display
    show_url = "https://github.com"

    headers = {
        'User-Agent': "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/144.0.0.0 Safari/537.36",
        'referer': "https://github.com/signup",
        'accept-language': "en-US,en;q=0.9",
    }

    # Specific error message from GitHub for validation rules
    GITHUB_INVALID_MSG = (
        "Username may only contain alphanumeric characters or single hyphens, "
        "and cannot begin or end with a hyphen."
    )

    def process(response):
        """
        Internal processing function.
        Note: You don't need to pass 'url' here;
        generic_validate will attach it automatically from the kwargs.
        """
        if response.status_code == 200:
            return Result.available()

        if response.status_code == 422:
            if GITHUB_INVALID_MSG in response.text:
                return Result.error("Invalid format: alphanumeric and single hyphens only")

            return Result.taken()

        return Result.error(f"GitHub returned unexpected status: {response.status_code}")

    # Pass show_url into generic_validate so the Orchestrator
    # can attach it to the final Result object.
    return generic_validate(url, process, headers=headers, show_url=show_url)
```

--------------------------------

### Write a New Email Module for MyPlatform

Source: https://context7.com/kaifcodec/user-scanner/llms.txt

An example of an asynchronous email validation module for 'MyPlatform'. It uses `httpx` to make a POST request to a signup check endpoint and returns a `Result` indicating availability or if the email is taken.

```python
# user_scanner/email_scan/social/myplatform.py
import httpx
from user_scanner.core.result import Result

async def validate_myplatform(email: str) -> Result:
    """
    Check email registration on MyPlatform via their signup endpoint.
    No API key required. Rate limit: ~10 req/min per IP.
    """
    show_url = "https://myplatform.example.com"
    api_url = "https://myplatform.example.com/api/auth/check-email"

    try:
        async with httpx.AsyncClient(timeout=10.0, follow_redirects=True) as client:
            resp = await client.post(api_url, json={"email": email},
                                     headers={"Content-Type": "application/json"})

            if resp.status_code == 200:
                data = resp.json()
                if data.get("exists"):
                    return Result.taken(url=show_url)
                return Result.available(url=show_url)

            if resp.status_code == 429:
                return Result.error("Rate limited", url=show_url)

            return Result.error(f"[{resp.status_code}] Unexpected response", url=show_url)

    except httpx.TimeoutException:
        return Result.error("Request timed out", url=show_url)
    except Exception as exc:
        return Result.error(str(exc), url=show_url)
```

--------------------------------

### Length Control Examples

Source: https://github.com/kaifcodec/user-scanner/blob/main/docs/PATTERNS.md

Specify the length of expansions from a character set using curly braces. Supports exact lengths, ranges, or specific lengths.

```plaintext
john[a-z]{0-2}    → "john", "johna", "johnb", ..., "johnz", "johnaa", ..., "johnzz"
code[0-9]{2}      → "code00", "code01", ..., "code99"
user[a-c]{1;3}    → "usera", "userb", "userc", "useraa", ..., "userccc"
text[0-1]{1-3}    → "text0", "text1", "text00", "text01", "text10", "text11", ..., "text111"
```

--------------------------------

### Mastodon Email Validation Example

Source: https://github.com/kaifcodec/user-scanner/blob/main/CONTRIBUTING.md

Demonstrates an asynchronous email validation process for Mastodon, including CSRF token handling, request/response analysis, and error management. Use this pattern for other email-scan modules.

```python
import httpx
import re
from user_scanner.core.result import Result


async def _check(email: str) -> Result:
    """
    Internal helper that performs the multi-step signup probe.

    This function demonstrates how to handle CSRF tokens, custom error
    messages (like IP bans), and passing the target URL back to Results.
    """
    # The display URL used for output and error reporting
    show_url = "https://mastodon.social"

    signup_url = f"{show_url}/auth/sign_up"
    post_url = f"{show_url}/auth"

    headers = {
        "user-agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 "
                      "(KHTML, like Gecko) Chrome/143.0.0.0 Safari/537.36",
        "accept": "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,*/*;q=0.8",
        "referer": f"{show_url}/explore",
        "origin": show_url,
    }

    async with httpx.AsyncClient(http2=True, headers=headers, follow_redirects=True) as client:
        try:
            # 1. Access the signup page to retrieve required CSRF tokens
            initial_resp = await client.get(signup_url, timeout=15.0)
            if initial_resp.status_code not in [200, 302]:
                return Result.error(f"Failed to access signup page: {initial_resp.status_code}", url=show_url)

            # Extract the CSRF/authenticity token from the HTML
            token_match = re.search(r'name="csrf-token" content="([^"]+)"', initial_resp.text)
            if not token_match:
                return Result.error("Could not find authenticity token", url=show_url)

            csrf_token = token_match.group(1)

            # 2. Prepare the probe payload with the email we want to check
            payload = {
                "authenticity_token": csrf_token,
                "user[account_attributes][username]": "no3motions_robot_020102",
                "user[email]": email,
                "user[password]": "Theleftalone@me",
                "user[password_confirmation]": "Theleftalone@me",
                "user[agreement]": "1",
                "button": ""
            }

            response = await client.post(post_url, data=payload, timeout=15.0)
            res_text = response.text
            res_status = response.status_code

            # 3. Analyze the response to determine account status
            if "has already been taken" in res_text:
                return Result.taken(url=show_url)

            elif "registration attempt has been blocked" in res_text:
                return Result.error("Your IP has been flagged by Mastodon", url=show_url)

            elif res_status == 429:
                return Result.error("Rate limited; try using the '-d' flag", url=show_url)

            elif res_status in [200, 302]:
                # If no 'taken' message is found and status is OK/Redirect, it's available
                return Result.available(url=show_url)

            else:
                return Result.error("Unexpected response body", url=show_url)

        except Exception as exc:
            # Always pass the url=show_url even in exceptions for clear reporting
            return Result.error(str(exc), url=show_url)


async def validate_mastodon(email: str) -> Result:
    """
    Public validator used by the email mode.

    All email modules must export a 'validate_<name>' function that
    returns a Result object.
    """
    return await _check(email)

```

--------------------------------

### Library Mode Email Scan Output

Source: https://github.com/kaifcodec/user-scanner/blob/main/README.md

Example JSON output from the user-scanner library mode email scan, showing registration status and detailed user information.

```json
{
        "email": "test@gmail.com",
        "category": "Shopping",
        "site_name": "Etsy",
        "status": "Registered",
        "url": "https://www.etsy.com",
        "extra": "ID: 98832\nName: test123\nUsername: test123\nGender: private\nIs Seller: No\nHas Public Page: No\nStats: 0 followers | 0 following | 0 favorites\nPrivacy: Items are Public | Shops are Public\nJoined: 2010-09-19 09:34:06\nLast Profile Update: 2020-07-31 06:10:24\nAvatar: https://i.etsystatic.com/site-assets/images/avatars/default_avatar.png?width=400",
        "reason": ""
}
```

--------------------------------

### Get Random User-Agent String

Source: https://context7.com/kaifcodec/user-scanner/llms.txt

Retrieves a random user-agent string using `get_random_user_agent()`. This is useful for simulating different client browsers.

```python
# Random user-agent string
ua = get_random_user_agent()
# "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 ..."
```

--------------------------------

### Perform Full OSINT Scan with Python

Source: https://github.com/kaifcodec/user-scanner/blob/main/docs/USAGE.md

Initiates a scan for all available modules against a given email address and saves the results to a JSON file named 'report.json'. Ensure the 'user_scanner' library is installed.

```python
import asyncio
from user_scanner.core import engine
from user_scanner.core.formatter import into_json

async def main():
    email = "target@example.com"
    
    # Scans every module available in 'email_scan/'
    results = await engine.check_all(email, is_email=True)
    
    # Save results to a file
    with open("report.json", "w") as f:
        f.write(into_json(results))

asyncio.run(main())
```

--------------------------------

### Python Orchestrator Helpers for Module Authors

Source: https://context7.com/kaifcodec/user-scanner/llms.txt

Provides examples of using orchestrator helper functions like generic_validate for response-body inspection and status_validate for HTTP-status-based checks, intended for writing new user-scan validator modules.

```python
from user_scanner.core.orchestrator import generic_validate, status_validate
from user_scanner.core.result import Result
```

--------------------------------

### Scan Email Variations

Source: https://github.com/kaifcodec/user-scanner/blob/main/docs/PATTERNS.md

Use the -e flag to scan email variations. This example scans emails with a single character prefix.

```bash
user-scanner -e "user[a-z]{0-1}@example.com"
```

--------------------------------

### Selective Module Scan

Source: https://github.com/kaifcodec/user-scanner/blob/main/README.md

Scan specific categories or single modules using the '-c' for categories or '-m' for modules. Example scans only developer platforms or just GitHub.

```bash
user-scanner -u johndoe -c dev                # developer platforms only
```

```bash
user-scanner -e johndoe@gmail.com -m github   # only GitHub
```

--------------------------------

### Username Variations with Numbers

Source: https://github.com/kaifcodec/user-scanner/blob/main/docs/PATTERNS.md

Scan username variations that include numbers. This example generates variations from 'john' followed by 0 to 3 digits.

```bash
user-scanner -u "john[0-9]{0-3}"
```

--------------------------------

### Limiting Scan Results with -s Flag

Source: https://github.com/kaifcodec/user-scanner/blob/main/docs/PATTERNS.md

Limit the number of permutations checked using the -s flag. This example checks only 10 permutations.

```bash
user-scanner -u "john[0-9]{0-3}" -s 10
```

--------------------------------

### CLI: Proxy Support

Source: https://context7.com/kaifcodec/user-scanner/llms.txt

Loads a proxy list from a file for round-robin rotation during scans. Use --validate-proxies to pre-filter non-working proxies.

```bash
# proxies.txt (one proxy per line, http:// prefix optional):
# http://1.2.3.4:8080
# socks5://5.6.7.8:1080

# Example usage (assuming proxies.txt exists):
# user-scanner -u testuser --proxy-file proxies.txt
# user-scanner -u testuser --proxy-file proxies.txt --validate-proxies
```

--------------------------------

### Configuration Management with load_config and save_config_value

Source: https://context7.com/kaifcodec/user-scanner/llms.txt

Shows how to load and save configuration values using `load_config` and `save_config_value`. The configuration is stored in a JSON file and can be overridden via an environment variable.

```python
# --- Config ---
config = load_config()              # reads user_scanner/config.json
# {"auto_update_status": True, "auto_hudson_prompt": True}

save_config_value("auto_update_status", False)   # disable update checks
save_config_value("auto_hudson_prompt", False)   # disable Hudson prompt

# Override config path via env var
import os
os.environ["USER_SCANNER_CONFIG"] = "/custom/path/config.json"
config = load_config()
```

--------------------------------

### Validate Launchpad Username using HTTP Status

Source: https://context7.com/kaifcodec/user-scanner/llms.txt

Uses `status_validate` to check username availability on Launchpad based on HTTP status codes. 404 indicates availability, 200 indicates taken.

```python
def validate_launchpad(user: str) -> Result:
    url = f"https://launchpad.net/~{user}"
    headers = {"User-Agent": "Mozilla/5.0"}
    # 404 -> available, 200 -> taken
    return status_validate(url, available=404, taken=200,
                           show_url="https://launchpad.net",
                           headers=headers, follow_redirects=True)
```

--------------------------------

### Python Patterns Module for Username Generation

Source: https://context7.com/kaifcodec/user-scanner/llms.txt

Illustrates using the patterns module to count possible permutations from a pattern string, deterministically expand patterns into a sequence, and randomly sample variations without full expansion.

```python
from user_scanner.core.patterns import expand_patterns, expand_patterns_random, count_patterns

# --- count_patterns: O(n blocks), never expands the full set ---
total = count_patterns("john[0-9]{0-2}")
print(total)  # 111  (john, john0-john9, john00-john99)

total2 = count_patterns("[a-z]{5}")
print(total2)  # 11_881_376

# --- expand_patterns: deterministic iterator ---
for username in expand_patterns("john[a-c]"):
    print(username)
# johna
# johnb
# johnc

# Length control: {0-2} means 0, 1, or 2 characters
list(expand_patterns("x[01]{0-2}"))
# ['x', 'x0', 'x1', 'x00', 'x01', 'x10', 'x11']

# Escaped literal brackets
list(expand_patterns(r"hello\[world\]"))
# ['hello[world]']

# --- expand_patterns_random: reservoir-sampled shuffle ---
# Get up to 10 shuffled variations without loading all into memory
from itertools import islice
sample = list(islice(expand_patterns_random("john[0-9]{0-3}", capacity=1000), 10))
print(sample)
# ['john57', 'john3', 'john812', 'john', 'john24', ...]
```

--------------------------------

### Validate proxies and scan

Source: https://context7.com/kaifcodec/user-scanner/llms.txt

First validates the proxies listed in a file by testing them against google.com, then proceeds with the scan using only the working proxies.

```APIDOC
## Validate proxies first (tests each against google.com), then scan
user-scanner -u johndoe -P proxies.txt --validate-proxies
```

--------------------------------

### Allow Loud Modules

Source: https://context7.com/kaifcodec/user-scanner/llms.txt

Enable modules that might trigger password-reset emails or other sensitive notifications. Use with caution.

```bash
# Allow "loud" modules (those that may trigger password-reset emails)
user-scanner -e johndoe@gmail.com --allow-loud
```

--------------------------------

### CLI: Bulk Scan from File

Source: https://context7.com/kaifcodec/user-scanner/llms.txt

Scans multiple email addresses or usernames listed in a plain text file. Supports category and other filtering flags.

```bash
# emails.txt content:
# alice@example.com
# bob@example.com

user-scanner -ef emails.txt

# usernames.txt content:
# johndoe
# janedoe

user-scanner -uf usernames.txt

# Combine with category filtering
user-scanner -uf usernames.txt -c social --only-found
```

--------------------------------

### CLI: Filter Scan by Category or Module

Source: https://context7.com/kaifcodec/user-scanner/llms.txt

Limits a scan to a specific category (e.g., 'social', 'dev') or a single module by name. Use -lu and -le to list available username and email modules, respectively.

```bash
# Scan only developer platforms for a username
user-scanner -u johndoe -c dev

# Scan only the GitHub module for an email
user-scanner -e johndoe@gmail.com -m github

# List all available username modules
user-scanner -lu

# List all available email modules
user-scanner -le
```

--------------------------------

### Python Result Object Constructors and Methods

Source: https://context7.com/kaifcodec/user-scanner/llms.txt

Demonstrates creating Result objects using factory methods, updating them with metadata, comparing statuses, and serializing them to JSON or CSV. Also shows rebuilding a Result from its numeric status.

```python
from user_scanner.core.result import Result, Status

# Factory constructors
r_taken     = Result.taken()                          # Found / Registered
r_available = Result.available()                      # Not Found / Not Registered
r_error     = Result.error("Connection timeout")      # Error with reason
r_skipped   = Result.skipped()                        # Loud module skipped

# Attach metadata (chainable)
r_taken.update(site_name="Github", username="johndoe", category="Dev",
               url="https://github.com", is_email=False)

# Status comparison
assert r_taken == Status.TAKEN
assert r_taken.is_found()                              # True
assert r_available == Status.AVAILABLE
assert r_error.to_number() == 2                        # 0=TAKEN, 1=AVAILABLE, 2=ERROR

# Serialize
print(r_taken.to_json())
# {"username": "johndoe", "category": "Dev", "site_name": "Github",
#  "status": "Found", "url": "https://github.com", "extra": "", "reason": ""}

print(r_taken.to_csv())
# johndoe,Dev,Github,Found,https://github.com,,

d = r_taken.as_dict()  # dict with is_email key included
d2 = r_taken.to_dict() # clean export dict, username -> email if is_email=True

# Rebuild from integer
r2 = Result.from_number(0)   # Status.TAKEN
r3 = Result.from_number(1)   # Status.AVAILABLE
```

--------------------------------

### Adding Custom Platform Modules

Source: https://context7.com/kaifcodec/user-scanner/llms.txt

Extend User Scanner by adding custom platform modules. Place a single Python file in the appropriate `email_scan/<category>/` or `user_scan/<category>/` folder and export one `validate_<name>` function. No registration or configuration is required.

```python
# Example structure for a custom module:
# email_scan/social_media/my_new_platform.py

def validate_my_new_platform(email):
    # ... implementation ...
    return True # or False, or platform-specific result
```

--------------------------------

### ProxyManager for Proxy Rotation and Validation

Source: https://context7.com/kaifcodec/user-scanner/llms.txt

Demonstrates the usage of `ProxyManager` for thread-safe proxy rotation and `validate_proxies` for checking proxy working status. Proxies can be loaded from a file.

```python
from user_scanner.core.helpers import (
    ProxyManager, validate_proxies, set_proxy_manager, get_proxy,
    load_config, save_config_value, get_random_user_agent,
)

# --- ProxyManager ---
pm = ProxyManager("proxies.txt")   # lines like "1.2.3.4:8080" or "socks5://..."
print(pm.count())                   # 5
print(pm.get_next_proxy())          # "http://1.2.3.4:8080"  (round-robin)
print(pm.get_random_proxy())        # random pick

# Validate before use (parallel, default 50 workers)
working = validate_proxies(pm.proxies, timeout=5, max_workers=50)
print(f"{len(working)} / {pm.count()} proxies are working")

# Set globally so all orchestrator requests use it
set_proxy_manager("proxies.txt")
proxy = get_proxy()                 # returns next proxy from global manager
```

--------------------------------

### Performance Tip: Add Delays Between Requests

Source: https://github.com/kaifcodec/user-scanner/blob/main/docs/PATTERNS.md

Use the --delay flag to introduce pauses between requests, helping to avoid rate limiting.

```bash
user-scanner -u "test[0-9]{1-2}" --delay 1.0
```

--------------------------------

### Validate Proxies Before Scanning

Source: https://context7.com/kaifcodec/user-scanner/llms.txt

This command first validates the proxies in the provided list by testing them against google.com, then proceeds with the scan using only the working proxies. This helps ensure the scan uses reliable connections.

```bash
user-scanner -u johndoe -P proxies.txt --validate-proxies
```

--------------------------------

### Performance Tip: Combine with Other Filters

Source: https://github.com/kaifcodec/user-scanner/blob/main/docs/PATTERNS.md

Narrow the scope of your scan by combining pattern matching with other flags like -c (category) or -m (module).

```bash
user-scanner -u "user[a-z]{0-1}" -c social -s 50
```

--------------------------------

### Scan with Proxy Rotation

Source: https://context7.com/kaifcodec/user-scanner/llms.txt

Use this command to scan targets using a list of proxies for rotation. Ensure your proxy list is correctly formatted.

```bash
user-scanner -u johndoe -P proxies.txt
```

--------------------------------

### Programmatic Integration with User Scanner

Source: https://context7.com/kaifcodec/user-scanner/llms.txt

Use these async functions for programmatic integration. They return typed Result objects. Ensure proper async context for execution.

```python
from user_scanner import engine

# Example usage (within an async function):
# result = await engine.check("example@domain.com")
# result_category = await engine.check_category("example", "social_media")
# result_all = await engine.check_all("example_username")
```

--------------------------------

### Upgrade to Latest PyPI Release

Source: https://context7.com/kaifcodec/user-scanner/llms.txt

Update the user-scanner tool to the latest version available on PyPI.

```bash
# Upgrade to the latest PyPI release
user-scanner -U
```

--------------------------------

### Basic Username and Email Scan

Source: https://github.com/kaifcodec/user-scanner/blob/main/README.md

Scan a single email or username across all available platforms. Use '-e' for email and '-u' for username.

```bash
user-scanner -e johndoe@gmail.com   # single email scanning 
```

```bash
user-scanner -u johndoe             # single username scanning 
```

--------------------------------

### engine.check_all()

Source: https://context7.com/kaifcodec/user-scanner/llms.txt

Performs a comprehensive scan of a target across all available platforms. This is the most exhaustive scanning function available.

```APIDOC
## engine.check_all()

### Description
Asynchronously scans a target across all supported platforms. This function provides the broadest possible overview of a target's online presence.

### Method
`async def check_all(target: str, pattern_filter: Optional[List[str]] = None, generate_patterns: bool = False, proxy_rotation: bool = False, verbose_urls: bool = False, hudson_rock_integration: bool = False) -> Result`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
import asyncio
from user_scanner import engine

async def main():
    result = await engine.check_all('another_example@email.com')
    print(result)

asyncio.run(main())
```

### Response
#### Success Response (Result Object)
- **result** (Result) - A typed object containing the scan results from all platforms.

#### Response Example
```json
{
  "success": true,
  "message": "Scan completed for all modules.",
  "data": {
    "email_address": "another_example@email.com",
    "platforms_found": [
      {
        "name": "LinkedIn",
        "url": "https://www.linkedin.com/in/another_example",
        "category": "social"
      },
      {
        "name": "GitHub",
        "url": "https://github.com/another_example",
        "category": "developer"
      }
    ]
  }
}
```
```

--------------------------------

### Validate Proxies with User Scanner

Source: https://github.com/kaifcodec/user-scanner/blob/main/README.md

Use this command to validate a list of proxies before scanning. It filters out non-working proxies and saves the working ones to a new file for subsequent use.

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

--------------------------------

### Skip NSFW/adult site modules

Source: https://context7.com/kaifcodec/user-scanner/llms.txt

Configures the scanner to completely ignore and skip any modules related to NSFW or adult content websites.

```APIDOC
## Skip NSFW/adult site modules entirely
user-scanner -u johndoe --no-nsfw
```

--------------------------------

### Asynchronously Scan All Modules (Python)

Source: https://context7.com/kaifcodec/user-scanner/llms.txt

Performs a full asynchronous OSINT scan across all available modules and categories for a given email or username. This is equivalent to running the CLI without specific module or category flags. Results can be filtered and saved.

```python
import asyncio
from user_scanner.core import engine
from user_scanner.core.formatter import into_json

async def main():
    # Full email OSINT scan
    results = await engine.check_all("target@example.com", is_email=True)

    # Full username scan
    user_results = await engine.check_all("johndoe", is_email=False)

    # Filter to only hits
    hits = [r for r in results if r.is_found()]
    print(f"Registered on {len(hits)} platforms")

    # Save full report
    with open("full_report.json", "w") as f:
        f.write(into_json(results))

asyncio.run(main())
```

--------------------------------

### CLI: Username Permutation Patterns

Source: https://context7.com/kaifcodec/user-scanner/llms.txt

Generates and scans username or email variations using patterns like character sets, ranges, and length controls. Use -s to limit the number of permutations scanned.

```bash
# Scans "johna", "johnb", "johnc"
user-scanner -u "john[a-c]"

# Scans "john", "john0"–"john9", "john00"–"john99" (up to 100 by default)
user-scanner -u "john[0-9]{0-2}"

# Limit to the first 25 permutations
user-scanner -u "john[0-9]{0-3}" -s 25

# Case-variation scan limited to social platforms
user-scanner -u "[jJ]ohn[0-9]{0-2}" -c social -s 50

# Underscore / dot separator variations
user-scanner -u "john[._-]doe"

# Email variations
user-scanner -e "user[a-z]{0-1}@example.com"
```

--------------------------------

### Multiple Name Parts with Case Variations

Source: https://github.com/kaifcodec/user-scanner/blob/main/docs/PATTERNS.md

Generate usernames with mixed case and numbers. This pattern scans for 'john' or 'John' followed by 0 to 2 digits.

```bash
user-scanner -u "[jJ]ohn[0-9]{0-2}"
```

--------------------------------

### Allow 'loud' modules

Source: https://context7.com/kaifcodec/user-scanner/llms.txt

Enables the execution of 'loud' modules, which are those that might trigger automated responses like password-reset emails from target services.

```APIDOC
## Allow "loud" modules (those that may trigger password-reset emails)
user-scanner -e johndoe@gmail.com --allow-loud
```

--------------------------------

### Python Formatter Utilities for Result Lists

Source: https://context7.com/kaifcodec/user-scanner/llms.txt

Shows how to convert a list of Result objects into JSON strings, CSV strings with headers, or a raw list of dictionaries using the formatter module. Useful for downstream processing.

```python
from user_scanner.core.formatter import into_json, into_csv, get_json_data
from user_scanner.core.result import Result, Status

results = [
    Result.taken().update(site_name="Reddit", username="johndoe",
                          category="Social", url="https://reddit.com"),
    Result.available().update(site_name="Bluesky", username="johndoe",
                              category="Social", url="https://bsky.social"),
    Result.error("Timeout").update(site_name="Tiktok", username="johndoe",
                                   category="Social", url="https://tiktok.com"),
]

# JSON array string (pretty-printed)
json_str = into_json(results)
print(json_str)
# [
#     {"username": "johndoe", "category": "Social", "site_name": "Reddit",
#      "status": "Found", "url": "https://reddit.com", "extra": "", "reason": ""},
#     ...
# ]

# CSV string with header row
csv_str = into_csv(results)
print(csv_str)
# username,category,site_name,status,url,extra,reason
# johndoe,Social,Reddit,Found,https://reddit.com,,
# johndoe,Social,Bluesky,Not Found,https://bsky.social,,

# Raw list of dicts (useful for feeding into a database or custom API)
data = get_json_data(results)
assert isinstance(data[0], dict)
assert data[0]["status"] == "Found"
```

--------------------------------

### Scan with proxy rotation

Source: https://context7.com/kaifcodec/user-scanner/llms.txt

Initiates a scan using a list of proxies for rotation. This is useful for avoiding IP-based rate limiting.

```APIDOC
## Scan with proxy rotation
user-scanner -u johndoe -P proxies.txt
```

--------------------------------

### Basic Username Scanning

Source: https://github.com/kaifcodec/user-scanner/blob/main/docs/PATTERNS.md

Use the -u flag to scan username variations. The pattern `john[a-c]` will scan 'johna', 'johnb', and 'johnc'.

```bash
user-scanner -u "john[a-c]"
```

--------------------------------

### Asynchronously Scan Category (Python)

Source: https://context7.com/kaifcodec/user-scanner/llms.txt

Performs an asynchronous scan across all modules within a specified category (e.g., 'social', 'dev') for either email or username. Results are returned as a list of `Result` objects and can be serialized.

```python
import asyncio
from user_scanner.core import engine
from user_scanner.core.formatter import into_json, into_csv

async def main():
    # Username scan across all social platforms
    results = await engine.check_category("social", "johndoe123", is_email=False)

    # Email scan across all dev platforms
    email_results = await engine.check_category("dev", "target@example.com", is_email=True)

    # Serialize the list
    print(into_json(results))
    # Write CSV to file
    with open("social_scan.csv", "w") as f:
        f.write(into_csv(results))

asyncio.run(main())
```

--------------------------------

### Bulk Email and Username Scanning

Source: https://github.com/kaifcodec/user-scanner/blob/main/README.md

Scan multiple emails or usernames from a file, with one entry per line. Can be combined with category or module flags.

```bash
user-scanner -ef emails.txt     # bulk email scan
```

```bash
user-scanner -uf usernames.txt  # bulk username scan
```

--------------------------------

### CLI: Scan Single Username

Source: https://context7.com/kaifcodec/user-scanner/llms.txt

Scans a single username across all username platforms. Use --only-found to display only platforms where the username was found.

```bash
# Full scan
user-scanner -u johndoe

# Show only platforms where the username was found
user-scanner -u johndoe --only-found
```

--------------------------------

### Scan a Specific Category of Usernames

Source: https://github.com/kaifcodec/user-scanner/blob/main/docs/USAGE.md

Scans all modules within a specified category (e.g., 'social') for a given username. Use is_email=False to specify the category folder. Results are formatted into a JSON array.

```python
import asyncio
from user_scanner.core import engine
from user_scanner.core.formatter import into_json

async def main():
    target = "johndoe123"
    
    # Scans everything inside 'user_scan/social/'
    # Use is_email=False to tell the engine where to look for the category folder
    results = await engine.check_category("social", target, is_email=False)
    
    # 'into_json' wraps the results into a valid JSON array []
    print(into_json(results))

asyncio.run(main())
```

--------------------------------

### CLI: Output Scan Results to File

Source: https://context7.com/kaifcodec/user-scanner/llms.txt

Exports scan results to JSON or CSV files. Repeated writes to the same JSON file merge results.

```bash
# Save results as JSON
user-scanner -u johndoe -f json -o results.json

# Save results as CSV
user-scanner -e johndoe@gmail.com -f csv -o results.csv
```

--------------------------------

### Asynchronously Check Single Module Scan (Python)

Source: https://context7.com/kaifcodec/user-scanner/llms.txt

Asynchronously checks a single email or username against a specific platform module using the `engine.check()` function. The result can be serialized into JSON, CSV, or a Python dictionary.

```python
import asyncio
from user_scanner.core import engine
from user_scanner.email_scan.shopping import etsy

async def main():
    result = await engine.check(etsy, "test@gmail.com")

    # Serialization options
    print(result.to_json())    # formatted JSON string
    print(result.to_csv())     # CSV row string
    print(result.as_dict())    # Python dict including is_email flag
    print(result.to_dict())    # clean dict (renames 'username' -> 'email')

asyncio.run(main())
```

--------------------------------

### Check Username for Infostealer Exposure

Source: https://context7.com/kaifcodec/user-scanner/llms.txt

Query Hudson Rock's OSINT API to check if a username is associated with infostealer malware logs. Consent may be requested on the first run.

```bash
# Check username for infostealer exposure
user-scanner -u johndoe --hudson
```

--------------------------------

### Add Delay Between Requests

Source: https://context7.com/kaifcodec/user-scanner/llms.txt

Introduce a delay between requests to avoid rate limiting by target sites. Adjust the duration as needed.

```bash
# Add a 1.5-second delay between requests (avoid rate limiting)
user-scanner -u johndoe --delay 1.5
```

--------------------------------

### engine.check()

Source: https://context7.com/kaifcodec/user-scanner/llms.txt

Scans a single target (email address or username) across multiple platforms to trace digital footprints or verify identity. Supports various options like category filtering, proxy rotation, and result export.

```APIDOC
## engine.check()

### Description
Asynchronously scans a single target (email address or username) across a wide range of platforms. This function is a core part of the User Scanner's OSINT capabilities, allowing users to discover a person's digital presence or check username availability.

### Method
`async def check(target: str, module_filter: Optional[List[str]] = None, pattern_filter: Optional[List[str]] = None, generate_patterns: bool = False, proxy_rotation: bool = False, verbose_urls: bool = False, hudson_rock_integration: bool = False) -> Result`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
import asyncio
from user_scanner import engine

async def main():
    result = await engine.check('example@email.com', module_filter=['social'], generate_patterns=True)
    print(result)

asyncio.run(main())
```

### Response
#### Success Response (Result Object)
- **result** (Result) - A typed object containing the scan results, including found platforms, potential matches, and other relevant data.

#### Response Example
```json
{
  "success": true,
  "message": "Scan completed successfully.",
  "data": {
    "email_address": "example@email.com",
    "platforms_found": [
      {
        "name": "Facebook",
        "url": "https://www.facebook.com/example",
        "category": "social"
      }
    ],
    "username_variations_generated": []
  }
}
```
```

--------------------------------

### Underscore and Dot Variations

Source: https://github.com/kaifcodec/user-scanner/blob/main/docs/PATTERNS.md

Scan usernames that include special separators like underscore or dot. This pattern searches for 'user' followed by either '_' or '.' and then 'name'.

```bash
user-scanner -u "user[_.]name"
```

--------------------------------

### Check Email for Infostealer Exposure

Source: https://context7.com/kaifcodec/user-scanner/llms.txt

Query Hudson Rock's OSINT API to check if an email address is associated with infostealer malware logs. The first run may prompt for consent to persist preferences.

```bash
# Check email for infostealer exposure
user-scanner -e johndoe@gmail.com --hudson
```

--------------------------------

### Scan Single Username with GitHub Module

Source: https://github.com/kaifcodec/user-scanner/blob/main/docs/USAGE.md

Scans a single username using the GitHub module. The engine detects 'user_scan' path and sets result status accordingly.

```python
import asyncio
from user_scanner.core import engine
from user_scanner.user_scan.dev import github

async def main():
    # Engine detects 'user_scan' path -> Result status: "Not Found" / "Found" / "Error"
    result = await engine.check(github, "johndoe123")
    
    print(result.to_json())

asyncio.run(main())
```

--------------------------------

### Skip NSFW Modules

Source: https://context7.com/kaifcodec/user-scanner/llms.txt

Use this flag to exclude modules that scan NSFW or adult websites from the scan results. This is useful for reducing irrelevant or sensitive data.

```bash
# Skip NSFW/adult site modules entirely
user-scanner -u johndoe --no-nsfw
```

--------------------------------

### Verbose Mode Scan

Source: https://github.com/kaifcodec/user-scanner/blob/main/README.md

Use the '-v' flag to display the URLs of the sites being checked during the scan. Useful for debugging or detailed tracking.

```bash
user-scanner -v -e johndoe@gmail.com -c dev
```

--------------------------------

### Check Username or Email Exposure with --hudson

Source: https://github.com/kaifcodec/user-scanner/blob/main/README.md

Utilize the --hudson flag to determine if a username or email has been exposed in infostealer malware logs. This is useful for security research and awareness.

```bash
user-scanner -e johndoe@gmail.com --hudson   # for email check
```

```bash
user-scanner -u johndoe --hudson             # for username check
```

--------------------------------

### Scan Multiple Variations with Case Differences

Source: https://github.com/kaifcodec/user-scanner/blob/main/docs/PATTERNS.md

Combine character ranges and case variations within a single pattern for comprehensive scanning.

```bash
user-scanner -u "[jJ]ohn[0-9]{1-2}"
```

--------------------------------

### CLI: Scan Single Email

Source: https://context7.com/kaifcodec/user-scanner/llms.txt

Performs a full scan of a single email address across all email-integrated platforms. Use -v for verbose output showing checked URLs.

```bash
# Full scan of all categories
user-scanner -e johndoe@gmail.com

# Verbose mode: shows the URL checked alongside each result
user-scanner -v -e johndoe@gmail.com
```

--------------------------------

### engine.check_category()

Source: https://context7.com/kaifcodec/user-scanner/llms.txt

Scans a target across platforms within a specified category. Useful for focusing OSINT efforts on particular types of online services.

```APIDOC
## engine.check_category()

### Description
Asynchronously scans a target across platforms belonging to a specific category. This allows for more targeted investigations by focusing on a subset of platforms, such as 'social' or 'ecommerce'.

### Method
`async def check_category(target: str, category: str, pattern_filter: Optional[List[str]] = None, generate_patterns: bool = False, proxy_rotation: bool = False, verbose_urls: bool = False, hudson_rock_integration: bool = False) -> Result`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
import asyncio
from user_scanner import engine

async def main():
    result = await engine.check_category('example_username', 'social')
    print(result)

asyncio.run(main())
```

### Response
#### Success Response (Result Object)
- **result** (Result) - A typed object containing the scan results for the specified category.

#### Response Example
```json
{
  "success": true,
  "message": "Scan completed for category 'social'.",
  "data": {
    "username": "example_username",
    "platforms_found": [
      {
        "name": "Twitter",
        "url": "https://twitter.com/example_username",
        "category": "social"
      }
    ]
  }
}
```
```

--------------------------------

### Generating Username Variations

Source: https://context7.com/kaifcodec/user-scanner/llms.txt

The patterns module can be used independently to generate username variations for purposes like account enumeration prevention or availability checks.

```python
from user_scanner import patterns

# Example usage:
# variations = patterns.generate("base_username")
```

--------------------------------

### patterns.generate_variations()

Source: https://context7.com/kaifcodec/user-scanner/llms.txt

Generates username variations based on provided patterns. This can be used for account enumeration prevention or availability checks.

```APIDOC
## patterns.generate_variations()

### Description
Generates a list of potential username variations based on a base username and a set of predefined or custom patterns. This is useful for checking username availability across platforms or for security-related tasks like preventing account enumeration.

### Method
`def generate_variations(username: str, patterns: Optional[List[str]] = None) -> List[str]`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
from user_scanner import patterns

username = "johndoe"
# Using default patterns if none are provided
variations = patterns.generate_variations(username)
print(variations)

# Using custom patterns
custom_patterns = ["{{username}}123", "{{username}}_dev"]
custom_variations = patterns.generate_variations(username, patterns=custom_patterns)
print(custom_variations)
```

### Response
#### Success Response (List of Strings)
- **variations** (List[str]) - A list of generated username strings.

#### Response Example
```json
[
  "johndoe1",
  "johndoe_",
  "1johndoe",
  "_johndoe",
  "johndoe123",
  "johndoe_dev"
]
```
```

--------------------------------

### Check username for infostealer exposure

Source: https://context7.com/kaifcodec/user-scanner/llms.txt

Queries the Hudson Rock OSINT API to check if a given username is associated with any infostealer malware logs. This operation may prompt for consent on the first run.

```APIDOC
## Check username for infostealer exposure
user-scanner -u johndoe --hudson
```