ProxyDoctor
Native Python read-only VPS diagnostics for Ubuntu 22.04 and newer. Python 3.10+; no third-party runtime dependencies. Ubuntu 22.04/24.04 are the current acceptance targets; other versions need separate testing. No automatic sudo, installation, SSH/firewall changes or fetching/executing remote scripts.
Run
Extract the source package and run from its directory:
bash proxydoctor.sh
bash proxydoctor.sh suite --lang en
bash proxydoctor.sh suite --offline --lang en
python3 -m proxydoctor check --lang en --port 8388 --json --output check.json
Downloading/cloning does not execute code. The default suite contacts external
services and streams compact colored rows. check defaults to local reads.
Ordinary users can run it; missing privileges remain unknown. Report files stay
local, do not overwrite existing files and redact IPs. Review before sharing;
redaction is not an anonymity guarantee. --show-ip displays egress IP in the
terminal only. Routes display actual hop IPs in the terminal; exports mask them.
Four modules
| Module | Terminal output | Limits |
|---|---|---|
| Resources/preflight | OS, architecture, CPU/model/count, kernel, memory, disk, SHA-256 sample; route/DNS config, target port, SSH guard/config, local/cloud firewall status | Visible resources may differ from quotas; SHA-256 is not a general CPU benchmark; local reads cannot establish cloud ingress |
| Network/IP | Real DNS/TCP probes; ownership/ASN/location/type, provider flags/scores, coverage and disagreements | AAAA answers do not prove IPv6 connectivity; provider scores are separate observations, not safety certification |
| Route | Linux IPv4/IPv6 UDP error queue, 30 hops by default, up to 64; IP, latency, estimated location | NAT/filtering or silent routers can prevent completion; geolocation is approximate |
| Media | Ten independent service adapters, repeat confirmation, catalog/metadata evidence and explicit unknown reasons | No paid account/DRM playback verification; public offers/catalogs do not prove full unlock |
Suite JSON schema_version=2 includes local checks, DNS/TCP, per-source bandwidth,
IP observations/provenance/conflicts, route hops and media probe evidence.
Green indicates acquired data/local success, red known warnings/restrictions,
yellow unknown/skipped/insufficient evidence. --color auto|always|never and
NO_COLOR are supported. Use check --json for detailed local evidence.
sshd -T defaults may differ from running instances/Match rules. Future repair
features still require separate SSH safeguards.
Bandwidth
bash proxydoctor.sh bandwidth --lang en
bash proxydoctor.sh bandwidth --lang en --source ovh-rbx --rounds 3 --sample-mib 4
bash proxydoctor.sh bandwidth --lang en --source hetzner-fsn --sample-mib 1
bash proxydoctor.sh suite --lang en --bandwidth-source cloudflare
| ID | Source/node label | Download | Upload | Default |
|---|---|---|---|---|
| cloudflare | Cloudflare / Anycast | Yes | Yes | Yes |
| ovh-rbx | OVHcloud / FR Roubaix | Yes | No | Yes |
| hetzner-fsn | Hetzner / DE Falkenstein | Yes | No | No; slow on current test network |
Excluded 128 KiB warmup per supported direction; 3–8 measured rounds of 1–20 MiB. Default requested benchmark payload is at most 36.375 MiB, excluding protocol and other module traffic. Medians/ranges/success counts stay separate per source. Short samples (<1s), missing rounds and high variation stay yellow. Wall-time HTTPS throughput includes connection setup and cannot verify advertised capacity. Static files require exact HTTP 206 ranges; ignored Range responses are closed without reading the full body, never falling back to a full-file download. Unsupported upload is skipped, not counted as failure. Bandwidth JSON schema=2.
IP sources and keys
bash proxydoctor.sh ipquality --lang en --show-ip --json-output ip.json
bash proxydoctor.sh ipquality --lang en --no-enrichment
bash proxydoctor.sh suite --lang en --no-ip-enrichment
Defaults: ipapi.is, proxycheck.io and IP2Location. On an ipapi.is transport failure,
ipify can provide an egress address. Subsequent sources query that exact address;
mismatched responses are rejected. These services see the source address and the
additional sources receive the selected egress IP. Disable extra sources with
--no-ip-enrichment or all suite networking with --offline.
Seventeen core fields cover ownership/ASN, location/timezone, type/network abuse share and datacenter/proxy/VPN/Tor/recent-abuse/mobile/satellite/anycast/bogon flags. Per-source observations and field provenance are retained. Conflicting booleans become unknown with disagreement evidence. IP2Location's limited free-plan proxy flag is kept separate, not converted into a broad VPN guarantee. proxycheck.io risk/confidence and AbuseIPDB scores are not averaged. Network abuse share is not a single-IP maliciousness probability.
Keyless limits currently include 100 queries/day for proxycheck.io and 1000/day for IP2Location, subject to provider rules. No automatic quota retries. Anonymous ipapi.is has limited fields; optional keys provide extended fields/AbuseIPDB reports. Enter locally without echoing; never send keys to chat or commit them:
read -rsp 'ipapi.is API Key: ' PROXYDOCTOR_IPAPI_KEY
export PROXYDOCTOR_IPAPI_KEY
printf '\n'
read -rsp 'AbuseIPDB API Key: ' PROXYDOCTOR_ABUSEIPDB_KEY
export PROXYDOCTOR_ABUSEIPDB_KEY
printf '\n'
bash proxydoctor.sh ipquality --lang en
ipapi.is keys travel in HTTPS POST JSON; AbuseIPDB keys use headers, not URLs or reports. Missing fields remain unknown. Complete coverage means defined fields, not every database or a security certification. Zero reports do not guarantee safety. Observed API egress/family may differ from media connections.
Route and media
bash proxydoctor.sh suite --lang en --max-hops 64 --route-target 1.1.1.1
bash proxydoctor.sh suite --lang en --route-target 2606:4700:4700::1111 --no-geo
bash proxydoctor.sh media --lang en --json-output media.json
ipwho.is geolocation is cached per run; private/reserved hops are never queried. Media covers Netflix, Disney+, YouTube Premium, Spotify, Prime Video, Max, Apple TV+, Hulu, BBC iPlayer and Paramount+. Clear regional messages and visible priced offers require repeat agreement. Netflix uses structured catalog metadata; BBC also checks public test-channel metadata. No media segments/paid content are fetched and signed media URLs are not retained. BBC's channel result is scoped to that channel. HTTP 200/403 or catalog/offer visibility never proves playback.
Exit codes
check: 0=no known warning/failure (unknowns may remain), 1=findings, 2=usage/export
error. Online suite/bandwidth/ipquality/media: 1 also covers incomplete/unknown/
variable measurements or unverified playback. Offline 0 means local execution
completed, not online success. Media intentionally leaves playback untested and
returns 1. Ctrl+C returns 130 without changing system settings.
Install and contribute
Source runs directly. Install the supplied wheel into a local virtual environment:
python3 -m venv .venv
.venv/bin/python -m pip install /path/to/proxydoctor-0.5.0-py3-none-any.whl
.venv/bin/proxydoctor suite --offline --lang en
If Ubuntu lacks venv support, install its matching OS component separately;
ProxyDoctor never installs it automatically. Development: install pytest and run
python -m pytest -q. An Actions workflow is supplied; remote CI is not claimed
before repository publication. See CONTRIBUTING.md and SECURITY.md.
Stage 1 and scope
This iteration targets code plus Ubuntu 22.04/24.04 VM acceptance as selected by the user; consult the delivered acceptance records for actual results. Overseas VPS tests, real-key extended data, paid-account playback and other Ubuntu releases remain separately unverified. Later stages cover sing-box installation, Karing protocol validation, repair previews/backups/rollback, Web UI and secure subscription transport. No public plaintext subscription server or automatic SSH/firewall changes.
License and acknowledgements
Original code is MIT. Thanks to ECS, NodeQuality, NetQuality/IPQuality, NextTrace and RegionRestrictionCheck for feature/presentation references. No upstream script source/databases are bundled by the default implementation. See THIRD_PARTY_NOTICES.md. Explicit local-script adapters are opt-in; external behavior/output may not be read-only or redacted.
Official data references: Cloudflare, OVHcloud, Hetzner, ipapi.is, proxycheck.io, IP2Location, AbuseIPDB, ipwho.is, ipify. Netflix VPN guidance explains catalog restrictions.