Add alert definitions for S7Comm

Author: cardigliano

include/flow_alerts/S7CommInvalidTransitionAlert.h

@@ -0,0 +1,59 @@
+/*
+ *
+ * (C) 2013-24 - ntop.org
+ *
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, write to the Free Software Foundation,
+ * Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
+ *
+ */
+
+#ifndef _S7COMM_INVALID_TRANSITION_ALERT_H_
+#define _S7COMM_INVALID_TRANSITION_ALERT_H_
+
+#include "ntop_includes.h"
+
+class S7CommInvalidTransitionAlert : public FlowAlert {
+ private:
+  u_int32_t packet_epoch;
+  u_int16_t type_i;
+  u_int8_t type_id;
+
+  ndpi_serializer *getAlertJSON(ndpi_serializer *serializer);
+
+ public:
+  static FlowAlertType getClassType() {
+    return {NDPI_NO_RISK, flow_alert_s7comm_invalid_transition, alert_category_security};
+  }
+  static u_int8_t getDefaultScore() { return SCORE_LEVEL_NOTICE; };
+
+  inline u_int32_t get_packet_epoch() { return packet_epoch; };
+  inline u_int16_t get_type_i() { return type_i; };
+  inline u_int8_t get_type_id() { return type_id; };
+
+  S7CommInvalidTransitionAlert(FlowCheck *c, Flow *f, struct timeval *_time,
+			       u_int16_t _type_i, u_int8_t _type_id) : FlowAlert(c, f) {
+    type_i = _type_i;
+    type_id = _type_id;
+    packet_epoch = _time->tv_sec;
+    setAlertScore(getDefaultScore());
+  };
+  ~S7CommInvalidTransitionAlert(){};
+
+  bool autoAck() const { return false; };
+
+  FlowAlertType getAlertType() const { return getClassType(); }
+};
+
+#endif /* _S7COMM_INVALID_TRANSITION_ALERT_H_ */

include/flow_alerts/S7CommTooManyErrorsAlert.h

@@ -0,0 +1,50 @@
+/*
+ *
+ * (C) 2013-24 - ntop.org
+ *
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, write to the Free Software Foundation,
+ * Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
+ *
+ */
+
+#ifndef _S7COMM_TOO_MANY_ERRORS_ALERT_H_
+#define _S7COMM_TOO_MANY_ERRORS_ALERT_H_
+
+#include "ntop_includes.h"
+
+class S7CommTooManyErrorsAlert : public FlowAlert {
+ private:
+  u_int32_t num_errors;
+
+  ndpi_serializer* getAlertJSON(ndpi_serializer* serializer);
+
+ public:
+  static FlowAlertType getClassType() {
+    return {NDPI_NO_RISK, flow_alert_s7comm_too_many_errors, alert_category_security};
+  }
+  static u_int8_t getDefaultScore() { return SCORE_LEVEL_ERROR; };
+
+  S7CommTooManyErrorsAlert(FlowCheck* c, Flow* f, u_int32_t _num_errors) : FlowAlert(c, f) {
+    num_errors = _num_errors;
+    setAlertScore(getDefaultScore());
+  };
+  ~S7CommTooManyErrorsAlert(){};
+
+  bool autoAck() const { return false; };
+
+  FlowAlertType getAlertType() const { return getClassType(); }
+};
+
+#endif /* _S7COMM_TOO_MANY_ERRORS_ALERT_H_ */

include/flow_alerts/S7CommUnexpectedFunctionCodeAlert.h

@@ -0,0 +1,52 @@
+/*
+ *
+ * (C) 2013-24 - ntop.org
+ *
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, write to the Free Software Foundation,
+ * Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
+ *
+ */
+
+#ifndef _S7COMM_UNEXPECTED_FUNCTION_CODE_ALERT_H_
+#define _S7COMM_UNEXPECTED_FUNCTION_CODE_ALERT_H_
+
+#include "ntop_includes.h"
+
+class S7CommUnexpectedFunctionCodeAlert : public FlowAlert {
+ private:
+  u_int8_t function_code;
+
+  ndpi_serializer* getAlertJSON(ndpi_serializer* serializer);
+
+ public:
+  static FlowAlertType getClassType() {
+    return {NDPI_NO_RISK, flow_alert_s7comm_unexpected_function_code, alert_category_security};
+  }
+  static u_int8_t getDefaultScore() { return SCORE_LEVEL_ERROR; };
+
+  inline u_int8_t get_function_code() { return function_code; };
+
+  S7CommUnexpectedFunctionCodeAlert(FlowCheck* c, Flow* f, u_int8_t _function_code) : FlowAlert(c, f) {
+    function_code = _function_code;
+    setAlertScore(getDefaultScore());
+  };
+  ~S7CommUnexpectedFunctionCodeAlert(){};
+
+  bool autoAck() const { return false; };
+
+  FlowAlertType getAlertType() const { return getClassType(); }
+};
+
+#endif /* _S7COMM_UNEXPECTED_FUNCTION_CODE_ALERT_H_ */

