简介本资源是一份面向网络协议开发与测试工程师、Wireshark高级使用者的实战型技术文档聚焦于利用Lua语言为Wireshark定制解析插件解决自定义UDP协议如员工ID查询服务在抓包中仅显示为原始Data的调试痛点。文档以QueryRequest/QueryResponse双消息结构为例系统讲解Proto协议注册、ProtoField字段定义、dissector函数编写、init.lua集成调用等核心步骤并结合Wireshark内置Lua 5.1引擎特性与关键APIbuffer/pinfo/tree操作展开说明附有实际抓包截图与字段映射对照。资源为单个264KB的Word文档.doc格式内容完整覆盖环境配置、协议建模、脚本实现与验证流程结构清晰、示例具体适合作为Lua扩展Wireshark的入门实践指南。目前已有371人学习下载可直接用于协议逆向分析、嵌入式通信调试及教学演示场景。1. 为什么用 Lua 写 Wireshark 插件解析自定义协议比改 C 源码更高效、更安全、更适合一线网络工程师你刚接手一个嵌入式设备的通信模块协议字段全是私有编码时间戳用 3 字节 BCD、状态位分散在 4 个不同字节的特定比特、校验和是异或再加 0x55。Wireshark 默认不识别它tcpdump 抓出来只有一堆十六进制。有人建议你去编译 Wireshark 源码、修改epan/dissectors/下的 C 文件——但你不是底层协议栈开发者没有时间搭编译环境、跑 test suite、处理 ABI 兼容性也有人提议用 Python 脚本后处理 pcap 文件——可这样就失去了实时着色、过滤器myproto.status 3、会话追踪Follow TCP Stream这些关键分析能力。Lua 插件正是这个场景的黄金解法它直接运行在 Wireshark 进程内共享所有协议树proto_tree、字段注册hf_register_info、解码上下文tvbuff_t却无需重新编译主程序。Ubuntu 上sudo apt install wireshark tshark lua5.3-dev后一个.lua文件丢进插件目录就能生效。本文面向已能用 Wireshark 抓包、熟悉基础协议分层如 TCP/IP、但没碰过 C 协议解析器的网络运维、IoT 测试、工控协议调试人员手把手带你从零写出可调试、可发布、能通过tshark -r trace.pcap -Y myproto.error精准过滤的 Lua 解析器。2. Lua 插件核心机制与 Wireshark 协议解析模型对齐为什么必须先理解 proto_tree 和 hf_register_infoWireshark 的协议解析不是简单字符串匹配而是一套基于“协议树”proto_tree的结构化展示系统。每个字段如源端口、HTTP 状态码都需预先注册为“可显示字段”registered field并绑定到特定数据类型FT_UINT16、FT_BOOLEAN、FT_STRING。Lua 插件必须严格遵循这套注册-解析-添加三步流程否则字段不会出现在 GUI 的 Packet Details 面板也无法被显示过滤器识别。这与你在 VSCode 里写 Lua 脚本完全不同——这里没有print()调试只有debug()函数输出到 Wireshark 的 ConsoleHelp → About Wireshark → Plugins → Console且所有操作必须在 Wireshark 的线程模型下安全执行。2.1 注册协议与字段用Proto和ProtoField构建协议骨架首先创建协议对象指定协议名用于过滤器和显示名GUI 中显示-- myproto.lua local myproto Proto(myproto, My Custom Protocol)接着定义所有待解析的字段。注意字段名第一个参数必须全小写、无空格、无特殊字符这是显示过滤器语法的基础显示名第二个参数可含空格和符号用于 GUI 展示第三个参数是数据类型第四个是显示格式如 BASE_DEC 表示十进制。例如针对你设备中那个 3 字节 BCD 时间戳local hf_myproto_timestamp ProtoField.uint24(myproto.timestamp, Timestamp (BCD), base.DEC, nil, 0xffffff, 3-byte BCD encoded time)提示base.DEC是显示格式不影响解析逻辑0xffffff是掩码mask表示取全部 24 位nil是值映射表value_string若需将数值转为2024-03-15字符串此处需传入{ [0x20240315] 2024-03-15 }但 BCD 解析需额外函数见 2.3 节。完整字段注册示例含状态位、校验和local hf_myproto_status_bit1 ProtoField.boolean(myproto.status.bit1, Status Bit 1, base.NONE, {Yes, No}, 0x01, Bit 0 of status byte) local hf_myproto_status_bit2 ProtoField.boolean(myproto.status.bit2, Status Bit 2, base.NONE, {Yes, No}, 0x02, Bit 1 of status byte) local hf_myproto_checksum ProtoField.uint8(myproto.checksum, Checksum, base.HEX)2.2 解析函数dissector()中的 tvbuff_t 与 proto_tree 操作注册完字段必须提供一个dissector()函数Wireshark 在遇到该协议流量时会调用它。函数签名固定为function dissector(buffer, pinfo, tree)其中buffer是tvbuff_t对象代表当前数据包的原始字节流支持:uint(),:bytes(),:string()等方法pinfo包含包元信息如源/目的 IP、端口、协议层级常用来设置pinfo.cols.protocol MYPROTO让列显示协议名tree是proto_tree对象用于向协议树添加子节点和字段。关键约束所有字段添加必须使用tree:add()或tree:add_item()且必须传入已注册的hf_*变量。错误做法是tree:add(buffer(0,2), Raw data)—— 这不会注册字段无法被过滤器识别。正确解析开头 8 字节含 3 字节 BCD 时间戳 1 字节状态 1 字节校验的代码function myproto.dissector(buffer, pinfo, tree) local len buffer:len() if len 8 then return end -- 数据不足不解析 pinfo.cols.protocol MYPROTO local subtree tree:add(myproto, buffer(), My Custom Protocol) -- 解析 3 字节 BCD 时间戳假设位于 offset 0 local bcd_bytes buffer(0,3):bytes() local bcd_val 0 for i0,2 do local byte bcd_bytes:byte(i1) bcd_val bcd_val * 100 ((byte 4) * 10 (byte 0x0f)) end subtree:add(hf_myproto_timestamp, buffer(0,3)):set_text(Timestamp: .. tostring(bcd_val)) -- 解析状态字节offset 3提取比特位 local status_byte buffer(3,1):uint() subtree:add(hf_myproto_status_bit1, buffer(3,1), status_byte 0x01) subtree:add(hf_myproto_status_bit2, buffer(3,1), (status_byte 0x02) 1) -- 解析校验和offset 7 subtree:add(hf_myproto_checksum, buffer(7,1)) end注意buffer(0,3)表示从 offset 0 开始取 3 字节buffer(3,1)表示从 offset 3 开始取 1 字节set_text()用于自定义显示文本不影响字段值。status_byte 0x01直接传入布尔值Wireshark 会根据ProtoField.boolean的定义渲染为 Yes/No。2.3 处理非标准编码BCD、位域、自定义校验的 Lua 实现技巧BCD 解析是常见痛点。上述代码中bcd_val的计算逻辑是核心对每个字节高 4 位 4是十位低 4 位 0x0f是个位组合成两位十进制数再按字节顺序拼接。若你的 BCD 是大端序高位字节在前此逻辑正确若为小端序需反转字节顺序。位域解析不能依赖ProtoField.uint8直接传入掩码Wireshark Lua 不支持ProtoField.uint8(..., ..., ..., 0x03)这种带掩码的构造必须手动提取。例如状态字节中 bit 2-3 表示模式local mode_bits (status_byte 0x0c) 2 -- 0x0c 0b00001100, 取 bit 2-3 subtree:add(hf_myproto_mode, buffer(3,1), mode_bits)自定义校验如异或加 0x55需在解析后验证并标记错误local calc_checksum 0 for i0,6 do -- 计算前 7 字节异或 calc_checksum calc_checksum ~ buffer(i,1):uint() end calc_checksum calc_checksum 0x55 local recv_checksum buffer(7,1):uint() if calc_checksum ~ recv_checksum then subtree:add_expert_info(PI_CHECKSUM, PI_WARN, Invalid checksum: expected .. string.format(%02x, calc_checksum) .. , got .. string.format(%02x, recv_checksum)) endadd_expert_info()会在 Packet Details 底部 Expert Info 面板显示警告这是调试协议逻辑错误的关键手段。3. 插件部署、调试与过滤器实战从 Ubuntu 安装到tshark命令行精准分析写完.lua文件只是第一步。Wireshark 必须能加载它且你得验证解析是否正确、字段是否可用。整个流程需在 Ubuntu 环境下完成因为 Windows 的路径和权限机制不同且tshark命令行工具是自动化分析的核心。3.1 Ubuntu 下插件安装路径与权限配置Wireshark 的 Lua 插件默认加载路径为~/.local/lib/wireshark/plugins/用户级或/usr/lib/wireshark/plugins/系统级。强烈推荐使用用户级路径避免sudo权限问题且升级 Wireshark 不会丢失插件。创建目录并复制文件mkdir -p ~/.local/lib/wireshark/plugins/ cp myproto.lua ~/.local/lib/wireshark/plugins/注意~/.local/lib/wireshark/plugins/目录必须存在且myproto.lua文件权限需为可读chmod 644 myproto.lua。Wireshark 启动时会扫描此目录下所有.lua文件若语法错误会在 Help → About Wireshark → Plugins → Console 中报错如attempt to index a nil value (global myproto)说明Proto创建失败或变量名不一致。3.2 GUI 内调试Console 输出与 Expert Info 验证启动 Wireshark确保未以 root 运行否则插件路径可能错乱打开一个包含你协议的 pcap 文件。若插件加载成功Packet List 列中会出现MYPROTO协议名。点击任意 MYPROTO 包在 Packet Details 面板展开应看到你注册的所有字段Timestamp、Status Bit 1 等。若字段缺失检查hf_*变量是否在dissector()函数内被tree:add()调用ProtoField的类型如uint24是否与buffer()取的字节数匹配buffer(0,3)对应uint24正确buffer(0,2)则错pinfo.cols.protocol是否设置影响列显示。打开 Help → About Wireshark → Plugins → Console输入debug(Hello from myproto)若看到输出证明插件已加载。在dissector()函数开头加入debug(Parsing packet of length .. buffer:len())可确认函数是否被调用。3.3tshark命令行过滤与导出脱离 GUI 的自动化分析tshark是 Wireshark 的命令行版支持完全相同的显示过滤器语法是 CI/CD 或批量分析的基石。验证你的字段能否被过滤# 显示所有 myproto 包的 timestamp 和 status.bit1 tshark -r trace.pcap -Y myproto -T fields -e myproto.timestamp -e myproto.status.bit1 # 过滤出 status.bit1 为 true 的包即值为 1 tshark -r trace.pcap -Y myproto.status.bit1 1 -V # 导出为 JSON供 Python 脚本进一步处理 tshark -r trace.pcap -Y myproto -T json myproto.json-Y myproto.status.bit1 1是关键 1表示布尔字段为真。若字段未正确注册为ProtoField.boolean此过滤器会返回空。-T fields指定输出字段值-e指定字段名字段名必须与ProtoField构造时的第一个参数如myproto.status.bit1完全一致包括大小写和点号。3.4 常见部署失败排错表现象可能原因解决方案Wireshark 启动时报Error loading plugin: ... syntax errorLua 语法错误如少end、括号不匹配用lua -l myproto命令行检查语法或逐行注释dissector()内容定位Packet List 列显示TCP或UDP而非MYPROTO协议未关联到端口或未触发dissector()在dissector()开头加debug(Dissector called)检查DissectorTable.get(tcp.port):add(12345, myproto)是否注册见 4.1 节字段在 Packet Details 中显示但tshark -Y myproto.timestamp无结果字段名拼写错误或未用tree:add()添加检查ProtoField第一个参数如myproto.timestamp与-Y中的字段名是否 100% 一致确认tree:add(hf_myproto_timestamp, ...)已调用Expert Info 警告不显示add_expert_info()调用位置错误或参数类型不符确保PI_CHECKSUM和PI_WARN是预定义常量add_expert_info()必须在subtree上调用不能在tree根上4. 协议识别与端口绑定让 Wireshark 自动将 TCP 流量交给你的 Lua 解析器写好解析逻辑后Wireshark 还不知道“什么数据属于你的协议”。它需要一种机制将网络层IP、传输层TCP/UDP的流量路由到你的dissector()函数。这通过DissectorTable解析器表实现本质是一个哈希表键是协议标识如tcp.port值是解析器函数列表。你必须将myproto.dissector注册到对应表中Wireshark 才会在收到目标端口的数据时自动调用它。4.1 TCP/UDP 端口绑定最常用且稳定的识别方式假设你的设备使用 TCP 端口50000发送自定义协议。在myproto.lua文件末尾添加-- 将 myproto 解析器绑定到 TCP 端口 50000 local tcp_table DissectorTable.get(tcp.port) tcp_table:add(50000, myproto) -- 若也走 UDP同样绑定可选 local udp_table DissectorTable.get(udp.port) udp_table:add(50000, myproto)DissectorTable.get(tcp.port)获取 TCP 端口解析器表add(50000, myproto)将myproto解析器注册到端口 50000。当 Wireshark 解析到目的端口或源端口为 50000 的 TCP 包时就会调用myproto.dissector()。这是最可靠的方式因为端口号是明确的、可配置的。4.2 Heuristic Dissector无固定端口时的启发式识别若协议无固定端口如 HTTP 可走 80 或 8080或需根据数据内容判断如前 4 字节为0x12 0x34 0x56 0x78则用启发式解析器heuristic dissector。它会在所有未被其他解析器捕获的 TCP/UDP 流中逐包调用你的函数由你决定是否解析。在myproto.lua中添加-- 注册启发式解析器 local heuristic_table DissectorTable.get(tcp.port) heuristic_table:add_for_decode_as(myproto) -- 启发式函数返回 true 表示“我来解析”false 表示“跳过” function myproto.heuristic(buffer, pinfo, tree) if buffer:len() 4 then return false end local magic buffer(0,4):bytes():tohex() -- 转为小写十六进制字符串 if magic 12345678 then myproto.dissector(buffer, pinfo, tree) return true end return false endadd_for_decode_as(myproto)告诉 Wireshark当用户手动选择 “Decode As...” → “My Custom Protocol” 时启用此解析器。heuristic()函数必须返回true或false且仅在确认是本协议时才调用myproto.dissector()。性能提示启发式解析器会显著降低抓包性能因每包都需调用仅在端口不可知时使用。4.3 Decode As 手动触发调试阶段的终极兜底方案即使端口绑定失败你仍可通过 GUI 强制指定某 TCP 流使用你的解析器。步骤在 Packet List 中右键一个 TCP 包 → “Decode As...” → 在 “Current” 选项卡下找到你的协议名My Custom Protocol→ 点击 “OK”。此后该 TCP 流的所有包都会被myproto.dissector()解析。这是验证解析逻辑是否正确的最快方法无需修改端口配置。5. 进阶技巧多层协议嵌套、会话追踪与导出为 CSV 供 Excel 分析当你的自定义协议承载在 TCP 之上而应用层又封装了 JSON 或二进制消息时Wireshark 的协议树天然支持嵌套。tree:add()返回的子树对象可继续调用add()形成父子关系。同时“Follow TCP Stream” 功能依赖 Wireshark 对 TCP 会话的维护你的 Lua 解析器无需额外代码即可参与。5.1 解析嵌套消息在myproto下解析 JSON 载荷假设myproto的 payload从 offset 8 开始是一个 UTF-8 编码的 JSON 字符串。你可以在dissector()中提取并解析它-- 继续在 dissector() 函数内 local payload_offset 8 if len payload_offset then local payload_bytes buffer(payload_offset, len - payload_offset):bytes() local payload_str payload_bytes:string() -- 尝试转为字符串 if payload_str and #payload_str 0 then -- 使用 Lua 的 JSON 库需提前安装 lua-cjson local cjson require(cjson.safe) local json_data, err cjson.decode(payload_str) if json_data then local payload_tree subtree:add(buffer(payload_offset, len - payload_offset), Payload (JSON)) payload_tree:add(buffer(payload_offset, #payload_str), Raw JSON):set_text(payload_str) -- 递归添加 JSON 字段简化版实际需遍历 table if json_data.id then payload_tree:add(hf_myproto_json_id, buffer(payload_offset, 1)):set_text(ID: .. tostring(json_data.id)) end else subtree:add(buffer(payload_offset, len - payload_offset), Payload (Invalid JSON)):set_text(JSON parse error: .. tostring(err)) end end end注意lua-cjson需单独安装sudo apt install lua-cjson且require(cjson.safe)是安全版本防止恶意 JSON 攻击。payload_tree是subtree的子节点使 JSON 字段在协议树中缩进显示逻辑清晰。5.2 利用 Follow TCP Stream 与导出 CSVWireshark 的 “Follow TCP Stream” 功能会自动重组 TCP 会话的所有数据无论是否被你的 Lua 解析。只要myproto被正确识别端口绑定或 Decode As该功能就能工作。右键 MYPROTO 包 → “Follow” → “TCP Stream”即可看到完整会话的原始字节流。导出为 CSV 供 Excel 分析是现场工程师的刚需。tshark支持按字段导出# 导出 timestamp、status.bit1、checksum 三列用逗号分隔 tshark -r trace.pcap -Y myproto -T fields -e frame.time -e myproto.timestamp -e myproto.status.bit1 -e myproto.checksum -E headery -E separator, myproto_analysis.csv-E headery添加 CSV 表头-E separator,指定分隔符frame.time是内置字段显示时间戳。生成的 CSV 可直接用 Excel 打开做排序、筛选、图表。5.3 调试技巧用debug()输出到 Console 并结合tshark -V最高效的调试循环是修改 Lua 文件 → 重启 Wireshark或tshark→ 观察 Console 输出 → 检查tshark -V的详细解析树。-V参数输出完整的协议树文本比 GUI 更易发现字段位置错误tshark -r trace.pcap -Y myproto -V | grep -A5 My Custom Protocol此命令会输出类似My Custom Protocol Timestamp (BCD): 20240315 Status Bit 1: Yes Status Bit 2: No Checksum: 0xab若某字段未出现说明tree:add()未被调用或buffer()offset 错误。将debug()输出与-V输出对照能快速定位解析逻辑断点。本文还有配套的精品资源点击获取
简介本资源是一份面向网络协议开发与测试工程师、Wireshark高级使用者的实战型技术文档聚焦于利用Lua语言为Wireshark定制解析插件解决自定义UDP协议如员工ID查询服务在抓包中仅显示为原始Data的调试痛点。文档以QueryRequest/QueryResponse双消息结构为例系统讲解Proto协议注册、ProtoField字段定义、dissector函数编写、init.lua集成调用等核心步骤并结合Wireshark内置Lua 5.1引擎特性与关键APIbuffer/pinfo/tree操作展开说明附有实际抓包截图与字段映射对照。资源为单个264KB的Word文档.doc格式内容完整覆盖环境配置、协议建模、脚本实现与验证流程结构清晰、示例具体适合作为Lua扩展Wireshark的入门实践指南。目前已有371人学习下载可直接用于协议逆向分析、嵌入式通信调试及教学演示场景。1. 为什么用 Lua 写 Wireshark 插件解析自定义协议比改 C 源码更高效、更安全、更适合一线网络工程师你刚接手一个嵌入式设备的通信模块协议字段全是私有编码时间戳用 3 字节 BCD、状态位分散在 4 个不同字节的特定比特、校验和是异或再加 0x55。Wireshark 默认不识别它tcpdump 抓出来只有一堆十六进制。有人建议你去编译 Wireshark 源码、修改epan/dissectors/下的 C 文件——但你不是底层协议栈开发者没有时间搭编译环境、跑 test suite、处理 ABI 兼容性也有人提议用 Python 脚本后处理 pcap 文件——可这样就失去了实时着色、过滤器myproto.status 3、会话追踪Follow TCP Stream这些关键分析能力。Lua 插件正是这个场景的黄金解法它直接运行在 Wireshark 进程内共享所有协议树proto_tree、字段注册hf_register_info、解码上下文tvbuff_t却无需重新编译主程序。Ubuntu 上sudo apt install wireshark tshark lua5.3-dev后一个.lua文件丢进插件目录就能生效。本文面向已能用 Wireshark 抓包、熟悉基础协议分层如 TCP/IP、但没碰过 C 协议解析器的网络运维、IoT 测试、工控协议调试人员手把手带你从零写出可调试、可发布、能通过tshark -r trace.pcap -Y myproto.error精准过滤的 Lua 解析器。2. Lua 插件核心机制与 Wireshark 协议解析模型对齐为什么必须先理解 proto_tree 和 hf_register_infoWireshark 的协议解析不是简单字符串匹配而是一套基于“协议树”proto_tree的结构化展示系统。每个字段如源端口、HTTP 状态码都需预先注册为“可显示字段”registered field并绑定到特定数据类型FT_UINT16、FT_BOOLEAN、FT_STRING。Lua 插件必须严格遵循这套注册-解析-添加三步流程否则字段不会出现在 GUI 的 Packet Details 面板也无法被显示过滤器识别。这与你在 VSCode 里写 Lua 脚本完全不同——这里没有print()调试只有debug()函数输出到 Wireshark 的 ConsoleHelp → About Wireshark → Plugins → Console且所有操作必须在 Wireshark 的线程模型下安全执行。2.1 注册协议与字段用Proto和ProtoField构建协议骨架首先创建协议对象指定协议名用于过滤器和显示名GUI 中显示-- myproto.lua local myproto Proto(myproto, My Custom Protocol)接着定义所有待解析的字段。注意字段名第一个参数必须全小写、无空格、无特殊字符这是显示过滤器语法的基础显示名第二个参数可含空格和符号用于 GUI 展示第三个参数是数据类型第四个是显示格式如 BASE_DEC 表示十进制。例如针对你设备中那个 3 字节 BCD 时间戳local hf_myproto_timestamp ProtoField.uint24(myproto.timestamp, Timestamp (BCD), base.DEC, nil, 0xffffff, 3-byte BCD encoded time)提示base.DEC是显示格式不影响解析逻辑0xffffff是掩码mask表示取全部 24 位nil是值映射表value_string若需将数值转为2024-03-15字符串此处需传入{ [0x20240315] 2024-03-15 }但 BCD 解析需额外函数见 2.3 节。完整字段注册示例含状态位、校验和local hf_myproto_status_bit1 ProtoField.boolean(myproto.status.bit1, Status Bit 1, base.NONE, {Yes, No}, 0x01, Bit 0 of status byte) local hf_myproto_status_bit2 ProtoField.boolean(myproto.status.bit2, Status Bit 2, base.NONE, {Yes, No}, 0x02, Bit 1 of status byte) local hf_myproto_checksum ProtoField.uint8(myproto.checksum, Checksum, base.HEX)2.2 解析函数dissector()中的 tvbuff_t 与 proto_tree 操作注册完字段必须提供一个dissector()函数Wireshark 在遇到该协议流量时会调用它。函数签名固定为function dissector(buffer, pinfo, tree)其中buffer是tvbuff_t对象代表当前数据包的原始字节流支持:uint(),:bytes(),:string()等方法pinfo包含包元信息如源/目的 IP、端口、协议层级常用来设置pinfo.cols.protocol MYPROTO让列显示协议名tree是proto_tree对象用于向协议树添加子节点和字段。关键约束所有字段添加必须使用tree:add()或tree:add_item()且必须传入已注册的hf_*变量。错误做法是tree:add(buffer(0,2), Raw data)—— 这不会注册字段无法被过滤器识别。正确解析开头 8 字节含 3 字节 BCD 时间戳 1 字节状态 1 字节校验的代码function myproto.dissector(buffer, pinfo, tree) local len buffer:len() if len 8 then return end -- 数据不足不解析 pinfo.cols.protocol MYPROTO local subtree tree:add(myproto, buffer(), My Custom Protocol) -- 解析 3 字节 BCD 时间戳假设位于 offset 0 local bcd_bytes buffer(0,3):bytes() local bcd_val 0 for i0,2 do local byte bcd_bytes:byte(i1) bcd_val bcd_val * 100 ((byte 4) * 10 (byte 0x0f)) end subtree:add(hf_myproto_timestamp, buffer(0,3)):set_text(Timestamp: .. tostring(bcd_val)) -- 解析状态字节offset 3提取比特位 local status_byte buffer(3,1):uint() subtree:add(hf_myproto_status_bit1, buffer(3,1), status_byte 0x01) subtree:add(hf_myproto_status_bit2, buffer(3,1), (status_byte 0x02) 1) -- 解析校验和offset 7 subtree:add(hf_myproto_checksum, buffer(7,1)) end注意buffer(0,3)表示从 offset 0 开始取 3 字节buffer(3,1)表示从 offset 3 开始取 1 字节set_text()用于自定义显示文本不影响字段值。status_byte 0x01直接传入布尔值Wireshark 会根据ProtoField.boolean的定义渲染为 Yes/No。2.3 处理非标准编码BCD、位域、自定义校验的 Lua 实现技巧BCD 解析是常见痛点。上述代码中bcd_val的计算逻辑是核心对每个字节高 4 位 4是十位低 4 位 0x0f是个位组合成两位十进制数再按字节顺序拼接。若你的 BCD 是大端序高位字节在前此逻辑正确若为小端序需反转字节顺序。位域解析不能依赖ProtoField.uint8直接传入掩码Wireshark Lua 不支持ProtoField.uint8(..., ..., ..., 0x03)这种带掩码的构造必须手动提取。例如状态字节中 bit 2-3 表示模式local mode_bits (status_byte 0x0c) 2 -- 0x0c 0b00001100, 取 bit 2-3 subtree:add(hf_myproto_mode, buffer(3,1), mode_bits)自定义校验如异或加 0x55需在解析后验证并标记错误local calc_checksum 0 for i0,6 do -- 计算前 7 字节异或 calc_checksum calc_checksum ~ buffer(i,1):uint() end calc_checksum calc_checksum 0x55 local recv_checksum buffer(7,1):uint() if calc_checksum ~ recv_checksum then subtree:add_expert_info(PI_CHECKSUM, PI_WARN, Invalid checksum: expected .. string.format(%02x, calc_checksum) .. , got .. string.format(%02x, recv_checksum)) endadd_expert_info()会在 Packet Details 底部 Expert Info 面板显示警告这是调试协议逻辑错误的关键手段。3. 插件部署、调试与过滤器实战从 Ubuntu 安装到tshark命令行精准分析写完.lua文件只是第一步。Wireshark 必须能加载它且你得验证解析是否正确、字段是否可用。整个流程需在 Ubuntu 环境下完成因为 Windows 的路径和权限机制不同且tshark命令行工具是自动化分析的核心。3.1 Ubuntu 下插件安装路径与权限配置Wireshark 的 Lua 插件默认加载路径为~/.local/lib/wireshark/plugins/用户级或/usr/lib/wireshark/plugins/系统级。强烈推荐使用用户级路径避免sudo权限问题且升级 Wireshark 不会丢失插件。创建目录并复制文件mkdir -p ~/.local/lib/wireshark/plugins/ cp myproto.lua ~/.local/lib/wireshark/plugins/注意~/.local/lib/wireshark/plugins/目录必须存在且myproto.lua文件权限需为可读chmod 644 myproto.lua。Wireshark 启动时会扫描此目录下所有.lua文件若语法错误会在 Help → About Wireshark → Plugins → Console 中报错如attempt to index a nil value (global myproto)说明Proto创建失败或变量名不一致。3.2 GUI 内调试Console 输出与 Expert Info 验证启动 Wireshark确保未以 root 运行否则插件路径可能错乱打开一个包含你协议的 pcap 文件。若插件加载成功Packet List 列中会出现MYPROTO协议名。点击任意 MYPROTO 包在 Packet Details 面板展开应看到你注册的所有字段Timestamp、Status Bit 1 等。若字段缺失检查hf_*变量是否在dissector()函数内被tree:add()调用ProtoField的类型如uint24是否与buffer()取的字节数匹配buffer(0,3)对应uint24正确buffer(0,2)则错pinfo.cols.protocol是否设置影响列显示。打开 Help → About Wireshark → Plugins → Console输入debug(Hello from myproto)若看到输出证明插件已加载。在dissector()函数开头加入debug(Parsing packet of length .. buffer:len())可确认函数是否被调用。3.3tshark命令行过滤与导出脱离 GUI 的自动化分析tshark是 Wireshark 的命令行版支持完全相同的显示过滤器语法是 CI/CD 或批量分析的基石。验证你的字段能否被过滤# 显示所有 myproto 包的 timestamp 和 status.bit1 tshark -r trace.pcap -Y myproto -T fields -e myproto.timestamp -e myproto.status.bit1 # 过滤出 status.bit1 为 true 的包即值为 1 tshark -r trace.pcap -Y myproto.status.bit1 1 -V # 导出为 JSON供 Python 脚本进一步处理 tshark -r trace.pcap -Y myproto -T json myproto.json-Y myproto.status.bit1 1是关键 1表示布尔字段为真。若字段未正确注册为ProtoField.boolean此过滤器会返回空。-T fields指定输出字段值-e指定字段名字段名必须与ProtoField构造时的第一个参数如myproto.status.bit1完全一致包括大小写和点号。3.4 常见部署失败排错表现象可能原因解决方案Wireshark 启动时报Error loading plugin: ... syntax errorLua 语法错误如少end、括号不匹配用lua -l myproto命令行检查语法或逐行注释dissector()内容定位Packet List 列显示TCP或UDP而非MYPROTO协议未关联到端口或未触发dissector()在dissector()开头加debug(Dissector called)检查DissectorTable.get(tcp.port):add(12345, myproto)是否注册见 4.1 节字段在 Packet Details 中显示但tshark -Y myproto.timestamp无结果字段名拼写错误或未用tree:add()添加检查ProtoField第一个参数如myproto.timestamp与-Y中的字段名是否 100% 一致确认tree:add(hf_myproto_timestamp, ...)已调用Expert Info 警告不显示add_expert_info()调用位置错误或参数类型不符确保PI_CHECKSUM和PI_WARN是预定义常量add_expert_info()必须在subtree上调用不能在tree根上4. 协议识别与端口绑定让 Wireshark 自动将 TCP 流量交给你的 Lua 解析器写好解析逻辑后Wireshark 还不知道“什么数据属于你的协议”。它需要一种机制将网络层IP、传输层TCP/UDP的流量路由到你的dissector()函数。这通过DissectorTable解析器表实现本质是一个哈希表键是协议标识如tcp.port值是解析器函数列表。你必须将myproto.dissector注册到对应表中Wireshark 才会在收到目标端口的数据时自动调用它。4.1 TCP/UDP 端口绑定最常用且稳定的识别方式假设你的设备使用 TCP 端口50000发送自定义协议。在myproto.lua文件末尾添加-- 将 myproto 解析器绑定到 TCP 端口 50000 local tcp_table DissectorTable.get(tcp.port) tcp_table:add(50000, myproto) -- 若也走 UDP同样绑定可选 local udp_table DissectorTable.get(udp.port) udp_table:add(50000, myproto)DissectorTable.get(tcp.port)获取 TCP 端口解析器表add(50000, myproto)将myproto解析器注册到端口 50000。当 Wireshark 解析到目的端口或源端口为 50000 的 TCP 包时就会调用myproto.dissector()。这是最可靠的方式因为端口号是明确的、可配置的。4.2 Heuristic Dissector无固定端口时的启发式识别若协议无固定端口如 HTTP 可走 80 或 8080或需根据数据内容判断如前 4 字节为0x12 0x34 0x56 0x78则用启发式解析器heuristic dissector。它会在所有未被其他解析器捕获的 TCP/UDP 流中逐包调用你的函数由你决定是否解析。在myproto.lua中添加-- 注册启发式解析器 local heuristic_table DissectorTable.get(tcp.port) heuristic_table:add_for_decode_as(myproto) -- 启发式函数返回 true 表示“我来解析”false 表示“跳过” function myproto.heuristic(buffer, pinfo, tree) if buffer:len() 4 then return false end local magic buffer(0,4):bytes():tohex() -- 转为小写十六进制字符串 if magic 12345678 then myproto.dissector(buffer, pinfo, tree) return true end return false endadd_for_decode_as(myproto)告诉 Wireshark当用户手动选择 “Decode As...” → “My Custom Protocol” 时启用此解析器。heuristic()函数必须返回true或false且仅在确认是本协议时才调用myproto.dissector()。性能提示启发式解析器会显著降低抓包性能因每包都需调用仅在端口不可知时使用。4.3 Decode As 手动触发调试阶段的终极兜底方案即使端口绑定失败你仍可通过 GUI 强制指定某 TCP 流使用你的解析器。步骤在 Packet List 中右键一个 TCP 包 → “Decode As...” → 在 “Current” 选项卡下找到你的协议名My Custom Protocol→ 点击 “OK”。此后该 TCP 流的所有包都会被myproto.dissector()解析。这是验证解析逻辑是否正确的最快方法无需修改端口配置。5. 进阶技巧多层协议嵌套、会话追踪与导出为 CSV 供 Excel 分析当你的自定义协议承载在 TCP 之上而应用层又封装了 JSON 或二进制消息时Wireshark 的协议树天然支持嵌套。tree:add()返回的子树对象可继续调用add()形成父子关系。同时“Follow TCP Stream” 功能依赖 Wireshark 对 TCP 会话的维护你的 Lua 解析器无需额外代码即可参与。5.1 解析嵌套消息在myproto下解析 JSON 载荷假设myproto的 payload从 offset 8 开始是一个 UTF-8 编码的 JSON 字符串。你可以在dissector()中提取并解析它-- 继续在 dissector() 函数内 local payload_offset 8 if len payload_offset then local payload_bytes buffer(payload_offset, len - payload_offset):bytes() local payload_str payload_bytes:string() -- 尝试转为字符串 if payload_str and #payload_str 0 then -- 使用 Lua 的 JSON 库需提前安装 lua-cjson local cjson require(cjson.safe) local json_data, err cjson.decode(payload_str) if json_data then local payload_tree subtree:add(buffer(payload_offset, len - payload_offset), Payload (JSON)) payload_tree:add(buffer(payload_offset, #payload_str), Raw JSON):set_text(payload_str) -- 递归添加 JSON 字段简化版实际需遍历 table if json_data.id then payload_tree:add(hf_myproto_json_id, buffer(payload_offset, 1)):set_text(ID: .. tostring(json_data.id)) end else subtree:add(buffer(payload_offset, len - payload_offset), Payload (Invalid JSON)):set_text(JSON parse error: .. tostring(err)) end end end注意lua-cjson需单独安装sudo apt install lua-cjson且require(cjson.safe)是安全版本防止恶意 JSON 攻击。payload_tree是subtree的子节点使 JSON 字段在协议树中缩进显示逻辑清晰。5.2 利用 Follow TCP Stream 与导出 CSVWireshark 的 “Follow TCP Stream” 功能会自动重组 TCP 会话的所有数据无论是否被你的 Lua 解析。只要myproto被正确识别端口绑定或 Decode As该功能就能工作。右键 MYPROTO 包 → “Follow” → “TCP Stream”即可看到完整会话的原始字节流。导出为 CSV 供 Excel 分析是现场工程师的刚需。tshark支持按字段导出# 导出 timestamp、status.bit1、checksum 三列用逗号分隔 tshark -r trace.pcap -Y myproto -T fields -e frame.time -e myproto.timestamp -e myproto.status.bit1 -e myproto.checksum -E headery -E separator, myproto_analysis.csv-E headery添加 CSV 表头-E separator,指定分隔符frame.time是内置字段显示时间戳。生成的 CSV 可直接用 Excel 打开做排序、筛选、图表。5.3 调试技巧用debug()输出到 Console 并结合tshark -V最高效的调试循环是修改 Lua 文件 → 重启 Wireshark或tshark→ 观察 Console 输出 → 检查tshark -V的详细解析树。-V参数输出完整的协议树文本比 GUI 更易发现字段位置错误tshark -r trace.pcap -Y myproto -V | grep -A5 My Custom Protocol此命令会输出类似My Custom Protocol Timestamp (BCD): 20240315 Status Bit 1: Yes Status Bit 2: No Checksum: 0xab若某字段未出现说明tree:add()未被调用或buffer()offset 错误。将debug()输出与-V输出对照能快速定位解析逻辑断点。本文还有配套的精品资源点击获取
