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 refererence 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.
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.
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,
base.HEX_DEC, base.UNIT_STRING or
base.RANGE_STRING.
The newly created ProtoField object.
Creates a ProtoField of an 8-bit ASCII character.
base.NONE, base.HEX, base.OCT or base.RANGE_STRING.
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 or base.OCT, base.DEC_HEX, base.HEX_DEC, base.UNIT_STRING or base.RANGE_STRING.
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, base.HEX_DEC, base.UNIT_STRING or base.RANGE_STRING.
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, base.HEX_DEC, base.UNIT_STRING, or base.RANGE_STRING.
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, base.HEX_DEC, base.UNIT_STRING, or base.RANGE_STRING.
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, base.HEX_DEC, base.UNIT_STRING, or base.RANGE_STRING.
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, base.UNIT_STRING, or base.RANGE_STRING.
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, base.UNIT_STRING, or base.RANGE_STRING.
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, base.UNIT_STRING, or base.RANGE_STRING.
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, base.UNIT_STRING, or base.RANGE_STRING.
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, base.UNIT_STRING, or base.RANGE_STRING.
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.
Make the TCP-layer invoke the given Lua dissection function for each PDU in the TCP segment, of the length returned by the given get_len_func function.
This function is useful for protocols that run over TCP and that are
either a fixed length always, or have a minimum size and have a length
field encoded within that minimum portion that identifies their full
length. For such protocols, their protocol dissector function can invoke
this dissect_tcp_pdus() function to make it easier to handle dissecting
their protocol’s messages (i.e., their protocol data unit (PDU)). This
function shouild not be used for protocols whose PDU length cannot be
determined from a fixed minimum portion, such as HTTP or Telnet.
TreeItem object passed to the dissect_func.
Tvb object
of the whole Tvb (possibly reassembled), (2) the Pinfo object,
and (3) an offset number of the index of the first byte
of the PDU (i.e., its first header byte). The Lua function
must return a Lua number of the full length of the PDU.
Tvb object of the PDU’s
Tvb (possibly reassembled), (2) the Pinfo object,
and (3) the TreeItem object. The Lua function must
return a Lua number of the number of bytes read/handled,
which would typically be the Tvb:len().