Quicklinks: Wireshark: Lua API docs | Lua Examples
Lua scripting allows you to dynamically access info that might not be available in Wireshark normally! Examples will be added at some point.
To use a lua script with tshark, use option -X lua_script:<path/to/script>.
Obligatory Hello World example, capturing one packet:
bash$ echo 'print("Hello World!")' > temp.lua
bash$ tshark -X lua_script:temp.lua -c 1
Hello World!
Capturing on 'Wi-Fi: en0'
1 0.000000 178.33.111.155 → mbp.attlocal.net TLSv1.2 839 Application Data
5 packets dropped from Wi-Fi: en0
1 packet captured
⚠️ AI-Generated Content: This section was added using Claude Code (Opus 4.6) and requires validation by the community. Please verify accuracy before relying on this information in production environments.
The -X flag enables advanced extension options for tshark, including loading custom Lua scripts, passing arguments to scripts, and controlling read formats. This is critical for custom dissectors, proprietary protocols, and IoT/ICS environments.
tshark -X <key>:<value>
Load custom dissectors or analysis scripts:
# Load a custom dissector
tshark -X lua_script:custom_dissector.lua -r capture.pcap
# Load multiple scripts
tshark -X lua_script:dissector1.lua \
-X lua_script:dissector2.lua \
-r capture.pcap
Real-world use cases:
Pass configuration to loaded Lua scripts using lua_scriptnum:argument:
# Load script and pass an argument to it
tshark -X lua_script:my_parser.lua \
-X lua_script1:config_value \
-r capture.pcap
# Pass arguments to multiple scripts
tshark -X lua_script:script1.lua \
-X lua_script:script2.lua \
-X lua_script1:arg_for_script1 \
-X lua_script2:arg_for_script2 \
-r capture.pcap
Script indexing: Scripts are numbered in the order they’re loaded (1, 2, 3, etc.).
Example Lua script that uses arguments:
-- my_parser.lua
-- Access the argument via arg global variable
local function init()
local config = arg or "default_value"
print("Script started with config: " .. config)
end
init()
Usage:
tshark -X lua_script:my_parser.lua \
-X lua_script1:production_mode \
-r capture.pcap
Override the file format detection to force tshark to read a file as a specific format:
# Read file as a specific format
tshark -r unusual.bin \
-X read_format:Custom_Format \
-X lua_script:custom_format_handler.lua
Use cases:
-- iot_protocol.lua
-- Simple dissector for proprietary IoT protocol
local iot_proto = Proto("iot", "Custom IoT Protocol")
local f_type = ProtoField.uint8("iot.type", "Packet Type", base.DEC)
local f_device_id = ProtoField.uint32("iot.device_id", "Device ID", base.HEX)
local f_data = ProtoField.bytes("iot.data", "Payload Data")
iot_proto.fields = {f_type, f_device_id, f_data}
function iot_proto.dissector(buffer, pinfo, tree)
pinfo.cols.protocol = "IoT"
local subtree = tree:add(iot_proto, buffer())
subtree:add(f_type, buffer(0,1))
subtree:add(f_device_id, buffer(1,4))
subtree:add(f_data, buffer(5))
end
-- Register on specific UDP port
local udp_table = DissectorTable.get("udp.port")
udp_table:add(5000, iot_proto)
Usage:
# Analyze IoT traffic with custom dissector
tshark -X lua_script:iot_protocol.lua \
-r iot_capture.pcap \
-Y "iot.device_id==0x12345678" \
-T fields -e iot.type -e iot.data
-- field_extractor.lua
-- Extract specific fields based on configuration
local config = arg or "ip.src,ip.dst"
print("Extracting fields: " .. config)
-- Add extraction logic here
Usage:
# Extract configured fields
tshark -X lua_script:field_extractor.lua \
-X lua_script1:"tcp.stream,tcp.port,http.host" \
-r web.pcap
-- modbus_analyzer.lua
-- Analyze MODBUS function codes for anomalies
local modbus_proto = Proto("modbus_ext", "MODBUS Analyzer")
function modbus_proto.dissector(buffer, pinfo, tree)
-- Check for dangerous function codes
local func_code = buffer(7,1):uint()
if func_code == 0x06 or func_code == 0x10 then
pinfo.cols.info:prepend("[WRITE OPERATION] ")
tree:add_expert_info(PI_SECURITY, PI_WARN, "MODBUS write detected")
end
end
DissectorTable.get("tcp.port"):add(502, modbus_proto)
Usage:
# Monitor MODBUS traffic for write operations
tshark -X lua_script:modbus_analyzer.lua \
-i eth0 \
-f "tcp port 502" \
-Y "modbus_ext"
#!/bin/bash
# Test custom protocol implementation
tshark -X lua_script:protocol_validator.lua \
-X lua_script1:strict_mode \
-r test_capture.pcap \
-q > validation_results.txt
if grep -q "VALIDATION FAILED" validation_results.txt; then
echo "Protocol validation failed!"
exit 1
fi
#!/bin/bash
# Analyze mixed IoT protocols
declare -a protocols=("zigbee" "zwave" "custom_rf")
for proto in "${protocols[@]}"; do
tshark -X lua_script:${proto}_dissector.lua \
-r iot_capture.pcap \
-Y ${proto} \
-T json > ${proto}_data.json
done
While -X primarily focuses on lua_script and read_format, it can also be used for other internal options. Check the tshark man page for the most current list:
man tshark | grep -A 20 "^[[:space:]]*-X"
# Verify script syntax
lua script.lua
# Check tshark recognizes the script
tshark -X lua_script:script.lua -v
# Debug: Print all arguments in Lua
print("Args:", table.concat({...}, ", "))
-- Ensure protocol is registered correctly
local function register()
print("Registering protocol...")
DissectorTable.get("tcp.port"):add(12345, my_proto)
end
register()
Lua scripts add processing overhead. Optimize by:
Filter early: Use -Y to reduce packets processed by Lua
tshark -Y "tcp.port==502" -X lua_script:heavy_script.lua -r capture.pcap
Disable unnecessary protocols: Speed up dissection
tshark --disable-all-protocols \
--enable-protocol ip --enable-protocol tcp \
-X lua_script:custom.lua -r capture.pcap
Minimize string operations: Use buffers directly in Lua
There are two libraries I came across that are more metaprogramming that lua dissectors:
I’ve compiled a list of the most popular lua dissectors on github.
Have a dissector you want added to this list? Has a dissector been merged into Wireshark? Make a pull request.
A ✔ is given for each of the following (in order of importance):
Star/Fork count in 2019 Aug [★] and can be converted to an in-browser javascript github API query. Repos below are on github and have at least 5 stars. None of these repos have been tested.
Note: Any derivative works of Wireshark MUST use a GPL2-compatible license.