include/flow_alerts_includes.h

@@ -98,6 +98,9 @@
 #include "flow_alerts/ModbusUnexpectedFunctionCodeAlert.h"
 #include "flow_alerts/ModbusTooManyExceptionsAlert.h"
 #include "flow_alerts/ModbusInvalidTransitionAlert.h"
+#include "flow_alerts/S7CommUnexpectedFunctionCodeAlert.h"
+#include "flow_alerts/S7CommTooManyErrorsAlert.h"
+#include "flow_alerts/S7CommInvalidTransitionAlert.h"
 #include "flow_alerts/DataExfiltrationAlert.h"
 #include "flow_alerts/ElephantFlowAlert.h"
 #include "flow_alerts/LateralMovementAlert.h"

include/flow_checks_includes.h

@@ -100,6 +100,9 @@
 #include "flow_checks/ModbusUnexpectedFunctionCode.h"
 #include "flow_checks/ModbusTooManyExceptions.h"
 #include "flow_checks/ModbusInvalidTransition.h"
+#include "flow_checks/S7CommUnexpectedFunctionCode.h"
+#include "flow_checks/S7CommTooManyErrors.h"
+#include "flow_checks/S7CommInvalidTransition.h"
 #include "flow_checks/TCPConnectionFailed.h"
 #include "flow_checks/FlowRiskTLSCertValidityTooLong.h"
 #include "flow_checks/FlowRiskTLSCertificateExpired.h"

include/ntop_defines.h

@@ -1608,6 +1608,12 @@ extern NtopngLuaContext* getUserdata(struct lua_State *vm);
   "ntopng.checks.modbus_too_many_exceptions"
 #define CHECKS_MODBUS_UNEXPECTED_FUNCTION_CODE \
   "ntopng.checks.modbus_unexpected_function_code_enabled"
+#define CHECKS_S7COMM_INVALID_TRANSITION \
+  "ntopng.checks.s7comm_invalid_transition_enabled"
+#define CHECKS_S7COMM_TOO_MANY_ERRORS \
+  "ntopng.checks.s7comm_too_many_errors_enabled"
+#define CHECKS_S7COMM_UNEXPECTED_FUNCTION_CODE \
+  "ntopng.checks.s7comm_unexpected_function_code_enabled"
 
 #define CUSTOM_FLOW_NDPI_SCRIPT \
   "scripts/callbacks/checks/flows/custom_flow_protocol_detected_script.lua"

include/ntop_typedefs.h

