Skip to main content

TunnelScope blue compass and vortex logo

TunnelScope

Evidence-based MTU and packet-size diagnostics for Linux networks.

v0.5.0 alpha: IPv4/IPv6 UDP probes, a cooperating receiver, bounded payload-size search, JSON evidence, per-direction comparison and offline HTML reports. Automatic path-MTU discovery and root-cause diagnosis are not implemented.

GitHub Release · PyPI

Terminal demo of TunnelScope showing a controlled blocked-feedback lab report

The animation runs tunnelscope show on a checked-in controlled lab report. It is not a live network capture. A timeout on an unknown path remains inconclusive.

Why use TunnelScope?

Small pings can work while larger traffic fails. ping checks selected ICMP sizes, tracepath depends on path feedback, and ip route get reports the kernel's route and available MTU information; none alone confirms that a chosen UDP payload reached the other endpoint. TunnelScope sends bounded payloads to a cooperating receiver and saves both endpoints' observations for comparison. Packet captures and these existing tools remain useful for root-cause work.

Quick start

Requires Python 3.10 or newer. In an empty working directory on Linux (or WSL2), install the published package in a virtual environment:

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

Open a second terminal and activate the same environment there with source .venv/bin/activate. Run these commands in order on one machine; no root access or network setup is needed for this loopback example.

Terminal 1 (receiver):

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

Wait for Listening on 127.0.0.1:9471, then run Terminal 2 (sender):

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

The receiver exits after the two probes and saves receiver.json. Back in either terminal, inspect the sender report and create a local HTML view:

tunnelscope show probe.json
tunnelscope html probe.json --output probe.html

Open probe.html in a browser. The receiver sends small acknowledgements, so this example checks delivery in one direction only. A timeout is inconclusive; it does not prove an MTU problem. For two machines, see the two-endpoint workflow.

On a controlled Linux path, search tests the endpoints and then narrows an observed interval using repeated no-fragment probes:

tunnelscope search 192.0.2.2 --min 1200 --max 1400 --count 2 --output search.json
tunnelscope show search.json

Start a receiver at that lab address first. A timeout stops the search as inconclusive; even adjacent successful and explicit-error sizes are not an independently measured path MTU. See the size-search guide.

What the results mean

  • acknowledged: the receiver got the UDP payload and a small reply returned.
  • packet_too_large: the local kernel rejected a no-fragment payload.
  • timeout: no matching reply arrived; the cause is unknown without more evidence.

Probe sizes are UDP payload bytes, including the 24-byte TunnelScope header. Success does not prove same-sized reverse delivery. The tool reports observed sizes, not an exact end-to-end path MTU.

Documentation

Contributing

Good first issues: Python 3.10 CI, receiver correlation quick start, and Windows PowerShell loopback guide. The roadmap connects all six open issues to the next release and field validation. Read CONTRIBUTING.md before opening a PR; share only synthetic or sanitized reports.

Run the unprivileged checks with python -m unittest discover -s tests -v. Linux network-namespace checks require root and explicit opt-in; see the usage reference.

Metadata

Release files for tunnelscope 0.5.0

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.5.0
File Size Uploaded Provenance Actions
tunnelscope-0.5.0.tar.gz 617.9 kB With provenance Details for tunnelscope-0.5.0.tar.gz

Built distribution (wheel)

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

Total release size: 810.3 kB

Release files / tunnelscope-0.5.0.tar.gz

Download URL tunnelscope-0.5.0.tar.gz
Size 617.9 kB
Tags Source
SHA-256 checksum
How to use checksums
c6120fae439ebf28c8d377fd9618f17371d4b515e02bf9965588f3bbbc48f345
BLAKE2b-256 checksum
How to use checksums
e20ee8125306087dec9863f8f5e3a62510f14a27f2cf264fe18afeb8d4c12747
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 Oct 30, 2026.

Transparency log

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

Download URL tunnelscope-0.5.0-py3-none-any.whl
Size 192.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
f58788766cdaeb8c55d1b9d7b3bdb95da76496d7e85931bcbf21bef61eafc1b1
BLAKE2b-256 checksum
How to use checksums
f1e636aed909786278dea26ca4fbdb9fa4da688ee825ab55adfaf86c7b8a5c82
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 Oct 30, 2026.

Transparency log

Security for tunnelscope 0.5.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.

Select from 2 files

Attestation for tunnelscope-0.5.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 Oct 30, 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