Refactors user_scripts into checks (lua)

scripts/plugins/examples/example/checks/host/example.lua

@@ -0,0 +1,196 @@
+--
+-- (C) 2019-21 - ntop.org
+--
+
+local alert_severities = require "alert_severities"
+local alert_consts = require("alert_consts")
+local alerts_api = require("alerts_api")
+
+-- This is a user script executed by scripts/callbacks/interface/host.lua .
+-- Changes to this script must be applied by reloading the plugins from
+-- http://127.0.0.1:3000/lua/plugins_overview.lua
+
+local global_state = nil
+
+-- #################################################################
+
+local script = {
+  -- Script category, see checks.script_categories for all available categories
+  category = checks.script_categories.other,
+
+  -- This module is enabled by default
+  default_enabled = true,
+
+  -- The default configuration for this plugin. The current configuration
+  -- is passed to the script hooks as the second parameter.
+  default_value = {
+    -- This configuration is specific of this script
+    some_setting = "my custom config value",
+    max_bytes = 128,
+  },
+
+  -- A user script must be attached some hooks in order to be executed.
+  -- This is only a placeholder, see below for the hooks definitions.
+  -- NOTE: the "all" hook is a virtual hook which causes the script to
+  -- be attached to all the available hooks.
+  hooks = {},
+
+  -- GUI specific stuff. If this section is missing, the user script
+  -- will not be shown in the gui.
+  gui = {
+    -- A title for this user script
+    i18n_title = "example.host_script_title",
+
+    -- A description for this user script
+    i18n_description = "example.host_script_description",
+  },
+
+  ----------------------------------------------------------------------
+
+  -- If true, the script will be automatically disabled when alerts are
+  -- disabled.
+  is_alert = false,
+
+  -- If true, this script will only be executed on packet interfaces
+  packet_interface_only = false,
+
+  -- If true, this script will only be executed in nEdge
+  nedge_only = false,
+
+  -- If true, this script will not be executed in nEdge
+  nedge_exclude = false,
+
+  -- If true, this script will not be available on Windows.
+  windows_exclude = false,
+
+  ----------------------------------------------------------------------
+
+  -- If true, the script will only be executed on local hosts
+  -- https://www.ntop.org/guides/ntopng/basic_concepts/hosts.html#local-hosts
+  local_only = false,
+}
+
+-- #################################################################
+
+-- @brief Called, for every enabled hook, upon ntopng startup or upon plugins reload at runtime
+-- @param hook The name of the enabled hook (e.g., min, hour)
+-- @param hook_config A Lua table with the hook configuration
+-- @return nil
+function script.onLoad(hook, hook_config)
+   tprint("loading: "..hook)
+   -- tprint(hook_config)
+end
+
+-- #################################################################
+
+-- @brief Called, for every enabled hook, upon ntopng termination
+-- @param hook The name of the enabled hook (e.g., min, hour)
+-- @param hook_config A Lua table with the hook configuration
+-- @return nil
+function script.onUnload(hook, hook_config)
+   tprint("unloading: "..hook)
+   -- tprint(hook_config)
+end
+
+-- #################################################################
+
+-- @brief Called when a user script hook is enabled
+-- @param hook The name of the enabled hook (e.g., min, hour)
+-- @param hook_config A Lua table with the hook configuration for the enabled hook
+-- @return nil
+function script.onEnable(hook, hook_config)
+   tprint("[+] enabling: "..hook)
+   -- tprint(hook_config)
+end
+
+-- #################################################################
+
+-- @brief Called when a user script hook is disabled
+-- @param hook The name of the disabled hook (e.g., min, hour)
+-- @param hook_config A Lua table with the hook configuration for the disabled hook
+-- @return nil
+function script.onDisable(hook, hook_config)
+   tprint("[-] disabling: "..hook)
+   -- tprint(hook_config)
+end
+
+-- #################################################################
+
+-- @brief Called when the configuration for an enabled user script hook has changed
+-- @param hook The name of the hook (e.g., min, hour) for which the configuration has changed
+-- @param hook_config A Lua table with the new (changed) configuration
+-- @return nil
+function script.onUpdateConfig(hook, hook_config)
+   tprint("[~] config change: "..hook)
+   -- tprint(hook_config)
+end
+
+-- #################################################################
+
+-- @brief Called  when the user script is loaded 
+-- @return true if the script should be loaded, false otherwise
+-- @notes Can be used to init some script global state or to skip the script
+-- execution on some particular conditions
+function script.setup()
+  local is_enabled = true -- your custom condition here
+
+  global_state = {}
+
+  return(is_enabled)
+end
+
+-- #################################################################
+
+-- An hook executed every minute on the active hosts.
+function script.hooks.min(info)
+  --tprint(info)
+  print("host:min hook called: " .. info.entity_info.ip)
+
+  -- Full host information can be extracted with interface.getHostInfo
+  --tprint(interface.getHostInfo(info.alert_entity.alert_entity_val))
+
+  local alert_info = {
+     alert_type = alert_consts.alert_types.alert_example,
+     alert_severity = alert_severities.notice,
+     alert_granularity = info.granularity,
+     alert_type_params = {
+	some_value = 1234,
+     },
+  }
+
+  local bytes = host.getBytes()
+  local tot_bytes = bytes["bytes.sent"] + bytes["bytes.rcvd"]
+
+  if(tot_bytes > info.check_config.max_bytes) then
+    -- Trigger alert
+    alerts_api.trigger(info.alert_entity, alert_info)
+  else
+    -- Release previously triggered alert (if any)
+    alerts_api.release(info.alert_entity, alert_info)
+  end
+end
+
+-- #################################################################
+
+-- An hook executed every 5 minutes on the active hosts.
+script.hooks["5mins"] = function(info)
+  print("host:5mins hook called: " .. info.entity_info.ip)
+end
+
+-- #################################################################
+
+-- An hook executed every hour on the active hosts.
+function script.hooks.hour(info)
+  print("host:hour hook called: " .. info.entity_info.ip)
+end
+
+-- #################################################################
+
+-- An hook executed every day on the active hosts.
+function script.hooks.day(info)
+  print("host:day hook called: " .. info.entity_info.ip)
+end
+
+-- #################################################################
+
+return script

