Introduction¶

This part is a technical introduction to CSjark. It gives a concise explanation of the most important terms used in the documentation. The first section briefly explains Wireshark, dissectors and how dissectors are used in Wireshark. The connection between Wireshark and the Lua structs protocol is also explained. The second section describes how the Lua code works and how it is generated by our utility.

Wireshark and dissectors¶

This section gives a brief introduction to Wireshark and dissectors. The rst part describes what Wireshark is and what it can be used for. The second part explains exactly what a dissector is, and how a dissector can be used to extend Wireshark.

Wireshark¶

Wireshark is a program used to analyze network traffic. A common usage scenario is when a person wants to troubleshoot network problems or look at the internal workings of a network protocol. An important feature of Wireshark is the ability to capture and display a live stream of packets sent through the network. A user could, for example, see exactly what happens when he opens up a website. Wireshark will then display all the messages sent between his computer and the web server. It is also possible to filter and search on given packet attributes, which facilitates the debugging process.

In Figure 1, you can see a view of Wireshark. This specific example shows a capture file with four messages, or packets, sent between internal 2 processes, in other words it is a view of messages sent by inter-process communication. Each of the packets contain one C struct. To be able to display the contents of the C struct, Wireshark has to be extended. This can be accomplished by writing a dissector for the C struct.

Figure 1: Wireshark

Dissector¶

In short, a dissector is a piece of code, run on a blob of data, which can dissect the data and display it in a readable format in Wireshark, instead of the binary representation. The Figure 1 displays four packets, with packet number 1 highlighted. The content of the packet is a C struct with two members, name and time, and it is displayed inside the green box. The C code for the struct is shown below.

/*
* Sample header file for testing Lua C structs script
* Copyright 2011 , Stig Bjorlykke <stig@bjorlykke.org>
*/

#include <time.h>

#define STRING_LEN 30

struct internal_snd {
    int type;
    char name [STRING_LEN];
    time_t time;
};

The dissector takes the C struct, decodes its binary representation and makes it readable by humans. Without a dissector, Wireshark would just display the struct and struct members as a binary blob.

All the packets containing C structs belong to the protocol called luastructs. When opening a capture file in Wireshark, this protocol maps the id of the messages to the correct dissector, and calls them.

From struct definition to Lua dissector¶

This section explains what happens under the hood of a Lua dissector.

Lua dissectors¶

The code below shows what the code for the Lua dissector, displayed in packet 1 in Figure 1, looks like. The Proto variable defines a new protocol. In this example, a dissector for the internal_snd struct, called internal_snd, is created. The different fields of the struct are created as instances of ProtoField, and put in Protocol.fields. For example, the name variable is a string in C, and as such it is created as a ProtoField.string with the name name.

The protocol dissector method is the method that does the actual dissecting. A subtree for the dissector is created, and the description of the dissector is appended to the information column. All the ProtoFields are added to the subtree. Here you can see that the type, name and time fields are added to the subtree for the internal_snd dissector. The buffer size allocated to the fields is the size of the members in C.

--
--  A sample dissector for testing Lua C structs scripts
--  Copyright 2011, Stig Bjorlykke <stig@bjorlykke.org>
--

local PROTOCOL = Proto ("internal_snd", "struct internal_snd")
local luastructs_dt = DissectorTable.get ("luastructs.message")

local types = { [0] = "None", [1] = "Regular", [42] = "Secure" }

local f = PROTOCOL.fields
f.type = ProtoField.uint32 ("internal_snd.type", "type", nil, types)
f.time = ProtoField.absolute_time ("internal_snd.time", "time")
f.name = ProtoField.string ("internal_snd.name", "name")

function PROTOCOL.dissector (buffer, pinfo, tree)
   local subtree = tree:add (PROTOCOL, buffer())
   pinfo.cols.info:append (" (" .. PROTOCOL.description .. ")")

   subtree:add (f.type, buffer(0,4))
   subtree:add (f.name, buffer(4,30))
   subtree:add (f.time, buffer(34,4))
end

luastructs_dt:add (1, PROTOCOL)

Note

Lua dissectors are usually files with extension .lua.

For further information on the Lua integration in Wireshark, please visit: Lua Support in Wireshark.

More information programming in Lua in general can be found in Lua reference manual.