First rest documentation update

attic/scripts/lua/rest/v2/get/datasource/datasource.lua

@@ -0,0 +1,155 @@
+--
+-- (C) 2013-23 - ntop.org
+--
+
+local dirs = ntop.getDirs()
+package.path = dirs.installdir .. "/scripts/lua/modules/?.lua;" .. package.path
+package.path = dirs.installdir .. "/scripts/lua/modules/datasources/?.lua;" .. package.path
+
+local json = require "dkjson"
+local rest_utils = require "rest_utils"
+local template = require "resty.template"
+-- Import the classes library.
+local classes = require "classes"
+
+-- ##############################################
+
+local datasource = classes.class()
+
+-- ##############################################
+
+-- This is the base REST prefix for all the available datasources
+datasource.BASE_REST_PREFIX = "/lua/rest/v2/get/datasource/"
+
+-- ##############################################
+
+-- @brief Base class constructor
+function datasource:init()
+   self._dataset_params     = {}  -- Holds per-dataset params
+   self._datamodel_instance = nil -- Instance of the datamodel holding data for each dataset
+end
+
+-- ##############################################
+
+-- @brief Parses params
+-- @param params_table A table with submitted params
+-- @return True if parameters parsing is successful, false otherwise
+function datasource:read_params(params_table)
+   if not params_table then
+      self.parsed_params = nil
+      return false
+   end
+
+   self.parsed_params = {}
+   for _, param in pairs(self.meta.params or {}) do
+      local parsed_param = params_table[param]
+
+      -- Assumes all params mandatory and not empty
+      -- May override this behavior in subclasses
+      if isEmptyString(parsed_param) then
+	 -- Reset any possibly set param
+	 self.parsed_params = nil
+
+	 return false
+      end
+
+      self.parsed_params[param] = parsed_param
+   end
+
+   -- Ok, parsin has been successful
+   return true
+end
+
+-- ##############################################
+
+-- @brief Parses params submitted along with the REST endpoint request. If parsing fails, a REST error is sent.
+-- @param params_table A table with submitted params, either _POST or _GET
+-- @return True if parameters parsing is successful, false otherwise
+function datasource:_rest_read_params(params_table)
+   if not self:read_params(params_table) then
+      rest_utils.answer(rest_utils.consts.err.widgets_missing_datasource_params)
+      return false
+   end
+
+   return true
+end
+
+-- ##############################################
+
+-- @brief Send datasource data via REST
+function datasource:rest_send_response()
+   -- Make sure this is a direct REST request and not just a require() that needs this class
+   if not _SERVER -- Not executing a Lua script initiated from the web server (i.e., backend execution)
+   or not _SERVER["URI"] -- Cannot reliably determine if this is a REST request
+   or not _SERVER["URI"]:starts(datasource.BASE_REST_PREFIX) -- Web Lua script execution but not for this REST endpoint
+   then
+      -- Don't send any REST response
+      return
+   end
+
+   if not self:_rest_read_params(_POST) then
+      -- Params parsing has failed, error response already sent by the caller
+      return
+   end
+
+   self:fetch()
+
+   rest_utils.answer(
+      rest_utils.consts.success.ok,
+      self.datamodel_instance:get_data()
+   )
+end
+
+-- ##############################################
+
+-- @brief Deserializes REST endpoint response into an internal datamodel
+-- @param rest_response_data Response data as obtained from the REST call
+function datasource:deserialize(rest_response_data)
+   if rest_response_data and rest_response_data.RESPONSE_CODE == 200 then
+      local data = json.decode(rest_response_data.CONTENT)
+      local when = os.time()
+
+      if data and data.rc == rest_utils.consts.success.ok.rc then
+	 self.datamodel_instance = self.meta.datamodel:new(data.rsp.header)
+
+	 for _, row in ipairs(data.rsp.rows) do
+	    self.datamodel_instance:appendRow(when, data.rsp.header, row)
+	 end
+      end
+   end
+end
+
+-- ##############################################
+
+-- @brief Returns instance metadata, which depends on the current instance and parsed_params
+function datasource:get_metadata()
+   local res = {}
+
+   -- Render a url with submitted parsed_params
+   if self.meta.url then
+      local url_func = template.compile(self.meta.url, nil, true)
+      local url_rendered = url_func({
+	    params = self.parsed_params,
+      })
+
+      res["url"] = url_rendered
+   end
+
+   return res
+end
+
+-- ##############################################
+
+-- @brief Transform data according to the specified transformation
+-- @param data The data to be transformed
+-- @param transformation The transformation to be applied
+-- @return transformed data
+function datasource:transform(transformation)
+   return self.datamodel_instance:transform(transformation)
+end
+
+-- ##############################################
+
+return datasource
+
+-- ##############################################

attic/scripts/lua/rest/v2/get/datasource/interface/packet_distro.lua