scripts/plugins/examples/example/checks/interface/example.lua

@@ -0,0 +1,141 @@
+--
+-- (C) 2019-21 - ntop.org
+--
+
+local alert_severities = require "alert_severities"
+local alert_consts = require("alert_consts")
+local alerts_api = require("alerts_api")
+
+-- This is a user script executed by scripts/callbacks/interface/interface.lua .
+-- Changes to this script must be applied by reloading the plugins from
+-- http://127.0.0.1:3000/lua/plugins_overview.lua
+
+local global_state = nil
+
+-- #################################################################
+
+local script = {
+  -- Script category, see checks.script_categories for all available categories
+  category = checks.script_categories.other,
+
+  -- This module is enabled by default
+  default_enabled = true,
+
+  -- The default configuration for this plugin. The current configuration
+  -- is passed to the script hooks as the second parameter.
+  default_value = {
+    -- This configuration is specific of this script
+    some_setting = "my custom config value",
+    max_sent_http_bytes = 128,
+  },
+
+  -- A user script must be attached some hooks in order to be executed.
+  -- This is only a placeholder, see below for the hooks definitions.
+  -- NOTE: the "all" hook is a virtual hook which causes the script to
+  -- be attached to all the available hooks.
+  hooks = {},
+
+  -- GUI specific stuff. If this section is missing, the user script
+  -- will not be shown in the gui.
+  gui = {
+    -- A title for this user script
+    i18n_title = "example.interface_script_title",
+
+    -- A description for this user script
+    i18n_description = "example.interface_script_description",
+  },
+
+  ----------------------------------------------------------------------
+
+  -- If true, the script will be automatically disabled when alerts are
+  -- disabled.
+  is_alert = false,
+
+  -- If true, this script will only be executed on packet interfaces
+  packet_interface_only = false,
+
+  -- If true, this script will only be executed in nEdge
+  nedge_only = false,
+
+  -- If true, this script will not be executed in nEdge
+  nedge_exclude = false,
+
+  -- If true, this script will not be available on Windows.
+  windows_exclude = false,
+}
+
+-- #################################################################
+
+-- @brief Called when the script is going to be loaded.
+-- @return true if the script should be loaded, false otherwise
+-- @notes Can be used to init some script global state or to skip the script
+-- execution on some particular conditions
+function script.setup()
+  local is_enabled = true -- your custom condition here
+
+  global_state = {}
+
+  return(is_enabled)
+end
+
+-- #################################################################
+
+-- An hook executed every minute on the network interfaces.
+function script.hooks.min(info)
+  --tprint(info)
+  print("interface:min hook called: " .. info.entity_info.name)
+
+  local exceeded = false
+  local bytes_delta = nil
+
+  if(info.entity_info["ndpi"] and info.entity_info["ndpi"]["HTTP"] and info.entity_info["ndpi"]["HTTP"]["bytes.sent"]) then
+    -- Calculate the delta bytes wrt the previous hook run
+    bytes_delta = alerts_api.interface_delta_val(script.key, info.granularity, info.entity_info["ndpi"]["HTTP"]["bytes.sent"])
+
+    if(bytes_delta > info.check_config.max_sent_http_bytes) then
+      exceeded = true
+    end
+  end
+
+  local alert_info = {
+    alert_type = alert_consts.alert_types.alert_example,
+    alert_severity = alert_severities.notice,
+    alert_granularity = info.granularity,
+    alert_type_params = {
+      http_sent_bytes = bytes_delta,
+    },
+  }
+
+  if(exceeded) then
+    -- Trigger alert
+    alerts_api.trigger(info.alert_entity, alert_info)
+  else
+    -- Release previously triggered alert (if any)
+    alerts_api.release(info.alert_entity, alert_info)
+  end
+end
+
+-- #################################################################
+
+-- An hook executed every 5 minutes on the network interfaces.
+script.hooks["5mins"] = function(info)
+  print("interface:5mins hook called: " .. info.entity_info.name)
+end
+
+-- #################################################################
+
+-- An hook executed every hour on the network interfaces.
+function script.hooks.hour(info)
+  print("interface:hour hook called: " .. info.entity_info.name)
+end
+
+-- #################################################################
+
+-- An hook executed every day on the network interfaces.
+function script.hooks.day(info)
+  print("interface:day hook called: " .. info.entity_info.name)
+end
+
+-- #################################################################
+
+return script