@@ -540,7 +540,10 @@ typedef enum {
   flow_alert_ndpi_obfuscated_traffic = 105,
   flow_alert_nedge_policy_violation = 106,
   flow_alert_ndpi_mismatching_protocol_with_ip = 107,
-  
+  flow_alert_s7comm_unexpected_function_code = 108,
+  flow_alert_s7comm_too_many_errors = 109,
+  flow_alert_s7comm_invalid_transition = 110,
+
   MAX_DEFINED_FLOW_ALERT_TYPE, /* Leave it as last member */
 
   MAX_FLOW_ALERT_TYPE =

scripts/locales/en.lua

@@ -3307,6 +3307,17 @@ local lang = {
     ["modbus_unexpected_function_code_ids_description"] = "Comma separated values of ModbusTCP Function Codes. Example: 1,2,3,4",
     ["modbus_unexpected_function_code_ids_title"] = "Allowed Function Codes",
     ["modbus_unexpected_function_code_title"] = "ModbusTCP Unexpected Function Code",
+    ["s7comm_description"] = "Trigger an alert when an invalid S7Comm transition is detected",
+    ["s7comm_invalid_function_code"] = "S7Comm Invalid Function Code",
+    ["s7comm_invalid_transition"] = "S7Comm Invalid Transition",
+    ["s7comm_title"] = "S7Comm Invalid Transition",
+    ["s7comm_too_many_errors"] = "S7Comm Too Many Errors",
+    ["s7comm_too_many_errors_description"] = "Trigger an alert when a flow reports a number of errors exceeding the specified threshold",
+    ["s7comm_too_many_errors_title"] = "S7Comm Too Many Errors",
+    ["s7comm_unexpected_function_code_description"] = "Trigger an alert when an unexpected S7Comm Function code is detected",
+    ["s7comm_unexpected_function_code_ids_description"] = "Comma separated values of S7Comm Function Codes. Example: 0x04,0x05,0xf0",
+    ["s7comm_unexpected_function_code_ids_title"] = "Allowed Function Codes",
+    ["s7comm_unexpected_function_code_title"] = "S7Comm Unexpected Function Code",
     ["network_behavior_check_list"] = "Networks to analyze",
     ["network_behavior_check_list_example"] = "A list of Networks to analyze, separated by commas",
     ["no_callbacks_available"] = "No callbacks available.",

scripts/lua/modules/alert_definitions/flow/alert_s7comm_invalid_transition.lua

@@ -0,0 +1,80 @@
+--
+-- (C) 2019-24 - ntop.org
+--
+
+-- ##############################################
+
+local flow_alert_keys = require "flow_alert_keys"
+local json = require "dkjson"
+local format_utils = require "format_utils"
+-- Import the classes library.
+local classes = require "classes"
+-- Make sure to import the Superclass!
+local alert = require "alert"
+-- Import Mitre Att&ck utils
+local mitre = require "mitre_utils"
+
+-- ##############################################
+
+local alert_s7comm_invalid_transition = classes.class(alert)
+
+-- ##############################################
+
+alert_s7comm_invalid_transition.meta = {
+   alert_key = flow_alert_keys.flow_alert_s7comm_invalid_transition,
+   i18n_title = "flow_checks.s7comm_invalid_transition",
+   icon = "fas fa-fw fa-industry",
+
+   -- Mitre Att&ck Matrix values
+   mitre_values = {
+      mitre_tactic = mitre.tactic.impact,
+      mitre_technique = mitre.technique.data_manipulation,
+      mitre_id = "T1565"
+   },
+}
+
+-- ##############################################
+
+-- @brief Prepare an alert table used to generate the alert
+-- @param last_error A string with the lastest influxdb error
+-- @return A table with the alert built
+function alert_s7comm_invalid_transition:init()
+   -- Call the parent constructor
+   self.super:init()
+end
+
+-- ##############################################
+
+local function function_code_to_string(function_id)
+  -- S7Comm function codes
+  if(function_id == 0x04) then return("Read Var (" .. function_id .. ")") end
+  if(function_id == 0x05) then return("Write Var (" .. function_id .. ")") end
+  if(function_id == 0xf0) then return("Setup Communication (" .. function_id .. ")") end
+  if(function_id == 0x00) then return("CPU Services (" .. function_id .. ")") end
+  if(function_id == 0x29) then return("PLC Control (" .. function_id .. ")") end
+  if(function_id == 0x28) then return("PLC Stop (" .. function_id .. ")") end
+
+  return(function_id)
+end
+
+-- #######################################################
+
+-- @brief Format an alert into a human-readable string
+-- @param ifid The integer interface id of the generated alert
+-- @param alert The alert description table, including alert data such as the generating entity, timestamp, granularity, type
+-- @param alert_type_params Table `alert_type_params` as built in the `:init` method
+-- @return A human-readable string
+function alert_s7comm_invalid_transition.format(ifid, alert, alert_type_params)
+   local from = function_code_to_string(alert_type_params.from) or alert_type_params.from or i18n('unknown')
+   local to   = function_code_to_string(alert_type_params.to) or alert_type_params.to or i18n('unknown')
+
+   local rsp = from .. " -> ".. to
+
+   -- tprint(alert_type_params)
+
+   return(rsp)
+end
+
+-- #######################################################
+
+return alert_s7comm_invalid_transition

scripts/lua/modules/alert_definitions/flow/alert_s7comm_too_many_errors.lua

@@ -0,0 +1,63 @@
+--
+-- (C) 2019-24 - ntop.org
+--
+
+-- ##############################################
+
+local flow_alert_keys = require "flow_alert_keys"
+local json = require "dkjson"
+local format_utils = require "format_utils"
+-- Import the classes library.
+local classes = require "classes"
+-- Make sure to import the Superclass!
+local alert = require "alert"
+-- Import Mitre Att&ck utils
+local mitre = require "mitre_utils"
+
+-- ##############################################
+
+local alert_s7comm_too_many_errors = classes.class(alert)
+
+-- ##############################################
+
+alert_s7comm_too_many_errors.meta = {
+   alert_key = flow_alert_keys.flow_alert_s7comm_too_many_errors,
+   i18n_title = "flow_checks.s7comm_too_many_errors",
+   icon = "fas fa-fw fa-industry",
+
+   -- Mitre Att&ck Matrix values
+   mitre_values = {
+      mitre_tactic = mitre.tactic.impact,
+      mitre_technique = mitre.technique.data_manipulation,
+      mitre_id = "T1565"
+   },
+}
+
+-- ##############################################
+
+-- @brief Prepare an alert table used to generate the alert
+-- @param last_error A string with the lastest influxdb error
+-- @return A table with the alert built
+function alert_s7comm_too_many_errors:init()
+   -- Call the parent constructor
+   self.super:init()
+end
+
+-- #######################################################
+
+-- @brief Format an alert into a human-readable string
+-- @param ifid The integer interface id of the generated alert
+-- @param alert The alert description table, including alert data such as the generating entity, timestamp, granularity, type
+-- @param alert_type_params Table `alert_type_params` as built in the `:init` method
+-- @return A human-readable string
+function alert_s7comm_too_many_errors.format(ifid, alert, alert_type_params)
+   local rsp = alert_type_params.num_errors .. " Errors"
+
+   -- tprint(alert_type_params)
+
+   return(rsp)
+end
+
+-- #######################################################
+
+return alert_s7comm_too_many_errors