Alert Scripts

Alert scripts are located into separate directories in order to separate them from the other scripts. Such separation is neeeded because alert scripts are only invoked if the alerts into ntopng are enabled.

Here is for example the host syn_flood_victim.lua script:

local alerts_api = require("alerts_api")
local user_scripts = require("user_scripts")

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

local script = {
  -- Specify an altenative alert type (the default is alerts_api.thresholdCrossType)
  threshold_type_builder = alerts_api.synFloodType,
  default_value = "syn_flood_victim;gt;50",

  hooks = {
    -- Call this every minute
    min = alerts_api.threshold_check_function,
  },
  ...
}

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

-- This function returns the current value for the threshold check
function script.get_threshold_value(granularity, info)
  return alerts_api.host_delta_val(script.key, granularity, info["packets.sent"] + info["packets.rcvd"])
end

Most alert scripts use the alerts_api.threshold_check_function which performs simple threshold checks (e.g. value > 10)

Triggering alerts

An alert user script should trigger alerts when some anomalous behaviour is detected. Users can use the already provided hook callbacks:

• alerts_api.threshold_check_function: can check thresholds and trigger threshold cross alerts
• alerts_api.anomaly_check_function: checks anomaly status, set by the C core

or build their own alert custom logic. In the latter case, the hook callback should call the following functions:

• alerts_api.trigger(entity_info, type_info) whenever the entity state is alerted
• alerts_api.release(entity_info, type_info) whenever the entity state is not alerted

Alerts state is kept internally so multiple trigger/releases of the same alert have no effect. The type_info is specific of the alert_type and should be built using one of the “type_info building functions” available into alerts_api.lua, for example alerts_api.thresholdCrossType.

Built-in Alerts

Alert types are defined into alert_consts.alert_types inside scripts/lua/modules/alert_consts.lua. In order to add new alert types, the alert definition must be inserted into alert_consts.alert_types. The new alert type must have a unique alert_id >= 0, a title and description.

Moreover, a new “type_info building function” should be added to the alerts_api.lua to describe the alert type.