Test your proxy. Find the leaks. Fix the problem.
Built with AI assistance — GitHub Copilot, OpenCode, GPT 5.5, and Gemini Pro.
ProxyDoctor is a CLI tool that runs network diagnostics through your proxy and tells you exactly what's broken.
- You're behind a proxy/VPN and sites don't load — is it DNS? TLS? The proxy itself?
- You think your proxy is private but your IP is leaking — through DNS, IPv6, or WebRTC?
- You want to use the proxy after testing it — browse, curl, wget through it
ProxyDoctor answers these questions in seconds, then exposes the proxy as a local forward proxy so you can use it immediately.
v0.5.0 — 9 checks, plugin system, web GUI, Homebrew cask.
# go install
go install github.com/francomano/proxydoctor/cmd/cli@latest
alias proxydoctor="$(go env GOPATH)/bin/cli"# Homebrew
brew install francomano/proxydoctor/proxydoctor
# Binary download# https://github.com/francomano/ProxyDoctor/releases# Run all checks — direct connection
proxydoctor diagnose --url https://example.com
# Run all checks — through a proxy
proxydoctor diagnose --url https://example.com --proxy socks5://user:pass@1.2.3.4:1080
# Compare direct vs proxied
proxydoctor diagnose --url https://example.com --proxy socks5://1.2.3.4:1080 --compare
# Run specific checks only
proxydoctor diagnose --url https://example.com --checks public_ip,dns_leak,webrtc_leak
# Export as JSON
proxydoctor diagnose --url https://example.com --export json --output report.jsonproxydoctor-server
# Open http://localhost:8080Every check tells you what it tests and what service it uses.
| Check | What it does | Service / Method |
|---|---|---|
public_ip | Detects your public IP address | ipify.org, icanhazip.com, ifconfig.me |
dns_resolve | Resolves the target hostname to IPs | System DNS (via Go net package) |
tls_certificate | Validates TLS cert (expiry, issuer, cipher) | Direct TLS handshake with the target host |
port_connectivity | Tests TCP connectivity to common ports | TCP connect to ports 80, 443, 8080, 8443 |
ipv6_leak | Detects if IPv6 bypasses the proxy | api6.ipify.org, ipv6.icanhazip.com, v6.ident.me |
dns_leak | Compares DNS through proxy vs direct path | System DNS on both adapter paths |
webrtc_leak | Detects if STUN/ICE could leak the real IP | STUN probes to Google, Twilio, and Viagenie servers via UDP |
header_leak | Detects if forwarded headers leak the real client IP or internal network metadata | httpbin.org/headers, httpbin.org/ip |
| Check | What it does | Service / Method |
|---|---|---|
route_trace | Traces network hops with country flags | System traceroute/tracepath + ipapi.co for geolocation |
Load plugins with --plugins:
# Route trace
proxydoctor diagnose --url https://example.com --plugins route_trace
# MCP server (AI assistant integration)
proxydoctor --plugins mcp_server
# Local forward proxy (browse through the tested proxy)
proxydoctor --plugins local_proxy --proxy socks5://1.2.3.4:1080| Plugin | Type | What it does |
|---|---|---|
route_trace | check | Adds route tracing with country annotations |
mcp_server | standalone | Exposes diagnose/compare as MCP tools on :9090 |
local_proxy | standalone | Exposes the proxy on 127.0.0.1:8081 for browser/curl/wget |
Once the local proxy is running:
curl -x http://127.0.0.1:8081 https://example.com
# Or set browser HTTP/HTTPS proxy to 127.0.0.1:8081socks5://user:pass@host:port # with auth
socks5://host:port # no auth
socks4://host:port # SOCKS4/4a
http://host:port # HTTP proxy
host:port --proxy-type socks5 # bare host + type
host --proxy-type http # bare host (default port)
# List checks
curl http://localhost:8080/api/checks
# Diagnose
curl -X POST http://localhost:8080/api/diagnose \
-H "Content-Type: application/json" \
-d '{"url":"https://example.com","proxy":"socks5://1.2.3.4:1080","proxy_type":"socks5"}'# Local proxy
curl -X POST http://localhost:8080/api/local-proxy/start \
-H "Content-Type: application/json" \
-d '{"proxy":"socks5://1.2.3.4:1080","proxy_type":"socks5"}'# Setup
git clone https://github.com/francomano/proxydoctor
cd ProxyDoctor
./setup.sh
# Test
go test ./...
# Build
go build ./cmd/cli && go build ./cmd/server- CODEBASE_GUIDE.md — where to add checks, adapters, CLI features
- CONTRIBUTING.md — PR process, code style, test patterns
cmd/cli/ CLI (diagnose, list-checks, version)
cmd/server/ HTTP server + web GUI
core/engine/ Orchestration engine + dependency DAG
core/check/ Checker interface + result types
core/checks/ Built-in checks (public_ip, dns_resolve, tls_cert, port_scan, ipv6_leak, dns_leak, webrtc_leak, header_leak)
core/adapters/ Proxy implementations (Direct, HTTP, HTTPS, SOCKS4, SOCKS5)
core/plugin/ Plugin system interfaces
core/plugins/ Plugin implementations (route_trace, mcp_server, local_proxy)
internal/testproxy/ Hermetic proxy fixtures for integration tests
GPL-3.0