TunnelScope
Collect sender and receiver evidence when packet size affects delivery.
v0.7.0 alpha · Python 3.10+ · Install from PyPI · Release notes · MIT license
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.
This 40-second replay uses sanitized, recorded WireGuard lab evidence and actual generated HTML views. It is not a live network capture. Replay the example or rebuild the GIF.
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.7.0
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.
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. |
Payload sizes include the 24-byte TunnelScope header. Small ACKs do not prove
same-sized reverse delivery. 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 |
| Cross-node Kubernetes/Calico | 6/6 baseline deliveries per direction; policy block and recovery | Two Docker-based Minikube nodes, IPv4 IP-in-IP |
These are controlled validations. Physical multi-host paths, production VPN incidents and other Kubernetes CNI modes need separate evidence.
Guides and contributing
- Usage and JSON reference, size search, fragmentation comparison and ICMP feedback.
- Sanitize reports before sharing and same-sized replies for return-path evidence.
- Receiver observations, HTML report view, Kubernetes lab and deployment guidance.
- Security boundaries, v0.7 plan and project history.
Contributions welcome. CI runs on Linux and Windows with Python 3.10 and 3.12. 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.7.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| tunnelscope-0.7.0.tar.gz | 1.3 MB | With provenance | Details for tunnelscope-0.7.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| tunnelscope-0.7.0-py3-none-any.whl | Python 3 | none | any | Details for tunnelscope-0.7.0-py3-none-any.whl |
Total release size: 1.5 MB
Release files / tunnelscope-0.7.0.tar.gz
| Download URL | tunnelscope-0.7.0.tar.gz |
|---|---|
| Size | 1.3 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
edf55066c7374e6628ab6887b3e14a7a8d4104813c96e88f87c189f7dbdc962c
|
|
BLAKE2b-256 checksum How to use checksums |
bae2ddba8e68f0fa8d1d27d478ab2b07be1951bf9304f13d9b734b8e1975a5b1
|
| 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 5, 2026.
Transparency logRelease files / tunnelscope-0.7.0-py3-none-any.whl
| Download URL | tunnelscope-0.7.0-py3-none-any.whl |
|---|---|
| Size | 210.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
8ebf6488ddeef39522666056da1b6f8c9f360add67299d1961547865dfc01735
|
|
BLAKE2b-256 checksum How to use checksums |
142cc2df22921a90e31a20f64b85da5877b80350b86e66a864b141afbc875af7
|
| 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 5, 2026.
Transparency logSecurity for tunnelscope 0.7.0
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.
Attestation for tunnelscope-0.7.0.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 5, 2026.
Transparency logA 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.