Repository navigation
Releases
TunnelScope v0.9.6
TunnelScope v0.9.6
Presentation patch after v0.9.5. There is no wire-protocol,
JSON schema, dependency or measurement change.
HTML report
HTML views (tunnelscope html REPORT and --html on correlate) now follow the viewer's light or
dark system setting. Summaries sit in cards, the table header stays visible
while scrolling, and wide tables scroll inside their panel instead of
widening the page. A print stylesheet drops the filter box and colours.
Known status values (for example timeout, receiver_reply_send_failed,
sized_reply_received) are coloured green, amber or red by a short script
that matches exact cell text. The markup is unchanged, so the page reads
the same with scripts off and existing scripts that parse it keep working.
Diagnosis table fix
Diagnosis reports gave every "DF vs permitted" row one empty trailing
cell, so those rows had seven cells under six headers. A new test renders
every example report and checks one cell per header.
README
The README starts from the problem (ping and SSH work, a bulk copy over
the tunnel hangs) and what the tool records, with the release-by-release
notes moved behind one link. The report screenshot follows GitHub's light
or dark theme.
Validation
169 tests passed on native Windows with Python 3.10 and 3.13 and on WSL
Ubuntu with Python 3.12. Light and dark screenshots of a correlation and a
diagnosis report were checked in headless Edge.
Install
python -m pip install --upgrade tunnelscope==0.9.6
tunnelscope --versionThis release adds no new field evidence. Reports from real VPN paths are
still the most useful contribution; see the
field report guide.
TunnelScope v0.9.5
Patch release for offline evidence handling and operator workflow.
- Reject whitespace inside probe/run IDs while retaining uppercase hexadecimal compatibility.
- Reject boolean payload sizes and probe IDs reused across diagnosis runs before building the sender-run lookup.
- Sanitize IPv6 text followed by punctuation; reserve existing placeholders and IPv4-mapped documentation addresses without collisions.
- Protect sanitized JSON/HTML outputs from files created after preflight using exclusive creation.
- Keep IPv4-mapped formatting consistent across supported Python versions.
- Add a sender/receiver OS support table and operator checklist for independent field reports.
Validation: 167 tests on native Windows with Python 3.10 and 3.13 (17 platform/opt-in skips each), installed-package workflows and a fresh 64/1400-byte sized-reply loopback run. All Linux/Windows Python 3.10/3.12/3.13 delivery jobs and routed WireGuard/OpenVPN checks passed for PR #72. The actual built source distribution was tested before PyPI publication.
No wire-protocol, JSON-schema, dependency or measurement changes. Existing lab/VM records retain their original producer versions. Sanitization remains best effort and requires manual review. A failed output batch may leave previously completed copies; it is not transactional. Independent VPN evidence remains open in issue #2.
Install: python -m pip install --upgrade tunnelscope==0.9.5
Release guide: https://github.com/lazypanic999/tunnelscope/blob/main/docs/releases/v0.9.5.md
Field report guide: https://github.com/lazypanic999/tunnelscope/blob/main/docs/field-reports.md
PyPI: https://pypi.org/project/tunnelscope/0.9.5/
TunnelScope v0.9.4
Patch release after v0.9.3 for tunnelscope show REPORT --format markdown. It makes the plain source readable again and stops report values
from becoming GitHub mentions, issue links or math when the summary is pasted
into an issue.
GitHub mentions, references and math
v0.9.0 to v0.9.3 encoded report values as numeric character references.
GitHub decodes those references before it links @mentions, #123 and
GH-123 references and renders $...$ math, so a report field such as
@name in a pasted summary still became a mention (and could notify that
user), #12 became an issue link and $x$ became inline math. A
zero-width space now follows @, # and GH- before a name or number and
precedes every $. GitHub's documented \$ and the $ reference both
still rendered as math inside table cells, so neither is used.
If you pasted a v0.9.0–v0.9.3 summary whose fields contained @, # or $,
check that issue for unintended mentions or links.
Readable plain source
The previous export encoded every punctuation character, so the source read
like 192.0.2.1 and sized_reply_returned. Only
characters that can change rendering are now encoded: |, `, *,
[, ], <, &, \, ~, non-ASCII characters, underscores at word
boundaries, ://, www. and colons that would form an emoji shortcode such
as :abc:. Addresses, timestamps and statuses appear as written. Truncated
probe IDs end in ... and missing values show -, so the output stays
ASCII for redirected Windows consoles.
A copied value can contain the invisible zero-width space; the JSON report
keeps exact values. See Markdown report export.
Validation
A sample with hostile values in every row (mentions, issue and GH-
references, URLs, www., email, emphasis, strikethrough, math, emoji
shortcodes including IPv6 hex groups, images, HTML and code) was rendered
through GitHub's Markdown API in the repository context: no links, images,
emoji, mentions, issue references, emphasis or code elements, or math, and
every cell displayed its original value. The 147-test suite passed on
Windows with Python 3.10 and 3.13 and on WSL2 with Python 3.12, and all
Linux/Windows delivery jobs and the WireGuard/OpenVPN checks passed for
#69.
Install
python -m pip install --upgrade tunnelscope==0.9.4
tunnelscope --versionThis patch changes no JSON schema, wire protocol, dependencies or network
behavior; the text and HTML views are unchanged.
TunnelScope v0.9.3
Patch release after v0.9.2, rejecting the wrong sender report
type before creating correlation outputs. Thanks to
sunxiuguo for
#66, addressing
#62.
Keep raw sender inputs distinct from joined evidence
Passing an already joined probe_receiver_correlation as the sender input
previously succeeded, producing null sender statuses and misleading legacy
pairing metadata. correlate_reports now rejects a present kind whose
value is not probe, including malformed null/list/object values. The CLI
exits with a short Error:, leaves both inputs unchanged and creates neither
the requested JSON nor HTML output.
Legacy probe reports with a genuinely absent kind remain accepted. An
explicit null value is not treated as an absent field. Valid probe joins
and the separate CLI diagnosis workflow are unchanged. See the
receiver guide.
The regressions use an actual retained correlation as the wrong input,
cover malformed declared kinds through subprocess CLI calls, and compare
valid/legacy results with the stored observations. All 145 tests passed in
independent maintainer runs on native Windows/Python 3.10 (17 expected
platform/opt-in skips) and unprivileged WSL2/Python 3.12 (11 privileged-lab
skips). All six Linux/Windows Python 3.10/3.12/3.13 delivery jobs and the
dedicated WireGuard/OpenVPN checks passed for the contributor's exact head.
Retain the receiver's local IPv6 scope
New receiver captures also retain receiver.scope_id when the bound IPv6
socket has a nonzero numeric scope. IPv4 and zero-scope IPv6 output are
unchanged. Sanitization preserves this local metadata; equal numbers on
different hosts do not identify the same link or authenticate an endpoint.
The original v0.9.1 validation captures predate this addition.
Thanks to HarshRajSinghania for
#67. The maintainer
limited the final diff to receiver metadata, clarified the historical
record and verified that sender/search/ICMP/budget behavior was preserved.
Three additional scoped/zero-scope/IPv4 tests and a sanitization assertion
passed on Windows and Linux, with all six delivery jobs and VPN checks.
Install and retained evidence
python -m pip install --upgrade tunnelscope==0.9.3
tunnelscope --versionThe source-distribution test gate introduced in v0.9.2 remains in place.
Existing native Windows validation records
retain the v0.9.1 producer used for their measurements, including the
IPv6 link-local and
oversized reply runs.
This patch changes no schema, wire protocol, dependencies or network settings.
Independent operator VPN and physical multi-host evidence remain separate work.
TunnelScope v0.9.2
Patch release after v0.9.1, with diagnosis input validation,
Python 3.13 delivery coverage and retained native Windows evidence.
Reject malformed diagnosis probe IDs cleanly
A JSON list or object used as a nested diagnosis probe_id previously
reached a cross-run dictionary lookup before the ordinary probe validator.
The CLI could raise an unhandled TypeError. It now rejects malformed row/ID
types before that lookup, with a short Error: and exit code 1. The
regression also checks null/numeric IDs, unchanged input files and absence
of both requested JSON and HTML outputs. Valid joins, full identifier checks
and conservative evidence cases are unchanged.
Python 3.13 delivery checks
The Linux/Windows matrix now covers Python 3.10, 3.12 and 3.13, preserving
the installed-command checks, isolated installed-package workflow,
unprivileged suite, Linux namespace labs and per-version artifacts. The
required Delivery checks aggregate still depends on every matrix job.
Dedicated OpenVPN checks retain their existing Python 3.10/3.12 matrix.
Thanks to HarshRajSinghania for
#61. The maintainer
repaired the transport-damaged README and updated the branch before
reviewing the final two-line change. All six matrix jobs and the aggregate
passed in run 42445085496.
The downloaded Python 3.13 lab ZIP matched GitHub's digest, and all eight
retained JSON files matched manifest sizes and SHA-256 values. Its manifest
records Python 3.13.18, source head and tested merge commit separately.
Reproducible demo in source distributions
Source distributions now include the repository's Python helper scripts,
including scripts/build_v09_demo.py, its checked-in input fixture and
replay guide, and scripts/write_lab_manifest.py, which the retained tests
import. The v0.9.1 source archive omitted those two helpers. The publication
workflow now safely extracts the actual built source archive and runs its
unprivileged suite before uploading distributions for publishing. Optional
demo rebuilding still requires Pillow; the CLI has no third-party runtime
dependencies.
Native Windows validation records
The new records were measured with v0.9.1 and retain that producer value:
- IPv4 host/guest path: 3/3 small
ACKs, 6/6 sized replies and 8/8 diagnosis replies. - IPv6 link-local path: the
same successful counts, with endpoint-local zones explained. - Oversized Windows replies:
1600-byte probes arrive and small ACKs return in both families, while
same-sized sends fail locally with actualWSAEMSGSIZE(10040). Receiver
correlation distinguishes that error from the sender's timeout.
These are two kernels on one physical host, using existing virtual networking
and MTU 1500 interfaces. No test-created firewall rule, route, MTU or access
change was needed. They do not establish an exact PMTU, capture fragments,
validate routed IPv6 or replace independent operator VPN evidence.
Install and validation
python -m pip install --upgrade tunnelscope==0.9.2
tunnelscope --versionThe suite has 139 tests. Native Windows/Python 3.10 and 3.13 passed with the
17 expected platform/opt-in skips; unprivileged Linux/Python 3.12 passed
with 11 privileged-lab skips. Hosted delivery, WireGuard and OpenVPN checks
passed for the diagnosis fix before merging. Schema version 1, the UDP wire
protocol and runtime dependencies are unchanged.
TunnelScope v0.9.1
TunnelScope v0.9.1
Patch release after v0.9.0, preserving uncertainty in partial
receiver captures and handling malformed offline input cleanly.
Reject malformed report kinds cleanly
List/object kind metadata no longer causes an uncaught TypeError in text
show before the normal report validator runs. The CLI exits with a concise
error, leaves the input unchanged and creates no output report. Valid and
legacy producer-version display is unchanged. Thanks to
sunxiuguo for
#53.
The field-report guide now includes the optional
Markdown summary after batch sanitization, recommends the latest published
release and keeps full sanitized JSON alongside the bounded summary. Thanks
also to sunxiuguo for #56.
Preserve uncertainty in partial receiver captures
A receiver records arrival before sending its reply. If it is interrupted
during that send, the saved capture can contain a valid arrival with no
ack_send_status. Previously, joining this capture with a timed-out sized
probe could label the reply as sent-but-missing (or as a sent small reply).
The join now uses return_evidence: receiver_reply_send_unverified when the
local send outcome is missing or unknown. It counts these separately in
correlations and joined diagnoses, and text, HTML and Markdown keep them
visible. Known accepted sends, explicit socket rejections and replies
recorded by the sender retain their existing cases.
The interpretation also describes accepted local sends and the sender's
deadline rather than claiming a reply never arrived or identifying its loss
location. Text summaries associate timeouts with receiver arrivals without
asserting their cross-host chronological order. Schema version 1 and the UDP protocol are unchanged; the new field
and evidence case are additive.
Validation includes interrupting the receiver's send call, reading its saved
partial capture and joining it, unknown small/sized send results, rendering,
and aggregation across three diagnosis runs. No VM or external network is
required for those regressions.
To rebuild a correlation from an older partial capture, use the original
sender and receiver files with fresh output names. Existing joined reports
are not relabeled automatically; an already joined diagnosis is not the
original sender input.
Install and validation
python -m pip install --upgrade tunnelscope==0.9.1
tunnelscope --versionThe combined suite has 138 tests. Windows/Python 3.10 passed with the 17
documented platform/opt-in skips; Linux/Python 3.12 passed with both privileged
lab flags and no skips. Hosted delivery checks cover Linux and Windows with
Python 3.10/3.12, alongside dedicated OpenVPN and WireGuard validation.
No runtime dependency or network-configuration change is introduced.
TunnelScope v0.9.0
TunnelScope v0.9.0
Share bounded evidence summaries and trace reports back to their declared
producer versions. This alpha release adds offline report improvements and
controlled OpenVPN validation; it does not add peer authentication or claim
automatic root-cause diagnosis. The UDP protocol and report schema version 1
remain compatible.
Sharing and report provenance
tunnelscope show REPORT --format markdownproduces an issue-ready
summary, limited to 50 rows and 24,000 ASCII characters. Report values are
escaped as text, omitted rows are explicit, sanitization metadata is shown,
and interpretation limits accompany the observations. The source JSON
remains the full evidence. See Markdown export.- New collectors and offline builders record
tunnelscope_versionand
immediateinput_versions. Older inputs remain unknown. Adding receiver
evidence to an old diagnosis preserves its original producer and records
the new join separately. These are untrusted metadata claims, not signatures.
See producer versions. - Text, HTML and Markdown share observation-table data. The default text
view supports named lab cases and multiple directions. Grouped cases with
sized replies retain return status, joined return evidence and ACK-send
status instead of collapsing them into a sender timeout.
Controlled OpenVPN evidence
Temporary mutually verified TLS/TUN peers add two reproducible IPv4/UDP
scenarios, with data-channel offload disabled:
- Routed visible/blocked feedback: a
known 1280-byte receiver LAN produces matched ICMP fragmentation-needed
feedback through the tunnel; blocking that feedback leaves the search
inconclusive without an observed interval. - Asymmetric return egress:
small ACKs return at all tested forward sizes, while larger same-sized
replies are accepted-but-missing or locally rejected after learned PMTU
state. All forward probes reach the receiver; the join keeps these cases
separate. The sized search still reports an inconclusive result.
Both scenarios keep non-secret JSON evidence, verify temporary namespace/key
directory cleanup and run in dedicated Python 3.10/3.12 CI jobs. They use
one kernel and deliberately configured MTUs; they do not establish behavior
on arbitrary production VPNs or measure encapsulation overhead.
Reliability and delivery
- CLI collection checks missing output directories and directory targets
before opening a receiver or sending probes. Existing regular-file
overwrite behavior remains where supported;diagnoseandsanitize
still require new outputs. - Offline commands accept UTF-8 BOM and UTF-16/UTF-32 JSON exports, including
BOM-marked PowerShell redirection. Invalid JSON names its input file;
malformed diagnosis summary/consistency containers fail cleanly. - Offline output guards compare filesystem identity, preventing a differently
named hard link from overwriting a raw input during HTML generation,
correlation or direction comparison. - Linux source snapshots preserve Unicode and raw OS-byte interface names.
HTML displays surrogate-escaped bytes without failing UTF-8 output. - The delivery matrix verifies installed report workflows with isolated
imports, including lazily loaded renderers and the packaged logo. - Retained namespace, WireGuard and OpenVPN CI artifacts include a
provenance/hash manifest, with source and
tested commit roles kept distinct. A downloaded WireGuard artifact was
checked against all 26 recorded JSON hashes during release preparation.
Install
python -m pip install --upgrade tunnelscope==0.9.0
tunnelscope --version
tunnelscope show shared/correlation.json --format markdownThe Linux/Windows delivery matrix covers Python 3.10 and 3.12. The release
suite has 134 tests; platform-specific and privileged checks require their
documented environment and opt-in flags. Runtime dependencies remain empty.
Still open
Independent operator VPN reports (#2),
a Windows receiver reached from a separate Linux host
(#28), and a
two-machine field-guide dry run remain separate follow-ups. Python 3.13 CI
is a contributor task in #33.
Timeouts, absent ICMP and missing receiver observations remain inconclusive
without supporting coverage. A small ACK does not establish same-sized return
delivery; reported size intervals are not independently measured end-to-end
path MTUs. Sanitize and review reports before sharing.
TunnelScope v0.8.2
TunnelScope v0.8.2
Patch release for report sanitization consistency, UTC display and reproducible
IPv6 feedback evidence. CLI options and report schema version 1 are unchanged.
Fixes
sanitizerecognizes label-prefixed IPv6 such assrc:fd00:77::1and
reserves documentation addresses found in that form. Older versions could
leave the original address in free text.- Interface and hostname labels avoid original names in the batch and are
replaced in one pass, so generated labels are not renamed again. Longer
known hostnames match before their prefixes. IPv6 scope IDs keep distinct,
consistent interface labels even without a separateinterfacefield. - ISO timestamps with 1–6 fractional digits parse consistently on Python
3.10 and newer. Invalid calendar values stay unrecognized text instead of
aborting sanitization. - Compact HTML timestamp cells convert nonzero offsets to UTC, matching the
column label. Full original timestamps remain in tooltips and search.
Before sharing copies produced by an older version, review label-prefixed
IPv6 and regenerate the sanitized batch from the original reports when needed.
Already sanitized files remain protected against accidental re-sanitization.
The command still cannot guarantee removal of arbitrary free-text identifiers;
read the copies before sharing them.
Validation and workflow
- The routed IPv6 lab now compares
visible and blocked Packet Too Big feedback, records receiver evidence,
and checks that the blocked size search remains inconclusive. Its recorded
output and CI artifacts retain the full observations. Offline HTML displays
both named lab cases. - The field report guide separates Linux
diagnose
and Windowsprobefilenames and explains how Ctrl+C saves a receiver log.
New real-process loopback tests exercise collection, joining, sanitization,
display and rejoining on supported platforms; Linux also checks interrupt
capture preservation. - GitHub CI checks Linux and Windows with Python 3.10 and 3.12, with privileged
IPv4/IPv6 namespace labs on Linux. Independent VPN reports and a Windows
receiver on a separate host remain open in
#2 and
#28.
Install
python -m pip install --upgrade tunnelscope==0.8.2
tunnelscope --versionTimeouts and absent ICMP remain inconclusive. These changes do not establish
an exact path MTU or identify the cause of a missing reply on an unknown path.
TunnelScope v0.8.1
Patch release that makes joined HTML reports readable and improves the package
listing.
Changes
- Joined HTML tables (probe/receiver correlation and diagnosis with receiver
evidence) put the evidence columns first: payload size, sender status,
whether the receiver saw the probe, evidence case and, for sized replies,
return evidence. Probe IDs show their first 8 characters and timestamps their
UTC time of day; the full values are in each cell's tooltip and the row
filter still matches them. In v0.8.0 these tables were about 2,200 pixels
wide and the evidence columns were off screen. The report page is now up
to 1,400 pixels wide. JSON reports are unchanged. - PyPI metadata lists the supported operating systems and tested Python
versions, networking topics, and links to the documentation, issues and
release notes. - The README image shows the joined HTML view of the recorded asymmetric
return-path lab, and the README mentions Windows receivers and the IPv6 lab.
Install
python -m pip install --upgrade tunnelscope==0.8.1
tunnelscope --versionReport formats and command-line options are unchanged from v0.8.0. See the
v0.8.0 notes for Windows receivers, the IPv6 lab and field
reports.
TunnelScope v0.8.0
Alpha release that widens return-path evidence to IPv6 and Windows receivers
and makes real-path field reports easier to contribute.
Highlights
receive --sized-replynow also runs on Windows. Sized replies are sent with
IP_DONTFRAGMENTorIPV6_DONTFRAG, so an oversized reply fails with
WSAEMSGSIZE(10040) instead of being fragmented; the receiver refuses to
start if the option cannot be set. Receiver reports record the option used
inreceiver.reply_fragmentation. See same-sized replies.- The asymmetric return-path lab runs over IPv6 with
--family ipv6. As over
IPv4, 1400-byte probes reach the receiver while their same-sized replies are
lost (ICMPv6 Packet Too Big goes to the receiver) or rejected locally, and
a small ACK at 1400 bytes still returns. CI runs both families. See the
validation record. - A field report guide and issue template describe how
to collectdiagnose --sized-replyand receiver reports on a real path,
sanitize them together and share them. - CI keeps the JSON printed by every privileged namespace lab as a workflow
artifact (lab-output-python-<version>, 90 days).
Compatibility
Report changes are additive within schema version 1. The probe protocol is
unchanged from v0.7: a v0.8 sender works with v0.7 receivers, and a v0.7
sender works with a v0.8 receiver, including on Windows.
Install
python -m pip install --upgrade tunnelscope==0.8.0
tunnelscope --versionThe package supports Python 3.10 and newer. receive --sized-reply works on
Linux (including WSL2) and Windows. DF comparisons, ICMP observation and
diagnose still require Linux.
Validation
- The full suite runs on Linux and Windows with Python 3.10 and 3.12; the
Linux jobs run the privileged labs, including both asymmetric-lab families. - On Windows, the real-receiver test returns 64-, 1400- and 8192-byte sized
replies on loopback, and a local send test turned an oversized 2000-byte
datagram intoWSAEMSGSIZEwithIP_DONTFRAGMENTset. - The field report guide's commands were run end to end on loopback.
Not yet validated
- A cross-host run with a Windows receiver: Windows Firewall blocks inbound
UDP 9471 unless a rule allows it for the test. - A maintainer dry run of the field report guide on two separate machines.
- Field evidence from production-like VPNs and routed IPv6 outside a lab
(#1,
#2).
Limits
A missing same-sized reply does not identify where or why it was lost. The
receiver is an unauthenticated UDP responder intended for controlled paths.
An observed payload interval is not an independently measured end-to-end
path MTU, and missing ACKs and absent ICMP remain inconclusive.