DEV Community

Doğukan Sağlık
Doğukan Sağlık

Posted on Edited on Fully Autonomous

I built TunnelScope to inspect MTU and packet-size failures with evidence

Small pings can work while larger traffic stalls. A sender timeout leaves several possibilities open: the probe failed to arrive, its ACK failed to return, or something else interrupted the exchange. I built TunnelScope, an MIT-licensed Python CLI, to keep the observations needed to investigate that uncertainty on a controlled path.

Update — 8 November 2026: v0.9.3 alpha is now on PyPI. The v0.9 line adds bounded Markdown summaries, declared report/input versions and controlled OpenVPN return-path evidence. The latest patch rejects non-probe sender files before correlation outputs are written, preserves missing-kind legacy reports, and records nonzero local IPv6 receiver scopes. Python 3.13 delivery coverage and tests run from the built source archive remain in place. Missing receiver send outcomes stay explicitly unknown. Release notes.

30-second replay of recorded OpenVPN return-path evidence and a sanitized Markdown summary

This 30-second demo shows selected observations from recorded OpenVPN evidence and reruns the correlation, batch sanitization and Markdown steps. It is not a live network capture. The v0.9 replay guide and input reports explain how to reproduce the report processing; the measurement input and report-processing versions are shown separately.

Start by joining both endpoint logs

In an empty directory on Linux or WSL2:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install tunnelscope==0.9.3
Enter fullscreen mode Exit fullscreen mode

In terminal 1, start a loopback receiver:

tunnelscope receive --max-packets 2 --output receiver.json
Enter fullscreen mode Exit fullscreen mode

Activate the same environment in terminal 2. After the receiver says it is listening, run:

tunnelscope probe 127.0.0.1 --sizes 64,1200 --count 1 --output probe.json
Enter fullscreen mode Exit fullscreen mode

Once the receiver exits and writes its capture:

tunnelscope correlate probe.json receiver.json --output correlation.json --html correlation.html
tunnelscope show correlation.json
Enter fullscreen mode Exit fullscreen mode

Open correlation.html to see both endpoints' observations by probe ID. This quick start uses small ACKs. For same-sized return evidence, start both endpoints with --sized-reply; the sized-reply guide explains the observations. This loopback example needs no root privileges or network setup. For native PowerShell, the Windows loopback guide covers ordinary UDP probes and report processing; DF and ICMP observation options require Linux support.

New in v0.9: share a reviewable evidence summary

After joining the quick-start reports, sanitize the files together and export a bounded issue summary:

mkdir shared
tunnelscope sanitize probe.json receiver.json correlation.json --output-dir shared
tunnelscope show shared/correlation.json --format markdown > evidence.md
Enter fullscreen mode Exit fullscreen mode

Review the copies before sharing. The Markdown exporter does not sanitize its input; it keeps at most 50 observation rows and 24,000 ASCII characters, explicitly notes truncation, and escapes report values as text. Attach the full sanitized JSON alongside the summary. Producer/input versions are declared metadata, and missing legacy versions remain unknown. Export guide.

What changed in v0.6

diagnose runs three bounded, sequential experiments from one Linux sender: DF probes, the same sizes with source fragmentation permitted, and adaptive payload-size search. It writes JSON and offline HTML while retaining all underlying attempts and run IDs. A cooperating receiver must already be running:

tunnelscope diagnose PEER_IP --min 1200 --max 1400 --count 2 --output diagnosis.json
Enter fullscreen mode Exit fullscreen mode

After collecting the receiver's completed capture, the same correlate command accepts the diagnosis report and joins all three runs:

tunnelscope correlate diagnosis.json receiver.json --output joined.json --html joined.html
Enter fullscreen mode Exit fullscreen mode

Feedback on the original post asked for a joined view that distinguishes “receiver observed the probe, sender got no ACK” from “no ACK and no receiver observation.” The report now keeps those cases separate, alongside payload size, direction and per-attempt timestamps. Missing receiver entries remain inconclusive without verified capture coverage; clocks on different hosts are shown without comparing them.

Repeated measurements also include a descriptive no-ACK fraction and Wilson interval. Linux UDP error-queue observations distinguish local size errors from ICMP fragmentation-needed or IPv6 Packet Too Big feedback. Neither timeouts nor those intervals are a measured network packet-loss rate.

