Flow Status Definitions¶

A plugin enables one or more statuses to be set on certain flows. A flow can have multiple statuses set and statuses can be associated to alerts. Flow statuses must be defined in plugin sub-directory ./status_definitions/ and they are set calling flow.triggerStatus. Definition is done using a Lua files, one file per status.

A flow status definition file must return a Lua table with the following keys:

status_key: A constant uniquely identifying this status.
i18n_title: A string indicating the title of the status. ntopng localizes the string as described in Localization.
i18n_description (optional): Either a string with the flow status description or a function returning a flow status description string. When i18n_description is a string, ntopng localizes as described in Localization.
alert_type (optional): When an alert is associated to the flow status, this key must be present. Key has the structure alert_consts.alert_types.<an alert key>, where <an alert key> is the name of a file created in Alert Definitions, without the .lua suffix.
alert_severity (optional): When an alert is associated to the flow status, this key indicates the severity of the alert. Key has the structure alert_consts.alert_severities.<alert severity>, where <alert severity> is one among the available alert severities.

Flow Status Key¶

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

ntopng
user

Plugins distributed with ntopng must have their status_key s defined in sub-table ntopng. User plugins 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.

Flow Status Description¶

Flow Status description i18n_description can be either a string with the flow status description or a function returning a flow status description string.

String¶

When the flow status description is string, it is localized as described in Localization. A flowstatus_info table is passed as the parameters table for the localization. Keys and values of flowstatus_info can be used to add parameters to the localization string. Refer to Flow User Scripts to see how to create and pass flowstatus_info.

Function¶

When the flow status description is a function, it gets called with one parameter:

flowstatus_info: A Lua table containing the details of the flow status.

Refer to Flow User Scripts for additional details on this parameter.

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

Example¶

Consider Blacklisted Flows plugin created in the Examples. It’s ./status_definitions sub-directory contains file status_blacklisted.lua. Contents of this file are

local status_keys = require "flow_keys"
local alert_consts = require("alert_consts")

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

local function formatBlacklistedFlow(flowstatus_info)
   local who = {}

   if not flowstatus_info then
      return i18n("flow_details.blacklisted_flow")
   end

   if flowstatus_info["blacklisted.cli"] then
      who[#who + 1] = i18n("client")
   end

   if flowstatus_info["blacklisted.srv"] then
      who[#who + 1] = i18n("server")
   end

   -- if either the client or the server is blacklisted
   -- then also the category is blacklisted so there's no need
   -- to check it.
   -- Domain is basically the union of DNS names, SSL CNs and HTTP hosts.
   if #who == 0 and flowstatus_info["blacklisted.cat"] then
      who[#who + 1] = i18n("domain")
   end

   if #who == 0 then
      return i18n("flow_details.blacklisted_flow")
   end

   local res = i18n("flow_details.blacklisted_flow_detailed", {who = table.concat(who, ", ")})

   return res
end

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

return {
  status_key = status_keys.ntopng.status_blacklisted,
  alert_severity = alert_consts.alert_severities.error,
  alert_type = alert_consts.alert_types.alert_flow_blacklisted,
  i18n_title = "flow_details.blacklisted_flow",
  i18n_description = formatBlacklistedFlow
}

This file returns a Lua table with five keys. An alert is associated to status_blacklisted, so both keys alert_severity and alert_type must be specified. Key alert_type indicates the alert which is going to be triggered is alert_flow_blacklisted. ntopng retrieves the alert definition as there is an alert definition file alert_flow_blacklisted.lua.

The i18n_description is assigned to the local function formatBlacklistedFlow. ntopng will call this function to generate the description of the status. The function takes care of producing a formatted, localized output.