Jump to content
Setting up an AI agent? ReverseEngineering.wiki skill (works from the command line, no configuration): https://reverseengineering.wiki/skill/rewiki/SKILL.md · setup for every client, including MCP: https://reverseengineering.wiki/llms.txt · REWiki:Connect

Tool:Wireshark Lua dissectors

From ReverseEngineering.wiki
Tool
Vendor The Wireshark developers
License GPL-2.0-or-later
Website https://www.wireshark.org
On this wiki Facts · Code · Notes · Topics

Writing a Wireshark protocol dissector in Lua: Proto and ProtoField objects, the dissector function, registering on a DissectorTable port and the structure of a minimal plugin, as used to test a reverse-engineered protocol model.

Overview

Wireshark loads Lua scripts from its plugin directory (or with -X lua_script:file.lua, also in tshark) and lets them dissect protocols without recompiling. For reversing a custom protocol (see Technique:Reversing network protocols) a Lua dissector is the quickest way to turn a model of the message format into a decoded view of every capture.

Skeleton

The Wireshark repository example test/lua/dissector.lua (a toy DNS dissector) shows the structure:

local p = Proto("myproto", "My Protocol")
local f_len  = ProtoField.uint16("myproto.len",  "Length", base.DEC)
local f_type = ProtoField.uint8 ("myproto.type", "Type",   base.HEX)
local f_body = ProtoField.bytes ("myproto.body", "Body")
p.fields = { f_len, f_type, f_body }

function p.dissector(tvb, pinfo, tree)
  if tvb:len() < 3 then return 0 end
  pinfo.cols.protocol = "MYPROTO"
  local t = tree:add(p, tvb())
  t:add(f_len,  tvb(0,2))
  t:add(f_type, tvb(2,1))
  t:add(f_body, tvb(3))
  return tvb:len()
end

DissectorTable.get("tcp.port"):add(9000, p)

The example registers with DissectorTable.get("udp.port"):add(port, proto) and removes the old port in a preferences callback; fields are created with ProtoField.new(name, abbr, ftypes.UINT16, nil, base.HEX, mask) or the typed constructors ProtoField.uint16(abbr, name, base, valuestring, mask, description), ProtoField.bool(abbr, name, display_width, valuestring, mask), with bit masks for flag words.

Field types

Typed constructors exist for uint8/16/24/32/64, int8..int64, framenum, float, double, string, stringz, bytes, ubytes, bool, ipv4, ipv6, ether, guid, oid and others; tvb(offset, len) gives a TvbRange with :uint(), :le_uint(), :string(), :bytes(). Use the le_ variants for little-endian protocols. (Unverified: the full type list is from the Wireshark Lua API documentation, not read for this page.)

TCP message framing

A TCP message may span segments: set pinfo.desegment_len and pinfo.desegment_offset to ask Wireshark for more bytes (DESEGMENT_ONE_MORE_SEGMENT), or use dissect_tcp_pdus from a length field (Unverified: API names from memory).

Heuristic dissectors

For protocols on arbitrary ports, register a heuristic: p:register_heuristic("tcp", function(tvb, pinfo, tree) ... end); return false quickly unless a magic or length check passes, and set pinfo.conversation on success so later packets go to the full dissector (Unverified: not read for this page; test before relying on it).

Working tips

  • Reload plugins with Ctrl+Shift+L; run tshark -X lua_script:x.lua -r cap.pcapng -V to test headless.
  • Add expert info or tree:add_expert_info for unknown trailing bytes so they stand out.
  • Add a column with pinfo.cols.info:set(...) showing the message type.
  • Use Tools > Lua > Evaluate to try expressions.

Sources

https://github.com/wireshark/wireshark (GPL-2.0-or-later): test/lua/dissector.lua, Lua API in doc/. Capture formats: Format:pcap (libpcap savefile), Format:pcapng.