scripts/plugins/examples/example/checks/network/example.lua

@@ -0,0 +1,131 @@
+--
+-- (C) 2019-21 - ntop.org
+--
+
+local alert_severities = require "alert_severities"
+local alert_consts = require("alert_consts")
+local alerts_api = require("alerts_api")
+
+-- This is a user script executed by scripts/callbacks/interface/network.lua .
+-- Changes to this script must be applied by reloading the plugins from
+-- http://127.0.0.1:3000/lua/plugins_overview.lua
+
+local global_state = nil
+
+-- #################################################################
+
+local script = { 
+  -- Script category, see checks.script_categories for all available categories
+  category = checks.script_categories.other,
+
+  -- This module is enabled by default
+  default_enabled = true,
+
+  -- The default configuration for this plugin. The current configuration
+  -- is passed to the script hooks as the second parameter.
+  default_value = {
+    -- This configuration is specific of this script
+    some_setting = "my custom config value",
+    max_inner_bytes = 128,
+  },
+
+  -- A user script must be attached some hooks in order to be executed.
+  -- This is only a placeholder, see below for the hooks definitions.
+  -- NOTE: the "all" hook is a virtual hook which causes the script to
+  -- be attached to all the available hooks.
+  hooks = {},
+
+  -- GUI specific stuff. If this section is missing, the user script
+  -- will not be shown in the gui.
+  gui = {
+    -- A title for this user script
+    i18n_title = "example.interface_script_title",
+
+    -- A description for this user script
+    i18n_description = "example.interface_script_description",
+  },
+
+  ----------------------------------------------------------------------
+
+  -- If true, the script will be automatically disabled when alerts are
+  -- disabled.
+  is_alert = false,
+
+  -- If true, this script will only be executed on packet interfaces
+  packet_interface_only = false,
+
+  -- If true, this script will only be executed in nEdge
+  nedge_only = false,
+
+  -- If true, this script will not be executed in nEdge
+  nedge_exclude = false,
+
+  -- If true, this script will not be available on Windows.
+  windows_exclude = false,
+}
+
+-- #################################################################
+
+-- @brief Called when the script is going to be loaded.
+-- @return true if the script should be loaded, false otherwise
+-- @notes Can be used to init some script global state or to skip the script
+-- execution on some particular conditions
+function script.setup()
+  local is_enabled = true -- your custom condition here
+
+  global_state = {}
+
+  return(is_enabled)
+end
+
+-- #################################################################
+
+-- An hook executed every minute on the local networks.
+function script.hooks.min(info)
+  --tprint(info)
+  print("network:min hook called: " .. info.entity_info.network_key)
+
+  local inner_bytes = info.entity_info.inner
+
+  local alert_info = {
+    alert_type = alert_consts.alert_types.alert_example,
+    alert_severity = alert_severities.notice,
+    alert_granularity = info.granularity,
+    alert_type_params = {
+      inner_bytes = inner_bytes,
+    },
+  }
+
+  if(inner_bytes > info.check_config.max_inner_bytes) then
+    -- Trigger alert
+    alerts_api.trigger(info.alert_entity, alert_info)
+  else
+    -- Release previously triggered alert (if any)
+    alerts_api.release(info.alert_entity, alert_info)
+  end
+end
+
+-- #################################################################
+
+-- An hook executed every 5 minutes on the local networks.
+script.hooks["5mins"] = function(info)
+  print("network:5mins hook called: " .. info.entity_info.network_key)
+end
+
+-- #################################################################
+
+-- An hook executed every hour on the local networks.
+function script.hooks.hour(info)
+  print("network:hour hook called: " .. info.entity_info.network_key)
+end
+
+-- #################################################################
+
+-- An hook executed every day on the local networks.
+function script.hooks.day(info)
+  print("network:day hook called: " .. info.entity_info.network_key)
+end
+
+-- #################################################################
+
+return script