@@ -0,0 +1,81 @@
+--
+-- (C) 2019-22 - ntop.org
+--
+
+local dirs = ntop.getDirs()
+package.path = dirs.installdir .. "/scripts/lua/modules/?.lua;" .. package.path
+package.path = dirs.installdir .. "/scripts/lua/modules/datamodel/?.lua;" .. package.path
+
+-- ##############################################
+
+-- Import the classes library.
+local classes = require "classes"
+-- This is the datamodel used to represent data associated with this datasource
+local slices = require "slices"
+-- Rest utilities
+local rest_utils = require "rest_utils"
+
+-- ##############################################
+
+local packet_distro = classes.class(slices)
+
+-- ##############################################
+
+packet_distro.meta = {
+   params = {
+      -- NOTE: Specify all the parameter keys that must be passed in the request
+       "ifid" -- validated according to http_lint.lua
+   },
+}
+
+-- ##############################################
+
+-- Human-friendly labels for the distribution
+local available_bins = {
+   { key = 'upTo64',    label = '<= 64'        },
+   { key = 'upTo128',   label = '64 <= 128'    },
+   { key = 'upTo256',   label = '128 <= 256'   },
+   { key = 'upTo512',   label = '256 <= 512'   },
+   { key = 'upTo1024',  label = '512 <= 1024'  },
+   { key = 'upTo1518',  label = '1024 <= 1518' },
+   { key = 'upTo2500',  label = '1518 <= 2500' },
+   { key = 'upTo6500',  label = '2500 <= 6500' },
+   { key = 'upTo9000',  label = '6500 <= 9000' },
+   { key = 'above9000', label = '> 9000'       },
+}
+
+-- ##############################################
+
+-- @brief Datasource constructor
+function packet_distro:init()
+   -- Initializes parent class slices
+   self.super:init(10 --[[ Maximum number of slices ]],
+		   3 --[[ Percentage under which the slice is ignored and added to other --]])
+end
+
+-- #######################################################
+
+function packet_distro:fetch()
+   -- Assumes all parameters listed in self.meta.params have been parsed successfully
+   -- and are available in self.parsed_params
+
+   interface.select(tostring(self.parsed_params.ifid))
+   local ifstats = interface.getStats()
+   local size_bins = ifstats["pktSizeDistribution"]["size"]
+
+   self:set_label(getHumanReadableInterfaceName(getInterfaceName(ifstats.id)))
+   for _, bin in ipairs(available_bins) do
+      self:append(bin.label, size_bins[bin.key] or 0)
+   end
+end
+
+-- #######################################################
+
+-- Checks if this module is being loaded as part of a REST request to this endpoint or not.
+-- If the module is being loaded as part of a REST request, then a response is sent, otherwise nothing is done.
+-- Must call this to ensure REST responses are sent when necessary
+packet_distro:new():rest_send_response()
+
+-- #######################################################
+
+return packet_distro

attic/scripts/lua/rest/v2/get/host/fingerprint/ja3.lua

@@ -0,0 +1,76 @@
+ --
+-- (C) 2013-21 - ntop.org
+--
+
+local dirs = ntop.getDirs()
+package.path = dirs.installdir .. "/scripts/lua/modules/?.lua;" .. package.path
+
+require "lua_utils"
+local graph_utils = require "graph_utils"
+require "flow_utils"
+local fingerprint_utils = require "fingerprint_utils"
+local rest_utils = require("rest_utils")
+
+local available_fingerprints = {
+   ja3 = {
+      stats_key = "ja3_fingerprint",
+      href = function(fp) return '<A class="ntopng-external-link" href="https://sslbl.abuse.ch/ja3-fingerprints/'..fp..'" target="_blank">'..fp..'  <i class="fas fa-external-link-alt"></i></A>' end
+   },
+   hassh = {
+      stats_key = "hassh_fingerprint",
+      href = function(fp) return fp end
+   }
+}
+
+-- Parameters used for the rest answer --
+local rc
+local res = {}
+
+local ifid = _GET["ifid"]
+local host_info = url2hostinfo(_GET)
+local fingerprint_type = _GET["fingerprint_type"]
+
+
+-- #####################################################################
+
+local stats
+
+if isEmptyString(fingerprint_type) then
+    rc = rest_utils.consts.err.invalid_args
+    rest_utils.answer(rc)
+    return
+ end
+
+if isEmptyString(ifid) then
+   rc = rest_utils.consts.err.invalid_interface
+   rest_utils.answer(rc)
+   return
+end
+
+if isEmptyString(host_info["host"]) then
+   rc = rest_utils.consts.err.invalid_args
+   rest_utils.answer(rc)
+   return
+end
+
+if(host_info["host"] ~= nil) then
+   stats = interface.getHostInfo(host_info["host"], host_info["vlan"])
+end
+
+stats = stats or {}
+
+if fingerprint_type == "ja3" then
+   stats = stats and stats.ja3_fingerprint
+elseif fingerprint_type == "hassh" then
+   stats = stats and stats.hassh_fingerprint
+end
+tprint(stats)
+for key, value in pairs(stats) do
+   res[#res + 1] = value
+   res[#res]["ja3_fingerprint"] = key
+end
+
+
+rc = rest_utils.consts.success.ok
+rest_utils.answer(rc, res)
+