Lua library to facilitate the development of Wireshark dissectors by enabling users to run them against packet data without Wireshark. The packet data can come from a hexadecimal string or a .pcap file. The goal here is to provide a tool reducing development time when creating a new dissector.
The following is an example of output produced when running your dissector with WireBait as a "standalone" script.
------------------------------------------------------------------------------------------------------------------------------[[
No. | Time | Source | Destination | Protocol | Length | Info
1 | 02:02:47.146635 | 192.168.0.1 | 255.255.255.255 | Demo | 173 | 59121 → 7437 Len=32
0E 07 DE 02 22 FC 03 19 75 5A 7F FF FF FF FF FF | Demo Protocol
FF 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 | └─ Unsigned integers:
| └─ 8-bit uint: 14
| └─ 16-bit uint: 2014
| └─ 24-bit uint: 140028
| └─ 32-bit uint: 52000090
| └─ 64-bit uint: 9223372036854775807
]]------------------------------------------------------------------------------------------------------------------------------
What does it do?
Requirements
Quick start
Examples
State of the project
What's next and how to contribute?
Licensing
It simply exposes the Wireshark Lua API (or here) and attempts to reproduce its behavior. As a result, your script becomes "self sufficient" and you can execute it directly and without Wireshark. If you provide it with some data, it will print a text version of the dissection tree along with the payload in hexadecimal format. Now you can make changes to your dissector and see the effects immediately without leaving your Lua IDE!
Note that WireBait does not interact at all with Wireshark.
Getting started takes less than a minute:
if disable_lua == nil and enable_lua == nil and not _WIREBAIT_ON_ then
local wirebait = require("wirebaitlib");
local dissector_tester = wirebait.new({only_show_dissected_packets=true});
dissector_tester:dissectHexData("72ABE636AFC86572") -- To dissect hex data from a string (no pcap needed)
dissector_tester:dissectPcap("path_to_your_pcap_file.pcap") -- To dissect packets from a pcap file
return
end
local dissector_tester = wirebait.new({dissector_filepath="path_to_your_dissector.lua", only_show_dissected_packets=true});
Execute your dissector script. Enjoy :smiley: And please, feel free to give me feedback!
If you run the example dissector script demo_dissector.lua, which dissects the data provided as an hexadecimal string, you should get the following output:
------------------------------------------------------------------------------------------------------------------------------[[
Dissecting hexadecimal data (no pcap provided)
0E 07 DE 02 22 FC 03 19 75 5A 7F FF FF FF FF FF | Demo Protocol
FF FF F2 F8 22 FD DD 04 FC E6 8A A6 80 00 00 00 | └─ Unsigned integers:
00 00 00 01 57 69 72 65 62 61 69 74 00 62 79 20 | └─ 8-bit uint: 14
4D 61 72 6B 6F 50 61 75 6C 30 00 00 AA BB CC 11 | └─ 16-bit uint: 2014
22 33 C0 A8 0E 1C AB CD EF 12 34 56 78 90 AB CD | └─ 24-bit uint: 140028
EF 12 34 56 78 90 00 00 00 00 00 00 00 00 00 00 | └─ 32-bit uint: 52000090
00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 | └─ 64-bit uint: 9223372036854775807
00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 | └─ Signed integers:
00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 | └─ 8-bit int: -14
00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 | └─ 16-bit int: -2014
00 00 00 00 00 00 00 00 00 00 00 00 00 | └─ 24-bit int: -140028
| └─ 32-bit int: -52000090
| └─ 64-bit int: -9223372036854775807
| └─ Strings:
| └─ String: Wirebait
| └─ Stringz: Wirebait
| └─ Other types:
| └─ bytes: aabbcc112233c0a80e1cabcdef1234567890abcdef1234567890...
| └─ ethernet: aa:bb:cc:11:22:33
| └─ IPv4: 192.168.14.28
| └─ GUID: abcdef12-3456-7890-abcd-ef1234567890
]]------------------------------------------------------------------------------------------------------------------------------
In wireshark the same dissection would look like this:
Something to note is that the hex string only contains the UDP (or TCP) payload, i.e. only the data to be dissected. No need to worry about making up ethernet, IP, or TCP/UDP headers.
If you run the example dissector script demo_dissector2.lua, which dissects the same data as in the first example but provided by the demo.pcap file, you should get the same dissection output. One difference is that you will also get packet information that is provided by ethernet, IP, and TCP/UDP headers:
------------------------------------------------------------------------------------------------------------------------------[[
No. | Time | Source | Destination | Protocol | Length | Info
1 | 02:02:47.146635 | 192.168.0.1 | 255.255.255.255 | Demo | 173 | 59121 → 7437 Len=173
0E 07 DE 02 22 FC 03 19 75 5A 7F FF FF FF FF FF | Demo Protocol
FF FF F2 F8 22 FD DD 04 FC E6 8A A6 80 00 00 00 | └─ Unsigned integers:
.......<trimmed output, same as example 1>
A few notes about the current state of the project:
For more information you can check what I'm up to in the Project section.
Right now I would like to collect feedback from Wireshark users. People who already have Lua dissectors can really help by running their dissectors using Wirebait. I would really appreciate any form of feedback about this tool.
I think - without having collected feedback yet - the next logical step is to expand Wirebait to enable users to unit test their dissectors. The clear cut specifications of protocol definitions are in my opinion a school book example of when unit test driven development makes sense. With unit tests, any protocol or dissector update can be tackled quicly while reducing the risk of introducing new bugs.
WireBait for Wireshark is a lua package to help create Wireshark Dissectors Copyright (C) 2015-2017 Markus Leballeux
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. (Checkout the full license)