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.
   bat

   Copy

   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.