[#wsluarm]

// Attributes
:build_dir: ..

== Lua Support in Wireshark

[#wsluarm_intro]

=== Introduction

Lua is a powerful light-weight programming language designed for extending
applications. Wireshark contains an embedded Lua interpreter which can
be used to write dissectors, taps, and capture file readers and writers.
Wireshark versions 4.2.x and earlier support Lua 5.1 and 5.2, and newer
versions support Lua 5.3 and 5.4. The Lua BitOp library is bundled with
all version of Wireshark; Lua 5.3 and later also have native support for
https://www.lua.org/manual/5.4/manual.html#3.4.2[bitwise operators].

If Lua is enabled, Wireshark will first try to load a file named `init.lua`
from the global link:{wireshark-users-guide-url}ChPluginFolders.html[_plugins directory_].
and then from the user’s
link:{wireshark-users-guide-url}ChAppFilesConfigurationSection.html[_personal plugins directory_].
Then all files ending with _.lua_ are loaded from the global plugins
directory and its subdirectories. Then all files ending with _.lua_ in the
personal Lua plugins directory and its subdirectories are loaded. The
files are processed in ASCIIbetical order (compared byte-by-byte, as `strcmp`),
descending into each subdirectory depth-first in order.

Whether or not Lua scripts are enabled can be controlled via the
_$$enable_lua$$_ variable. Lua scripts are enabled by
default. To disable Lua scripts, set the _$$enable_lua$$_ variable to _false_.
Wireshark 2.6 and earlier enabled or disabled Lua scripts using
the variable _$$disable_lua$$_ (deprecated). If both _$$enable_lua$$_ and
_$$disable_lua$$_ are present, _$$disable_lua$$_ is ignored.

.Example for init.lua
[source,lua]
----
-- Set enable_lua to false to disable Lua support.
enable_lua = true

if not enable_lua then
    return
end

-- If false and Wireshark was started as (setuid) root, then the user
-- will not be able to execute custom Lua scripts from the personal
-- configuration directory, the -Xlua_script command line option or
-- the Lua Evaluate menu option in the GUI.
-- Note: Not checked on Windows. running_superuser is always false.
run_user_scripts_when_superuser = true
----

The command line option _$$-X lua_script:$$++file.lua++_ can also be used to load
specific Lua scripts. Arguments can be given to a script loaded at the command
line with the option _$$-X lua_scriptN:$$++arg++_, where _N_ is the ordinal
index of the script on the command line. For example, if two scripts were loaded
on the command line with _$$-X lua_script:$$++my.lua++_ and
_$$-X lua_script:$$++other.lua++_ in that order, then _$$-X lua_script1:$$++foo++_
would pass _foo_ to _my.lua_ and _$$-X lua_script2:$$++bar++_ would pass _bar_ to
_other.lua_. Multiple command line options could be passed to _my.lua_ by
repeating the option _$$-X lua_script1:$$_.  Arguments are available in a script in
a global table called _arg_, similar to when
link:https://www.lua.org/manual/5.4/manual.html#7[running Lua standalone].

[IMPORTANT]
.Loading order matters
====
Lua dissectors, unlike <<ChapterDissection,compiled protocol dissectors>>, do
not have separate <<ChDissectSetup,registration and handoff>> stages yet
(see wsbuglink:15907[]). Each Lua dissector's registration and handoff is
completed before moving to the next Lua file in turn.
That means that the order in which Lua files are read is quite important;
in order for a Lua dissector to register in a dissector table set up by another
dissector, the latter dissector must have been already processed. The easiest
way to ensure this is to put Lua dissectors that need to be registered first
in files whose name is earlier in ASCIIbetical order (the name of the script
does not necessarily need to relate to the name of the dissector.)

The Lua code is executed after all compiled dissectors, both built-in and plugin,
are initialized and before reading any file.
This means that Lua dissectors can add themselves to tables registered by compiled
dissectors, but not vice versa; compiled dissectors cannot add themselves to
dissector tables registered by Lua dissectors.
====

Wireshark for Windows uses a modified Lua runtime
(link:https://github.com/Lekensteyn/lua-unicode[lua-unicode]) to
support Unicode (UTF-8) filesystem paths. This brings consistency with other
platforms (for example, Linux and macOS).

[#wslua_menu_example]

=== Example: Creating a Menu with Lua

The code below adds a menu "Lua Dialog Test" under the Tools menu.
When selected, it opens a dialog prompting the user for input
and then opens a text window with the output.

[source,lua]
----

-- Define the menu entry's callback
local function dialog_menu()
    local function dialog_func(person,eyes,hair)
        local window = TextWindow.new("Person Info");
        local message = string.format("Person %s with %s eyes and %s hair.", person, eyes, hair);
        window:set(message);
    end

    new_dialog("Dialog Test",dialog_func,"A Person","Eyes","Hair")
end

-- Create the menu entry
register_menu("Lua Dialog Test",dialog_menu,MENU_TOOLS_UNSORTED)

-- Notify the user that the menu was created
if gui_enabled() then
   local splash = TextWindow.new("Hello!");
   splash:set("Wireshark has been enhanced with a useless feature.\n")
   splash:append("Go to 'Tools->Lua Dialog Test' and check it out!")
end

----

[#wslua_dissector_example]

=== Example: Dissector written in Lua

[source,lua]
----
local p_multi = Proto("multi", "MultiProto");

local vs_protos = {
        [2] = "mtp2",
        [3] = "mtp3",
        [4] = "alcap",
        [5] = "h248",
        [6] = "ranap",
        [7] = "rnsap",
        [8] = "nbap"
}

local f_proto = ProtoField.uint8("multi.protocol", "Protocol", base.DEC, vs_protos)
local f_dir = ProtoField.uint8("multi.direction", "Direction", base.DEC, { [1] = "incoming", [0] = "outgoing"})
local f_text = ProtoField.string("multi.text", "Text")

p_multi.fields = { f_proto, f_dir, f_text }

local data_dis = Dissector.get("data")

local protos = {
        [2] = Dissector.get("mtp2"),
        [3] = Dissector.get("mtp3"),
        [4] = Dissector.get("alcap"),
        [5] = Dissector.get("h248"),
        [6] = Dissector.get("ranap"),
        [7] = Dissector.get("rnsap"),
        [8] = Dissector.get("nbap"),
        [9] = Dissector.get("rrc"),
        [10] = DissectorTable.get("sctp.ppi"):get_dissector(3), -- m3ua
        [11] = DissectorTable.get("ip.proto"):get_dissector(132), -- sctp
}

function p_multi.dissector(buf, pkt, tree)

        local subtree = tree:add(p_multi, buf(0,2))
        subtree:add(f_proto, buf(0,1))
        subtree:add(f_dir, buf(1,1))

        local proto_id = buf(0,1):uint()

        local dissector = protos[proto_id]

        if dissector ~= nil then
                -- Dissector was found, invoke subdissector with a new Tvb,
                -- created from the current buffer (skipping first two bytes).
                dissector:call(buf(2):tvb(), pkt, tree)
        elseif proto_id < 2 then
                subtree:add(f_text, buf(2))
                -- pkt.cols.info:set(buf(2, buf:len() - 3):string())
        else
                -- fallback dissector that just shows the raw data.
                data_dis:call(buf(2):tvb(), pkt, tree)
        end

end

local wtap_encap_table = DissectorTable.get("wtap_encap")
local udp_encap_table = DissectorTable.get("udp.port")

wtap_encap_table:add(wtap.USER15, p_multi)
wtap_encap_table:add(wtap.USER12, p_multi)
udp_encap_table:add(7555, p_multi)
----

[#wslua_tap_example]

=== Example: Listener written in Lua

[source,lua]
----
-- This program will register a menu that will open a window with a count of occurrences
-- of every address in the capture

local function menuable_tap()
	-- Declare the window we will use
	local tw = TextWindow.new("Address Counter")

	-- This will contain a hash of counters of appearances of a certain address
	local ips = {}

	-- this is our tap
	local tap = Listener.new();

	local function remove()
		-- this way we remove the listener that otherwise will remain running indefinitely
		tap:remove();
	end

	-- we tell the window to call the remove() function when closed
	tw:set_atclose(remove)

	-- this function will be called once for each packet
	function tap.packet(pinfo,tvb)
		local src = ips[tostring(pinfo.src)] or 0
		local dst = ips[tostring(pinfo.dst)] or 0

		ips[tostring(pinfo.src)] = src + 1
		ips[tostring(pinfo.dst)] = dst + 1
	end

	-- this function will be called once every few seconds to update our window
	function tap.draw(t)
		tw:clear()
		for ip,num in pairs(ips) do
			tw:append(ip .. "\t" .. num .. "\n");
		end
	end

	-- this function will be called whenever a reset is needed
	-- e.g. when reloading the capture file
	function tap.reset()
		tw:clear()
		ips = {}
	end

	-- Ensure that all existing packets are processed.
	retap_packets()
end

-- using this function we register our function
-- to be called when the user selects the Tools->Test->Packets menu
register_menu("Test/Packets", menuable_tap, MENU_TOOLS_UNSORTED)
----

[#wslua_require_example]

=== Example: Lua scripts with shared modules

Lua plugins that depend on protocols, dissectors, dissector tables, and other
items registered with Wireshark by other Lua scripts can access those through
the Wireshark Lua API. The key is ensuring that the providing script is
read first, as previously mentioned.

It is also possible to depend on Lua functions defined in other Lua scripts.
The recommended method is to load those scripts as
link:https://www.lua.org/manual/5.4/manual.html#6.3[modules] via
link:https://www.lua.org/manual/5.4/manual.html#pdf-require[require].
Modules preferably should avoid defining globals, and should return a
table containing functions indexed by name. Globals defined in modules will
leak into the global namespace when `require()` is used, and name collisions
can cause unexpected results. (As an aside, local variables are faster in
Lua because global variables require extra table lookups.) Directories
containing loaded Lua scripts (including those specified on the command line
with _$$-X lua_script:$$++my.lua++_) are automatically added to the `require()`
search path.

For example, suppose there is a Lua script in the personal plugins directory
named _bar.lua_ as follows:

[source,lua]
----
-- bar.lua
-- Converts an integer representing an IPv4 address into its dotted quad
-- string representation.

-- This is the module object, which will be returned at the end of this file.
local M = {
}

M.GetIPAddressString = function(ip)
    -- Lua BitOp library, included in all versions of Wireshark
    --local octet1 = bit.rshift(bit.band(0xFF000000, ip), 24)
    --local octet2 = bit.rshift(bit.band(0x00FF0000, ip), 16)
    --local octet3 = bit.rshift(bit.band(0x0000FF00, ip), 8)
    --local octet4 = bit.band(0x000000FF, ip)

    -- Lua >= 5.3 native bit operators, supported in Wireshark >= 4.4
    local octet1 = ip >> 24
    local octet2 = ip >> 16 & 0xFF
    local octet3 = ip >> 8 & 0xFF
    local octet4 = ip & 0xFF

    return octet1 .. "." .. octet2 .. "." .. octet3 .. "." .. octet4
end

-- Return the table we've created, which will be accessible as the return
-- value of require() or dofile(), and at the global package.loaded["bar"]
return M
----

Other Lua plugins that wish to use the module can then `require()` it
(note that the _.lua_ extension is not used in `require()`, unlike the
similar `dofile()`):

[source,lua]
----
-- Foo dissector
local p_foo = Proto("foo", "Foo")

local bar = require("bar")

local f_ip = ProtoField.ipv4("foo.ip", "IP")
local f_ipint = ProtoField.uint32("foo.ipint", "IP as Uint32")
local f_ipstr = ProtoField.string("foo.ipstr", "IP as String")

p_foo.fields = { f_ip, f_ipint, f_ipstr }

function p_foo.dissector(tvbuf, pktinfo, tree)

    -- Set the protocol column to show this name
    pktinfo.cols.protocol:set("FooMessage")

    local pktlen = tvbuf:reported_length_remaining()

    local subtree = tree:add(p_foo, tvbuf:range(0,pktlen))

    local child, ipaddr = subtree:add_packet_field(f_ip, tvbuf(8, 4), ENC_BIG_ENDIAN)
    local child, ipint = subtree:add_packet_field(f_ipint, tvbuf(8, 4), ENC_BIG_ENDIAN)

    -- These two are the same string
    subtree:add(f_ipstr, tvbuf(8,4), bar.GetIPAddressString(ipint))
    subtree:add(f_ipstr, tvbuf(8,4), tostring(ipaddr))

    return pktlen
end

DissectorTable.get("udp.port"):add(2012, p_foo)
----

Using `require()` is another way to control the order in which files are loaded.
Lua `require()` ensures that a module is only executed once. Subsequent calls
will return the same table already loaded.

[IMPORTANT]
.Avoid duplicate registration
====
In versions of Wireshark before 4.4, the initial loading of Lua plugins in the
plugins directory does not register them in the table of already loaded modules
used by `require()`. This means that Lua script in the plugins directory that
are initially loaded can be executed a second time by `require()`. For scripts
that register dissectors or tables with Wireshark, this will result in errors like
`Proto new: there cannot be two protocols with the same description`. It is
safer to `require()` only Lua scripts that define common functions but do not
call the Wireshark Lua API to register protocols, dissectors, etc.

In 4.4 and later, scripts in the plugin directories are loaded using the same
internal methods as `require()`, which eliminates duplicate registration errors
from loading of files in the plugin directory and using `require()`. This also
means that the order in which plugins are loaded can be adjusted by using
`require()` in addition to changing file names. However, duplicate registration
errors can still happen with other methods of executing a file that do
not check if it has already been loaded, like `dofile()`.
====

Lua scripts loaded on the command line are sandboxed into their own environment
and globals defined in them do not leak in the general global environment.
Modules loaded via `require()` within those scripts can escape that sandboxing,
however. Plugins in the personal (but not global) directory had similar
sandboxing prior to Wireshark 4.4, but now globals defined in plugins in the
personal directory will enter the global namespace for other plugins, as has
always been the case for plugins in the global plugin directory.

[#wsluarm_modules]

== Wireshark’s Lua API Reference Manual

This Part of the User Guide describes the Wireshark specific functions in the embedded Lua.

Classes group certain functionality, the following notational conventions are
used:

* _Class.function()_ represents a class method (named _function_) on class
  _Class_, taking no arguments.

* _Class.function(a)_ represents a class method taking one argument.

* _Class.function(...)_ represents a class method taking a variable number of
  arguments.

* _class:method()_ represents an instance method (named _method_) on an instance
  of class _Class_, taking no arguments. Note the lowercase notation in the
  documentation to clarify an instance.

* _class.prop_ represents a property _prop_ on the instance of class _Class_.

Trying to access a non-existing property, function or method currently gives an
error, but do not rely on it as the behavior may change in the future.


include::{build_dir}/wsluarm_src/wslua_utility.adoc[]
include::{build_dir}/wsluarm_src/wslua_gui.adoc[]
include::{build_dir}/wsluarm_src/wslua_proto.adoc[]
include::{build_dir}/wsluarm_src/wslua_field.adoc[]
include::{build_dir}/wsluarm_src/wslua_pinfo.adoc[]
include::{build_dir}/wsluarm_src/wslua_tvb.adoc[]
include::{build_dir}/wsluarm_src/wslua_tree.adoc[]
include::{build_dir}/wsluarm_src/wslua_listener.adoc[]
include::{build_dir}/wsluarm_src/wslua_dumper.adoc[]
include::{build_dir}/wsluarm_src/wslua_wtap.adoc[]
include::{build_dir}/wsluarm_src/wslua_file.adoc[]
include::{build_dir}/wsluarm_src/wslua_dir.adoc[]
include::{build_dir}/wsluarm_src/wslua_int64.adoc[]
include::{build_dir}/wsluarm_src/wslua_struct.adoc[]
include::{build_dir}/wsluarm_src/wslua_gcrypt.adoc[]

[#lua_module_PCRE2]

=== PCRE2 Regular Expressions

Lua has its own native _pattern_ syntax in the string library, but sometimes a
real regex engine is more useful. Wireshark comes with Perl Compatible Regular
Expressions version 2 (PCRE2). This engine is exposed into Wireshark’s Lua engine through the
well-known Lrexlib library. The module is loaded in the global environment using
the "rex_pcre2" table. The manual is available at https://rrthomas.github.io/lrexlib/manual.html.

=== Bitwise Operations

Lua 5.3 and greater has native https://www.lua.org/manual/5.4/manual.html#3.4.2[bitwise operators].
The https://www.lua.org/manual/5.2/manual.html#6.7[bit32 library] introduced
in Lua 5.2 is in Lua 5.3, albeit https://www.lua.org/manual/5.3/manual.html#8[deprecated],
but not present in Lua 5.4. For maximum backwards compatibility, all versions of Wireshark
with Lua support include the Lua BitOp library, which has been ported to be compatible with
Lua 5.3 and 5.4. The BitOp API reference is available at https://bitop.luajit.org/api.html.
The API is similar to that of the `bit32` library, and in many cases can function as a drop
in replacement for code written to use that library by simply replacing a
`bit32 = require("bit32")` statement with `bit32 = bit`.

[NOTE]
The library is already loaded in the global environment as the `bit` table; a
statement like `local bit = require("bit")` is not necessary in Lua dissectors.
On Wireshark versions prior to 4.6 this will give an error (unless another copy
of the BitOp library is also accessible to the system Lua outside the Wireshark
distributed code.) On Wireshark version 4.6 and later such statements behave as
expected but are largely superfluous.