Monday, May 2, 2011

GUIDE: Creating your own fast Wireshark plugin / dissector using LUA.

After hitting my head agains the keyboard to create my own LUA protocol, I've desided that none shall suffer anymore.

Some background to understand stuff

  • Wireshark reads PCAP file format for captured files.
  • Wireshark can be extended using C code or, for fast development you can use LUA code (I'll explain later...).

Creating LUA based plugin / dissector

  1. Download and install Wireshark.
  2. Create LUA dissector (let's save it as 'trivial.lua')

-- trivial protocol example
-- declare our protocol
trivial_proto = Proto("trivial","Trivial Protocol")
-- create a function to dissect it
function trivial_proto.dissector(buffer,pinfo,tree)
    pinfo.cols.protocol = "TRIVIAL"
    local subtree = tree:add(trivial_proto,buffer(),"Trivial Protocol Data")
    subtree:add(buffer(0,2),"The first two bytes: " .. buffer(0,2):uint())
    subtree = subtree:add(buffer(2,2),"The next two bytes")
    subtree:add(buffer(2,1),"The 3rd byte: " .. buffer(2,1):uint())
    subtree:add(buffer(3,1),"The 4th byte: " .. buffer(3,1):uint())
-- load the udp.port table
udp_table = DissectorTable.get("udp.port")
-- register our protocol to handle udp port 7777

  1. Edit  ...\Wireshark\init.lua file as follows
    1. disable_lua = false
    2. At the end of the file: dofile("trivial.lua"
      1. You can read more here -
  2. Open Wireshark
    1. Menu >> Edit >> Preferences >> Protocols >> DLT_USER >> Edit >> New:
      1. DLT: User 0 (147)
      2. Payload protocol: MyProtocolName
      3. Header size 0
      4. Trailer size: 0
      5. Press OK
  3. Create PCAP dumps for analyze.
    1. Using HEX-Editor (see below for nice hex-editor recomendations).
    2. If you can - ask the protocol team to provide their dumps. 
  4. Open the PCAP dump for editing (binary mode).
    1. Change the dump's 'Global Header' section / 'data link type' (network) to 147 (LINKTYPE_USER0)
      1. Read more here -
    2. save it.
  5. Load the dump to Wireshark for analyses.
  6. Start changing the trivial.lua code to parse your protocol.
Hope this will bring you to a working point fast. In the process read related stuff to understand more, you can upgrade this solution to create better and better protocol sniffer using Wireshark.

More nice stuff that can help


  1. Here's how to create a binary pcap file suitable for input to Wireshark or tshark *without* the
    aid of a hex editor.

    The payload is 4 bytes long (matches the Trivial protocol dissector given in this blog post)

    $ echo -n abcd | od -Ax -tx1 -v | text2pcap -l 147 - trivial.pcap

    Nice for doing smallish stuff :-)

  2. I hardly ever write comments on blogs, but your article urged me to praise your blog.
    Thanks for the read, I will surely favorite your site and check in occasionally.Cheers
    Get Wireshark

  3. It's spelled "Lua" (it is not an acronym "LUA").

  4. Hi, great guide! btw, if you still need a custom dissector and don't want to make it yourself again, check out our website We make custom dissectors. Regards!

  5. Another related tool: