Debugging Wireshark Lua scripts

Wireshark is a cross-platform network analyzer that conveniently supports scripting some of its functions in Lua. One of ZeroBrane Studio users asked if he could use ZBS to debug Wireshark scripts and I thought I would take a look. It turned out it is indeed possible; I'll describe how this can be done on Windows, but you can map these steps to your platform of choice.

Enable Lua support in Wireshark

Make sure your Wireshark version include Lua interpreter and enable processing of Lua scripts. Go to Help | About Wireshark and check if you see "with Lua 5.1" there (or run tshark -v and check its output). Then find init.lua in the wireshark folder and comment out the following line (this is only needed if you are using wireshark earlier than 1.4):

-- Lua is disabled by default, comment out the following line to enable Lua support.
--disable_lua = true; do return end;

Setup Wireshark environment for debugging

Create the following batch file in your wireshark folder; adjust the value of ZBS according to the location of ZeroBrane Studio.

set ZBS=D:\users\paul\ZeroBraneStudio
set LUA_PATH=.\?.lua;%ZBS%\lualibs/?/?.lua;%ZBS%\lualibs/?.lua
set LUA_CPATH=%ZBS%\bin/?.dll;%ZBS%\bin/clibs52/?.dll
tshark -X lua_script:test.lua

This script points to libraries included with ZBS that are required for debugging (luasocket and mobdebug). tshark is the command-line version of wireshark and -X enables various extension options.

Note that LUA_CPATH points for libraries for Lua 5.2 as wireshark v1.8+ is using Lua 5.2. If you use an older version (which may include Lua 5.1), you need to use set LUA_CPATH=%ZBS%\bin/?.dll;%ZBS%\bin/clibs/?.dll instead.

Create a Lua script to run

Create a Lua script (test.lua) with the following lines:

_G.debug = require("debug")
require("mobdebug").start()
print("Hello!")
print("World!")

The first line is needed, because there is a bug in wireshark that causes the default debug table to be overwritten by a logging function with the same name; the first line restores the default value. The second line starts the debugger and connects to ZeroBrane Studio IDE.

Start debugger server in ZeroBrane Studio

Start ZeroBrane Studio, open test.lua file, and start the debugger server (by going to Project | Start Debugger Server).

Now when you ran the batch file, you should see a green arrow in ZBS and should be able to step through the script.

Minimally useful script

The test.lua script is not very useful, but you can do more complex processing by implementing taps and dissectors using Lua scripts. Here is the script that counts the number of http packets.

local taphttp = Listener.new(nil, "http")
local httppackets = 0
local log = debug
_G.debug = require('debug') -- restore proper 'debug' table
require("mobdebug").start() -- start the debugger

-- called at the end of the capture to print the summary
function taphttp.draw()
  log("http packets: " .. httppackets)
end

-- called once each time the filter of the tap matches
function taphttp.packet()
  httppackets = httppackets + 1
end

You can run this script with the same command we put in the run.bat file: tshark -X lua_script:simple_http.lua. If you want to process captures from a file, you can add -r myfile.pcap to the command. If you put a breakpoint on line httppackets = httppackets + 1 you will see it activated every time a new packet is matched by the filter.

Some other resources with information on writing taps, dissectors, or other wireshark Lua scripts.

You should get a copy of my slick ZeroBrane Studio IDE and follow me on twitter here.

2 Comments

I downloaded the 0.39 version of the IDE and I keep running into the lua51.dll issue.

"The program can't start because 511.dll is missing from your computer. Try reinstalling the program to fix this problem"

followed by:

"Lua: Error during loading: error loading module 'socket.core' from file \core.dll" The specified module could not be found"

I utilize the "set LUA_PATH" from above, but still has issues. I cannot find a good resolution on-line. Any thoughts?

Hi Jason, you are right; some of the changes to stay consistent with DLL naming and to support various debugging scenarios, made things more complex in some of the cases. In this case, wireshark is using lua5.1.dll, but socket/core.dll that ships with ZBS is linked against lua51.dll. ZBS also provides a proxy DLL that forwards requests from lua5.1.dll to lua51.dll, but in your case it needs to go in the opposite direction (requests from ua51.dll need to go to lua5.1.dll).

You probably don't care about most of these details, but to address this issue for you, there are two options. (1) you can copy lua51.dll and lua5.1.dll from /bin folder to your Wireshark folder; everything else should continue to work just fine. (2) you can compile lua proxy DLL to forward requests from lua51.dll to lua5.1.dll and put it into the Wireshark folder (you can follow the instructions here: http://lua-users.org/wiki/LuaProxyDllThree and you can use either gcc or visual studio script).

Leave a comment

what will you say?
(required)
(required)

About

I am Paul Kulchenko.
I live in Kirkland, WA with my wife and three kids.
I do consulting as a software developer.
I study robotics and artificial intelligence.
I write books and open-source software.
I teach introductory computer science.
I develop a slick Lua IDE and debugger.

Recommended

Close