These functions can be used to access the metadata associated with a flow.
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) |
--- 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) |
--- 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) |
--- 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) |
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) |
--- 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.
--- 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.
--- 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) |
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 |