Skip to main content
Skip table of contents

Access Metadata

These functions can be used to access the metadata associated with a flow.

General Functions

General functions allow you to access any metadata field by data type. Many of these functions depend on a protocol name and an attribute name. To find valid protocol and attribute names, see Application Metadata Fields. For a code example, see Get Metadata Fields from DpiMessage (String, Int, Long). Some of these methods return a Lua table object. To work with Lua tables, see Work with Tables.

--- Returns the value of a specified string metadata field.
--- Use the Protocol Name and Attribute Name from the metadata fields.
string GetString(dpiMessage, protocol, attribute)
--- Returns the value of a specified int metadata field.
--- Use the Protocol Name and Attribute Name from the metadata fields.
--- NOTE: this is for uint32
int GetInt(dpiMessage, protocol, attribute)
--- Returns the value of a specified long metadata field.
--- Use the Protocol Name and Attribute Name from the metadata fields.
--- NOTE: this is for uint64
long GetLong(dpiMessage, protocol, attribute)
--- Returns the data associated with the given protocol and attribute as a table
--- NOTE: This is in contrast from GetString, which returns the data as a single string.
table<int, string> GetStrings(dpiMessage, protocol, attribute)
--- Returns all of the metadata field names that are string datatype and associated with the flow or packet.
table<int, string> GetAllStringAttributes(dpiMessage)
--- Returns all the metadata field names that are int datatype and associated with the flow or packet.
table<int, int> GetAllIntAttributes(dpiMessage)
--- Returns all the metadata field names that are long datatype and associated with the flow or packet.
table<int, long> GetAllLongAttributes(dpiMessage)

Classification Metadata

--- Returns the Session ID of the flow as a GUID—for example, a3a5d49c-2d93-4366-8ae9-a5506e800726. Often
--- useful to add in warning or debug statements.
string GetUuid(dpiMessage)
--- Returns true if the application is in the application path. For example, if the application path is
--- "/tcp/ssl/https/skype," looking for "ssl" would return true. This function is useful when you are not
--- explicitly looking for the final classification ("skype" in the example).
bool HasApplication(dpiMessage, application)
--- Returns the latest application associated with the flow. Most efficient way to determine the final
--- application classification. Note that in a packet rule or long-running flow, the final application
--- may change as more data is collected.
string GetLatestApplication(dpiMessage)
--- Returns true if the flow has any protocol classification. Most commonly used in packet rules to determine
--- if enough metadata is available to run an analysis.
bool GetFlowClassified(dpiMessage)

Specific Metadata Functions

--- Returns the Http Content for a session.
--- NOTE: If the session contains no HTTP data, this returns an empty string.
string GetHttpContent(dpiMessage)
--- Returns only the Http Request content for a session.
--- NOTE: If the session contains no HTTP client data, this returns an empty string.
string GetHttpRequestContent(dpiMessage)
--- Returns only the Http Response content for a session.
--- NOTE: If the session contains no HTTP server data, this returns an empty string.
string GetHttpResponseContent(dpiMessage)
--- Returns the Email content for a session.
--- NOTE: If the session contains no email content, this returns an empty string.
string GetSmtpContent(dpiMessage)
--- Returns the FTP payload for a session.
--- NOTE: If the session contains no FTP_DATA data, this returns an empty string.
string GetFtpDataContent(dpiMessage)
--- Returns TLS version for a session.
--- NOTE: If the session contains no TLS version, this returns an empty string.
--- For more information, refer to Application Metadata Fields. For a code example, see Detect TLS Version.
string GetTlsVersion(dpiMessage)

Host Functions

--- Returns the Source IP Address from the flow as an integer
unsigned int GetSrcIP4Int(dpiMessge)
--- Returns the Destination IP Address from the flow as an integer
unsigned int GetDstIP4Int(dpiMessage)
--- Returns the Source IP Address from the flow as a string
string GetSrcIP4String(dpiMessage)
--- Returns the Destination IP Address from the flow as a string
string GetDstIP4String(dpiMessage)
--- Returns true (1) if the source IP address in the message is associated with an IPv6
--- flow, otherwise false (nil) is returned
boolean IsSrcIP6(dpiMessage)
--- Returns true (1) if the destination IP address in the message is associated with an
--- IPv6 flow, otherwise false (nil) is returned
boolean IsDstIP6(dpiMessage)
--- Returns the Source IP6 Address from the flow
string GetSrcIP6String(dpiMessage)
--- Returns the Dest IP6 Address from the flow
string GetDstIP6String(dpiMessage)
--- Returns the Source MAC Address from the flow
string GetSrcMacString(dpiMessage)
--- Returns the Destination MAC Address from the flow
string GetDstMacString(dpiMessage)

