.. _Alert Definitions:

Alert Definitions

A plugin may need to generate alerts when it detects a certain condition. All the alerts a plugin is willing to generate require a file in plugin sub-directory :code:./alert_definitions/. The file contains all the necessary information which is required to properly show and format an alert.

The file can contain one or more functions to properly format the alert and it must return a lua table with the following keys:

• :code:i18n_title: Is a string indicating the title of the alert. The string is first looked up among the localized strings under the plugin directory :code:./locales, then among the localized strings under the ntopng :code:scripts/locales directory and, finally, if no localization is found, the string is taken verbatim. When a string is searched among the localized strings, it is considered as a key of the localization lua table. Points :code:. present in the string are used to search among localization sub-tables. For example, string :code:alerts_dashboard.blacklisted_flow is localized when the localization table contains a table :code:alerts_dashboard which, in turn, contains a key :code:blacklisted_flow.
• :code:i18n_description (optional): Is either a string with the alert description or a function returning the alert description. a string. When it is a string, the same logic described for the :code:i18n_title is applied. When it is a function, it gets called by the plugin with certain parameters and it returns the alert description. Parameters can be used to augment the alert description with information on the current alert that is being triggered. For example, a parameter can be the interface id, and another parameter can be the IP address of an host. Localization :code:i18n is available as well so that the function can produce a localized description.
• :code:icon (optional): A Font Awesome 5 icon shown next to the :code:i18n_title.

Examples

Let's have a look at a couple of examples. Let's start with plugin :ref:Blacklisted Flows created in the :ref:Plugin Examples. It's :code:./alert_definitions sub-directory <https://github.com/ntop/ntopng/tree/dev/scripts/plugins/blacklisted/alert_definitions>_ contains file :code:alert_flow_blacklisted.lua. Contents of this file are

.. code:: lua

return { i18n_title = "alerts_dashboard.blacklisted_flow", icon = "fas fa-exclamation", }

This file is very simple as it just :code:return s a table with two keys. :code:i18n_title is localized as :code:scripts/locales/en.lua and other localization files contain a table :code:alerts_dashboard with a key :code:blacklisted_flow. Then, :code:icon is used to select the warning sign <https://fontawesome.com/icons/exclamation-triangle>_ which will be printed next to the title. :code:i18n_description has been omitted as the :ref:Flow Definitions format function is re-used.

Let's now move to the other example plugin :ref:Flow Flooders. It's :code:./alert_definitions sub-directory <https://github.com/ntop/ntopng/tree/dev/scripts/plugins/flow_flood/alert_definitions>_ contains file :code:alert_flows_flood.lua. Contents of this file are

.. code:: lua

 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 {
   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, :code:i18n_description is a function. This function will be called automatically with three parameters, namely the interface id of the interface which is triggering the alert, an alert table, and information on the exceeded threshold. This function uses :code:alert_consts.formatAlertEntity to properly format the alert (remember that either an host or a network can be a flooder) and then returns an :code:i18n localized string.