The Checker & Judges
Relevant source files
The following files were used as context for generating this wiki page:
The Checker and Judge components form the validation engine of ProxyBroker2. The Checker coordinates the validation of discovered proxies by testing them against Judge servers to determine their operational status, protocol support, and anonymity levels.
Sources: proxybroker/checker.py, proxybroker/judge.py, CLAUDE.md:37-41
Overview of the Validation Pipeline
The validation process ensures that a proxy is not only reachable but also satisfies specific user-defined requirements such as anonymity level or geographic location.
The flow diagram above illustrates the step-by-step validation logic executed by the Checker.
Sources: proxybroker/checker.py:114-160, proxybroker/checker.py:192-234
The Judge Component
A Judge represents a remote server used to verify proxy functionality. It identifies the external IP address perceived by the server and detects headers inserted by the proxy.
Judge Types and Protocols
Judges are categorized by the protocols they support:
- HTTP: Standard web judges (e.g., httpbin.org, azenv.net).
- HTTPS: Judges supporting encrypted connections.
- SMTP: Specialized judges for
CONNECT:25support.
Sources: proxybroker/judge.py:16-25, proxybroker/judge.py:146-159
Verification Logic
Before a Judge validates a proxy, the Checker validates the Judge itself. A Judge is marked as working if it correctly echoes the host's real external IP address and a unique verification token.
The sequence diagram shows the self-verification process for a Judge server.
Sources: proxybroker/judge.py:73-143
The Checker Component
The Checker manages the concurrency and retry logic for proxy validation. It supports multiple protocols including HTTP, HTTPS, SOCKS4, SOCKS5, and CONNECT (ports 80 and 25).
Core Responsibilities
| Feature | Description |
|---|---|
| Protocol Negotiation | Uses specific negotiators to establish connections via SOCKS or CONNECT. |
| DNSBL Checking | Optionally checks if a proxy IP is listed in Domain Name System Blacklists. |
| Anonymity Detection | Classifies proxies as Transparent, Anonymous, or High Anonymity. |
| Retry Logic | Attempts validation up to a configured max_tries (default 3). |
Sources: proxybroker/checker.py:38-76, proxybroker/checker.py:162-234
Anonymity Level Classification
The system determines anonymity by comparing the host's real external IP address(es) against the data returned by the Judge.
- Transparent: The host's real IP address is visible in the judge's response.
- Anonymous: The real IP is hidden, but proxy-related headers (like
ViaorProxy-Connection) are present. - High (Elite): The real IP is hidden, and no proxy-related headers are detected.
Sources: proxybroker/checker.py:349-378, tests/test_checker.py:100-118
Technical Implementation Details
IPv6 Support
The validation engine uses RFC 5952 canonical forms for IP comparison. This ensures that different textual representations of the same IPv6 address (e.g., uppercase vs. lowercase) are correctly identified as a match during transparency checks.
def _get_anonymity_lvl(real_ext_ips, proxy, judge, content):
content = content.lower()
foundIP = get_all_ip(content)
# ... canonicalize IPs ...
if real_canonicals & foundIP:
lvl = "Transparent"
elif via:
lvl = "Anonymous"
else:
lvl = "High"
return lvl
Sources: proxybroker/checker.py:349-378, proxybroker/utils.py:104-115
Configuration Options
The Checker is initialized with several parameters that define its behavior:
| Parameter | Type | Default | Description |
|---|---|---|---|
max_tries | int | 3 | Number of attempts to check a proxy. |
timeout | int | 8 | Timeout in seconds for requests. |
verify_ssl | bool | False | Whether to verify SSL certificates of judges. |
strict | bool | False | If True, discards proxies that don't match exactly requested levels. |
real_ext_ips | set | None | Set of host IPs used for leak detection. |
Sources: proxybroker/checker.py:40-66, tests/test_checker.py:20-40
Conclusion
The Checker & Judges system provides a robust framework for real-time proxy validation. By leveraging multiple judge servers and performing deep header analysis, it accurately identifies the capabilities and privacy characteristics of discovered proxies while maintaining compatibility across IPv4 and IPv6 networks.