v0.2.0 - B2B Signalling Correlation, Windows Portable & 3GPP Diagnostics

The correlation and root-cause layer on top of tshark: one subscriber's
session across 5G, 4G and IMS on a single ladder, every failure explained from
a table a person verified.

Windows x64 portable zip

TelcoLadder-Windows-x64.zip is attached below. Unzip and run
telcoladder.exe — nothing is installed, no registry key is written, delete
the folder to remove it. It needs Wireshark 4.0 or newer on the machine
for tshark.exe: found in its default location automatically, or pointed at
with TELCOLADDER_TSHARK. Wireshark is deliberately not bundled — it is
GPL-2.0 and ships its own dissector set. check-environment.cmd runs first
and says whether tshark and the dissectors were found.

The zip is built by CI from this tag and smoke-tested in the same job with a
real tshark: check, a rendered fixture, and a known cause looked up.

Cross-interface: the N26 5GS-to-EPS handover (#32)

One subscriber's handover stitched across NGAP, NAS-5GS, S1AP and GTPv2-C into
a single flow, five network elements on one diagram. The target side carries
no IMSI — it joins through the S1-U SGW F-TEID that the Create Session
Response hands to the MME and the MME places in the E-RAB. Preparation and
execution times are reported per handover segment.

3GPP timer matching and blast radius (#31)

A silent gap that matches a network-side NAS timer is now named as one:
T3550 / T3560 / T3570 / T3555 / T3522 (TS 24.501) and T3450 / T3460 / T3470 /
T3422 (TS 24.301), matched within ±15%. UE-side timers are deliberately
excluded — a capture sees the network's own retransmission behaviour, not the
handset's clock.

Failures are clustered by TAC, cell, DNN and core-side element, so a
multi-subscriber capture answers where the failures sit, not only how many
there are.

Release attribution: RAN or core (#30)

A UE context release now says who asked for it — a UEContextReleaseRequest
from the gNB/eNB is RAN-initiated, a UEContextReleaseCommand from the
AMF/MME is core-initiated. RRC establishment cause, handover type, TAC and
cell identity are extracted alongside and reach both the ladder and the xDR
export.

Licence: PolyForm Noncommercial 1.0.0 (#29)

Free for personal, non-commercial and educational research use. Commercial
deployment requires a separate licence — open an issue titled
"Commercial licence".

Front page rewritten for people who read signalling for a living (#33)

Aimed at core-network SRE, RAN-to-core interop testing and third-line
troubleshooting: a pain-versus-relief table, four ways in (CLI, browser,
Windows portable, MCP), five things a protocol decoder cannot do for you, and
three scenarios that each run against a fixture committed in this repository.
docs/deep-dive.md is new — streaming architecture, the identity model,
the cause library's oracle discipline, and what the tool cannot see.

Offline by construction

No network calls, no telemetry, no model. Cause explanations come from static
YAML tables checked against tshark -G values; the tool never produces a 3GPP
clause number that a person has not verified, and says "not catalogued"
instead. serve binds 127.0.0.1 only and MCP speaks stdio.

Verified

1,167 tests, no skips, across five platform and Python combinations, with
tshark 4.2 and 4.6 as the oracle.

Full changelog: v0.1.0...v0.2.0

v0.1.0

First tagged release.

TelcoLadder turns a telecom signalling capture into each subscriber's call
flow, with every failure explained — the cause code resolved to the 3GPP
clause it comes from, plus the most common field causes.

Highlights

• 10 protocol adapters across three generations on one timeline:
  5G core (NGAP, NAS-5GS, HTTP/2 SBI, PFCP, GTP-U), 4G/EPC (S1AP, NAS-EPS,
  GTPv2-C) and IMS (SIP), plus Diameter (S6a, Cx/Dx, Gx)
• Per-subscriber correlation — identifiers are scoped and lifecycle-aware,
  so recycled TEIDs and reused RAN UE IDs do not merge strangers into one flow
• Explanations with provenance: cause → 3GPP clause always comes from a
  static, human-verified table — never generated
• Three outputs: Mermaid sequence diagrams (paste into GitHub), an
  interactive browser viewer (telcoladder serve, light/dark), and an MCP
  server so AI agents can query captures as tools
• 723 tests, cross-validated against tshark as an independent oracle, on
  Linux / macOS / Windows CI

Known gaps (stated, not hidden)

• 4G cause numbers are extracted but not yet catalogued — describe() answers
  honestly instead of inventing an explanation
• Ciphered NAS and ECIES-protected SUCIs are reported as blind spots, per
  capture

Install

pip install telcoladder     # requires Python 3.11+ and tshark (Wireshark 4.0+)
telcoladder check