IP Match Functions

All IP Match functions require the instantiation of an IpMatch object:

require 'IpMatch'
if (myIpMatch == nil) then
  --- One time only, set up the IpMatch object
  myIpMatch = IpMatch:new()
  --- After instantiation, you may use any of the below functions by calling the method on your class instance. For example:
  myIpMatch:SetIP4Src("192.168.1.1")
end
--- Converts a IP4 string (dotted notation) into an integer
int IpMatch:ConvertIP4ToInt(dottedIp)
--- Set the Source IP4 address to use for matching. The ip4 value is passed as a string in dotted notation.
void IpMatch:SetIP4Src(ip4)
--- Set the Destination IP4 address to use for matching. The ip4 value is passed as a string in dotted notation.
void IpMatch:SetIP4Dst(ip4)
--- Return true if the source IP in dpiMsg matches the ip4 value previously set using SetIP4Src().
boolean IpMatch:MatchIP4Src(dpiMsg)
--- Return true if the destination IP in dpiMsg matches the ip4 value previously set using SetIP4Dst().
boolean IpMatch:MatchIP4Dst(dpiMsg)
--- Return true if the source and destination IP addresses in dpiMsg match the ip4 values previously set
--- with SetIP4Src() and SetIP4Dst().
boolean IpMatch:MatchIP4SrcAndDst(dpiMsg)
--- Return true if the source or destination IP addresses in dpiMsg match the ip4 values previously set
--- with SetIP4Src() and SetIP4Dst().
boolean IpMatch:MatchIP4SrcOrDst(dpiMsg)

Internal LAN Define Functions

--- IPv4LanDefine defines the boundaries of a LAN. The class determines whether or not an IP address is within
--- the boundaries of the defined LAN.
---
--- All IPv4LanDefine functions require the instantiation of an IPv4LanDefine object. See the instantiation
--- example below:
require 'IPv4LanDefine'
--- One time only setup
if (ipRange == nil) then
  ipRange = IPv4LanDefine:new('10.0.0.0', '10.0.0.10')
end
--- After initialization you may use any of the below functions by calling the instantiated instance.
--- Example:
local destip = GetDstIP4Int(dpiMsg)
local srcip = GetSrcIP4Int(dpiMsg)
if (ipRange:IsInLan(destip) or ipRange:IsInLan(srcip)) then
  --- take an appropriate action
end
--- Return true if the given IP address, in int format, is within the defined LAN boundaries
boolean IPv4LanDefine:IsInLan(IPAddress)

For more information, refer to Application Metadata Fields. For a code example, see Classify Custom Networks.

Private LAN Define Functions

--- IPv4PrivateLan contains a set of predefined IPv4LanDefine objects. The class
--- determines whether or not an IP address is outside (offsite) of the predefined LAN boundaries
---
--- Currently the private LAN ranges are defined as:
--- LAN Begin           LAN End
--- -------------------------------------
--- "10.0.0.0",         "10.255.255.255"
--- "192.168.0.0",      "192.168.255.255"
--- "172.16.0.0",       "172.31.255.255"
--- "0.0.0.0",          "0.0.0.0"
--- "255.255.255.255",  "255.255.255.255"
---
--- All IPv4PrivateLan functions require the instantiation of an IPv4PrivateLan object. See the instantiation
--- example below:
require 'IPv4PrivateLan'
if (privateLan == nil) then
  privateLan = IPv4PrivateLan:new()
end
--- Return true if the given IP address, in int format, is outside the predefined boundaries
boolean IPv4PrivateLan::IsOffsiteIp(ip)

For more information, refer to Application Metadata Fields. For a code example, see Detect External Network Traffic.

Time Functions

--- Returns the start time of the flow in EPOCH time
int GetStartTime(dpiMessage)
--- Returns the end time of the flow in EPOCH time
int GetEndTime(dpiMessage)

Work with Tables

In Lua, tables are associative arrays that have elements in the format key,value. The key is an index and the value could be any data type such as string, integer, or another user-defined type. To learn more about Lua tables, refer to http://www.lua.org/pil/2.5.html. If a function that returns a table is being used, use the following syntax:

--- require 'LOG'
--- Creating the variable
local tableVariable = FunctionReturningTable()

--- Using the variable
--- NOTE: The key will be an index (1-based) to the table
for key,value in pairs(tableVariable) do
  EZINFO("Key: ", key)
  EZINFO("Value: ", value)
end
JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.