scripts/plugins/examples/example/checks/snmp_device/example.lua

@@ -0,0 +1,143 @@
+--
+-- (C) 2019-21 - ntop.org
+--
+
+local alert_severities = require "alert_severities"
+local alert_consts = require("alert_consts")
+local alerts_api = require("alerts_api")
+local snmp_utils = require "snmp_utils"
+
+-- This is a user script executed by scripts/callbacks/system/snmp_device.lua .
+-- The SNMP devices must be already configured from the System -> SNMP page.
+-- Changes to this script must be applied by reloading the plugins from
+-- http://127.0.0.1:3000/lua/plugins_overview.lua
+
+local global_state = nil
+
+-- #################################################################
+
+local script = {
+  -- Script category, see checks.script_categories for all available categories
+  category = checks.script_categories.other,
+
+  -- This module is enabled by default
+  default_enabled = true,
+
+  -- The default configuration for this plugin. The current configuration
+  -- is passed to the script hooks as the second parameter.
+  default_value = {
+    -- This configuration is specific of this script
+    some_setting = "my custom config value",
+  },
+
+  -- A user script must be attached some hooks in order to be executed.
+  -- This is only a placeholder, see below for the hooks definitions.
+  -- NOTE: the "all" hook is a virtual hook which causes the script to
+  -- be attached to all the available hooks.
+  hooks = {},
+
+  -- GUI specific stuff. If this section is missing, the user script
+  -- will not be shown in the gui.
+  gui = {
+    -- A title for this user script
+    i18n_title = "example.snmp_script_title",
+
+    -- A description for this user script
+    i18n_description = "example.snmp_script_description",
+  },
+
+  ----------------------------------------------------------------------
+
+  -- If true, the script will be automatically disabled when alerts are
+  -- disabled.
+  is_alert = false,
+
+  -- If true, this script will only be executed on packet interfaces
+  packet_interface_only = false,
+
+  -- If true, this script will only be executed in nEdge
+  nedge_only = false,
+
+  -- If true, this script will not be executed in nEdge
+  nedge_exclude = false,
+
+  -- If true, this script will not be available on Windows.
+  windows_exclude = false,
+
+  ----------------------------------------------------------------------
+
+  -- Skip virtual interfaces (e.g. loopback) in the "snmpDeviceInterface" hook
+  skip_virtual_interfaces = true,
+}
+
+-- #################################################################
+
+-- @brief Called when the script is going to be loaded.
+-- @return true if the script should be loaded, false otherwise
+-- @notes Can be used to init some script global state or to skip the script
+-- execution on some particular conditions
+function script.setup()
+  local is_enabled = true -- your custom condition here
+
+  global_state = {}
+
+  return(is_enabled)
+end
+
+-- #################################################################
+
+-- An hook executed at every poll of the SNMP device.
+-- @param device_ip the SNMP device IP address
+-- @param info information about the device and its interfaces.
+function script.hooks.snmpDevice(device_ip, info)
+  local device_name = snmp_utils.get_snmp_device_sysname(device_ip)
+
+  print("SNMP:snmpDevice hook called: " .. device_ip)
+
+  local alert_info = {
+     alert_type = alert_consts.alert_types.alert_example,
+     alert_severity = alert_severities.notice,
+     alert_granularity = info.granularity,
+     alert_type_params = {
+	device = device_ip,
+	device_name = device_name,
+     },
+  }
+
+  if isSNMPDeviceUnresponsive(device_ip) then
+    -- Trigger alert
+    alerts_api.trigger(info.alert_entity, alert_info)
+  else
+    -- Release previously triggered alert
+    alerts_api.release(info.alert_entity, alert_info)
+  end
+end
+
+-- #################################################################
+
+-- An hook executed at every poll of the SNMP device, for each interface.
+-- @param device_ip the SNMP device IP address
+-- @param device_name the SNMP device name
+-- @param if_index numeric index of the interface
+-- @param info information about the interface
+-- @notes Check out skip_virtual_interfaces
+function script.hooks.snmpDeviceInterface(device_ip, if_index, info)
+  local device_name = snmp_utils.get_snmp_device_sysname(device_ip)
+
+  print("SNMP:snmpDeviceInterface hook called: " .. device_ip .. "@" .. if_index)
+
+  alerts_api.store(info.alert_entity, {
+     alert_type = alert_consts.alert_types.alert_example,
+     alert_severity = alert_severities.warning,
+     alert_type_params = {
+	device = device_ip,
+	device_name = device_name,
+	interface = if_index,
+	interface_name = info["name"],
+     },
+  })
+end
+
+-- #################################################################
+
+return script

