3. Flow Status Definitions

A plugin may need to set a status on certain flows. As seen in the Examples, plugin Blacklisted Flows needs to set a blacklisted status on flows it detects as being blacklisted. Other plugins may need to set other statuses (e.g, low throughput, too many retransmissions, connection issues, etc.). A flow can have multiple statuses. An alert can be associated to each status. Statuses can be set once they have been defined in a plugin ./status_definitions/ and they are set calling flow.triggerStatus. Definition is done via a Lua file, one file per status.

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

• i18n_title: A title for the flow status. This title is shown within the web user interface, for example to filter active flows on their status, or when browsing historical flows. For the rules of how to specify this title, refer to i18n_title in Alert Definitions.
• i18n_description: A description for the flow status. This description is shown within the web user interface and follows the same rules as the i18n_description in Alert Definitions.
• alert_type (optional): When an alert needs to be associated to the status, this key must be present. Key has the structure alert_consts.alert_types.<an alert key>, where <an alert key> is the file name of an alert definition without the .lua suffix.
• alert_severity (optional): When an alert needs to be associated to the status, this key indicated 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.

3.1. Example

Let’s look at how a flow status can be defined for the plugin Blacklisted Flows created in the Examples. It’s ./status_definitions sub-directory contains file status_blacklisted.lua. Contents of this file are

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 {
  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 the keys as highlighted above. The i18n_description is a function which receives as input parameter a table with the flow details, and return a localized string built using the flow details received as input.