The classes and functions in this chapter allow Lua scripts to create new protocols for Wireshark.
Proto protocol objects can have Pref preferences, ProtoField fields for filterable values that can be displayed in a details view tree, functions for dissecting the new protocol, and so on.
The dissection function can be hooked into existing protocol tables through DissectorTable so that the new protocol dissector function gets called by that protocol, and the new dissector can itself call on other, already existing protocol dissectors by retrieving and calling the Dissector object.
A Proto dissector can also be used as a post-dissector, at the end of every frame’s dissection, or as a heuristic dissector.
A reference to a dissector, used to call a dissector against a packet or a part of it.
Obtains a dissector reference by name.
The Dissector reference if found, otherwise nil.
Gets a Lua array table of all registered Dissector names.
Note: This is an expensive operation, and should only be used for troubleshooting.
The array table of registered dissector names.
Calls a dissector against a given packet (or part of it).
Number of bytes dissected. Note that some dissectors always return number of bytes in incoming buffer, so be aware.
Calls a dissector against a given packet (or part of it).
Calls a dissector against a given packet (or part of it).
Number of bytes dissected and decrypted content
A table of subdissectors of a particular protocol (e.g. TCP subdissectors like http, smtp, sip are added to table "tcp.port").
Useful to add more dissectors to a table so that they appear in the “Decode As…” dialog.
Creates a new DissectorTable for your dissector’s use.
tablename, but can be any string.
ftypes.UINT8, ftypes.UINT16,
ftypes.UINT24, ftypes.UINT32,
ftypes.STRING, ftypes.NONE,
or ftypes.GUID.
Defaults to ftypes.UINT32.
base.NONE, base.DEC, base.HEX,
base.OCT, base.DEC_HEX or base.HEX_DEC.
Defaults to base.DEC.
Proto object that uses this dissector table.
The newly created DissectorTable.
Creates a new heuristic DissectorTable for your dissector’s use. Returns true if table was created successfully.
Since: 4.2.0
tablename, but can be any string.
Proto object that uses this dissector table.
The newly created DissectorTable.
Gets a Lua array table of all DissectorTable names - i.e., the string names you can use for the first argument to DissectorTable.get().
Note: This is an expensive operation, and should only be used for troubleshooting.
The array table of registered DissectorTable names.
Gets a Lua array table of all heuristic list names - i.e., the string names you can use for the first argument in Proto:register_heuristic().
Note: This is an expensive operation, and should only be used for troubleshooting.
The array table of registered heuristic list names
Try all the dissectors in a given heuristic dissector table.
True if the packet was recognized by the sub-dissector (stop dissection here).
Obtain a reference to an existing dissector table.
The DissectorTable reference if found, otherwise nil.
Add a Proto with a dissector function or a Dissector object to the dissector table.
Clear all existing dissectors from a table and add a new dissector or a range of new dissectors.
Remove a dissector or a range of dissectors from a table.
Try to call a dissector from a table.
Tvb to dissect.
Pinfo.
TreeItem on which to add the protocol items.
Number of bytes dissected. Note that some dissectors always return number of bytes in incoming buffer, so be aware.
Try to obtain a dissector from a table.
The Dissector handle if found, otherwise nil
Add the given Proto to the “Decode as…” list for this DissectorTable.
The passed-in Proto object’s dissector() function is used for dissecting.
Proto to add.
Gets some debug information about the DissectorTable.
A string of debug information about the DissectorTable.
A preference of a Proto.
Creates a boolean preference to be added to a Proto.prefs Lua table.
-- create a Boolean preference named "bar" for Foo Protocol
-- (assuming Foo doesn't already have a preference named "bar")
proto_foo.prefs.bar = Pref.bool( "Bar", true, "Baz and all the rest" )
Creates an (unsigned) integer preference to be added to a Proto.prefs Lua table.
Creates a string preference to be added to a Proto.prefs Lua table.
Creates an enum preference to be added to a Proto.prefs Lua table.
local OUTPUT_OFF = 0
local OUTPUT_DEBUG = 1
local OUTPUT_INFO = 2
local OUTPUT_WARN = 3
local OUTPUT_ERROR = 4
local output_tab = {
{ 1, "Off" , OUTPUT_OFF },
{ 2, "Debug" , OUTPUT_DEBUG },
{ 3, "Information" , OUTPUT_INFO },
{ 4, "Warning" , OUTPUT_WARN },
{ 5, "Error" , OUTPUT_ERROR },
}
-- Create enum preference that shows as Combo Box under
-- Foo Protocol's preferences
proto_foo.prefs.outputlevel = Pref.enum(
"Output Level", -- label
OUTPUT_INFO, -- default value
"Verbosity of log output", -- description
output_tab, -- enum table
false -- show as combo box
)
-- Then, we can query the value of the selected preference.
-- This line prints "Output Level: 3" assuming the selected
-- output level is _INFO.
debug( "Output Level: " .. proto_foo.prefs.outputlevel )
Creates a range (numeric text entry) preference to be added to a Proto.prefs Lua table.
Creates a static text string to be added to a Proto.prefs Lua table.
Creates an uat preference to be added to a Proto.prefs Lua table, or
read an existent uat table content, and returns in a table, all returned cell conent is in string format.
local fieldlist = {
{"field 1", "Description 1"},
{"field 2", "Description 2"},
}
-- Create a uat preference that appears as a button on the Foo Protocol preference page.
-- The user accessible table can be edited with this button.
proto_foo.prefs.preference_uat_name = Pref.uat("Label", fieldlist, "Description", "uat_filename")
-- Value checker:
-- Create a file in Personal Lua plugins directory named as preferences_uat_callbacks.lua
-- Create a checker function named as uat_update_cb:
-- The uat editor will call this function for checks the values.
function uat_update_cb(records, uat_filename)
print("UAT filename: " .. uat_filename)
print("UAT record 0 = " .. records[0])
print("UAT record 1 = " .. records[1])
local result = true
local errstring = ""
-- do not allow 5 in the "field 1
if (tonumber(records[0]) == 5) then
result = false
errstring = "Firsct collumn cannot be 5!"
end
print("Check result = " .. tostring(result))
-- return check result as boolean and errstring if needed
return result, errstring
end
-- Reading existent uat:
proto_foo.prefs.preference_existent_uat_name = Pref.uat("Protobuf Search Paths")
for i, row in ipairs(proto_foo.prefs.preference_existent_uat_name) do
local row_str = ""
for j, value in ipairs(row) do
row_str = row_str .. value .. "\t"
end
print(row_str)
end
The table of preferences of a protocol.
A new protocol in Wireshark. Protocols have several uses. The main one is to dissect a protocol, but they can also be dummies used to register preferences for other purposes.
Creates a new Proto object.
The newly created Proto object.
Creates a Proto object.
The new Proto object.
Registers a heuristic dissector function for this Proto protocol,
for the given heuristic list name.
When later called, the passed-in function will be given:
The function must return true if the payload is for it, else false.
The function should perform as much verification as possible to ensure the payload is for it, and dissect the packet (including setting TreeItem info and such) only if the payload is for it, before returning true or false.
Since version 1.99.1, this function also accepts a Dissector object as the second argument,
to allow re-using the same Lua code as the function proto.dissector(…). In this case,
the Dissector must return a Lua number of the number of bytes consumed/parsed: if 0 is returned,
it will be treated the same as a false return for the heuristic; if a positive or negative
number is returned, then the it will be treated the same as a true return for the heuristic,
meaning the packet is for this protocol and no other heuristic will be tried.
Mode: Retrieve or assign.
The protocol’s dissector, a function you define.
When later called, the function will be given:
Mode: Assign only.
The preferences changed routine of this dissector, a Lua function you define.
The function is called when the protocol’s preferences are changed. It is passed no arguments.
Mode: Assign only.
The init routine of this dissector, a function you define.
The init function is called when the a new capture file is opened or when the open capture file is closed. It is passed no arguments.
Mode: Retrieve or assign.
The Lua table of this dissector’s ProtoFields.
ProtoFields added to this table are registered to the Proto (and any
removed are deregistered if previously registered.)
A Protocol expert info field, to be used when adding items to the dissection tree.
Creates a new ProtoExpert object to be used for a protocol’s expert information notices.
expert.group.CHECKSUM,
expert.group.SEQUENCE,
expert.group.RESPONSE_CODE,
expert.group.REQUEST_CODE,
expert.group.UNDECODED,
expert.group.REASSEMBLE,
expert.group.MALFORMED,
expert.group.DEBUG,
expert.group.PROTOCOL,
expert.group.SECURITY,
expert.group.COMMENTS_GROUP,
expert.group.DECRYPTION,
expert.group.ASSUMPTION,
expert.group.DEPRECATED,
expert.group.RECEIVE,
or expert.group.INTERFACE.
expert.severity.COMMENT,
expert.severity.CHAT,
expert.severity.NOTE,
expert.severity.WARN,
or expert.severity.ERROR.
The newly created ProtoExpert object.
A Protocol field (to be used when adding items to the dissection tree).
It must be registered via being added to a Proto.fields table.
Creates a new ProtoField object to be used for a protocol field.
ftypes.BOOLEAN, ftypes.CHAR, ftypes.UINT8,
ftypes.UINT16, ftypes.UINT24, ftypes.UINT32, ftypes.UINT64, ftypes.INT8,
ftypes.INT16, ftypes.INT24, ftypes.INT32, ftypes.INT64, ftypes.FLOAT,
ftypes.DOUBLE , ftypes.ABSOLUTE_TIME, ftypes.RELATIVE_TIME, ftypes.STRING,
ftypes.STRINGZ, ftypes.UINT_STRING, ftypes.ETHER, ftypes.BYTES,
ftypes.UINT_BYTES, ftypes.IPv4, ftypes.IPv6, ftypes.IPXNET, ftypes.FRAMENUM,
ftypes.PCRE, ftypes.GUID, ftypes.OID, ftypes.PROTOCOL, ftypes.REL_OID,
ftypes.SYSTEM_ID, ftypes.EUI64 or ftypes.NONE.
base.RANGE_STRING, or a table containing unit name
for the values if base is base.UNIT_STRING, or one of frametype.NONE, frametype.REQUEST,
frametype.RESPONSE, frametype.ACK or frametype.DUP_ACK if field type is ftypes.FRAMENUM.
base.NONE, base.DEC,
base.HEX, base.OCT, base.DEC_HEX or base.HEX_DEC.
It can be ORed with base.UNIT_STRING, base.RANGE_STRING
or base.SPECIAL_VALS.
The newly created ProtoField object.
Creates a ProtoField of an 8-bit ASCII character.
base.NONE, base.HEX or base.OCT. It can be ORed with both base.RANGE_STRING and base.SPECIAL_VALS.
base.RANGE_STRING.
A ProtoField object to be added to a table set to the Proto.fields attribute.
Creates a ProtoField of an unsigned 8-bit integer (i.e., a byte).
base.DEC, base.HEX, base.OCT, base.DEC_HEX or base.HEX_DEC. It can be ORed with base.UNIT_STRING, base.RANGE_STRING or base.SPECIAL_VALS.
base.RANGE_STRING, or a table containing the unit name for the values if base is base.UNIT_STRING.
A ProtoField object to be added to a table set to the Proto.fields attribute.
Creates a ProtoField of an unsigned 16-bit integer.
base.DEC, base.HEX, base.OCT, base.DEC_HEX or base.HEX_DEC. It can be ORed with base.UNIT_STRING, base.RANGE_STRING or base.SPECIAL_VALS.
base.RANGE_STRING, or a table containing unit name for the values if base is base.UNIT_STRING.
A ProtoField object to be added to a table set to the Proto.fields attribute.
Creates a ProtoField of an unsigned 24-bit integer.
base.DEC, base.HEX, base.OCT, base.DEC_HEX or base.HEX_DEC. It can be ORed with base.UNIT_STRING, base.RANGE_STRING or base.SPECIAL_VALS.
base.RANGE_STRING, or a table containing the unit name for the values if base is base.UNIT_STRING.
A ProtoField object to be added to a table set to the Proto.fields attribute.
Creates a ProtoField of an unsigned 32-bit integer.
base.DEC, base.HEX, base.OCT, base.DEC_HEX or base.HEX_DEC. It can be ORed with base.UNIT_STRING, base.RANGE_STRING or base.SPECIAL_VALS.
base.RANGE_STRING, or a table containing the unit name for the values if base is base.UNIT_STRING.
A ProtoField object to be added to a table set to the Proto.fields attribute.
Creates a ProtoField of an unsigned 64-bit integer.
base.DEC, base.HEX, base.OCT, base.DEC_HEX or base.HEX_DEC. It can be ORed with base.UNIT_STRING, base.RANGE_STRING or base.SPECIAL_VALS.
base.RANGE_STRING, or a table containing the unit name for the values if base is base.UNIT_STRING.
A ProtoField object to be added to a table set to the Proto.fields attribute.
Creates a ProtoField of a signed 8-bit integer (i.e., a byte).
base.DEC, optionally ORed with base.UNIT_STRING, base.RANGE_STRING or base.SPECIAL_VALS.
base.RANGE_STRING, or a table containing unit name for the values if base is base.UNIT_STRING.
A ProtoField object to be added to a table set to the Proto.fields attribute.
Creates a ProtoField of a signed 16-bit integer.
base.DEC, optionally ORed with base.UNIT_STRING, base.RANGE_STRING or base.SPECIAL_VALS.
base.RANGE_STRING, or a table containing unit name for the values if base is base.UNIT_STRING.
A ProtoField object to be added to a table set to the Proto.fields attribute.
Creates a ProtoField of a signed 24-bit integer.
base.DEC, optionally ORed with base.UNIT_STRING, base.RANGE_STRING or base.SPECIAL_VALS.
base.RANGE_STRING, or a table containing unit name for the values if base is base.UNIT_STRING.
A ProtoField object to be added to a table set to the Proto.fields attribute.
Creates a ProtoField of a signed 32-bit integer.
base.DEC, optionally ORed with base.UNIT_STRING, base.RANGE_STRING or base.SPECIAL_VALS.
base.RANGE_STRING, or a table containing unit name for the values if base is base.UNIT_STRING.
A ProtoField object to be added to a table set to the Proto.fields attribute.
Creates a ProtoField of a signed 64-bit integer.
base.DEC, optionally ORed with base.UNIT_STRING, base.RANGE_STRING or base.SPECIAL_VALS.
base.RANGE_STRING, or a table containing unit name for the values if base is base.UNIT_STRING.
A ProtoField object to be added to a table set to the Proto.fields attribute.
Creates a ProtoField for a frame number (for hyperlinks between frames).
base.NONE is supported for framenum.
frametype.NONE, frametype.REQUEST, frametype.RESPONSE, frametype.ACK or frametype.DUP_ACK.
A ProtoField object to be added to a table set to the Proto.fields attribute.
Creates a ProtoField for a boolean true/false value.
base.NONE is used for NULL-value).
A ProtoField object to be added to a table set to the Proto.fields attribute.
Creates a ProtoField of a time_t structure value.
base.LOCAL, base.UTC or base.DOY_UTC.
A ProtoField object to be added to a table set to the Proto.fields attribute.
Creates a ProtoField of a time_t structure value.
A ProtoField object to be added to a table set to the Proto.fields attribute.
Creates a ProtoField of a floating point number (4 bytes).
A ProtoField object to be added to a table set to the Proto.fields attribute.
Creates a ProtoField of a double-precision floating point (8 bytes).
A ProtoField object to be added to a table set to the Proto.fields attribute.
Creates a ProtoField of a string value.
base.ASCII or base.UNICODE.
A ProtoField object to be added to a table set to the Proto.fields attribute.
Creates a ProtoField of a zero-terminated string value.
base.ASCII or base.UNICODE.
A ProtoField object to be added to a table set to the Proto.fields attribute.
Creates a ProtoField for an arbitrary number of bytes.
base.NONE, base.DOT, base.DASH, base.COLON or base.SPACE.
A ProtoField object to be added to a table set to the Proto.fields attribute.
Creates a ProtoField for an arbitrary number of unsigned bytes.
base.NONE, base.DOT, base.DASH, base.COLON or base.SPACE.
A ProtoField object to be added to a table set to the Proto.fields attribute.
Creates a ProtoField of an unstructured type.
A ProtoField object to be added to a table set to the Proto.fields attribute.
Creates a ProtoField of an IPv4 address (4 bytes).
A ProtoField object to be added to a table set to the Proto.fields attribute.
Creates a ProtoField of an IPv6 address (16 bytes).
A ProtoField object to be added to a table set to the Proto.fields attribute.
Creates a ProtoField of an Ethernet address (6 bytes).
A ProtoField object to be added to a table set to the Proto.fields attribute.
Creates a ProtoField for a Globally Unique IDentifier (GUID).
A ProtoField object to be added to a table set to the Proto.fields attribute.
Creates a ProtoField for an ASN.1 Organizational IDentified (OID).
A ProtoField object to be added to a table set to the Proto.fields attribute.
Creates a ProtoField for a sub-protocol.
A ProtoField object to be added to a table set to the Proto.fields attribute.
Creates a ProtoField for an ASN.1 Relative-OID.
A ProtoField object to be added to a table set to the Proto.fields attribute.
Creates a ProtoField for an OSI System ID.
A ProtoField object to be added to a table set to the Proto.fields attribute.
Creates a ProtoField for an EUI64.
A ProtoField object to be added to a table set to the Proto.fields attribute.
Returns a string with info about a protofield (for debugging purposes).
Make a Proto protocol (with a dissector function) a post-dissector.
It will be called for every frame after dissection.