How user-scanner Handles Authentication: Browser Impersonation and Proxy Rotation Explained

user-scanner does not store credentials; instead, it authenticates HTTP requests by impersonating real browsers via curl_cffi, rotating proxies for anonymity, and optionally warming up sessions to collect clearance cookies before accessing protected endpoints.

The kaifcodec/user-scanner repository implements a sophisticated authentication handling system that prioritizes operational security and bot detection evasion. Rather than maintaining a credential database, the tool focuses on authenticating outbound requests through browser-like TLS signatures, intelligent proxy rotation, and session persistence. This architecture enables the scanner to interact with protected endpoints while respecting rate limits and avoiding detection mechanisms like Cloudflare and DataDome.

Browser Impersonation and Session Persistence

At the core of user-scanner's authentication strategy is the impersonate_request() function in user_scanner/core/impersonate.py (lines 19-33). This function creates a curl_cffi session that mimics a real browser's TLS fingerprint, making requests appear to originate from genuine Chrome or Firefox instances rather than Python scripts.

For sites protected by Cloudflare or DataDome, the scanner can perform a warm-up request to collect clearance cookies before executing the actual query. The session is cached per unique (impersonate, proxy) pair (lines 84-110), ensuring that subsequent requests to the same target reuse the authenticated session without repeating the warm-up overhead.

Proxy Management and Timeout Configuration

All network calls first respect the global timeout configured via the -t flag through get_global_timeout() in user_scanner/core/helpers.py (lines 15-20). When proxy rotation is enabled, the ProxyManager class (lines 102-132) provides thread-safe access to a pool of HTTP or SOCKS5 proxies.

The manager supports both round-robin (get_next_proxy()) and random (get_random_proxy()) selection strategies, allowing concurrent scans to share a proxy pool without contention. Proxies are injected into the browser-impersonating sessions, ensuring that authentication requests originate from diverse IP addresses.

Defensive Error Handling and Loud Module Protection

To prevent scan interruptions from authentication failures, the impersonate_validate() wrapper (lines 36-41 in user_scanner/core/impersonate.py) translates any network or authentication exceptions into structured Result.error() objects. This allows the engine in user_scanner/core/engine.py to continue processing remaining targets without crashing on individual endpoint failures.

For modules that require checking authenticated endpoints—such as verifying whether an email address is already registered—the scanner implements a loud module system. These validators are gated behind the --allow-loud flag, with the is_loud() helper function (lines 27-35 in user_scanner/core/helpers.py) controlling access. The command-line interface in user_scanner/cli/__main__.py explicitly warns users when these authentication-heavy validators are activated.

Practical Implementation Examples

Here are concrete implementations demonstrating the authentication handling:

# Example 1 – Use the impersonating request directly (e.g. inside a validator)

from user_scanner.core.impersonate import impersonate_request

resp = impersonate_request(
    "https://example.com/protected/profile",
    warmup_url="https://example.com",
    impersonate="chrome",
)

# `resp` is a curl_cffi.Response; you can inspect status_code, text, etc.

# Example 2 – Wrap a validator with impersonate_validate

from user_scanner.core.impersonate import impersonate_validate
from user_scanner.core.result import Result

def parse_profile(resp):
    return Result.taken(extra={"name": resp.json()["name"]})

# The wrapper handles warm-up, proxy, timeout and error conversion.

result = impersonate_validate(
    url="https://example.com/api/profile",
    func=parse_profile,
    warmup_url="https://example.com",
)

# Example 3 – Configure a proxy pool and run a scan with a custom timeout

from user_scanner.core.helpers import set_proxy_manager, set_global_timeout

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

# Subsequent calls to `impersonate_request` will automatically pick a proxy

# and respect the 10‑second timeout.

Summary

• No credential storage: user-scanner authenticates via HTTP session behavior rather than storing passwords or tokens.
• Browser impersonation: Uses curl_cffi in user_scanner/core/impersonate.py to mimic browser TLS signatures and evade bot detection.
• Session persistence: Caches authenticated sessions per (browser, proxy) pair to reuse clearance cookies across requests.
• Proxy rotation: Thread-safe ProxyManager in user_scanner/core/helpers.py supports round-robin and random proxy selection.
• Graceful degradation: impersonate_validate() converts exceptions to Result objects, preventing scan failures.
• Opt-in loud modules: Authentication-heavy validators require explicit --allow-loud flag activation.

Frequently Asked Questions

Does user-scanner store my login credentials?

No. According to the source code in kaifcodec/user-scanner, the tool does not implement any credential database or storage mechanism. Authentication is handled entirely at the HTTP transport layer through browser impersonation and session management.

How does user-scanner bypass Cloudflare and DataDome protection?

The scanner uses curl_cffi via the impersonate_request() function in user_scanner/core/impersonate.py to replicate the exact TLS fingerprint of real browsers like Chrome. It can also execute warm-up requests to obtain clearance cookies before accessing protected resources, making automated requests indistinguishable from legitimate browser traffic.

What is the purpose of the --allow-loud flag?

The --allow-loud flag enables validator modules that check authenticated endpoints, such as verifying email existence on registration pages. These modules are disabled by default to minimize the scanner's footprint and only run when explicitly permitted by the user through the CLI in user_scanner/cli/__main__.py.

Can I use custom proxies with user-scanner?

Yes. You can configure a custom proxy pool using set_proxy_manager() from user_scanner/core/helpers.py, passing a list of HTTP or SOCKS5 proxies. The ProxyManager class (lines 102-132) will then rotate through these proxies automatically during scan execution.

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