telcoladder

TelcoLadder

确定性的 5G / 4G / IMS 信令分析器和呼叫流程关联工具。 构建于 tshark 之上的关联与根因分析层：跨所有接口追踪同一用户，依据经过验证的原因表解释每一次失败，并且不生成任何内容。

面向核心网 SRE 和研发团队、RAN/核心网互通测试，以及厂商和运营商的三线故障排查。默认你已熟练阅读信令。

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

你将获得什么

一次分析，生成两种输出。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

这是来自 tests/fixtures/ki-mismatch 的真实输出，并非示意图：在本地 Open5GS 测试环境中抓取了一个配置了错误密钥的 UE。这并不是你所预期的 MAC 失败——K 不匹配的 UE 会计算出网络无法据此重新同步的 AUTS，因此会先出现 #21，随后是一个没有具体原因的 #111。原因表之所以这样说明，是因为我们实际验证过，而不是因为听起来合理。

同一份抓包也可在浏览器中查看：由真实 tshark 显示过滤器驱动的分组列表、每帧的解码树和字节、标注了发起方且为每个失败事件说明原因的梯形图，以及一个逐个 PDU 会话列出各单元格来源帧的矩阵。

可读取的内容

代际	协议	原因说明
5G 核心网	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（呼叫、KPI）、Diameter、H.248/MEGACO	333

每个原因码都会通过人工核验的表格进行解析，表格列明其所属规范、通俗含义，以及在实际网络中确实会导致该原因码的根因——共 775 个。每个名称都直接取自 tshark，并由测试再次核验。所有内容均非自动生成：表格未收录的原因会标记为未编入目录；仅当条款编号由人工转录时才会显示。每个网元都会显示其名称而非 IP 地址，悬停时还会显示该名称的证据。

痛点，以及替代方案

现状	使用 TelcoLadder 后
在不同窗口间手动复制 UE ID，以跟踪一位用户	在一个流程中查看一位用户的完整生命周期：SUPI、5G-S-TMSI、NGAP 和 S1AP UE ID、TEID、Call-ID——并将已回收的密钥视为已回收
N2 和 SBI 分别保存在不同的抓包中，无法对齐	在同一时间线上串联 N2、SBI 和 N4；N4 通过 UPF 分配并由 NGAP 转发的 GTP-U 隧道端点关联
一次 N26 切换分散在 NGAP、N26、S11 和 S1AP 中	将四者整合到同一段中，通过 S1-U SGW F-TEID 关联；MME 会将其从 Create Session Response 复制到 HandoverRequest
只有一个原因编号，还得去查规范	提供 775 种原因，注明规范名称、通俗说明和字段级根因；对人工核对过的内容标注对应条款
RAN 和核心网互相指责，称对方丢弃了上下文	每次 UE 上下文释放都会标明是由 RAN 请求还是由核心网指令——这是线路上的事实，而非主观判断
某个流程莫名其妙地停滞	当延迟符合 NAS 定时器默认值（T3560、T3460 …）时，指出对应定时器；并按 TAC、小区、DNN 和核心网网元统计失败
隐藏在 IPsec ESP 中的 VoLTE Gm 信令	检测并解码 NULL 加密的 ESP，让其中的 SIP 和 SDP 能关联到用户信令流程。真正加密的 ESP 仍不可读，只会被统计，不会被猜测
B2BUA（AS，或保留计费 ID 的 SBC）会更改 Call-ID，导致同一个通话显示为互不相关的对话	共享计费 ID（ICID）且时间重叠的呼叫段会被视为同一个端到端通话——仅在证据能将 H.248、HSS、计费和 ENUM 与该通话关联时才附加这些信息
绝不能离开办公场所的客户抓包	在你的机器上运行命令：除 127.0.0.1 外不监听网络，无遥测、无云端、无模型

快速入门：五种使用方式

没有 Python 的 Windows 用户？ 跳过 pip，直接前往 4. Windows，无需安装——唯一的前置条件是 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，无需安装。 独立可执行文件打包在便携式 zip 中，由 CI 根据 已标记的源代码构建。无需安装，也不会写入注册表项；只需机器上安装 Wireshark 4.0 或更新版本，无需其他依赖。

