wgprobe
Userspace WireGuard endpoint verification.
A Rust CLI and library for userspace WireGuard handshake, ping, and DNS verification, with Python bindings and NordVPN endpoint discovery.
brew tap scotthaleen/wgprobe https://github.com/scotthaleen/wgprobebrew install scotthaleen/wgprobe/wgprobe
wgprobe tests one WireGuard peer through one short-lived userspace session. Every run attempts an authenticated handshake; optional IPv4 ping and DNS checks use the same UDP socket and BoringTun session. The process exits without leaving a tunnel, route, or background session behind.
A confirmed handshake applies only to the tested identity, server key, and endpoint. An optional ping or DNS result confirms only that packet exchange, while an unconfirmed result means no valid response arrived before the deadline and remains inconclusive rather than proving that the endpoint is invalid.
The provider-neutral CLI and Rust library are the foundation. The Python package exposes typed synchronous bindings to the same engine. nordprobe is a separate workflow that exchanges a Nord access token for the account’s WireGuard private key, lists locations from Nord’s public inventory, checks candidate servers with that key, and exports a configuration for a confirmed endpoint.
Version 0.1.1 is available through Homebrew on macOS and Linux, as x86-64 and ARM64 Linux release binaries, and as Python 3.10+ ABI3 wheels. WireGuard configurations and private-key files contain secrets; restrict their permissions and keep them out of version control, shell arguments, and logs.
Probe behavior and evidence contracts.
One explicit probe
Test one identity, server key, and endpoint through one short-lived userspace WireGuard session.
No host reconfiguration
Runs through one UDP socket and BoringTun session without creating a TUN interface, installing routes, or requiring administrator access.
Evidence by phase
Separate endpoint resolution, socket, handshake, keepalive, ping, and DNS results instead of collapsing silence into failure.
Automation surfaces
Exposes human output, compact schema-versioned JSON, a Rust API, and typed synchronous Python 3.10+ bindings.
Bounded secret handling
Zeroize secret-bearing buffers where controlled, reject unsafe secret paths, and exclude private and preshared keys from reports.
Bounded execution
Applies phase timeouts and a whole-run deadline, performs no retries, and caps outstanding resolver work.
Execution model.
- 01
Provide identity
Use a one-peer WireGuard configuration or regular private-key file; keep key material out of arguments and logs.
- 02
Probe
Attempt an authenticated handshake and optionally send IPv4 ping and DNS checks through the same session.
- 03
Read evidence
Distinguish confirmed authentication, confirmed data exchange, inconclusive silence, and local errors.
- 04
Extend
Automate through compact JSON, the Rust API, or typed synchronous Python bindings.
nordprobe: automated Nord endpoint checks
nordprobe was built for the case where Nord advertises many WireGuard servers but connecting to them is unreliable. It retrieves the account's WireGuard private key through an explicit access-token exchange, lists countries and cities from Nord's public inventory, and tests a bounded set of candidate endpoints instead of requiring manual server-by-server checks.
Account key retrieval
Accepts a Nord access token at a hidden prompt, calls the service-credentials API, extracts the WireGuard private key, and writes a new mode-0600 file without printing either secret.
Public location inventory
Fetches Nord's unauthenticated server inventory, validates WireGuard records, and exposes country and city selection without sending the account token to the inventory API.
Candidate verification
Uses the retrieved private key to probe a bounded, paced server set, stops at the confirmation goal, and exports configurations only for endpoints that authenticate.
brew install scotthaleen/wgprobe/nordprobeSetup requires a Nord account and an access token. Run nordprobe key fetch --output <path> for the explicit credential exchange. Discovery then uses Nord's public inventory and the retrieved WireGuard private key. nordprobe is independent and is not affiliated with or endorsed by Nord Security.