Tool:Wireshark Lua dissectors
| 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 -Vto test headless. - Add expert info or
tree:add_expert_infofor 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.