wgprobe Python package

The optional wgprobe package provides typed synchronous bindings to the generic Rust probe. It has no provider API or account coupling and uses Python's stable ABI for Python 3.10 and newer.

Warning: Configuration and private-key files contain secrets. Restrict their permissions, keep them out of version control, and never put key values in source, logs, command-line arguments, or environment variables.

Install

Install a Python 3.10+ wheel from PyPI:

python -m pip install wgprobe

Build from Source

Requirements are Python 3.10 or newer, a Rust toolchain, and a PEP 517 wheel builder. Build from the workspace root without installing Maturin globally:

uv run --isolated --with 'maturin>=1.14,<2' \
  maturin build --release --out dist

Install the exact platform-specific wheel emitted under dist/:

WHEEL='dist/wgprobe-0.1.0-<python-abi-platform>.whl'
python -m pip install "$WHEEL"

Usage

Probe a one-peer configuration:

from wgprobe import probe_file

report = probe_file(
    "path/to/test.conf",
    ping=("10.5.0.1",),
    resolve=("example.com",),
)
print(report.verdict)
for phase in report.phases:
    print(phase.phase, phase.status, phase.detail)

The configuration must contain one peer. Data checks require IPv4 Interface.Address, matching peer AllowedIPs, and an IPv4 DNS server for DNS queries.

Probe explicit key and endpoint inputs:

from wgprobe import probe_key_file

report = probe_key_file(
    "path/to/private-key",
    "<server-public-key>",
    "<server-host-or-ip>:51820",
    address="10.5.0.2/32",
    allowed_ips=("0.0.0.0/0",),
    ping=("1.1.1.1",),
    resolve=("example.com",),
    dns_server="103.86.96.100",
)
print(report.verdict, report.resolved_endpoint)

Omit all data-check arguments for a handshake-only call. Raw-key data checks require address and at least one allowed_ips entry; DNS also requires dns_server.

For a provider-specific integration, see the editable examples/nord_find.py script:

uv run --with . examples/nord_find.py

It probes sequentially, tries each candidate once, and enforces six seconds between starts that share a server key. Progress goes to standard error; a confirmed result is compact JSON on standard output. Exit statuses are 0 for a confirmation, 1 for none, and 2 for inventory or configuration errors. The script has no cache or export; use native nordprobe find for those features.

API Contracts

The checked _wgprobe.pyi stub is the canonical function signature reference.

Verdicts and Errors

Reports use the stable verdict and phase-status names defined in the wgprobe evidence contract. A passed ping or DNS phase confirms only that exchange, not general connectivity.

Invalid files, keys, addresses, routes, DNS arguments, timeouts, and plans raise ConfigurationError before probing. Operational unconfirmed and local_error outcomes return reports for inspection.

Synchronous and Async Use

Calls are synchronous. Rust releases the global interpreter lock while reading and parsing secret files and while probing. Offload calls from an asyncio event loop:

import asyncio
from wgprobe import probe_file

report = await asyncio.to_thread(probe_file, "path/to/test.conf")

Cancelling the awaiting task does not cancel the Rust probe or an operating- system resolver call.

Limits and Security

The overall deadline caps phase timeouts. Shared probe and resolver behavior is documented in the core limits.

Secret files are read into zeroizing Rust buffers. Reports and representations contain the derived client public key but no private or preshared key. Treat reports as sensitive operational metadata.

Verify the Packaged Wheel

Cargo tests do not validate an installed extension. Set the exact wheel path emitted by Maturin, then run:

WHEEL='./dist/wgprobe-0.1.0-cp310-abi3-<platform>.whl'

uv run --isolated --with "$WHEEL" --with 'pytest>=9,<10' \
  pytest python/tests
uv run --isolated --with "$WHEEL" --with 'mypy>=1.19,<2' mypy
uv run --isolated --with "$WHEEL" --with 'ruff>=0.14,<1' ruff check .

Run Rust tests separately:

cargo test --workspace