Telcoladder

TelcoLadder

Deterministic 5G / 4G / IMS signalling analyzer and call-flow correlator. The correlation and root-cause layer on top of tshark: one subscriber across every interface, every failure explained from a verified cause table, and nothing generated.

For core-network SRE and R&D, RAN/core interoperability test, and third-line troubleshooting at vendors and operators. It assumes you already read signalling for a living.

pip install telcoladder

telcoladder check # verifies tshark and its dissectors telcoladder summarize failed_attach.pcapng # one page of facts, every failure cited

What you get

Two outputs from one analysis. Mermaid you can paste into a ticket:

sequenceDiagram

autonumber participant gNB participant AMF Note over gNB,AMF: SUPI 001011234567895 gNB->>AMF: #35;7 InitialUEMessage ▸ Registration request AMF->>gNB: #35;8 DownlinkNASTransport ▸ Authentication request rect rgb(255, 226, 226) gNB->>AMF: #35;9 UplinkNASTransport ▸ Authentication failure Note over AMF: Synch failure (#35;21) — 3GPP TS 24.501 §9.11.3.2 end rect rgb(255, 226, 226) AMF->>gNB: #35;10 DownlinkNASTransport ▸ Registration reject Note over gNB: Protocol error, unspecified (#35;111) — 3GPP TS 24.501 §9.11.3.2 end

That is real output from tests/fixtures/ki-mismatch, not an illustration: a UE provisioned with the wrong key, captured on a local Open5GS testbed. It is not the MAC failure you would expect — a UE whose K does not match computes an AUTS the network cannot resynchronise from, so you get #21 and then a bare #111. The cause table says so because we ran it, not because it sounded right.

And the same capture in the browser: a packet list driven by real tshark display filters, per-frame decode tree and bytes, the ladder with the initiator and the cause on every failing event, and a per-PDU-session matrix where every cell cites the frame it came from.

What it reads

Every cause code is resolved through a hand-verified table to the specification it comes from, what it means in plain language, and the root causes that actually produce it in the field — 775 of them, every name taken verbatim from tshark and re-checked against it by a test. Nothing is generated: a cause the table does not carry is reported as not catalogued, and a clause number is printed only where a person transcribed it. Every network function is named rather than shown as an IP, with the evidence for that name on hover.

The pain, and what replaces it

Quickstart: five ways in

Windows without Python? Skip pip and jump to

4. Windows, no install — the only prerequisite is Wireshark.

# 1. CLI — one page of deterministic facts, Markdown or JSON

telcoladder summarize capture.pcapng telcoladder analyze capture.pcapng -o flow.mmd # Mermaid, byte-for-byte reproducible

2. Browser — drop a capture, or paste a path for anything large

telcoladder serve # http://127.0.0.1:3005

3. AI agent — the same facts as MCP tools over stdio

claude mcp add telcoladder -- telcoladder mcp

4. Windows, no install. A standalone executable in a portable zip, built by CI from the tagged source. Nothing is installed and no registry key is written; it needs Wireshark 4.0 or newer on the machine, nothing else.

1. Download and unzip. Get TelcoLadder-Windows-x64.zip (about 10 MB) from the Releases page.
2. Double-click `check-environment.cmd`. It finds tshark.exe in Wireshark's default install location under Program Files — or wherever TELCOLADDER_TSHARK points — and checks the dissectors.
3. Run it from that folder.

   telcoladder.exe summarize capture.pcapng

telcoladder.exe serve

   `serve` listens on `http://127.0.0.1:3005`: open it in your browser, drop a

capture (up to 1 GB), or paste a path for anything larger.

5. Hand a capture to someone else. telcoladder anonymize in.pcap out.pcap rewrites subscriber identities, addresses, hostnames, PLMN and cell identifiers into keyed pseudonyms of the *same length* — TBCD, ASCII, JSON and HPACK-Huffman alike — recomputes every checksum, then re-reads its own output and refuses to keep it if any original value is still visible. The output walks the same pipeline to the same procedures, roles and failures; only the names differ. Same key, same pseudonyms across captures; the key is printed once and never written down. Compressed HTTP/2 bodies cannot be rewritten in place and are refused unless --blank-opaque-bodies.

Requires Python 3.11+ and tshark (Wireshark 4.0 or newer) for the pip route. Neither the macOS nor the Windows installer puts tshark on your PATH; TelcoLadder looks in the standard install directories and finds it anyway, or takes TELCOLADDER_TSHARK. The venv-by-venv Windows walkthrough is in the user guide.

Five things it does that a decoder does not

Cross-interface correlation. A subscriber is a union of identity keys, each with the right scope: NGAP and S1AP UE IDs are unique only within one association, TEIDs and TMSIs are reallocated and treated as episodes, and the GTP-U tunnel endpoint is one definition shared by NGAP, PFCP, GTP-U and now S1AP. The failure mode of a wrong key is two people in one flow with a ladder that still renders, so the key shapes are tested against captures built to provoke exactly that.

775 verified causes. Names from tshark -G values, re-checked by tests on every CI platform; two Diameter number spaces kept apart; NGAP and S1AP cause groups looked up in the group the message selected. Ordered-sequence rules written by people — #21 followed by #111 is a key mismatch, not a sequence problem — are matched and reported with the frames.

Fault attribution. UEContextReleaseRequest is only ever sent by the RAN and the release Command only by the core; the ladder, the procedure list and the xDR say which one started it. The reason still comes from the cause table; there is no second verdict string.

Timer match and blast radius. An unanswered network request followed by a release or reject a timer's default later is reported as *consistent with* that timer — never as a proven timeout, because the capture shows timing and not the AMF's state. With several subscribers, failures are counted by TAC, cell, DNN and core-side element; an unknown location is a null row, not a dropped one.

Air-gapped by construction. serve binds 127.0.0.1 and checks the Host header; the MCP server is stdio only; the browser bundle ships in the package and loads nothing from the network; there is no telemetry and no model. What the tool could not read — ciphered NAS, ECIES-protected SUCIs, TLS on SBI, frames no dissector claimed — is counted and stated before any conclusion.

Three scenarios from the test captures

Each of these is a fixture in tests/fixtures/ you can run yourself.

1. A key mismatch that does not look like one — ki-mismatch. Synch failure (#21) then a bare protocol error (#111). The sequence rule in the cause table names the real cause and says what does *not* fix it: resetting the SQN. telcoladder summarize tests/fixtures/ki-mismatch/capture.pcap
2. A context released 6.000 s after an unanswered Authentication request — 5gc-context-release. The release is marked as ordered by the core, and the gap is reported as consistent with T3560's default. The second subscriber in the same file is released at the gNB's request after the radio link was lost, and is marked as such.
3. A 5GS → EPS handover the target eNB refuses — n26-handover. Five elements on one ladder; the failure appears three times on the wire (S1AP HandoverFailure, the N26 Forward Relocation Response, the NGAP HandoverPreparationFailure) and is explained once, from the S1AP table, with the specification named and no clause invented.

What it does today

• Reads all three generations from one `pcap` / `pcapng` via tshark.
• Names the network functions and shows the IP when the evidence is ambiguous rather than guessing. Relays — a 5G SCP, a Diameter DRA, a SIP proxy — keep their own lane and are never credited with the services behind them.
• Correlates one subscriber across identifiers and across protocols, with the scopes described above. On a production trace with TLS on SBI and ECIES-protected SUCIs the N2 side still forms its own per-UE flow; what could not be read is counted and reported, not silently dropped.
• Splits a subscriber's traffic into scenarios — registration, att