Alert Definitions

A script enables alerts to be generated. All the alerts a script is willing to generate require a file in script subdirectory ./alert_definitions/. The file contains all the necessary information which is required to properly show, localize and format an alert.

The file must return a Lua table with the following keys:

  • alert_key: A constant uniquely identifying this alert.
  • i18n_title: A string indicating the title of the alert. ntopng localizes the string as described in Localization.
  • i18n_description (optional): Either a string with the alert description or a function returning an alert description string. When i18n_description is a string, ntopng localizes as described in Localization.
  • icon: A Font Awesome 5 icon shown next to the i18n_title.

Alert Key

The alert_key is a constant uniquely identifying the alert. Constants are available in file alert_keys.lua. The file contains a table alert_keys with two sub-tables:

  • ntopng
  • user

Scripts distributed with ntopng must have their alert_key s defined in sub-table ntopng. User scripts must have their alert_key s defined in sub-table user.

Sub-tables can be extended adding new alert_key s to either the ntopng or the user table. Each alert_key has an integer number assigned which must be unique.

Note

Alert keys are guaranteed to be constant and never changing, even across ntopng releases.

Warning

Prior to 2020-04-15 there was no concept of alert_key. Backward compatibility with alerts generated before that date is not ensured.

Flow Status Key

The status_key is a constant uniquely identifying the status used only by alerts regarding flows. Constants are available in file flow_keys.lua. The file contains a table flow_keys with two sub-tables:

  • ntopng
  • user

Scripts distributed with ntopng must have their status_key s defined in sub-table ntopng. User scripts must have their status_key s defined in sub-table user.

Sub-tables can be extended adding new status_key s to either the ntopng or the user table. Each status_key has an integer number assigned which must be unique.

Note

Status keys are guaranteed to be constant and never changing, even across ntopng releases.

Warning

Prior to 2020-04-15 there was no concept of status_key. Backward compatibility with statuses generated before that date is not ensured.

Alert Description

Alert description i18n_description can be either a string with the alert description or a function returning an alert description string.

String

When the alert description is string, it is localized as described in Localization. An alert_json table is passed as the parameters table for the localization. Keys and values of alert_json can be used to add parameters to the localization string.

Function

When the alert description is a function, it gets called with three parameters:

  • ifid: An integer number uniquely identifying the interface which is triggering the alert.
  • alert: A Lua table containing the details of the alert.
  • alert_json: A Lua table that can be used to add parameters to the localization string.

The function is expected to return a string which is possibly localized. It is up to the script to call the i18n() localization function to do the actual localization. ntopng will not perform any localization on the returned value of the function.

Examples

The first example considers Blacklisted Flows created in the Examples. It’s ./alert_definitions blacklisted sub-directory contains file alert_flow_blacklisted.lua. Contents of this file are

local alert_keys = require "alert_keys"

return {
  alert_key = alert_keys.ntopng.alert_flow_blacklisted,
  i18n_title = "alerts_dashboard.blacklisted_flow",
  icon = "fas fa-exclamation",
}

This file is very simple as it just return s a table with three keys. alert_key is a constant defined in alert_keys.ntopng, i18n_title is localized in en.lua and other localization files. icon is used to select the warning sign which will be printed next to the title. i18n_description has been omitted as the alert does not need any extra description apart from the title.

Second example considers script Flow Flooders. It’s ./alert_definitions flow_flood sub-directory contains file alert_flows_flood.lua. Contents of this file are

local alert_keys = require "alert_keys"

local function formatFlowsFlood(ifid, alert, threshold_info)
  local alert_consts = require("alert_consts")
  local entity = alert_consts.formatAlertEntity(ifid, alert_consts.alertEntityRaw(alert["alert_entity"]), alert["alert_entity_val"])
  local value = threshold_info.value

  if(value == nil) then value = 0 end

  if(alert.alert_subtype == "flow_flood_attacker") then
    return i18n("alert_messages.flow_flood_attacker", {
      entity = firstToUpper(entity),
      value = string.format("%u", math.ceil(value)),
      threshold = threshold_info.threshold,
    })
  else
    return i18n("alert_messages.flow_flood_victim", {
      entity = firstToUpper(entity),
      value = string.format("%u", math.ceil(value)),
      threshold = threshold_info.threshold,
    })
  end
end

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

return {
  alert_key = alert_keys.ntopng.alert_flows_flood,
  i18n_title = "alerts_dashboard.flows_flood",
  i18n_description = formatFlowsFlood,
  icon = "fas fa-life-ring",
}

The file returns a table with the keys as described above. However, here, i18n_description is a function. This function will be called automatically with the three parameters as described above. This function uses alert_consts.formatAlertEntity to properly format the alert (remember that either an host or a network can be a flooder) and then returns an i18n localized string.

Alert Summary

It is possible to find all the Alerts defined with their general infos into ntopng WEB GUI in the section Developer -> Alert and Flow Status Definitions.

The general infos are:

  • Alert Key: The constant uniquely identifying this alert defined above with alert_key.
  • Alert Key String: The string indicating the title of the alert, defined above with i18n_title.
  • Alert Name: A human readable string indicating the name of the alert.
  • Known Attacker: Checked if an attacker is set up by the alert script.
  • Known Victim: Checked if a victim is set up by the alert script.
  • Flow Status Key: The constant uniquely identifying the status, defined above with status_key.
../_images/alert_overview.png