Proxy Anonymity Detection

Relevant source files

The following files were used as context for generating this wiki page:

• proxybroker/checker.py
• proxybroker/proxy.py
• proxybroker/api.py
• proxybroker/judge.py
• tests/test_checker.py
• README.md

Proxy Anonymity Detection is the process by which ProxyBroker2 evaluates how effectively a proxy server hides the user's real IP address. The system classifies proxies into three distinct levels: Transparent, Anonymous, or High (Elite). This detection relies on "judge" servers—external endpoints that echo the headers and IP addresses they receive—to determine if a proxy leaks identifying information.

The detection logic is integrated into the Checker class, which orchestrates connections, protocol negotiations, and response analysis. This functionality ensures that users can filter proxies based on their required privacy level, particularly for HTTP and HTTPS protocols.

Sources: README.md, proxybroker/checker.py:30-65, proxybroker/proxy.py:127-142

Anonymity Levels

The system assigns an anonymity level to a proxy based on the presence of specific HTTP headers and whether the user's real IP address is visible in the judge's response.

Level	Description
Transparent	The proxy reveals the user's real external IP address in the request headers or body.
Anonymous	The proxy hides the user's real IP but reveals that a proxy is being used (e.g., via Via or Proxy-Connection headers).
High	The proxy hides both the user's real IP and the fact that a proxy is being used.

Sources: proxybroker/checker.py:317-340, tests/test_checker.py:90-110, proxybroker/proxy.py:127-142

Detection Architecture

The Checker utilizes Judge objects to perform detection. A judge is a server that returns a response containing the headers sent by the proxy and the IP address from which the connection originated.

Component Interaction Flow

The following diagram illustrates how the Checker interacts with the Proxy and Judge to determine anonymity.

The diagram shows the data flow from initialization by the Broker to the final anonymity classification stored in the Proxy object.

Sources: proxybroker/api.py:157-175, proxybroker/checker.py:166-215, proxybroker/checker.py:317-340

Detection Logic and Comparison

The core logic resides in the _get_anonymity_lvl function. It performs a set-based comparison between the host's known real external IP addresses and the IP addresses found in the judge's response body.

IPv6 Support and Canonicalization

The system supports both IPv4 and IPv6. To ensure accurate detection across different textual representations of IPv6 addresses (e.g., uppercase vs. lowercase, expanded vs. compressed), the system uses canonicalize_ip to normalize addresses before comparison.

• Dual-Stack Support: On dual-stack hosts, the system stores both v4 and v6 real external IPs in a frozenset. If any of these IPs appear in the judge's response, the proxy is marked as Transparent.
• Header Analysis: The system checks for the presence of "marks" (headers like via or proxy) defined by the Judge. If the count of these terms in the response exceeds the baseline defined by the judge, the proxy is classified as Anonymous.

Sources: proxybroker/checker.py:46-64, proxybroker/checker.py:317-340, CHANGELOG.md:21-65, tests/test_checker.py:112-140

Anonymity Classification Logic

def _get_anonymity_lvl(real_ext_ips, proxy, judge, content):
    content = content.lower()
    foundIP = get_all_ip(content)

    # Intersection of real IPs and IPs found in response
    if real_canonicals & foundIP:
        lvl = "Transparent"
    elif via: # Based on 'via' or 'proxy' header count
        lvl = "Anonymous"
    else:
        lvl = "High"
    return lvl

Sources: proxybroker/checker.py:317-340

Sequence of Validation

Before anonymity detection occurs, the Checker must verify that the proxy is functional.

The sequence diagram details the steps from initial connection to the final validity and anonymity check.

Sources: proxybroker/checker.py:195-215, proxybroker/checker.py:277-293, tests/test_checker.py:165-188

Configuration Parameters

The behavior of anonymity detection can be tuned through Broker and Checker initialization parameters.

Parameter	Type	Description
types	dict	Maps protocols to desired anonymity levels (e.g., {'HTTP': ['High', 'Anonymous']}).
strict	bool	If True, the proxy must satisfy all requested anonymity levels. If False, satisfying one is sufficient.
real_ext_ips	frozenset	The set of the host's actual external IP addresses used for leak detection.
judges	list	A list of URLs or Judge objects used to perform the checks.

Sources: proxybroker/checker.py:31-45, proxybroker/api.py:164-184, tests/test_checker.py:18-35

Summary

Proxy Anonymity Detection in ProxyBroker2 provides a technical mechanism to categorize proxy privacy levels. By comparing the content returned from judge servers against the host's canonicalized IP addresses and analyzing HTTP headers, the system distinguishes between proxies that leak identity, those that merely reveal proxy usage, and those that offer high anonymity. This multi-layered check, supporting both IPv4 and IPv6, is critical for the project's goal of providing production-ready proxy management.

Sources: README.md, proxybroker/checker.py:317-340