Skip to main content

TunnelScope blue compass and vortex logo

TunnelScope

Collect sender and receiver evidence when packet size affects delivery.

v0.9.4 alpha · Python 3.10+ · Install from PyPI · Release notes · MIT license

v0.9 adds Markdown evidence export. Watch the 30-second recorded evidence replay for the OpenVPN return-path example and report-sharing steps.

v0.9.4 keeps Markdown summaries readable and stops report values from becoming GitHub mentions, issue links or math.

v0.9.3 rejects non-probe sender inputs before writing correlation outputs, and retains nonzero local IPv6 receiver scope IDs.

v0.9.2 adds diagnosis input checks and Python 3.13 CI coverage.

v0.9.1 adds partial receiver-capture handling.

Small pings can succeed while larger traffic stalls. TunnelScope sends bounded UDP payloads to a cooperating receiver and keeps acknowledgements, explicit size errors, timeouts and optional Linux ICMP feedback. Join both endpoints' logs by probe ID and browse the evidence in an offline HTML report. With --sized-reply, a Linux or Windows receiver answers with replies of the probe's own size, so one run also tests the return direction.

tunnelscope show output: 64- and 1200-byte probes return same-sized replies; 1400-byte probes reach the receiver but their replies are lost or rejected

HTML view of the same run after joining the receiver log: each probe arrived; the 1400-byte replies were lost or rejected

Real output from the asymmetric return-path lab, recorded on 2026-11-05 in Ubuntu under WSL2 with v0.7.0. Return traffic crosses a 1280-byte link: 1400-byte probes arrive, but their same-sized replies do not come back, while an ordinary 24-byte ACK at 1400 bytes still does. The same lab also runs over IPv6 with the same result. The images are rebuilt from the checked-in report by scripts/build_v07_images.py. The v0.6 workflow replay is still available.

Quick start: join both endpoint logs

For native Windows PowerShell, use the Windows loopback guide.

On Linux or WSL2, create a virtual environment in an empty working directory:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install tunnelscope==0.9.4

In terminal 1, start the loopback receiver:

tunnelscope receive --max-packets 2 --output receiver.json

Activate the same environment in terminal 2. After the receiver prints Listening on 127.0.0.1:9471, run:

tunnelscope probe 127.0.0.1 --sizes 64,1200 --count 1 --output probe.json

The receiver exits after two probes. In either terminal, join the saved logs and generate the offline view:

tunnelscope correlate probe.json receiver.json --output correlation.json --html correlation.html
tunnelscope show correlation.json

Open correlation.html in a browser. A matching receiver entry confirms forward arrival, even if the sender saw no ACK. A timeout alone does not establish an MTU problem. No root access or network setup is needed for this loopback example. For two hosts, use the two-endpoint guide.

One Linux sender workflow

With a cooperating receiver already running on a controlled path:

tunnelscope diagnose PEER_IP --min 1200 --max 1400 --count 2 --output diagnosis.json

diagnose retains DF probes, the same sizes with source fragmentation permitted, and a bounded adaptive search. It writes JSON and HTML for one sender direction. After the receiver saves its capture, correlate can join all three runs in one report. The diagnose guide covers setup and interpretation.

Test the return direction

The receiver's 24-byte ACK shows that a payload arrived, not that the same size can travel back. With --sized-reply on both sides, the receiver answers with a reply of the probe's own size (never larger):

tunnelscope receive --bind B_IP --sized-reply --output receiver.json
tunnelscope probe B_IP --sizes 64,1200,1400 --count 2 --dont-fragment --sized-reply --output probe.json
tunnelscope correlate probe.json receiver.json --html correlation.html

The receiver side needs Linux (including WSL2) or Windows. search, compare-fragmentation and diagnose accept the same flag. Before posting reports in an issue, run tunnelscope sanitize. The sized-reply guide lists every field.

What the evidence establishes

Result Observation
acknowledged The chosen UDP payload arrived and a small ACK returned.
packet_too_large Linux reported an explicit size error; ICMP evidence may distinguish local and routed feedback.
timeout No matching ACK arrived; the cause remains inconclusive.
sized_reply_received With --sized-reply: the payload arrived and a reply of the same size returned.
receiver_observed_sized_reply_missing After correlate: the probe arrived and the receiver's socket accepted a same-sized reply; the sender recorded none before its deadline. The failure location remains unknown.
receiver_reply_send_unverified From v0.9.1: arrival was recorded, but the receiver's local send outcome is absent or unknown. A sent or rejected reply is not assumed.