1. 下载并解压。 从 Releases 页面获取 TelcoLadder-Windows-x64.zip（约 10 MB）。
2. 双击 check-environment.cmd。 它会在 Program Files 下的 Wireshark 默认安装位置找到 tshark.exe——或者查找 TELCOLADDER_TSHARK 指定的位置——并检查协议解析器。
3. 在该文件夹中运行。

   telcoladder.exe summarize capture.pcapng
   telcoladder.exe serve
   

   serve 会监听 http://127.0.0.1:3005：在浏览器中打开该地址，拖入抓包文件（最大 1 GB），或粘贴路径以处理更大的文件。

5. 将抓包交给他人。 telcoladder anonymize in.pcap out.pcap 会将用户身份、地址、主机名、PLMN 和小区标识符改写为带密钥的伪名，且长度相同——无论是 TBCD、ASCII、JSON 还是 HPACK-Huffman 格式；随后重新计算每个校验和，再重新读取输出文件；如果仍能看到任何原始值，就会拒绝保留该文件。输出文件经过同一处理流程，得到相同的过程、角色和失败结果；变化的只有名称。相同的密钥会在不同抓包中生成相同的伪名；密钥只打印一次，不会写入文件。压缩的 HTTP/2 正文无法原地改写；除非使用 --blank-opaque-bodies，否则会拒绝处理。

使用 pip 方式需要 Python 3.11+ 和 tshark（Wireshark 4.0 或更新版本）。macOS 和 Windows 安装程序都不会将 tshark 放入 PATH；TelcoLadder 会在标准安装目录中查找并找到它，也可以使用 TELCOLADDER_TSHARK 指定路径。Windows 虚拟环境逐步操作指南见 用户指南。

解码器做不到的五件事

跨接口关联。 订户由一组身份键定义，每个键都有合适的作用范围：NGAP 和 S1AP UE ID 仅在单个关联内唯一；TEID 和 TMSI 会重新分配，因此按会话处理；GTP-U 隧道端点则是 NGAP、PFCP、GTP-U 以及现在的 S1AP 共用的一种定义。错误键导致的问题是同一条流程中出现两个人，而时序图仍能正常渲染，因此我们会用专门构造来触发这类问题的抓包来测试键的形态。

775 个经验证的原因。 名称取自 tshark -G values，并由测试在每个 CI 平台上重新验证；两个 Diameter 编号空间分别处理；NGAP 和 S1AP 原因组会在消息所选定的组中查找。由人编写的有序序列规则——#21 后接 #111 是键不匹配，而不是序列问题——会与帧一起匹配并报告。

故障归因。 UEContextReleaseRequest 只由 RAN 发送，Release Command 则只由核心网发送；时序图、过程列表和 xDR 会指出是哪一方发起的。原因仍取自原因表；不会另给一条判定字符串。

定时器匹配与影响范围。 未应答的网络请求之后，若在某个定时器默认时长过后收到释放或拒绝消息，系统会报告这与该定时器相符——绝不会断言超时已获证实，因为抓包显示的是时间，而不是 AMF 的状态。存在多个订户时，故障会按 TAC、小区、DNN 和核心网侧网元统计；未知位置会作为 null 行保留，而不会被丢弃。

从设计上实现物理隔离。 serve 绑定到 127.0.0.1 并检查 Host 标头；MCP 服务仅使用 stdio；浏览器资源包随软件包一同分发，不会从网络加载任何内容；没有遥测，也没有模型。工具无法读取的内容——加密的 NAS、受 ECIES 保护的 SUCI、SBI 上的 TLS、没有任何解析器认领的帧——都会计数，并在给出任何结论之前说明。

测试抓包中的三个场景

以下每个场景都是 tests/fixtures/ 中的一个测试样例，你可以自行运行。

