tunnelscope 0.2.1__tar.gz

tunnelscope-0.2.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TunnelScope contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tunnelscope-0.2.1/MANIFEST.in

@@ -0,0 +1,5 @@
+include tunnelscope-logo-blue.png
+include LICENSE
+recursive-include docs *.md *.png
+recursive-include examples *.json
+recursive-include labs *.py

tunnelscope-0.2.1/PKG-INFO

@@ -0,0 +1,166 @@
+Metadata-Version: 2.4
+Name: tunnelscope
+Version: 0.2.1
+Summary: Evidence-based MTU and packet-size diagnostics for Linux networks
+License-Expression: MIT
+Project-URL: Repository, https://github.com/lazypanic999/tunnelscope
+Keywords: network,mtu,pmtu,diagnostics
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/lazypanic999/tunnelscope/main/tunnelscope-logo-blue.png" alt="TunnelScope blue compass and vortex logo" width="400">
+</p>
+
+# TunnelScope
+
+Evidence-based MTU and packet-size diagnostics for Linux networks.
+
+**Status: v0.2.1 alpha prototype. UDP delivery probes, Linux IPv4 Don't Fragment mode, per-direction report combination, optional receiver observations and controlled MTU labs are available. Automatic path-MTU discovery and root-cause diagnosis are not implemented.**
+
+## The problem
+
+A connection can appear healthy while larger transfers fail. Small probes may succeed even when larger packets cannot traverse the path. Tunnel overhead, MTU configuration and blocked Path MTU Discovery feedback can contribute to this behavior. Other causes can produce similar symptoms.
+
+TunnelScope aims to help network engineers, system administrators and learners investigate these failures through repeatable measurements and inspectable evidence.
+
+## Planned first version
+
+- A Python command-line tool and a cooperating receiver for controlled Linux environments.
+- Repeated, size-controlled IPv4 UDP probes with fragmentation disabled.
+- Separate measurements for each direction, with timeouts and loss recorded explicitly.
+- JSON reports containing probe sizes, outcomes, relevant interface information and test settings.
+- A reproducible Linux lab demonstrating healthy delivery, explicit packet-too-large feedback and a possible PMTU black hole.
+
+A failed probe alone will not be labeled as proof of an MTU problem. Reports separate observations, hypotheses and missing evidence. An observed working packet size is not presented as the exact path MTU.
+
+## Milestones
+
+- [x] **M0 - Reproduce the problem:** build a small Linux network-namespace lab and record a healthy baseline and a controlled MTU failure.
+- [x] **M1 - Probe and receive:** implement bounded, identifiable probes and acknowledgements between two endpoints.
+- [x] **M2 - Explain the evidence:** export JSON and distinguish successful delivery, explicit errors and inconclusive timeouts.
+- [x] **M3 - Validate:** check the tool against known lab configurations, document limitations and publish a short demo.
+- [x] **M4 - Observe at the receiver:** record which identified probes reached the cooperating receiver and correlate them with sender outcomes.
+- [x] **M5 - Make evidence usable:** validate receiver-observed timeouts in a controlled lab and provide a concise terminal view of reports.
+
+Kubernetes, VPN-specific workflows, IPv6 and 5G user-plane tunnels are possible later directions. They are not currently supported features.
+
+For a quick walkthrough of both controlled failure modes, see the [two-minute Linux demo](https://github.com/lazypanic999/tunnelscope/blob/main/docs/demo.md).
+The [two-VM validation record](https://github.com/lazypanic999/tunnelscope/blob/main/docs/validation/two-vm-field-test.md) documents a successful bidirectional DF run between Ubuntu and Debian guests.
+The [v0.1 scope](https://github.com/lazypanic999/tunnelscope/blob/main/docs/v0.1-scope.md) lists what the installable prototype does and does not cover.
+The [v0.2 receiver workflow](https://github.com/lazypanic999/tunnelscope/blob/main/docs/receiver-observations.md) explains how to capture and correlate receiver evidence.
+The [two-VM correlation record](https://github.com/lazypanic999/tunnelscope/blob/main/docs/validation/two-vm-receiver-correlation.md) documents the new workflow on independent Linux guests.
+The [blocked ACK return lab](https://github.com/lazypanic999/tunnelscope/blob/main/docs/validation/ack-return-blocked.md) validates a receiver-observed sender timeout.
+
+Use `tunnelscope show report.json` for a short terminal table of a probe,
+bidirectional comparison, correlation, or lab report. JSON remains the
+machine-readable source of evidence.
+
+## Install locally
+
+From the repository root, in a Python 3.10+ virtual environment:
+
+```sh
+python3 -m pip install .
+tunnelscope --help
+```
+
+The package installs the `tunnelscope` command. It has no third-party runtime dependencies. Published releases can be installed with `python3 -m pip install tunnelscope`. The laboratory scripts still run from a source checkout.
+
+## Getting started
+
+Requires Python 3.10 or newer. No third-party runtime packages are needed. Start with a local experiment in two terminals, from the repository directory. Use `tunnelscope` in place of `python tunnelscope.py` after installing the package.
+
+Terminal 1 (receiver):
+
+```sh
+python tunnelscope.py receive
+```
+
+Terminal 2 (sender):
+
+```sh
+python tunnelscope.py probe 127.0.0.1 --sizes 64,512,1200,1400 --count 3 --output report.json
+```
+
+The receiver exits after 100 datagrams or 30 seconds without a datagram. Restart it if it has already exited. `--max-packets` and `--idle-timeout` change these limits.
+
+Probe sizes are **UDP payload bytes**, including TunnelScope's 24-byte header. They exclude IP and UDP headers. The receiver sends only a small acknowledgement, so this is not a same-sized round-trip test. Reverse endpoint roles to investigate delivery in the other direction.
+
+Each probe report includes a `source` snapshot taken from the first connected sender socket. It records the local IPv4 address. On Linux, it also records the selected interface and its link MTU when discoverable, plus `kernel_route_mtu_bytes` when the kernel supplies it. The link MTU and kernel route MTU are different facts; neither is an independently measured end-to-end path MTU. A failed connection may leave `source` as `null`, and optional fields may be absent.
+
+`acknowledged` means that the receiver got that payload and its acknowledgement returned. `timeout` means no matching acknowledgement arrived before the deadline; it does not prove an MTU issue. `socket_error` records a socket error. Without `--dont-fragment`, fragmentation follows OS defaults; the tool does not force it on or off. The CLI exits successfully when it produces a report; inspect per-probe statuses for delivery outcomes.
+
+JSON reports also include `summary.by_payload_size`. Each entry counts `acknowledged`, `packet_too_large`, `timeout` and `socket_error` attempts separately. Its `assessment` is `delivery_observed`, `kernel_rejected_df_payload`, `inconclusive`, `socket_error` or `mixed_observations`. Repeated payload sizes share one entry, while individual attempts remain in `results`. The summary does not infer an exact path MTU or turn a timeout into a diagnosis.
+
+The `evidence` section lists counted observations, tentative hypotheses and missing checks separately. A clean pattern where every acknowledged size is below every timed-out size suggests a possible size-related delivery problem; in DF mode it also lists a possible PMTU-feedback black hole. Filtering and ordinary loss remain alternative explanations. Mixed or reversed size patterns produce no such hypothesis. Missing evidence calls out same-sized reverse traffic, receiver/path observation for timeouts, ICMP feedback visibility in DF mode and fragmentation control when DF is off. These are prompts for investigation, not automatic root-cause findings.
+
+To compare directions, run `probe` once from A to B and once from B to A, then combine the two JSON files:
+
+```sh
+python tunnelscope.py combine a-to-b.json b-to-a.json --output bidirectional.json
+```
+
+The command preserves the two reports and aligns per-size assessments; it does not initiate a remote measurement. See the [two-endpoint workflow](https://github.com/lazypanic999/tunnelscope/blob/main/docs/bidirectional.md) for the receiver and sender steps. `endpoint_check` compares the recorded IPv4 addresses but cannot authenticate endpoints or account for address translation.
+
+### Linux IPv4 Don't Fragment mode
+
+```sh
+python tunnelscope.py probe 192.0.2.2 --sizes 64,1252,1253,1400 --count 1 --dont-fragment --output report.json
+```
+
+Use the address of your lab receiver; `192.0.2.2` is an example. This mode sets `IP_MTU_DISCOVER=IP_PMTUDISC_DO` on each sender socket. The kernel sets DF and rejects datagrams above its currently known path MTU. It does not bypass cached PMTU information or search automatically for a boundary. The flag requires Linux, including WSL2. Other platforms reject it; socket-option errors stop the experiment rather than silently reverting to defaults.
+
+In DF mode, `EMSGSIZE` is reported as `packet_too_large`, with its numeric `errno`. When available, `kernel_reported_mtu_bytes` contains the connected socket's `IP_MTU` value. That value is kernel knowledge, not an independently measured end-to-end MTU. Timeouts remain inconclusive. The JSON schema version remains 1 with additive fields and the new `packet_too_large` status; consumers must handle it explicitly.
+
+### Reproduce a known MTU boundary
+
+On Linux with root access and iproute2 installed:
+
+```sh
+sudo python3 labs/mtu_boundary.py > mtu-boundary.json
+```
+
+The lab creates two temporary network namespaces connected by a veth pair with MTU 1280. It probes both directions and checks that 1252-byte UDP payloads succeed while 1253-byte payloads fail in DF mode (20-byte IPv4 header + 8-byte UDP header). It changes no host interface MTU or host route and removes its namespaces on completion or ordinary interruption. As with any process, forced termination such as SIGKILL can prevent cleanup.
+
+This validates a directly attached link boundary, not an unknown multi-hop bottleneck or a PMTU black hole. See the [validation record](https://github.com/lazypanic999/tunnelscope/blob/main/docs/validation/mtu-boundary.md) and [captured example report](https://github.com/lazypanic999/tunnelscope/blob/main/examples/mtu-boundary.json).
+
+### Reproduce blocked PMTU feedback
+
+On Linux with root access, iproute2, iptables and sysctl installed:
+
+```sh
+sudo python3 labs/pmtu_blackhole.py > pmtu-blackhole.json
+```
+
+This lab creates a sender, router and receiver in temporary network namespaces. The sender-facing link has MTU 1500; the router's receiver-facing link has MTU 1280. The router drops only its outgoing ICMP fragmentation-needed messages. In DF mode, 64- and 1252-byte UDP payloads are acknowledged, while 1253- and 1400-byte payloads time out. The lab changes no host routes, interfaces or firewall rules and removes its namespaces on ordinary completion or interruption. Forced termination such as SIGKILL can prevent cleanup.
+
+The known lab topology explains these timeouts; a timeout on an unknown network remains inconclusive. See the [validation record](https://github.com/lazypanic999/tunnelscope/blob/main/docs/validation/pmtu-blackhole.md) and [captured report](https://github.com/lazypanic999/tunnelscope/blob/main/examples/pmtu-blackhole.json). This lab demonstrates one controlled failure mode; it does not establish automatic black-hole detection.
+
+The receiver binds to loopback by default. For your own two-host lab, use `--bind <receiver-lab-IPv4>` and probe that address. The experimental protocol is unencrypted and unauthenticated; use a controlled lab, not a public service.
+
+Run checks:
+
+```sh
+python -m unittest discover -s tests -v
+```
+
+Privileged Linux integration check (also run by CI on Ubuntu):
+
+```sh
+sudo env TUNNELSCOPE_RUN_NETNS_TESTS=1 python3 -m unittest discover -s tests -v
+```
+
+## Prior art and scope
+
+Existing tools such as ping, tracepath and packet analyzers already provide important building blocks. TunnelScope will explore whether controlled two-endpoint tests and evidence-oriented reporting make this investigation easier. It is not a replacement for a full packet analyzer.
+
+## Contributing
+
+Early feedback is welcome through GitHub Issues, especially reproducible examples where small traffic succeeds and larger transfers fail. Describe the environment, expected behavior and observed behavior. Use synthetic or sanitized examples; do not attach credentials or private packet captures.

tunnelscope-0.2.1/README.md

@@ -0,0 +1,150 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/lazypanic999/tunnelscope/main/tunnelscope-logo-blue.png" alt="TunnelScope blue compass and vortex logo" width="400">
+</p>
+
+# TunnelScope
+
+Evidence-based MTU and packet-size diagnostics for Linux networks.
+
+**Status: v0.2.1 alpha prototype. UDP delivery probes, Linux IPv4 Don't Fragment mode, per-direction report combination, optional receiver observations and controlled MTU labs are available. Automatic path-MTU discovery and root-cause diagnosis are not implemented.**
+
+## The problem
+
+A connection can appear healthy while larger transfers fail. Small probes may succeed even when larger packets cannot traverse the path. Tunnel overhead, MTU configuration and blocked Path MTU Discovery feedback can contribute to this behavior. Other causes can produce similar symptoms.
+
+TunnelScope aims to help network engineers, system administrators and learners investigate these failures through repeatable measurements and inspectable evidence.
+
+## Planned first version
+
+- A Python command-line tool and a cooperating receiver for controlled Linux environments.
+- Repeated, size-controlled IPv4 UDP probes with fragmentation disabled.
+- Separate measurements for each direction, with timeouts and loss recorded explicitly.
+- JSON reports containing probe sizes, outcomes, relevant interface information and test settings.
+- A reproducible Linux lab demonstrating healthy delivery, explicit packet-too-large feedback and a possible PMTU black hole.
+
+A failed probe alone will not be labeled as proof of an MTU problem. Reports separate observations, hypotheses and missing evidence. An observed working packet size is not presented as the exact path MTU.
+
+## Milestones
+
+- [x] **M0 - Reproduce the problem:** build a small Linux network-namespace lab and record a healthy baseline and a controlled MTU failure.
+- [x] **M1 - Probe and receive:** implement bounded, identifiable probes and acknowledgements between two endpoints.
+- [x] **M2 - Explain the evidence:** export JSON and distinguish successful delivery, explicit errors and inconclusive timeouts.
+- [x] **M3 - Validate:** check the tool against known lab configurations, document limitations and publish a short demo.
+- [x] **M4 - Observe at the receiver:** record which identified probes reached the cooperating receiver and correlate them with sender outcomes.
+- [x] **M5 - Make evidence usable:** validate receiver-observed timeouts in a controlled lab and provide a concise terminal view of reports.
+
+Kubernetes, VPN-specific workflows, IPv6 and 5G user-plane tunnels are possible later directions. They are not currently supported features.
+
+For a quick walkthrough of both controlled failure modes, see the [two-minute Linux demo](https://github.com/lazypanic999/tunnelscope/blob/main/docs/demo.md).
+The [two-VM validation record](https://github.com/lazypanic999/tunnelscope/blob/main/docs/validation/two-vm-field-test.md) documents a successful bidirectional DF run between Ubuntu and Debian guests.
+The [v0.1 scope](https://github.com/lazypanic999/tunnelscope/blob/main/docs/v0.1-scope.md) lists what the installable prototype does and does not cover.
+The [v0.2 receiver workflow](https://github.com/lazypanic999/tunnelscope/blob/main/docs/receiver-observations.md) explains how to capture and correlate receiver evidence.
+The [two-VM correlation record](https://github.com/lazypanic999/tunnelscope/blob/main/docs/validation/two-vm-receiver-correlation.md) documents the new workflow on independent Linux guests.
+The [blocked ACK return lab](https://github.com/lazypanic999/tunnelscope/blob/main/docs/validation/ack-return-blocked.md) validates a receiver-observed sender timeout.
+
+Use `tunnelscope show report.json` for a short terminal table of a probe,
+bidirectional comparison, correlation, or lab report. JSON remains the
+machine-readable source of evidence.
+
+## Install locally
+
+From the repository root, in a Python 3.10+ virtual environment:
+
+```sh
+python3 -m pip install .
+tunnelscope --help
+```
+
+The package installs the `tunnelscope` command. It has no third-party runtime dependencies. Published releases can be installed with `python3 -m pip install tunnelscope`. The laboratory scripts still run from a source checkout.
+
+## Getting started
+
+Requires Python 3.10 or newer. No third-party runtime packages are needed. Start with a local experiment in two terminals, from the repository directory. Use `tunnelscope` in place of `python tunnelscope.py` after installing the package.
+
+Terminal 1 (receiver):
+
+```sh
+python tunnelscope.py receive
+```
+
+Terminal 2 (sender):
+
+```sh
+python tunnelscope.py probe 127.0.0.1 --sizes 64,512,1200,1400 --count 3 --output report.json
+```
+
+The receiver exits after 100 datagrams or 30 seconds without a datagram. Restart it if it has already exited. `--max-packets` and `--idle-timeout` change these limits.
+
+Probe sizes are **UDP payload bytes**, including TunnelScope's 24-byte header. They exclude IP and UDP headers. The receiver sends only a small acknowledgement, so this is not a same-sized round-trip test. Reverse endpoint roles to investigate delivery in the other direction.
+
+Each probe report includes a `source` snapshot taken from the first connected sender socket. It records the local IPv4 address. On Linux, it also records the selected interface and its link MTU when discoverable, plus `kernel_route_mtu_bytes` when the kernel supplies it. The link MTU and kernel route MTU are different facts; neither is an independently measured end-to-end path MTU. A failed connection may leave `source` as `null`, and optional fields may be absent.
+
+`acknowledged` means that the receiver got that payload and its acknowledgement returned. `timeout` means no matching acknowledgement arrived before the deadline; it does not prove an MTU issue. `socket_error` records a socket error. Without `--dont-fragment`, fragmentation follows OS defaults; the tool does not force it on or off. The CLI exits successfully when it produces a report; inspect per-probe statuses for delivery outcomes.
+
+JSON reports also include `summary.by_payload_size`. Each entry counts `acknowledged`, `packet_too_large`, `timeout` and `socket_error` attempts separately. Its `assessment` is `delivery_observed`, `kernel_rejected_df_payload`, `inconclusive`, `socket_error` or `mixed_observations`. Repeated payload sizes share one entry, while individual attempts remain in `results`. The summary does not infer an exact path MTU or turn a timeout into a diagnosis.
+
+The `evidence` section lists counted observations, tentative hypotheses and missing checks separately. A clean pattern where every acknowledged size is below every timed-out size suggests a possible size-related delivery problem; in DF mode it also lists a possible PMTU-feedback black hole. Filtering and ordinary loss remain alternative explanations. Mixed or reversed size patterns produce no such hypothesis. Missing evidence calls out same-sized reverse traffic, receiver/path observation for timeouts, ICMP feedback visibility in DF mode and fragmentation control when DF is off. These are prompts for investigation, not automatic root-cause findings.
+
+To compare directions, run `probe` once from A to B and once from B to A, then combine the two JSON files:
+
+```sh
+python tunnelscope.py combine a-to-b.json b-to-a.json --output bidirectional.json
+```
+
+The command preserves the two reports and aligns per-size assessments; it does not initiate a remote measurement. See the [two-endpoint workflow](https://github.com/lazypanic999/tunnelscope/blob/main/docs/bidirectional.md) for the receiver and sender steps. `endpoint_check` compares the recorded IPv4 addresses but cannot authenticate endpoints or account for address translation.
+
+### Linux IPv4 Don't Fragment mode
+
+```sh
+python tunnelscope.py probe 192.0.2.2 --sizes 64,1252,1253,1400 --count 1 --dont-fragment --output report.json
+```
+
+Use the address of your lab receiver; `192.0.2.2` is an example. This mode sets `IP_MTU_DISCOVER=IP_PMTUDISC_DO` on each sender socket. The kernel sets DF and rejects datagrams above its currently known path MTU. It does not bypass cached PMTU information or search automatically for a boundary. The flag requires Linux, including WSL2. Other platforms reject it; socket-option errors stop the experiment rather than silently reverting to defaults.
+
+In DF mode, `EMSGSIZE` is reported as `packet_too_large`, with its numeric `errno`. When available, `kernel_reported_mtu_bytes` contains the connected socket's `IP_MTU` value. That value is kernel knowledge, not an independently measured end-to-end MTU. Timeouts remain inconclusive. The JSON schema version remains 1 with additive fields and the new `packet_too_large` status; consumers must handle it explicitly.
+
+### Reproduce a known MTU boundary
+
+On Linux with root access and iproute2 installed:
+
+```sh
+sudo python3 labs/mtu_boundary.py > mtu-boundary.json
+```
+
+The lab creates two temporary network namespaces connected by a veth pair with MTU 1280. It probes both directions and checks that 1252-byte UDP payloads succeed while 1253-byte payloads fail in DF mode (20-byte IPv4 header + 8-byte UDP header). It changes no host interface MTU or host route and removes its namespaces on completion or ordinary interruption. As with any process, forced termination such as SIGKILL can prevent cleanup.
+
+This validates a directly attached link boundary, not an unknown multi-hop bottleneck or a PMTU black hole. See the [validation record](https://github.com/lazypanic999/tunnelscope/blob/main/docs/validation/mtu-boundary.md) and [captured example report](https://github.com/lazypanic999/tunnelscope/blob/main/examples/mtu-boundary.json).
+
+### Reproduce blocked PMTU feedback
+
+On Linux with root access, iproute2, iptables and sysctl installed:
+
+```sh
+sudo python3 labs/pmtu_blackhole.py > pmtu-blackhole.json
+```
+
+This lab creates a sender, router and receiver in temporary network namespaces. The sender-facing link has MTU 1500; the router's receiver-facing link has MTU 1280. The router drops only its outgoing ICMP fragmentation-needed messages. In DF mode, 64- and 1252-byte UDP payloads are acknowledged, while 1253- and 1400-byte payloads time out. The lab changes no host routes, interfaces or firewall rules and removes its namespaces on ordinary completion or interruption. Forced termination such as SIGKILL can prevent cleanup.
+
+The known lab topology explains these timeouts; a timeout on an unknown network remains inconclusive. See the [validation record](https://github.com/lazypanic999/tunnelscope/blob/main/docs/validation/pmtu-blackhole.md) and [captured report](https://github.com/lazypanic999/tunnelscope/blob/main/examples/pmtu-blackhole.json). This lab demonstrates one controlled failure mode; it does not establish automatic black-hole detection.
+
+The receiver binds to loopback by default. For your own two-host lab, use `--bind <receiver-lab-IPv4>` and probe that address. The experimental protocol is unencrypted and unauthenticated; use a controlled lab, not a public service.
+
+Run checks:
+
+```sh
+python -m unittest discover -s tests -v
+```
+
+Privileged Linux integration check (also run by CI on Ubuntu):
+
+```sh
+sudo env TUNNELSCOPE_RUN_NETNS_TESTS=1 python3 -m unittest discover -s tests -v
+```
+
+## Prior art and scope
+
+Existing tools such as ping, tracepath and packet analyzers already provide important building blocks. TunnelScope will explore whether controlled two-endpoint tests and evidence-oriented reporting make this investigation easier. It is not a replacement for a full packet analyzer.
+
+## Contributing
+
+Early feedback is welcome through GitHub Issues, especially reproducible examples where small traffic succeeds and larger transfers fail. Describe the environment, expected behavior and observed behavior. Use synthetic or sanitized examples; do not attach credentials or private packet captures.

tunnelscope-0.2.1/docs/bidirectional.md

@@ -0,0 +1,77 @@
+# Measure both directions
+
+TunnelScope's receiver sends a small acknowledgement. One `probe` run therefore
+measures delivery of the requested payload in one direction, plus return of the
+small acknowledgement. To measure the reverse direction, the endpoints must
+exchange sender and receiver roles. This workflow is for a controlled Linux
+environment where both sides can run Python 3.10+ and reach each other over UDP.
+
+Use the actual endpoint IPv4 addresses in place of `A_IP` and `B_IP`. Start each
+receiver shortly before its probe; by default it exits after 30 seconds idle.
+
+## A to B
+
+On endpoint B:
+
+```sh
+python3 tunnelscope.py receive --bind B_IP
+```
+
+On endpoint A:
+
+```sh
+python3 tunnelscope.py probe B_IP --sizes 64,1252,1253,1400 --count 3 --dont-fragment --output a-to-b.json
+```
+
+## B to A
+
+On endpoint A:
+
+```sh
+python3 tunnelscope.py receive --bind A_IP
+```
+
+On endpoint B:
+
+```sh
+python3 tunnelscope.py probe A_IP --sizes 64,1252,1253,1400 --count 3 --dont-fragment --output b-to-a.json
+```
+
+Copy `b-to-a.json` to the machine holding `a-to-b.json`. Then run:
+
+```sh
+python3 tunnelscope.py combine a-to-b.json b-to-a.json --output bidirectional.json
+```
+
+`bidirectional.json` contains the unmodified probe reports under `directions`,
+with `a-to-b` and `b-to-a` labels supplied by the command order. Its
+`comparison.by_payload_size` aligns each direction's assessment for the same
+UDP payload size. A missing size has a `null` assessment. The command does not
+turn two timeouts into a diagnosis.
+Each embedded report's `evidence` describes that one run; `combine` preserves
+it without retroactively treating the other file as verified evidence.
+
+`endpoint_check` is `reversed_ipv4_match` when both recorded source IPv4
+addresses equal the opposite report's target address. It is
+`ipv4_mismatch_or_translation` when they differ, or `unavailable` if either
+source snapshot is missing. NAT, multiple local addresses and user-selected
+files can affect this check; the command cannot verify that the files came
+from the intended endpoints.
+
+## Source fields
+
+`source.ipv4` is the first connected sender socket's local IPv4 address. On
+Linux, `source.interface` and `source.interface_mtu_bytes` are included when
+the address can be matched to a local interface. `source.kernel_route_mtu_bytes`
+is the kernel's current MTU value for that connected route when available. A
+link MTU is local interface configuration; a kernel route MTU can reflect
+cached path knowledge. Neither field alone proves the end-to-end path MTU.
+
+The report contains a source snapshot, not a live record of route changes
+during later attempts. When a socket cannot connect, `source` can be `null`.
+The probe protocol is unauthenticated and unencrypted; use a controlled lab.
+
+For each direction, you can also save observations at the receiving endpoint
+and use `tunnelscope correlate` to check which individual probes arrived. See
+the [receiver observation workflow](receiver-observations.md). This provides
+different evidence from a reverse-direction probe.

tunnelscope-0.2.1/docs/demo.md

@@ -0,0 +1,67 @@
+# TunnelScope: two-minute Linux demo
+
+Run this from the repository root on Linux with root access, Python 3.10+,
+iproute2, iptables and sysctl. The labs create temporary network namespaces;
+they do not change host interfaces, routes or firewall rules. Forced termination
+such as SIGKILL can prevent namespace cleanup.
+
+## 1. Run two controlled experiments
+
+```sh
+sudo python3 labs/mtu_boundary.py > boundary.json
+sudo python3 labs/pmtu_blackhole.py > blackhole.json
+```
+
+The first experiment uses a direct 1280-byte link. The second routes traffic
+from a 1500-byte link onto a 1280-byte link while blocking the router's ICMP
+fragmentation-needed feedback.
+
+## 2. Compare what the sender observed
+
+```sh
+python3 - <<'PY'
+import json
+
+with open("boundary.json", encoding="utf-8") as source:
+    boundary = json.load(source)
+with open("blackhole.json", encoding="utf-8") as source:
+    blackhole = json.load(source)
+
+def show(label, results):
+    statuses = ", ".join(f"{row['payload_bytes']}={row['status']}" for row in results)
+    print(f"{label}: {statuses}")
+
+for direction in boundary["directions"]:
+    show(direction["direction"], direction["results"])
+show("blocked ICMP", blackhole["probe"]["results"])
+print("blocked feedback packets:", blackhole["blocked_feedback_packets"])
+PY
+```
+
+Example output (statuses are checked by the labs; the firewall counter can vary):
+
+```text
+a-to-b: 64=acknowledged, 1252=acknowledged, 1253=packet_too_large, 1400=packet_too_large
+b-to-a: 64=acknowledged, 1252=acknowledged, 1253=packet_too_large, 1400=packet_too_large
+blocked ICMP: 64=acknowledged, 1252=acknowledged, 1253=timeout, 1400=timeout
+blocked feedback packets: 2
+```
+
+The direct-link sender receives a local `EMSGSIZE` error above 1252 UDP payload
+bytes. In the routed lab, the large DF packets cannot cross the 1280-byte
+egress link, and the router's ICMP feedback is blocked. The sender sees only
+timeouts. The lab knows why; an unknown network path would require more
+evidence before calling a timeout a PMTU black hole.
+
+## 3. Inspect the JSON evidence
+
+Each probe report keeps individual attempts in `results`, counts outcomes
+per payload size in `summary.by_payload_size`, and separates observations,
+possible explanations and missing checks in `evidence`. The routed lab also records
+`blocked_feedback_packets` from its isolated firewall rule. Compare your run
+with the [direct-link example](../examples/mtu-boundary.json) and the
+[blocked-feedback example](../examples/pmtu-blackhole.json).
+
+The validation records explain the [direct-link boundary](validation/mtu-boundary.md)
+and [routed black-hole scenario](validation/pmtu-blackhole.md). These labs do
+not validate arbitrary networks, VPNs, IPv6 or same-sized return traffic.

tunnelscope-0.2.1/docs/receiver-observations.md

@@ -0,0 +1,55 @@
+# Correlate receiver observations
+
+In v0.2, a cooperating receiver can save the probe IDs and payload sizes it
+observed. The sender also includes each 128-bit random probe ID in its JSON
+results. From v0.2.1, the sender puts one random run ID in every payload, and
+both reports record it. Correlation answers whether a particular probe reached
+the receiver and whether the receiver attempted to send an acknowledgement.
+
+Start the receiver on endpoint B and give it an output path:
+
+```sh
+tunnelscope receive --bind B_IP --output receiver.json
+```
+
+Run the sender on endpoint A:
+
+```sh
+tunnelscope probe B_IP --sizes 64,1252,1253,1400 --count 3 --dont-fragment --output a-to-b.json
+```
+
+After the sender finishes, stop the receiver with Ctrl-C or wait for its idle
+timeout. The receiver writes `receiver.json` when it exits. Copy it to the
+machine holding `a-to-b.json`, then run:
+
+```sh
+tunnelscope correlate a-to-b.json receiver.json --output correlation.json
+```
+
+`correlation.json` has one row per sender attempt. `receiver_observed: true`
+confirms that the matching payload arrived at this receiver. A timeout with
+`receiver_observed: true` narrows the investigation toward acknowledgement
+transmission or return delivery, but does not identify which failed. A successful
+acknowledgement send call only confirms that the local socket accepted it.
+
+`receiver_observed: false` is inconclusive unless the receiver was running for
+the full probe period and its report is complete. A packet may have been lost,
+filtered, sent to another endpoint or missed because capture started late.
+`unmatched_receiver_observations` counts valid probes seen by the receiver that
+were not present in the sender file. It can reveal a mixed or incorrect pairing.
+
+`pairing.run_id_check` is `matched` when the receiver observed this sender run.
+The command rejects a receiver file containing only observations from another
+run. An empty receiver file cannot establish which run it covered and is marked
+`unverified_no_receiver_observations`. `pairing.endpoint_checks` compares the
+target port and, unless the receiver bound to `0.0.0.0`, the target IPv4 address.
+Mismatches need review; address translation can legitimately change them.
+The two UTC capture windows and the receiver's `exit_reason` help review
+coverage, but the command does not compare clocks across hosts because they
+may be unsynchronized.
+
+The reports are unauthenticated. Use them only in a controlled environment and
+pair the files from the same run. Reports created before v0.2 do not contain
+probe IDs and cannot be correlated. v0.2 reports can still be correlated by
+probe ID, but their run ID check is unavailable. Receiver observation is complementary to
+running probes in the reverse direction; it does not replace that test.

tunnelscope-0.2.1/docs/releases/v0.2.1.md

@@ -0,0 +1,24 @@
+# TunnelScope v0.2.1
+
+First public alpha release of the Python command-line prototype.
+
+## Highlights
+
+- Bounded IPv4 UDP probes with optional Linux Don't Fragment mode, JSON evidence,
+  and separate per-direction comparison.
+- Receiver observation reports and `correlate` for matching individual probes.
+  Run IDs and endpoint checks help catch incorrectly paired reports.
+- `show` prints concise terminal tables for probe, correlation, bidirectional
+  comparison and lab JSON reports.
+- Reproducible Linux namespace labs for a direct MTU boundary, blocked PMTU
+  feedback and a blocked acknowledgement return.
+- Two-VM validation of successful delivery and receiver correlation in both
+  directions.
+
+## Known limits
+
+Timeouts remain inconclusive without cooperating receiver or path evidence.
+The CLI does not discover an exact end-to-end path MTU or prove a root cause on
+an unknown network. The UDP protocol is unauthenticated and unencrypted; run
+it only in a controlled environment. IPv6, VPN-specific, Kubernetes and 5G
+workflows are not implemented.

tunnelscope-0.2.1/docs/v0.1-scope.md

@@ -0,0 +1,32 @@
+# TunnelScope v0.1 scope
+
+v0.1 is an installable prototype of the existing Python CLI. It can be built
+and installed locally; it is not yet published to a package index.
+
+## Included
+
+- A `tunnelscope` console command with `receive`, `probe` and `combine`.
+- Bounded IPv4 UDP payload probes and small acknowledgements between controlled
+  endpoints.
+- Optional Linux Don't Fragment mode and explicit local `EMSGSIZE` reporting.
+- JSON reports with per-size counts, source/interface snapshot, observations,
+  tentative hypotheses and missing evidence.
+- Separate direction reports that can be combined without treating either
+  direction as proof of the other's behavior.
+- Direct-link MTU boundary and blocked-feedback Linux namespace labs.
+- A two-VM bidirectional delivery validation record.
+
+## Outside v0.1
+
+- Automatic discovery of an exact end-to-end path MTU or root cause.
+- Automatic remote orchestration, authentication or encryption.
+- IPv6, VPN-specific, Kubernetes or 5G tunnel workflows.
+- A graphical interface and a published package-index release.
+
+## Before a public release
+
+The local wheel and source distribution must build and install cleanly on
+supported Python versions. We also need to choose and add a project license,
+confirm the package name and publish a release only after reviewing the
+distribution metadata and contents. These decisions are separate from local
+v0.1 packaging.

tunnelscope-0.2.1/docs/validation/ack-return-blocked.md

@@ -0,0 +1,25 @@
+# Blocked acknowledgement return validation
+
+Run the controlled lab as root on Linux with iproute2 and iptables:
+
+```sh
+sudo python3 labs/ack_return_blocked.py > ack-return-blocked.json
+python3 tunnelscope.py show ack-return-blocked.json
+```
+
+The lab creates two temporary network namespaces on a 1500-byte direct link.
+The receiver observes two UDP probes and sends small acknowledgements. A rule
+in the sender namespace drops only incoming UDP packets from the receiver's
+port. The lab changes no host firewall rule, route or interface and removes
+the namespaces when it exits normally.
+
+In the validated run, both 64- and 1400-byte probes timed out at the sender.
+The receiver recorded both probes and both local acknowledgement sends. The
+correlation reported `timed_out_but_receiver_observed: 2`, a matched run ID,
+and zero unmatched receiver observations. The isolated firewall counted two
+blocked acknowledgements.
+
+This establishes the cause only inside the known lab topology. On an unknown
+network, the same sender/receiver pattern narrows the investigation to the
+acknowledgement path but does not identify a failing hop or rule. Forced
+termination such as SIGKILL can prevent namespace cleanup.