How to Configure user-scanner for Specific Network Environments: Proxy Setup and Validation

Configure user-scanner for specific network environments by supplying a proxy list via the --proxy-file CLI flag and optionally enabling --validate-proxies to filter dead servers before scanning, with all HTTP traffic automatically routing through the centralized ProxyManager defined in core/helpers.py.

The kaifcodec/user-scanner repository is built to operate seamlessly behind corporate firewalls, VPNs, and residential proxy pools. Whether you are conducting reconnaissance in a restricted network or distributing high-volume requests across rotating exit nodes, configuring user-scanner for specific network environments requires only a text file and two optional flags—no modifications to the source code are necessary.

Understanding the Proxy Architecture

At the core of user-scanner's networking layer sits the thread-safe ProxyManager class located in user_scanner/core/helpers.py. This utility handles loading proxy lists from disk, rotating through entries per request, and validating connectivity against remote endpoints. When you invoke the CLI with a proxy file, the entry point in user_scanner/__main__.py instantiates this manager and registers it globally via set_proxy_manager(), ensuring that subsequent calls to get_proxy() automatically retrieve the next available proxy for every HTTP request.

CLI Configuration for Network Environments

Specifying Proxy Lists with --proxy-file

The command-line interface exposes the --proxy-file <path> argument, parsed between lines 60-66 of __main__.py. This flag accepts a plain text file containing one proxy per line. The scheme is optional; entries without a protocol prefix default to http://.

Pre-Scan Validation using --validate-proxies

Enable the --validate-proxies flag to discard unreachable proxies before the scan initiates. According to lines 71-81 in helpers.py, the validate_proxies function performs asynchronous HTTP HEAD requests against http://gstatic.com/generate_204—a lightweight, no-content Google endpoint—to confirm liveness. Only responsive proxies are passed to set_proxy_manager(proxies=working_proxies) as implemented in lines 58-88 of __main__.py.

Implementation Details and Request Flow

Global Proxy Access in helpers.py

Once initialized, the ProxyManager instance is stored in a module-level _proxy_manager variable. The get_proxy() accessor (lines 82-90) retrieves the current proxy from this global state and is invoked uniformly across orchestrator.py, email_orchestrator.py, and impersonate.py, ensuring every outbound request is correctly tunneled without additional configuration.

HTTP Client Reuse in orchestrator.py

To optimize throughput, user_scanner/core/orchestrator.py defines a get_client() function (lines 233-245) that caches an httpx.Client instance per unique proxy value. This approach maintains persistent connection pools, respects the optional http2 flag, and eliminates the overhead of spawning new TLS handshakes for every request.

Integration with Email and Impersonation Modules

The proxy infrastructure is fully transparent to specialized subsystems. The impersonate_validate function in impersonate.py and the async workers in email_orchestrator.py both call get_proxy() to inject the current proxy into their respective transport layers, guaranteeing that username scans, email checks, and browser impersonation traffic all respect the same network configuration.

Practical Configuration Examples

Run a username scan through a residential proxy pool with full validation:

python -m user_scanner \
    --username johndoe \
    --proxy-file /path/to/proxies.txt \
    --validate-proxies \
    --concurrency 30 \
    --timeout 10

Execute an email scan using a pre-validated list to skip startup checks:

python -m user_scanner \
    --email example@example.com \
    --proxy-file /path/to/working_proxies.txt \
    --allow-loud

Integrate proxy configuration programmatically within a Python script:

from user_scanner.core.helpers import set_proxy_manager, get_proxy

# Load proxies directly from a Python list

proxies = ["http://1.2.3.4:8080", "socks5://5.6.7.8:1080"]
set_proxy_manager(proxies=proxies)

# Verify the active proxy

print("Current proxy:", get_proxy())

Summary

• Centralized Management: The ProxyManager in core/helpers.py provides thread-safe rotation and validation, exposed globally via set_proxy_manager() and get_proxy().
• CLI Simplicity: Supply --proxy-file to load a list and --validate-proxies to filter dead entries before scanning, as implemented in __main__.py.
• Zero-Code Integration: All request modules—including orchestrators and impersonation logic—automatically inherit proxy support without manual injection.
• Performance Optimization: get_client() in orchestrator.py caches httpx.Client instances per proxy, ensuring efficient connection reuse across concurrent workers.

Frequently Asked Questions

How do I format the proxy file for user-scanner?

Create a plain text file with one proxy per line. You may include the scheme (e.g., http://1.2.3.4:8080 or socks5://5.6.7.8:1080) or omit it—entries without a protocol default to http://. The ProxyManager parses this list during initialization in __main__.py and rotates through it sequentially.

What is the difference between using --validate-proxies and skipping validation?

When enabled, --validate-proxies triggers the validate_proxies function in helpers.py (lines 71-81) to perform asynchronous HEAD requests to http://gstatic.com/generate_204 before the scan begins. This filters out dead proxies, ensuring only responsive servers enter the rotation pool. Skipping this flag loads the file immediately, which reduces startup latency but risks connection failures if the list contains stale entries.

Can I use SOCKS5 proxies with user-scanner?

Yes. The proxy strings are passed directly to the underlying httpx client constructor. As demonstrated in the programmatic example, you can include socks5:// URLs in your proxy list. The get_client() function in orchestrator.py uses these full URLs as cache keys, ensuring proper client isolation across different proxy types and protocols.

How does user-scanner handle proxy rotation during scans?

The ProxyManager maintains an internal index that advances each time get_proxy() is invoked (lines 82-90 in helpers.py). Because every request-making helper calls this function to retrieve the current proxy, the tool automatically rotates through the list for each new connection. This mechanism is thread-safe and applies uniformly to username enumeration, email validation, and impersonation requests.

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