ProxyDoctor

Test your proxy. Find the leaks. Fix the problem.

Built with AI assistance — GitHub Copilot, OpenCode, GPT 5.5, and Gemini Pro.

What is ProxyDoctor?

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.

Install

# 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

Quick Start

# 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.json

Web GUI

proxydoctor-server
# Open http://localhost:8080

Checks

Every check tells you what it tests and what service it uses.

Built-in Checks

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

Plugin Checks

Check	What it does	Service / Method
route_trace	Traces network hops with country flags	System traceroute/tracepath + ipapi.co for geolocation

Plugins

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

Local Proxy Usage

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:8081

Proxy Formats

socks5://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)

API

# 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"}'

Development

# 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

File Structure

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

Contributing

• Report a Bug
• Request a Feature
• Good First Issues

License

GPL-3.0