New Monitor: remote queries via ssh

.gitignore

@@ -45,3 +45,4 @@ docs/_build
 .tox
 pyrightconfig.json
 simplemonitor/html/node_modules
+.venv

docs/monitors/remote_ssh.rst

@@ -0,0 +1,122 @@
+remote_ssh - Monitor Remote Entities With SSH
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``remote_ssh`` is a generic Monitor intended to be used for remote machines that do not have Simplemonitor installed.
+It connects with ``ssh`` to run a remote command, then parses the reply and monitors the result.
+
+.. warning::
+    This Monitor uses bare `ssh` commands, in the context of the user they are run againt. This means that you can break everything and a little bit more if you are not careful.
+
+    You should also consider the security risk of having an SSH private key on the monotoring machine. And while we are at the topic of cybersecurity, you should ensure that the SSH command is not injected (this is not liklely if you do not dynamically generate `monitors.ini`)
+
+The sequence of this Monitor is to send to ``ssh_username@target_host:target_port`` the ``command`` via SSH, retrieve the output and parse it with ``regex`` to extract a value.
+
+This value is then compared with ``target_value`` with ``operator``. A failed comparison raises an alert.
+
+.. info::
+    This Monitor is limited in the edge cases it can manage. If you use a command with a predictible output and a proper regex you are good. If you start to tinker or have a regex that is not solid you may crash your Monitor (which just means you have to correct something)
+
+
+.. confval:: description
+
+    :type: string
+    :required: false
+
+    The description of the Monitor which is sent back upon configuring an instance of this Monitor. Fallsback to a generic description.
+
+.. confval:: target_hostname
+
+    :type: string
+    :required: true
+
+    The remote host to run the command on.
+
+.. confval:: target_port
+
+    :type: int
+    :required: true
+
+    The port SSH runs on (on the remote server). Defaults to 22.
+
+.. confval:: ssh_username
+
+    :type: string
+    :required: true
+
+    Login username.
+
+.. confval:: ssh_private_key_path
+
+    :type: string
+    :required: true
+
+    The absolute path to the OpenSSH *private* key to login on the remote server. The remote server must have a corresponding entry in ``authorized_keys`` for the user that connects.
+
+.. confval:: command
+
+    :type: string
+    :required: true
+
+    The command to run. It will use the context of the logged-in user and it is recommended to use absolute pathnames for commands. It is best to test the command by logging in as ``ssh_username`` and trying the command at the prompt.
+
+.. confval:: regex
+
+    :type: string
+    :required: true
+
+    The regular expression the output of the command above will be matched to.
+
+    * Make sure to have one matching group - this is the value that will be checked
+    * Do not escape the sequences (i.e. use ``\s`` in the configuration when you mean "whitespace")
+    * A fantastic site to check your regex is https://regex101.com (do not block their ads!)
+
+.. confval:: result_type
+
+    :type: string
+    :required: true
+
+    The type of the extracted value. Can be ``str`` (a string) or ``int`` (a number)
+
+.. confval:: target_value
+
+    :type: string
+    :required: true
+
+    The value to compare extracted results with. Must be of the same type as the extracted value.
+
+.. confval:: operator
+
+    :type: string
+    :required: true
+
+    The operator that compares the extracted value with ``target_value``. The possible operators are:
+
+    * ``equals`` - works with numbers and strings
+    * ``not_equals`` - works with number and strings
+    * ``greater_than`` - works with numbers
+    * ``less_than`` - works with numbers
+
+.. confval:: success_message
+
+    :type: string
+    :required: false
+
+    A templated message for monitoring success. It must be a string `compatible with ``.format()`` https://docs.python.org/3/tutorial/inputoutput.html#the-string-format-method`_. You can use one bracket (``{}``) which will be replaced with the extracted value.
+
+An example of a full configuration that checks if the ``/dev/sda`` disk on machine ``srv.example.com`:2255`` has more that 10% of free space available:
+
+.. code-block::
+
+    [srv]
+    type = remote_ssh
+    description=check disk space on srv
+    command = df -k | grep /dev/sda
+    ssh_private_key_path = C:\Users\mark\.ssh\srv.private.openssh
+    ssh_username = root
+    target_hostname = srv.example.com
+    target_port = 2255
+    regex = .*\s(\d+)%
+    operator = greater_than
+    target_value = 10
+    result_type = int
+    success_message=free disk {}%

simplemonitor/Monitors/__init__.py

@@ -38,6 +38,7 @@
     MonitorWindowsDHCPScope,
 )
 from .unifi import MonitorUnifiFailover, MonitorUnifiFailoverWatchdog
+from .remote_ssh import MonitorRemoteSSH
 
 __all__ = [
     "CompoundMonitor",
@@ -61,6 +62,7 @@
     "MonitorRingDoorbell",
     "MonitorSensor",
     "MonitorService",
+    "MonitorRemoteSSH",
     "MonitorSvc",
     "MonitorSwap",
     "MonitorSystemdUnit",

simplemonitor/Monitors/remote_ssh.py

@@ -0,0 +1,135 @@
+"""
+Remote command via ssh to check for stuff without simplemonitor on the remote target
+
+Input: 
+ - command to execute
+ - regex to extract the monitored value
+ - expected value
+ - logic to apply
+"""
+
+from venv import logger
+from .monitor import Monitor, register
+from enum import Enum
+import paramiko
+import re
+from typing import Tuple, cast
+
+
+class Operator(Enum):
+    EQUALS = "equals"
+    NOT_EQUALS = "not_equals"
+    GREATER_THAN = "greater_than"
+    LESS_THAN = "less_than"
+
+
+class OperatorType(Enum):
+    STRING = "str"
+    INTEGER = "int"
+
+
+@register
+class MonitorRemoteSSH(Monitor):
+
+    monitor_type = "remote_ssh"
+
+    def __init__(self, name: str, config_options: dict) -> None:
+        super().__init__(name, config_options)
+        # description
+        self.description = cast(str, self.get_config_option("description", required=False))  # maybe define default here instead of a try: ?
+        self.success_message = cast(str, self.get_config_option("success_message", required=False, default="it worked"))
+        # ssh configuration
+        self.command = cast(str, self.get_config_option("command", required=True))
+        self.ssh_private_key_path = cast(str, self.get_config_option("ssh_private_key_path", required=True))
+        self.ssh_username = cast(str, self.get_config_option("ssh_username", required=True))
+        self.target_hostname = cast(str, self.get_config_option("target_hostname", required=True))
+        self.target_port = cast(int, self.get_config_option("target_port", required=False, default="22"))
+        # operator logic
+        self.operator = cast(
+            str,
+            self.get_config_option(
+                "operator",
+                required=True,
+                allowed_values=[Operator.EQUALS.value, Operator.NOT_EQUALS.value, Operator.LESS_THAN.value, Operator.GREATER_THAN.value],
+            ),
+        )
+        self.regex = re.compile(cast(str, self.get_config_option("regex", required=True)))
+        # values to compare, cast to the expected type
+        self.result_type = cast(
+            str,
+            self.get_config_option("result_type", required=True, allowed_values=[OperatorType.INTEGER.value, OperatorType.STRING.value]),
+        )
+        match self.result_type:
+            case OperatorType.INTEGER.value:
+                self.target_value = cast(int, self.get_config_option("target_value", required=True))
+            case OperatorType.STRING.value:
+                self.target_value = cast(str, self.get_config_option("target_value", required=True))
+
+    def run_test(self) -> bool:
+        # run remote command
+        client = paramiko.SSHClient()
+        client.set_missing_host_key_policy(paramiko.AutoAddPolicy)
+        try:
+            client.connect(
+                self.target_hostname,
+                username=self.ssh_username,
+                key_filename=self.ssh_private_key_path,
+                port=self.target_port,
+            )
+        except TimeoutError:
+            return self.record_fail(f"connection to {self.target_hostname} timed out")
+        except ConnectionRefusedError:
+            return self.record_fail(f"connection to {self.target_hostname} actively refused")
+        except Exception as e:
+            return self.record_fail(f"connection to {self.target_hostname} failed: {e}")
+        else:
+            _, stdout, _ = client.exec_command(self.command)
+
+        # extract and cast the actual value
+        command_result = stdout.read().decode("utf-8")  # let's hope for the best
+        client.close()  # it's only now that we are done with the client
+        actual_value = re.match(self.regex, command_result).groups()[0]
+        match self.result_type:
+            case OperatorType.INTEGER.value:
+                actual_value = cast(int, actual_value)
+            case OperatorType.STRING.value:
+                actual_value = cast(str, actual_value)
+
+        # assess the comparison logic. str and int can be checked for equality, only int can be checked for greater/less than
+        test_succeeded = False  # better be pessimistic
+        match self.operator:
+            case Operator.EQUALS.value:
+                test_succeeded = actual_value == self.target_value
+            case Operator.NOT_EQUALS.value:
+                test_succeeded = actual_value != self.target_value
+            case Operator.GREATER_THAN.value:
+                test_succeeded = actual_value > self.target_value
+            case Operator.LESS_THAN.value:
+                test_succeeded = actual_value < self.target_value
+        if self.result_type == OperatorType.STRING.value and (self.operator in [Operator.GREATER_THAN.value, Operator.LESS_THAN.value]):
+            logger.warning(f"strings compared with '{self.operator}'")
+        if test_succeeded:
+            return self.record_success(self.success_message.format(actual_value))
+        else:
+            return self.record_fail(f"actual value: {actual_value} | operator: {self.operator} | target value: {self.target_value}")
+
+    def get_params(self) -> Tuple:
+        return (
+            self.command,
+            self.description,
+            self.success_message,
+            self.regex,
+            self.target_value,
+            self.operator,
+            self.result_type,
+            self.ssh_private_key_path,
+            self.ssh_username,
+            self.target_hostname,
+            self.target_port,
+        )
+
+    def describe(self) -> str:
+        try:
+            return self.description
+        except AttributeError:
+            return "run a remote command, extract its output and apply logic"

simplemonitor/util/envconfig.py

@@ -2,11 +2,11 @@
 
 import os
 import re
-from configparser import BasicInterpolation, ConfigParser
+from configparser import BasicInterpolation, ConfigParser, RawConfigParser
 from typing import Any, List, Optional
 
 
-class EnvironmentAwareConfigParser(ConfigParser):
+class EnvironmentAwareConfigParser(RawConfigParser):
     """A subclass of ConfigParser which allows %env:VAR% interpolation via the
     get method."""
 
@@ -16,11 +16,11 @@ def __init__(self, *args: Any, **kwargs: Any) -> None:
         """Init with our specific interpolation class (for Python 3)"""
         interpolation = EnvironmentAwareInterpolation()
         kwargs["interpolation"] = interpolation
-        ConfigParser.__init__(self, *args, **kwargs)
+        RawConfigParser.__init__(self, *args, **kwargs)
 
     def read(self, filenames: Any, encoding: Optional[str] = None) -> List[str]:
         """Load a config file and do environment variable interpolation on the section names."""
-        result = ConfigParser.read(self, filenames)
+        result = RawConfigParser.read(self, filenames)
         for section in self.sections():
             original_section = section
             matches = self.r.search(section)