1. 看起来不像键不匹配的键不匹配 — ki-mismatch。同步失败（#21）后接一条不带具体信息的协议错误（#111）。原因表中的序列规则指出了真正的原因，并说明什么做法不能解决问题：重置 SQN。telcoladder summarize tests/fixtures/ki-mismatch/capture.pcap
2. Authentication 请求未获应答后 6.000 s，上下文被释放 — 5gc-context-release。释放被标记为由核心网发起，时间间隔被报告为与 T3560 的默认时长相符。同一文件中的第二个订户在无线链路丢失后，于 gNB 发起请求时被释放，并据此标记。
3. 目标 eNB 拒绝的 5GS → EPS 切换 — n26-handover。一条时序图上有五个网元；故障在线路上出现三次（S1AP HandoverFailure、N26 Forward Relocation Response、NGAP HandoverPreparationFailure），但只解释一次，依据 S1AP 表，注明规范，不杜撰条款。

当前功能

• 通过 tshark 从一个 pcap / pcapng 中读取三代网络的数据。
• 识别网络功能；证据模糊时显示 IP，而不是猜测。中继设备——5G SCP、Diameter DRA、SIP 代理——各司其职，绝不会被误认为提供了其后方的服务。
• 按上述范围，跨标识符和协议关联同一订阅用户。在 SBI 使用 TLS 且 SUCI 受 ECIES 保护的生产跟踪中，N2 侧仍会形成独立的每 UE 流；无法读取的内容会被统计并报告，不会被悄悄丢弃。
• 将订阅用户的流量拆分为各个场景——注册、附着、PDU 会话、服务请求（由 UE 或网络触发）、专用承载建立、修改和释放、注销、切换（包括已取消的切换，这不算失败）、空闲态移动性、IMS 注册和呼叫——每个场景都包含结果、原因、首次失败、持续时间，以及适用时的发起方、匹配的定时器或切换准备和执行时间。分类依据是订阅用户正在进行的操作，而不是承载该操作的协议：附着中的 S6a 交互属于该附着，结束某个场景的上下文释放属于该场景（其发起方和原因会一并记录，xDR 仍会将释放单独列为一行），HSS 返回“用户未知”则是该附着的失败。若某个 Diameter 交互不属于任何场景，就会作为独立的 HSS 发起交互显示——S6a/Gx 归入 4G，Cx/Sh 归入 IMS，具体由 Application-Id 决定。
• 通过 DRA 读取 Diameter：涵盖 S6a/S6d、Cx/Dx、Sh、Rx、Gx、SWx 和 S6b；根据发起各命令的一方判定角色；若在中继两侧都观察到请求，则显示为包含两跳的单笔事务；中继转发的失败只统计一次。
• 将 SIP 呼叫视为一个过程，记录响铃时间、接听时间和通话时间、释放方及原因；忙线或拒接的被叫会归类为 ended-by-user，而非失败——此分类定义在原因表中，而不是代码里。
• 导出过程记录（--xdr）和固定字段的 JSON 摘要；两者均可逐字节复现，因此可用 jq 查询“这批数据的失败率是多少”。
• 支持英语或繁体中文（--lang zh_TW，或在浏览器中切换），有意不使用系统区域设置：同一条命令在两台机器上必须输出相同的文字，因为输出会被粘贴到工单中。
• 需要指定非标准端口。如果抓包开始时 TCP 连接已经建立，tshark 就找不到 HTTP/2 前导；适配器会声明常见情况，其余情况由 --decode-as 处理。

处理大型抓包时，应先缩小范围再绘图：

telcoladder analyze big.pcapng --subscriber 001011234567895
telcoladder analyze big.pcapng --since 120 --until 180
telcoladder analyze big.pcapng --filter 'ngap || s1ap'      # any tshark display filter

无法通过缩小范围处理的内容会明确列出，绝不会被悄悄丢弃。解码速度约为 0.19 s/MB，且呈线性增长（一台机器上，145 MB、78 万帧的文件耗时 28 s）；tshark 的输出采用流式处理，因此内存占用取决于保留的消息数量，而非文件大小。

既有工具，以及为什么它仍有存在的意义

这些工具问世更早，也值得你花时间了解。TelcoLadder 并不打算取代它们。

