ovpn-checker

🛡️ Honest OpenVPN endpoint benchmarker & config optimizer

Test your .ovpn files, find the fastest working OpenVPN server, and emit a safe, optimized config — without lying to you about what was actually proven.

If this project saves you time, please ⭐ star the repo — it genuinely helps others find it.

---

📖 What is ovpn-checker?

ovpn-checker is a fast, dependency-free command-line tool that scans a folder full of OpenVPN .ovpn config files, probes every endpoint, and tells you which server is actually fast and reachable — then writes an optimized .ovpn config pointing at the best one.

Downloaded a pile of free .ovpn files and don't know which ones still work? Managing dozens of VPN profiles and tired of connecting one-by-one to find the fastest? This tool does it automatically, in parallel, and honestly.

The guiding principle: correctness and honesty over impressive-looking-but-wrong output. Most "VPN testers" happily print ✅ handshake validated after merely sending a single packet. ovpn-checker refuses to. It reports exactly what it proved — and no more — using explicit, stage-based confidence tiers.

---

✨ Features

• ⚡ Parallel benchmarking of every endpoint across all your .ovpn files.
• 🎯 Picks the fastest working server and writes an optimized config for it.
• 🔐 Real control-channel validation via the OpenVPN management interface (>STATE: / >REMOTE:) when the openvpn binary is present — timing derived from the server's actual first control-channel reply, not a process timeout.
• 📊 Honest statistics — median, p95, RTT standard deviation, and packet loss (clamped to a sane range; no fabricated "100% loss" narratives).
• 🪜 Stage-based confidence tiers — TUNNEL_UP › SERVER_RESPONSE › VPN_PORT_TCP › ICMP › DNS_ONLY, so a mere "host is reachable" is never sold as "the VPN works".
• 🧱 Sandboxed probing — untrusted configs are run through a default-deny allowlist; anything that executes code, writes files, or reads credentials is stripped.
• 🔒 Secure output — optimized configs may contain a private key, so they are written atomically with 0600 permissions, never through a symlink, and never overwrite an input.
• 🧩 A real OpenVPN parser — proper lexing (quotes, comments, backslash escapes matched to the official manual), connection-block scoping, and profile-fingerprint de-duplication.
• 🌐 IPv4 + IPv6 aware — tries every A and AAAA record in preference order; preserves IPv6 scope-id; respects udp4/udp6/tcp4/tcp6 address-family constraints.
• 🖥️ Cross-platform — Linux, macOS, Windows. Zero required dependencies (pure stdlib).

---

🎬 Demo

$ python ovpn_checker.py -d ./configs -o optimized.ovpn

====================================================================
  ovpn_checker 8.0 — honest OpenVPN endpoint benchmarker
====================================================================

📂 Found 1 .ovpn file(s).
🔗 Extracted 2 unique connection profile(s).

Probing with 3 attempt(s), 16 workers...

  sample | 8.8.8.8:443 [TCP]                       🟢    2.2ms  σ=0.1ms  [vpn_port_tcp_connect]
  sample | 1.1.1.1:1194 [UDP]                      🟢    1.4ms  σ=0.1ms  [other_port_tcp:8080]

📊 2 profile(s) | 2 host-reachable | 0 server-responded | 0 tunnel-up

Results by confidence tier (higher tier = more trustworthy):

── Tier: vpn-port-tcp (probable) (1) ──
   1. sample | 8.8.8.8:443 [TCP]                   🟢    2.2ms  score=    2.2

🚀 Selected: sample | 8.8.8.8:443 [TCP]
   tier=vpn-port-tcp (probable)  method=vpn_port_tcp_connect
   median=2.2ms  p95=2.2ms  σ=0.1ms  loss=0%

With the openvpn binary installed, endpoints reach the higher SERVER_RESPONSE and TUNNEL_UP tiers — a real handshake, timed from the server's own reply.

---

🚀 Installation

Zero dependencies required — clone and run:

git clone https://github.com/0xRadikal/ovpn-checker.git
cd ovpn-checker
python ovpn_checker.py --help

For real control-channel validation, install the OpenVPN client:

# Debian/Ubuntu
sudo apt-get install openvpn
# macOS
brew install openvpn
# Windows: install the official OpenVPN client (openvpn.exe on PATH)

# Point at a specific binary if needed:
export OPENVPN_BIN=/usr/sbin/openvpn

(Optional) install as a command with pip:

pip install -e .        # then just run:  ovpn-checker --help

---

⚡ Quickstart

# 1. Benchmark every .ovpn in a folder and write the best as optimized.ovpn
python ovpn_checker.py -d /path/to/ovpn/files -o optimized.ovpn

