TelcoLadder

# TelcoLadder

<!-- mcp-name: io.github.gollumw/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.

[![CI](https://github.com/gollumw/TelcoLadder/actions/workflows/ci.yml/badge.svg)](https://github.com/gollumw/TelcoLadder/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/telcoladder)](https://pypi.org/project/telcoladder/)
[![Python](https://img.shields.io/pypi/pyversions/telcoladder)](https://pypi.org/project/telcoladder/)
[![Causes](https://img.shields.io/badge/3GPP_causes-775_verified_against_tshark-2563eb)](#what-it-reads)
[![Oracle](https://img.shields.io/badge/oracle-tshark_4.2_%2F_4.6_in_CI-475569)](#how-it-is-verified)
[![Offline](https://img.shields.io/badge/runtime-100%25_local%2C_no_network-16a34a)](#air-gapped-by-construction)
[![License](https://img.shields.io/badge/license-PolyForm_Noncommercial_1.0.0-red)](LICENSE)

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.

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

![Drop a capture, get each subscriber's correlated ladder — failures explained with their specification reference and the most common field causes](docs/demo.gif)

## What you get

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

```mermaid
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.

![TelcoLadder browser interface](docs/images/browser.png)

## What it reads

| Generation | Protocols | Cause explanations |
|---|---|---|
| **5G core** | NGAP, NAS-5GS, HTTP/2 SBI, PFCP, GTP-U | 206 |
| **4G / EPC** | S1AP, NAS-EPS, GTPv2-C (S11, S5/S8, N26) | 236 |
| **IMS** | SIP (calls, KPIs), Diameter, H.248/MEGACO | 333 |

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

| Today | With TelcoLadder |
|---|---|
| Copying UE IDs by hand between windows to follow one subscriber | One subscriber's whole lifetime in one flow: SUPI, 5G-S-TMSI, NGAP and S1AP UE IDs, TEIDs, Call-ID — with keys that are recycled treated as recycled |
| N2 and SBI in separate captures that never line up | N2, SBI and N4 stitched on one timeline; N4 joins through the GTP-U tunnel endpoint the UPF allocated and NGAP relayed |
| An N26 handover spread across NGAP, N26, S11 and S1AP | One segment across all four, joined through the S1-U SGW F-TEID the MME copies from Create Session Response into HandoverRequest |
| A bare cause number and a trip to the spec | 775 causes with the specification named, plain language and field root causes; clauses where a person checked them |
| RAN and core blaming each other for a dropped context | Every UE context release marked **requested by the RAN** or **ordered by the core** — a wire fact, not an opinion |
| A procedure that stalls for no visible reason | The gap named when it matches a NAS timer's default (T3560, T3460 …), and failures counted by TAC, cell, DNN and core element |
| Customer captures that must never leave the building | A command on your machine: no network listener beyond `127.0.0.1`, no telemetry, no cloud, no model |

## Thirty seconds, four ways in

```bash
# 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.** Download `TelcoLadder-Windows-x64.zip` from the
[Releases](https://github.com/gollumw/TelcoLadder/releases) page — a standalone
executable in a portable zip, built by CI from the tagged source. Unzip,
run `check-environment.cmd`, and use `telcoladder.exe` from that folder. It
needs Wireshark 4.0 or newer on the machine, nothing else.

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](docs/user-guide.md#2-installation-and-environment-check).

## 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 fo