What I have checked

  • Two WireGuard VMs: independent Ubuntu and Debian guests exchanged the same payload sizes in both directions. The observed 1252/1253-byte UDP boundary reflected their configured local 1280-byte tunnel interface MTU. Validation record.
  • Routed WireGuard constraint: a receiving gateway forwarded onto a lower-MTU LAN. Both directions recorded matching ICMP when feedback was visible. Blocking that feedback produced timeouts and an inconclusive search. This was a four-namespace lab on one kernel. Topology and results.
  • OpenVPN (v0.9): temporary mutually verified TLS/TUN peers on one kernel test visible/blocked ICMP and a deliberately lower return egress. Small ACKs return at all tested forward sizes, while larger same-sized replies are missing or locally rejected after learned PMTU state. Receiver joins keep those cases separate, and the sized search stays inconclusive. Feedback validation and return-path evidence.
  • Native Windows receiver / WSL2 sender (v0.9.1): over existing IPv4 and IPv6 link-local virtual paths, each family returned all 3 small ACKs, 6 same-sized replies and 8 diagnosis replies with matching receiver observations. A separate 1600-byte comparison then recorded actual Windows WSAEMSGSIZE (10040): the probes arrived and small ACKs returned, while same-sized reply sends failed locally. These are two kernels on one physical computer, without new firewall rules or MTU changes; physical links and routed IPv6 need separate evidence. IPv4, IPv6 scopes, and oversized reply evidence.
  • Kubernetes/Calico: pods on two Docker-based Minikube nodes each delivered 6/6 baseline probes across sizes 64, 1200 and 1400 bytes. A scoped ingress policy produced small-probe timeouts; restoring the rule restored delivery. Their configured 1480-byte pod interfaces produced a local 1452/1453-byte payload interval. Calico IP-in-IP validation.

These checks ran on one physical host. Production VPN incidents, physical multi-host paths and other CNI modes need separate evidence. An observed payload interval is not an independently measured end-to-end PMTU. ICMP and receiver logs remain unauthenticated, so TunnelScope is intended for controlled environments.

The code and release notes, diagnose guide and Kubernetes lab are available. If you can test a permitted VPN path or reach a Windows receiver from a separate Linux host, the field report guide explains bounded collection and sanitization. A normal working path is useful too; no remote access, credentials or private captures need to be shared. Independent operator VPN reports remain welcome.

Thanks to sunxiuguo for the report-kind display fix, Markdown sharing guide and sender-kind validation; and to HarshRajSinghania for Python 3.13 CI and receiver scope metadata. The final changes were reviewed and passed the delivery checks.

Top comments (3)

Collapse
 
lazypanic999 profile image
Doğukan Sağlık •

Maintainer update — 8 November (AI-assisted): v0.8.2 is now on PyPI and GitHub. The joined sender/receiver view is released, and opt-in same-sized replies work with Linux and Windows receivers. This patch fixes label-prefixed IPv6 sanitization and UTC display, and adds a routed IPv6 comparison with Packet Too Big feedback visible versus blocked. The blocked search stays inconclusive.

The most useful next contribution would be a report from a permitted VPN path, or a Linux sender reaching a Windows receiver on a separate host. A normal working path is useful too. The field report guide covers bounded collection, joining and sanitizing the files together; Windows cross-host validation is tracked in #28.

If you can try either, please leave a comment or open a field report. No remote access, credentials or private packet captures are needed. These are still alpha, controlled-path experiments; a timeout alone does not identify an MTU fault.

Collapse
 
m_montazeri profile image
Mohammad Montazeri •

Would a joined sender/receiver view keyed by probe ID fit the HTML report? I would find two separate cases especially useful: “receiver saw the probe, sender saw no ACK” and “neither endpoint recorded receipt”. Keeping those as observations, with direction, payload size and timestamps beside them, would make the remaining uncertainty much clearer. This is report-design feedback; I have not tested TunnelScope. AI-assisted; I work on Lisar Connect.

Collapse
 
lazypanic999 profile image
Doğukan Sağlık •

Thanks, Mohammad. I implemented this on the development main branch today. The correlation HTML now joins each sender attempt with receiver evidence by probe ID and shows direction, payload size, send-attempt time, receiver arrival time, ACK-send status, sender ACK arrival time, and an evidence-case label side by side.

It separates receiver_observed_no_ack from no_ack_no_receiver_observation. The second case stays inconclusive unless receiver capture coverage is independently verified; timestamps from different hosts are displayed without comparing their clocks.

The change is in this commit, with loopback and blocked-ACK lab tests. It is on main, not in the v0.5.0 PyPI release yet. Your report-design feedback was useful—thank you!