项目	功能	TelcoLadder 仍有存在意义的原因
telekom/5g-trace-visualizer	将 pcap 转换为 5GC 的 SVG 时序图（HTTP/2、NAS、PFCP）。由 Deutsche Telekom 开发，采用 Apache-2.0 许可证。	自 2023 年 8 月起便无人维护。PlantUML 输出需要 plantuml.jar；该工具通过 Jupyter notebook 驱动，配置项繁多，主要面向 k8s 部署。
irontec/sngrep	出色且持续维护的 ncurses SIP 流查看器。	仅限终端且仅支持 SIP——你无法将其输出粘贴到文档中，它也不涉及 5G。
sipcapture/homer	完整的抓包平台：服务器、Agent、数据库和 Web UI。	这是需要部署和运维的基础设施。TelcoLadder 则是一个针对单个文件运行的命令。
dgudtsov/pcap2uml	将 IMS 呼叫流程中的 SIP/Diameter/MAP/CAMEL 转换为 PlantUML。	理念上最接近的工具。不支持 5G（没有 NGAP/NAS-5GS），输出为 PlantUML。
agranig/pcap2mermaid	使用 Perl 将 SIP 转换为 Mermaid。	2019 年 1 月有两天提交记录，之后便再无动静。它证明了人们需要这样的工具，却无人接手。

这些工具都无法同时做到：在一张关联图中呈现 5G 、 4G 和 IMS，使用 Mermaid 作为输出，并验证对故障原因的解释。

坦诚说明局限性

• SBI 仅针对一种部署完成验证：使用 SCP 的 Open5GS，且仅适用于空方案 SUCI 和明文 h2c。生产环境中的 SBI 通常使用 TLS：这些帧会按端口计入 不可见。tshark 偏好设置会直接传递（--tshark-pref tls.keylog_file:…），因此可以像在 Wireshark 中一样提供密钥日志，但此处没有 TLS 测试样例，也未通过测试覆盖这条路径。无论哪种情况，N2 都不受影响。
• 完全透明且不发送 3gpp-Sbi-Target-apiRoot 的 SCP 无法与端点区分，因此会退回到未标注的 IP。这是正确的失败方向，也是一个真实的缺口。
• Diameter 覆盖七种接口，并为其提供角色和精选的原因值（S6a/S6d、Cx/Dx、Sh、Rx、Gx、SWx、S6b）；其余接口（包括 Rf）会被解码并显示其 Application-Id，但不会推断角色。所有 Diameter 测试样例均根据 RFC 6733 编写，而非抓包所得：仅使用 TCP，不含 SCTP，时间信息为虚构。
• 四条行为规则没有抓包作为依据。 S10 跨 MME 切换、Xn/X2 路径切换、CS 回落，以及呼叫期间的 Cx 认证延迟，均根据消息名称编写，且仅由合成测试覆盖；它们在真实抓包中的表现尚未测量。故障前显示的链条表示单个片段内的消息顺序，并不能证明因果关系。
• 仅凭 SIP 无法确定核心代理的名称。 UE 和 P-CSCF 信息来自 Gm 本身——依据安全协商标头，或与多个对端建立 IPsec 关联的地址；若无法据此确定，则回退到带有用户身份的 Contact。只有当同一抓包中包含 I-CSCF、S-CSCF 或 AS 的 Cx 或 Sh 交互时，才会标注它们。Gm 是唯一标注的 SIP 参考点——未标注 Mw 和 ISC，因为此处没有抓包验证过它们。H.248 使用中性的 MGC / MGW 角色，不标注参考点，因为仅凭协议无法判断它是 Iq、Mn 还是 Mp。
• 只有在有证据时，才会关联呼叫和号码。 只有当 B2BUA 呼叫段共用同一个计费 ID（ICID），且时间上有重叠时，才会合并为一个呼叫；如果 B2BUA 或 SBC 替换了 ICID，则会保留为独立行。只有国际格式的号码才会与 HSS、计费和 ENUM 记录关联；绝不会用猜测的国家代码补全本地格式的号码。只有在 P-Access-Network-Info 声明时，才会显示 VoLTE、VoNR 和 VoWiFi；没有该标头时，接入方式会报告为未声明。
• 21 张原因值表中，只有 9 张引用了条款。 其余 12 张仅列出规范名称。缺少条款也好过引用错误条款。
• 4G、IMS 和切换测试样例均逐字节编写，并以 tshark 为判定依据：协议内容精确，但不代表任何真实部署。每个 scenario.md 都会列出其测试样例无法证明的内容。不会解析 UE 无线能力：提取期间会跳过 NR 和 LTE RRC 容器，因为解剖这些容器速度较慢；但它们仍可在逐帧解码树中查看。
• Security Mode Command 之后的 NAS 已加密，其内容不可见；这些数据包仍会以 NGAP 承载消息的形式显示。Gm 上的 IPsec ESP 也一样：只会读取 NULL 加密的 ESP，加密的 ESP 会计为不可读。GTP-U 会关联用户，但不提供吞吐量或丢包 KPI；没有 RTP 适配器；ISUP 和 CAMEL 会被识别，但不会被读取。
• 通过 SBI 消息中引用的隧道进行关联，属于推断。 关联依据为方向和时间窗口，绝不会跨越释放事件，也不会导致一个流对应两个 SUPI；摘要会统计每次此类关联。仍存在一种可能：某条过期的转发引用在隧道释放后到达，而 UPF 在 10 s 内为一个流未显示 SUPI 的 UE 重用了完全相同的 TEID，此时仍可能发生关联。在单个抓包点上，这种顺序违反协议。
• 流量非常大时，Mermaid 会变慢。 使用 --max-messages；图表中始终会注明发生了截断。
• anonymize 只能证明 tshark 能识别的内容已被匿名化。 从未解码的身份信息会原样保留；TLS 负载是不透明的；gzip 消息体和跨 DATA 帧重组的消息体会被拒绝处理，而不会猜测其内容；IPv6 的文本和二进制形式，以及 TAC 的文本和二进制形式，会分别进行假名化。报告会列出上述每一项。