# 2. Just benchmark, don't write anything
python ovpn_checker.py -d ./configs --no-output

# 3. Machine-readable output for scripts/CI
python ovpn_checker.py -d ./configs --no-output --json

# 4. Try it right now on the bundled example
python ovpn_checker.py -d examples --no-output

Command-line options

Flag	Meaning
-d, --dir	Directory to scan for .ovpn files (default .)
-o, --output	Output config path (default optimized.ovpn, written 0600)
--probes N	Attempts per endpoint (default 4)
--workers N	Concurrent workers (default 16)
--tcp-timeout / --openvpn-timeout	Per-probe timeouts (seconds)
--minimum-tier	Lowest tier allowed to auto-write a config (default server-response)
--stddev-weight	Weight for RTT standard deviation in the score
--loss-penalty	ms penalty for 100% loss (count-independent)
--prefer-ipv6	Prefer AAAA over A
--no-output	Benchmark only, don't write a config
--json	Also print machine-readable JSON
--run / --yes	After building, offer to launch (opt-in; warns on dangerous directives)
--allow-exec-directives	Permit launching a config that contains code-executing directives

---

🪜 Confidence tiers (the honest part)

Higher = more trustworthy. Endpoints are ranked within a tier, never across non-comparable measurements (an OpenVPN handshake is never scored against a bare TCP connect).

Tier	Meaning	Proves VPN?
TUNNEL_UP	management STATE=CONNECTED — a full, usable tunnel came up	✅ yes
SERVER_RESPONSE	server replied on the control channel (AUTH+)	✅ server is real
VPN_PORT_TCP	TCP connect to the real VPN port (TCP proto only)	⚠️ probable
ICMP	host answered ping	❌ host only
OTHER_PORT_TCP	connect to 443/80/… (a host-path estimate)	❌ host only
DNS_ONLY	name resolved; nothing reachable proven	❌
UNREACHABLE	nothing worked	❌

If the selection is below the VPN-proven tiers, the tool prints ⚠️ This selection is NOT VPN-proven (host reachability only). — instead of pretending.

---

🧪 Testing

python -m pytest ovpn_checker/tests/ -q     # 53 tests
python -m pyflakes ovpn_checker             # lint, clean

CI runs the full suite on Python 3.8–3.13 across Linux, macOS, and Windows on every push.

---

🗂️ Project layout

ovpn_checker.py                  # entry point
ovpn_checker/
├── __init__.py                  # package overview / design rationale (v8.0.0)
├── model.py                     # Transport/Family, honest ConfidenceTier, ProbeResult, Remote
├── netutil.py                   # getaddrinfo resolution, TTL cache, all-address ordering, IPv6 scope
├── parser.py                    # OpenVPN-accurate lexer + scoped parser + profile dedup
├── measure.py                   # management-interface probe (STATE/REMOTE), sandboxed probe config
├── config_builder.py            # safe minimal optimizer, secure write, categorised security scan
├── cli.py                       # CLI, reporting, minimum-tier gate, opt-in launch
└── tests/                       # pytest suite (test_parser.py + test_measure.py)

---

🔒 Security

ovpn-checker handles untrusted .ovpn files and private keys, so security is a first-class design goal:

• Untrusted configs are probed through a default-deny allowlist (crypto + verification directives only). Code-executing / file-writing / credential-reading directives are dropped.
• Output configs are written atomically, 0600, never through a symlink.
• Launching a config is opt-in (--run) and warns loudly first.

See SECURITY.md for the full threat model and how to report a vulnerability.

---

🤔 Honest limitations

• openvpn binary required for real validation. Without it, the tool cannot reach the SERVER_RESPONSE / TUNNEL_UP tiers — it says so clearly and reports only transport-level reachability.
• ICMP requires the OS ping; on Linux raw ICMP may need cap_net_raw/root.
• tls-crypt-v2 and enterprise auth flows are delegated to openvpn, not re-implemented.
• Maturity: a solid, honest, well-tested technical-beta — not a world-class production product. It never labels results "enterprise-grade" without evidence.

---

🤝 Contributing

Contributions are welcome! Please read CONTRIBUTING.md — the one non-negotiable rule is never over-claim: new tiers/metrics must define exactly what they prove. Bug fixes should include a regression test.

---

📜 License

Released under the MIT License.

---

Found this useful? ⭐ Star ovpn-checker on GitHub to help others discover it.

_{Keywords: OpenVPN config checker · .ovpn tester · VPN server benchmark · fastest OpenVPN server picker · OpenVPN connectivity test · VPN latency tool · Python CLI}