The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Telcoladder listing page.
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.

Two outputs from one analysis. Mermaid you can paste into a ticket:
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.

| 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), SGsAP (SGs) | 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.
| 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 |
| VoLTE Gm signalling hidden inside IPsec ESP | NULL-encrypted ESP is detected and decoded, so the SIP and SDP inside join the subscriber's ladder. ESP that is really encrypted stays unreadable and is counted, not guessed |
| A B2BUA (an AS, or an SBC that keeps the charging ID) changes the Call-ID, so one call shows up as unrelated dialogs | Legs that share a charging ID (ICID) and overlap in time are one call, end to end — H.248, HSS, charging and ENUM attached only where evidence ties them to that call |
| 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 |
Windows without Python? Skip
pipand jump to 4. Windows, no install — the only prerequisite is Wireshark.
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.
TelcoLadder-Windows-x64.zip (about 10 MB) from
the Releases page.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.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.
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.
Each of these is a fixture in tests/fixtures/ you can run yourself.
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.pcap5gc-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.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.pcap / pcapng via tshark.ended-by-user rather than a failure — a classification that lives in the
cause table, not in code.--xdr) and a pinned-field JSON summary,
both byte-for-byte reproducible, so jq can answer "what is the failure rate
across this batch".--lang zh_TW, or the switch in
the browser), deliberately never the system locale: the same command must
print the same words on two machines, because output gets pasted into tickets.tshark to find;
adapters declare the common cases and --decode-as covers the rest.On a large capture, narrow before you draw:
Whatever narrowing could not reach is listed explicitly, never silently
dropped. Dissection runs at roughly 0.19 s/MB and is linear (a 145 MB, 780k-frame
file in 28 s on one machine); tshark output is streamed, so memory follows the
messages kept rather than the file size.
These tools came first and are worth your time. TelcoLadder is not trying to replace them.
| Project | What it does | Why TelcoLadder still exists |
|---|---|---|
| telekom/5g-trace-visualizer | pcap → SVG sequence diagrams for 5GC (HTTP/2, NAS, PFCP). Deutsche Telekom, Apache-2.0. | Unmaintained since Aug 2023. PlantUML output needs plantuml.jar; driven from Jupyter notebooks with a large config surface aimed at k8s deployments. |
| irontec/sngrep | Excellent, actively maintained ncurses SIP flow viewer. | Terminal-only and SIP-only — you cannot paste its output into a document, and it does not touch 5G. |
| sipcapture/homer | Full capture platform: server, agents, database, web UI. | It is infrastructure you deploy and operate. TelcoLadder is a command you run against one file. |
| dgudtsov/pcap2uml | IMS call flows across SIP/Diameter/MAP/CAMEL → PlantUML. | The closest in spirit. No 5G support (no NGAP/NAS-5GS), PlantUML output. |
| agranig/pcap2mermaid | SIP → Mermaid, in Perl. | Two days of commits in January 2019, then nothing. It proved people want this; nobody picked it up. |
What none of them do together: 5G and 4G and IMS in one correlated diagram, Mermaid as the output, and a verified explanation of what went wrong.
tshark preferences
pass straight through (--tshark-pref tls.keylog_file:…), so a key log can be
supplied as in Wireshark, but no TLS fixture exists here and that path is not
covered by the tests. N2 is unaffected either way.3gpp-Sbi-Target-apiRoot is
indistinguishable from the endpoint and falls back to an unlabelled IP. The
correct failure direction, and a real gap.Contact that carries a
subscriber identity; an I-CSCF, S-CSCF or AS is named only when its Cx or Sh
exchange is in the same capture. Gm is the only SIP
reference point labelled — Mw and ISC are not, because no capture here has
verified them. H.248 gets neutral MGC / MGW roles and no reference point,
because the protocol alone cannot say whether it is Iq, Mn or Mp.P-Access-Network-Info declares them; without that header the access
is reported as not declared.tshark
as the oracle: exact about the protocol, silent about any real deployment.
Each scenario.md lists what its fixture cannot prove. UE radio capability
is not parsed: the NR and LTE RRC containers are skipped during extraction
because dissecting them is slow, and stay readable in the per-frame decode
tree.--max-messages; truncation
is always stated inside the diagram.anonymize proves absence only for what tshark can name. Identities it
never decoded stay where they are; TLS payloads are opaque; gzip bodies and
bodies reassembled across DATA frames are refused rather than guessed at;
IPv6 text and binary forms, and TAC text and binary forms, are pseudonymised
independently. The report lists every one of these.A flow missing three messages looks exactly like a correct one, so the suite
cross-checks against tshark as an independent oracle rather than only
asserting on its own parse: message counts, procedure and message names, every
cause table, and the identity keys of the fixtures built to provoke a wrong
merge. New tests are mutation-checked — the code is broken on purpose and the
test must go red. Every push runs the full suite on Python 3.11, 3.12 and 3.13
on Linux with tshark 4.2, and on macOS and Windows with tshark 4.6; the badge at
the top is live. What the badge does not cover is named at the top of
.github/workflows/ci.yml.
There is no network path out of this tool. The analysis is a child tshark
process reading a file; serve binds the loopback address only and refuses
other Host headers; the MCP transport is stdio; the browser bundle is packaged
with the code and references no external resource; nothing phones home and no
model is involved anywhere in the pipeline. Uploaded captures are kept in the
system temp directory with mode 0600 until released or idle-expired, and for
anything large you paste a path so nothing is copied at all.
The engine — streaming architecture and its measured throughput, the identity model and key recycling, the cause library and its oracle discipline, the N26 stitching, release attribution, timers — is written up in docs/deep-dive.md. The operating guide for real captures is docs/user-guide.md; the contract for adding a protocol is docs/plugin-contract.md; the contract for an agent using the tool is AGENTS.md.
CONTRIBUTING.md is short. It has two rules that matter
more than anything else in it: no real subscriber or customer data, anywhere,
and every spec clause is verified by a human, never generated.
Found a vulnerability? SECURITY.md — not a public issue.
PolyForm Noncommercial License 1.0.0. See LICENSE.
Free for personal, non-commercial, and educational research use. Commercial deployment, commercial distribution, or embedding into for-profit offerings requires a separate commercial licence: open a GitHub issue titled "Commercial licence" or contact the maintainer through the repository, and expect a reply on terms rather than a form.
Release 0.1.0 was published under Apache-2.0 and remains available under those
terms. Third-party material keeps its own licence: the browser bundle's
dependencies (MIT/ISC, listed in NOTICE) and the http2-multistream
fixture (Apache-2.0, Deutsche Telekom).