验证方式

缺少三条消息的流程看起来与正确流程完全一样，因此测试套件会将结果与 tshark 交叉核对，把它作为独立的判定依据，而不只是断言自身的解析结果：消息数量、过程和消息名称、每张原因表，以及为诱发错误合并而构建的测试样例的身份键。新测试会经过变异测试——故意破坏代码，测试必须失败。每次推送都会在 Linux 上使用 Python 3.11、3.12 和 3.13 以及 tshark 4.2 运行完整测试套件，并在 macOS 和 Windows 上使用 tshark 4.6 运行；顶部的徽章会实时更新。徽章未覆盖的内容列在 .github/workflows/ci.yml 顶部。

从设计上实现气隙隔离

此工具没有任何外部网络连接路径。分析由读取文件的子 tshark 进程执行；serve 仅绑定回环地址，并拒绝其他 Host 标头；MCP 传输使用 stdio；浏览器包与代码一起打包，不引用外部资源；不会回传任何数据，整个流程也不会涉及任何模型。上传的捕获文件会以 0600 权限保存在系统临时目录中，直到文件被释放或因闲置超时而过期；对于较大的文件，你可以粘贴路径，因此根本不会复制文件。

深入了解

docs/deep-dive.md 介绍了引擎的流式架构及其测得的吞吐量、身份模型和键回收、原因库及其判定依据规范、N26 拼接、发布归因和计时器。真实捕获文件的操作指南见 docs/user-guide.md；添加协议的规范见 docs/plugin-contract.md；Agent 使用此工具的规范见 AGENTS.md。

贡献与问题报告

CONTRIBUTING.md 内容很简短。其中有两条规则比其他内容都重要：任何地方都不得使用真实的订阅者或客户数据，以及每条规范条款都必须由人工验证，绝不允许自动生成。

发现漏洞？请参阅 SECURITY.md——不要公开提交问题。

许可证

PolyForm Noncommercial License 1.0.0。详见 LICENSE。

可免费用于个人、非商业和教育研究用途。商业部署、商业分发或嵌入营利性产品，均须另行获得商业许可证：请创建标题为 "Commercial licence" 的 GitHub issue，或通过代码仓库联系维护者；请做好收到关于许可条款的回复而非填写表单的准备。

Release 0.1.0 依据 Apache-2.0 发布，仍可按该许可条款使用。第三方材料保留其各自的许可证：浏览器包的依赖项（MIT/ISC，列于 NOTICE）以及 http2-multistream 测试样例（Apache-2.0，Deutsche Telekom）。