Scripting nProbe Using Lua

nProbe Professional allows the user to script custom actions and behaviors right before a flow is exported out. Scripted actions and behaviors are executed on a per-protocol basis and require the corresponding plugin. For example, scripting actions and behaviors for HTTP flows requires the HTTP plugin installed and available. Similarly, scripting actions and behaviors for DNS flows requires the DNS plugin to be enabled and available.

Scripts have to be written in Lua language (https://www.lua.org/about.html). Lua is a lightweight scripting language that is dynamically typed, runs by interpreting byte-code with a register-based virtual machine, and has automatic memory management with incremental garbage collection, making it ideal for configuration, scripting, and rapid prototyping.

Lua scripts are specified using nProbe option –lua. For example, to tell nProbe to execute script dnsSearch.lua located in folder lua/ one can run the following command

./nprobe -i eth1 --lua lua/dnsSearch.lua

But how does nProbe know which function to call? The answer is pretty straightforward: it looks for Lua functions with specific name patterns inside the Lua script received as input.

Lua Functions Naming Convention

nProbe looks for Lua functions that are structured as

check<Protocol>Flow

Every nProbe plugin will inspect the input Lua file and try to find its corresponding function. Plugins must be correctly enabled and set up in order to properly call Lua functions. Plugins that support Lua scripts are outlined in the following table

Protocol	Lua Function Name	Lua Global Table Name
DHCP	checkDHCPFlow	dhcp
DNS	checkDNSFlow	dns
FTP	checkFTPFlow	ftp
GTPV1	checkGTPV1Flow	gtpv1
HTTP	checkHTTPFlow	http
IMAP	checkIMAPFlow	imap
POP	checkPOPFlow	pop
RADIUS	checkRADIUSFlow	radius
SIP	checkSIPFlow	sip
SMTP	checkSMTPFlow	smtp

Every plugin, for every flow – before calling, if available, its corresponding Lua function – pushes into the Lua stack a global table that contains:

• Flow elements that are common to any flow

• Additional elements that are peculiar to flows captured with the plugin

Elements are pushed in the global Lua table as pairs Key - Value.

Common Lua Flow Elements

Every flow has some basic elements that are made available, in a global lua table, my plugin. Common information include source and destination ports, for example. The list of common information fields are outlined in the following table

Common Element Name	Description
nprobe.pid	The process id of the nProbe instance
flow.id	A unique integer identification to uniquely represent the flow
flow.from	The flow source IP address
flow.to	The flow destination IP address
flow.sport	The flow source Layer-3 port
flow.dport	The flow destination Layer-3 port
flow.duration	The duration of the flow in seconds
flow.beginTime	The epoch of the flow start time
flow.endTime	The epoch of the flow end time
flow.l7_proto	A unique integer number to represent the Layer-7 protocol
flow.protocol	A unique, standard, integer number to represent the Layer-4 protocol as approved by IANA

Plugin-Specific Lua Flow Elements

These additional fields vary depending on the plugin that called the Lua function. Every plugin prefixes its additional fields with a name that resembles the plugin.

For example, the DNS plugin adds the following fields

Additional DNS Plugin Element Name	Description
dns.dns_client	The IP address of the client that made the DNS request
dns.as	The Autonomous System of the client that made the DNS request
dns.clientcountry	The country of the client that made the DNS request
dns.clientcity	The city of the client that made the DNS request
dns.query	The DNS query performed
dns.answers	The DNS answers received

Examples

In the remainder of this section are shown examples of nProbe Lua scripting.

Intercepting DNS Flows

Let’s say a custom action has to be performed right before the export of any DNS flow. Let’s also assume, in the interest of pedagogical clarity, that the custom action consists in printing to the console the global flow Lua table dns that has been pushed in by nProbe. To accomplish the action outlined above it suffices to create a Lua script with the following contents

function checkDNSFlow()
   for k, v in pairs(dns) do
      print('k: '..k..' v: '..v..'\n')
   end
end

The script above iterates over the global dns table and prints all the key-value pairs to the console, one per line. The execution occurs one time for every DNS flow detected, right before exporting the flow. Assuming the script is saved to file dnsSearch.lua under the lua/ directory, then nProbe can be started as follow

./nprobe -i en4 --lua lua/dnsSearch.lua  --dns-dump-dir /tmp

Console logs will confirm the DNS plugin is enabled and that the Lua interpreter correctly parsed dnsSearch.lua:

[...]
[LUA] Successfully interpreted lua/dnsSearch.lua
DNS log files will be saved in /tmp
1 plugin(s) enabled
[...]

At this point it is possible fire a query to a DNS server

$ dig google.it @8.8.8.8

nProbe, right after dig termination, will output to the console the following information

[...]
k: flow.duration v: 1
k: dns.dns_client v: 192.168.2.130
k: flow.sport v: 54209
k: flow.protocol v: 17
k: dns.query v: google.it
k: flow.endTime v: 1466425499
k: flow.beginTime v: 1466425499
k: flow.dport v: 53
k: dns.answers v:
k: dns.as v: 0
k: flow.to v: 8.8.8.8
k: nprobe.pid v: 3278
k: flow.id v: 42
k: flow.from v: 192.168.2.130
[...]