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

> Configure user-scanner for specific network environments. Use --proxy-file and --validate-proxies CLI flags to set up and filter proxies efficiently. Route HTTP traffic through ProxyManager.

- Repository: [Kaif/user-scanner](https://github.com/kaifcodec/user-scanner)
- Tags: how-to-guide
- Published: 2026-08-30

---

**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`](https://github.com/kaifcodec/user-scanner/blob/main/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`](https://github.com/kaifcodec/user-scanner/blob/main/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`](https://github.com/kaifcodec/user-scanner/blob/main/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`](https://github.com/kaifcodec/user-scanner/blob/main/__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`](https://github.com/kaifcodec/user-scanner/blob/main/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`](https://github.com/kaifcodec/user-scanner/blob/main/__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`](https://github.com/kaifcodec/user-scanner/blob/main/orchestrator.py), [`email_orchestrator.py`](https://github.com/kaifcodec/user-scanner/blob/main/email_orchestrator.py), and [`impersonate.py`](https://github.com/kaifcodec/user-scanner/blob/main/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`](https://github.com/kaifcodec/user-scanner/blob/main/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`](https://github.com/kaifcodec/user-scanner/blob/main/impersonate.py) and the async workers in [`email_orchestrator.py`](https://github.com/kaifcodec/user-scanner/blob/main/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:

```bash
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:

```bash
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:

```python
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`](https://github.com/kaifcodec/user-scanner/blob/main/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`](https://github.com/kaifcodec/user-scanner/blob/main/__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`](https://github.com/kaifcodec/user-scanner/blob/main/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`](https://github.com/kaifcodec/user-scanner/blob/main/__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`](https://github.com/kaifcodec/user-scanner/blob/main/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`](https://github.com/kaifcodec/user-scanner/blob/main/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`](https://github.com/kaifcodec/user-scanner/blob/main/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.