Flow Scripts¶

Flow scripts are executed on each network flow. The user can inspect the flow protocol, peers involved in the communication, and other specific information.

Hooks¶

A user script can hook the following functions:

protocolDetected: called after the Layer-7 application protocol has been detected

statusChanged: called when the internal status of the flow has changed since the previous invocation. The flow status can be used to detect anomalous behaviours.

periodicUpdate: called every few minutes on long-lived flows

flowEnd: called when the flow is considered finished

all can be used to register to all the functions.

Example: Country based Alert¶

Let’s see how to create a custom script which checks flow client and server countries, and perform certain actions when either the client or the server is found to be from a country (China in this example). As this script should be executed as early as possible in the lifecycle of a flow, the protocolDetected hook is used to do the check on the countries and to perform the actions.

The script can be written to file suspicious_countries.lua. Although any file name is valid, it is recommended to pick a name which is somehow indicative of the actual script actions. To make sure ntopng will execute it, suspicious_countries.lua must be placed under directory /usr/share/ntopng/scripts/callbacks/interface/flow.

local user_scripts = require("user_scripts")

-- #################################################################

local script = {
   hooks = {},

   gui = {
      i18n_title = "Suspicious Countries",
      i18n_description = "Trigger an alert when at least one among the client and server is from a suspicious country",
   }
}

-- #################################################################

function script.hooks.protocolDetected()
   local cli_geo = flow.getClientGeolocation()
   local srv_geo = flow.getServerGeolocation()

   if cli_geo["cli.country"] == "CN" or srv_geo["srv.country"] == "CN" then
      tprint("From China") -- this will print the message "From China" to the standard output
      -- Execute custom actions:
      -- Raise an alert...
      -- Increase the flow score...
   end
end

-- #################################################################

return(script)

The script logic resides into the script.hooks.protocolDetected function. The flow object keeps a context of the currently processed flow. The flow.getClientGeolocation and flow.getServerGeolocation functions extract the peers country information. The country code is then processed to determine if any of the peers is located in China (country code CN).

An easier way to access all the flow information would be to call flow.getFullInfo(), but this should not be used in production as it’s a very expensive call.

See the Flow API for a documentation of the available functions.