Payload sizes include the 24-byte TunnelScope header. Small ACKs do not prove same-sized reverse delivery; use --sized-reply for that. An observed payload interval is not an independently measured end-to-end path MTU. ICMP feedback and receiver logs are unauthenticated. ping, tracepath, route inspection and packet captures remain useful alongside these observations.

Recorded validation

Environment Checked behavior Scope
Ubuntu ↔ Debian WireGuard VMs Both directions, receiver pairing and a 1252/1253-byte boundary Local tunnel MTU on a host-only link
Routed WireGuard lab Token-matched ICMP when visible; inconclusive timeouts when blocked Four namespaces on one kernel
Routed OpenVPN lab and return-path case Matched ICMP, blocked search and receiver-joined missing sized replies through TLS/TUN peers Controlled labs; three namespaces on one kernel, IPv4 UDP
Routed IPv6 feedback Matched Packet Too Big versus blocked-feedback timeouts, receiver pairing and inconclusive search Three namespaces on one kernel; runs in CI
Native Windows receiver from WSL2 / IPv6 follow-up Each family: 3/3 small ACKs, 6/6 sized replies and 8/8 diagnosis replies, with saved receiver evidence IPv4 and IPv6 link-local virtual paths; two kernels on one physical host; MTU 1500 interfaces
Windows oversized replies 1600-byte probes arrive and small ACKs return; same-sized Windows replies fail locally with WSAEMSGSIZE (10040), over both families Same host/guest virtual paths; existing MTU 1500; no network-policy changes
Cross-node Kubernetes/Calico 6/6 baseline deliveries per direction; policy block and recovery Two Docker-based Minikube nodes, IPv4 IP-in-IP
Asymmetric return-path lab 1400-byte probes arrive while same-sized replies are lost or rejected; a small ACK still returns Three namespaces on one kernel, IPv4 and IPv6; runs in CI

These are controlled validations. Physical multi-host paths, production VPN incidents and other Kubernetes CNI modes need separate evidence. If you can test such a path, the field report guide shows how to collect and share a sanitized report.

Guides and contributing

Contributions welcome. Pick an open starter task or help with a field report. CI runs on Linux and Windows with Python 3.10, 3.12 and 3.13. Read CONTRIBUTING.md; share synthetic or sanitized reports. Run unprivileged checks with python -m unittest discover -s tests -v. Privileged Linux labs require explicit opt-in as described in the usage reference.

Metadata

Release files for tunnelscope 0.9.4

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for tunnelscope 0.9.4
File Size Uploaded Provenance Actions
tunnelscope-0.9.4.tar.gz 1.7 MB With provenance Details for tunnelscope-0.9.4.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for tunnelscope 0.9.4
File Interpreter ABI Platform Actions
tunnelscope-0.9.4-py3-none-any.whl Python 3 none any Details for tunnelscope-0.9.4-py3-none-any.whl

Total release size: 1.9 MB

Release files / tunnelscope-0.9.4.tar.gz

Download URL tunnelscope-0.9.4.tar.gz
Size 1.7 MB
Tags Source
SHA-256 checksum
How to use checksums
246ed1345a52488a7a69caf89b8c8fe862161fa9a5252ae04fd232c924e920ed
BLAKE2b-256 checksum
How to use checksums
c0b6df7023779efa59bd12c63dfca10cfed77aa71fb6793c1a4490321035f172
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 8, 2026.

Transparency log

Release files / tunnelscope-0.9.4-py3-none-any.whl

Download URL tunnelscope-0.9.4-py3-none-any.whl
Size 220.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
a64326ac46123116597768f658766468b797a2d761bf2a6243e35f31b27ec969
BLAKE2b-256 checksum
How to use checksums
555ef1515ae552b1940247fe4d85b75cfde93c28332243bbf519f41532e8a8a8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 8, 2026.

Transparency log

Security for tunnelscope 0.9.4

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for tunnelscope-0.9.4.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 8, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page