scripts/plugins/examples/example/checks/system/example.lua

@@ -0,0 +1,144 @@
+--
+-- (C) 2019-21 - ntop.org
+--
+
+local alert_severities = require "alert_severities"
+local alert_consts = require("alert_consts")
+local alerts_api = require("alerts_api")
+
+-- This is a user script executed by scripts/callbacks/system/system.lua .
+-- Changes to this script must be applied by reloading the plugins from
+-- http://127.0.0.1:3000/lua/plugins_overview.lua
+
+local global_state = nil
+
+-- #################################################################
+
+local script = {
+  -- Script category, see checks.script_categories for all available categories
+  category = checks.script_categories.other,
+
+  -- This module is enabled by default
+  default_enabled = true,
+
+  -- The default configuration for this plugin. The current configuration
+  -- is passed to the script hooks as the second parameter.
+  default_value = {
+    -- This configuration is specific of this script
+    ip_address = "8.8.8.8",
+    v6 = false,
+  },
+
+  -- A user script must be attached some hooks in order to be executed.
+  -- This is only a placeholder, see below for the hooks definitions.
+  -- NOTE: the "all" hook is a virtual hook which causes the script to
+  -- be attached to all the available hooks.
+  hooks = {},
+
+  -- GUI specific stuff. If this section is missing, the user script
+  -- will not be shown in the gui.
+  gui = {
+    -- A title for this user script
+    i18n_title = "example.interface_script_title",
+
+    -- A description for this user script
+    i18n_description = "example.interface_script_description",
+  },
+
+  ----------------------------------------------------------------------
+
+  -- If true, the script will be automatically disabled when alerts are
+  -- disabled.
+  is_alert = false,
+
+  -- If true, this script will only be executed on packet interfaces
+  packet_interface_only = false,
+
+  -- If true, this script will only be executed in nEdge
+  nedge_only = false,
+
+  -- If true, this script will not be executed in nEdge
+  nedge_exclude = false,
+
+  -- If true, this script will not be available on Windows.
+  windows_exclude = false,
+}
+
+-- #################################################################
+
+-- @brief Called when the script is going to be loaded.
+-- @return true if the script should be loaded, false otherwise
+-- @notes Can be used to init some script global state or to skip the script
+-- execution on some particular conditions
+function script.setup()
+  local is_enabled = true -- your custom condition here
+
+  global_state = {}
+
+  return(is_enabled)
+end
+
+-- #################################################################
+
+-- An hook executed every minute.
+function script.hooks.min(info)
+  --tprint(info)
+  print("system:min hook called")
+
+  ntop.pingHost(info.check_config.ip_address, info.check_config.v6)
+
+  -- Wait results
+  ntop.msleep(2000)
+
+  local res = ntop.collectPingResults()
+
+  -- The alert entity must be built manually for system scripts
+  local alert_entity = {
+    alert_entity = alert_consts.alert_entities.am_host,
+    alert_entity_val = info.check_config.ip_address,
+  }
+
+  local alert_info = {
+    alert_type = alert_consts.alert_types.alert_example,
+    alert_severity = alert_severities.notice,
+    alert_granularity = info.granularity,
+    alert_type_params = {},
+  }
+
+  if(res[info.check_config.ip_address] ~= nil) then
+    print(string.format("Host %s is active", info.check_config.ip_address))
+
+    -- Release previously triggered alert (if any)
+    alerts_api.release(alert_entity, alert_info)
+  else
+    print(string.format("Host %s is down", info.check_config.ip_address))
+
+    -- Trigger alert
+    alerts_api.trigger(alert_entity, alert_info)
+  end
+end
+
+-- #################################################################
+
+-- An hook executed every 5 minutes.
+script.hooks["5mins"] = function(info)
+  print("system:5mins hook called")
+end
+
+-- #################################################################
+
+-- An hook executed every hour.
+function script.hooks.hour(info)
+  print("system:hour hook called")
+end
+
+-- #################################################################
+
+-- An hook executed every day.
+function script.hooks.day(info)
+  print("system:day hook called")
+end
+
+-- #################################################################
+
+return script