Checks

Checks are the core of scripts. They actually allow certain actions to be performed periodically, or when a certain event occurs. The logic of a script is contained in its users scripts. A script contains zero to many checks.

Structure

The structure of a check is the following:

local checks = require("checks")

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

local script = {
  hooks = {},

  -- other script attributes ...
}

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

function script.setup()
  -- return false to disable the script
  return true
end

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

return(script)

Every check must return a Lua table with the following keys:

  • hooks: a Lua table with hook names as key and checks as values. Check Hooks are events or points in time. ntopng uses hooks to know when to call a check. A check defining a hook will get the hook callaback called by ntopng. Checks must register to at least one hook. See Check Hooks.
  • gui: a Lua table specifying check name, description and configuration. Data is used by ntopng to show the check configurable from the Checks GUI.
  • packet_interface_only (optional): only execute the script on packet interfaces, excluding ZMQ interfaces.
  • nedge_only (optional): if true, the script is only executed in nEdge.
  • nedge_exclude (optional): if true, the script is not executed in nEdge.
  • default_value (optional): the default value for the script configuration, in the form <script_key>;<operator>;<value> (e.g. syn_flood_victim;gt;50). See Checks GUI.
  • default_enabled (optional): if false, the script is disabled by default.

Furthermore, a script may define the following extra functions, which are only called once per script:

  • setup(): called once per check. If it returns false then the script is considered disabled and its hooks are not be called.
  • teardown(): called after the script operation is complete (e.g. after all the hosts have been iterated and hooks called).

Flow and Host Checks

Flow and Host checks are currently executed in the core engine by means of C++ checks. Flow checks have access to flow information such as L4 and L7 protocols, peers involved in the communication, and other things. Similarly Host checks have access to all the host information available in the engine. Please read the Developing Alerts section for instructions about the implementation of C++ checks.

ntopng supports users scripts (Lua) for the following traffic elements:

  • interface: a network interface of ntopng. Check out the Interface Checks API.
  • network: a local network of ntopng. Check out the Network Checks API.
  • system: the system on top of which is running ntopng
  • SNMP interfaces: interfaces of monitored SNMP devices

Refer to Check Hooks for available hooks.

Syslog Checks

Syslog scripts are used to handle syslog events and ingest data, including flows and alerts, from external sources (e.g. alerts from Intrusion Detection Systems).

Scripts Location

Syslog scripts are located under /usr/share/ntopng/scripts/callbacks/system/syslog and should use the source name (e.g. application name) with the .lua extension as file name. In fact messages demultiplexing is implemented by using the source name for matching the script name. For example, log messages coming from suricata will be delivered to the /usr/share/ntopng/scripts/checks/syslog/suricata.lua script.

Script API

A syslog module shoule implement the below functions:

  • setup (optional) which is called once to initialize the module.
  • teardown (optional) which is called once to terminate the module.
  • hooks.handleEvent which is called for each log message matching the module.

Script Example

Here is a sample script suricata.lua processing log messages from Suricata, exported to syslog in Eve JSON format.

local dirs = ntop.getDirs()
package.path = dirs.installdir .. "/scripts/lua/modules/?.lua;" .. package.path
require "lua_utils"
local json = require ("dkjson")

local syslog_module = {
   hooks = {},
}

-- The function below is called once to initialize the script
function syslog_module.setup()
   return true
end

-- The function below is called for each log message received from Suricata
function syslog_module.hooks.handleEvent(message)
   local alert = json.decode(message)
   tprint(alert)
end

-- The function below is called once to terminate the script
function syslog_module.teardown()
   return true
end

return syslog_module