/ How to

How to Use Lua Protocol Dissector in Wireshark Network Analyzer Tool

Wireshark is a popular open-source network protocol analyzer that allows users to examine data from a live network or from a capture file. It comes with many built-in protocol dissectors that allow Wireshark to parse and display data from common protocols like HTTP, DNS, and others.

However, if you are working with a custom or proprietary protocol that Wireshark doesn’t understand out of the box, you’ll just see the raw packet data. This is where creating a Lua protocol dissector comes in handy.

What is a Lua Protocol Dissector

A Lua protocol dissector is a Lua script that teaches Wireshark how to parse a custom protocol by specifying:

  • The structure of the protocol data
  • How to extract and interpret different fields
  • How to display the parsed data in the Wireshark UI

By writing a dissector, you can take a proprietary binary protocol that just looks like gibberish inside Wireshark and transform it into an easy to read structure.

Why Use Lua for Dissector Development

Wireshark supports writing dissectors in C and Lua. Lua is a great choice for writing your first dissector for several reasons:

  • Easy to learn: Lua has a simple syntax that is easy to pick up even if you’ve never coded before.
  • Rapid prototyping: You can quickly write and iterate on a Lua dissector script.
  • No compilation required: Lua dissectors can be reloaded on the fly without having to recompile Wireshark.
  • Large community: There are many code samples and documentation available for Lua dissectors.

The main tradeoff is that Lua dissectors won’t be as fast as optimized C dissectors. But for analyzing most protocols, Lua is more than fast enough.

How to Write a Lua Dissector

The process for developing a Lua dissector involves:

  1. Finding out what dissector table to hook into
  2. Creating the dissector script
  3. Registering the dissector
  4. Testing and troubleshooting

1. Determine the Dissector Table

Dissector tables in Wireshark contain mappings that decide which dissector gets called for a packet.

For example, the TCP dissector table maps TCP ports to dissectors so that packets to port 80 call the HTTP dissector.

To hook your Lua dissector into this logic, you first need to figure out which table it should register itself with.

If your custom protocol runs on top of TCP, UDP or SCTP, then register with those protocol tables using ports or PPIs. If your protocol uses a custom frame encapsulation, you can register with the Wtap encapsulation table.

2. Create the Dissector Script

The dissector script itself will:

  • Define a Proto object to represent the protocol
  • Register ProtoFields to define what data to extract
  • Implement a dissector() function to parse packets

Here is a simple example:

-- Protocol definition
MyProto = Proto("myproto","My Protocol")  

-- Protocol fields
local f_magic = ProtoField.uint8("myproto.magic","Magic", base.HEX)
local f_type = ProtoField.uint8("myproto.type","Type")
local f_data = ProtoField.string("myproto.data","Data")

-- Dissector function
function MyProto.dissector(buffer,pinfo,tree)
    length = buffer:len()
    if length == 0 then return end

    pinfo.cols.protocol = "MYPROTO"

    local subtree = tree:add(MyProto,buffer(),"MyProto Data")
        subtree:add(f_magic,buffer(0,1))
        subtree:add(f_type,buffer(1,1))
        subtree:add(f_data,buffer(2))
end

This simple dissector extracts a magic number, type field and data payload. More advanced dissectors can have complex logic for reassembly, validation, etc.

3. Register the Dissector

The next step is registering your MyProto dissector function with a dissector table like:

-- Register with a TCP port
DissectorTable.get("tcp.port"):add(1234, MyProto)

This will cause Wireshark to call MyProto.dissector() on TCP packets going to port 1234.

You can also register dissectors for UDP ports, SCTP PPIDs, frame encapsulations or heap-based call tables.

4. Test and Troubleshoot

Finally, test your dissector against some sample capture files to troubleshoot issues:

  • Load the dissector in Wireshark
  • Enable debugging to see errors
  • Analyze protocol traffic to see if it’s parsing as expected
  • Make corrections and repeat

Some common issues are not handling TCP reassembly, registering with the wrong tables and off-by-one errors in field lengths.

Conclusion

Writing custom dissectors is a powerful way to extend Wireshark to understand proprietary protocols and get meaningful insights from network traces.

Lua provides a simple yet flexible language to rapidly prototype dissectors that can parse, analyze and display custom protocols for analysis.

So next time you need to reverse engineer some unknown network traffic, give Lua dissectors a try!

More Resources

Related Posts