PLG: ICMP v2 #1331

Signed-off-by: jokob-sk <jokob.sk@gmail.com>

Dockerfile

@@ -129,7 +129,7 @@ ENV NETALERTX_USER=netalertx NETALERTX_GROUP=netalertx
 ENV LANG=C.UTF-8
 
 
-RUN apk add --no-cache bash mtr libbsd zip lsblk tzdata curl arp-scan iproute2 iproute2-ss nmap \
+RUN apk add --no-cache bash mtr libbsd zip lsblk tzdata curl arp-scan iproute2 iproute2-ss nmap fping \
     nmap-scripts traceroute nbtscan net-tools net-snmp-tools bind-tools awake ca-certificates \
     sqlite php83 php83-fpm php83-cgi php83-curl php83-sqlite3 php83-session python3 envsubst \
     nginx supercronic shadow && \

Dockerfile.debian

@@ -135,8 +135,8 @@ COPY --chmod=775 --chown=${USER_ID}:${USER_GID} . ${INSTALL_DIR}/
 # hadolint ignore=DL3008,DL3027
 RUN apt-get update && apt-get install -y --no-install-recommends \
     tini snmp ca-certificates curl libwww-perl arp-scan sudo gettext-base \
-    nginx-light php php-cgi php-fpm php-sqlite3 php-curl sqlite3 dnsutils net-tools  \
+    nginx-light php php-cgi php-fpm php-sqlite3 php-curl sqlite3 dnsutils net-tools   \
-    python3 python3-dev iproute2 nmap python3-pip zip git systemctl usbutils traceroute nbtscan openrc \
+    python3 python3-dev iproute2 nmap fping python3-pip zip git systemctl usbutils traceroute nbtscan openrc \
     busybox nginx nginx-core mtr python3-venv && \
     rm -rf /var/lib/apt/lists/*
 

front/plugins/icmp_scan/config.json

@@ -75,6 +75,34 @@
         }
       ]
     },
+    {
+      "function": "MODE",
+      "events": ["run"],
+      "type": {
+        "dataType": "string",
+        "elements": [
+          { "elementType": "select", "elementOptions": [], "transformers": [] }
+        ]
+      },
+      "default_value": "ping",
+      "options": [
+        "ping",
+        "fping"
+      ],
+      "localized": ["name", "description"],
+      "name": [
+        {
+          "language_code": "en_us",
+          "string": "Mode"
+        }
+      ],
+      "description": [
+        {
+          "language_code": "en_us",
+          "string": "Selects the ICMP engine to use. <code>ping</code> checks devices individually and works even when the ARP / neighbor cache is empty, but is slower on larger networks. <code>fping</code> scans IP ranges in parallel and is significantly faster, but relies on the system neighbor cache to resolve IP addresses to MAC addresses. For most networks, <code>fping</code> is recommended. The default command arguments <code>ICMP_ARGS</code> are compatible with both modes."
+        }
+      ]
+    },
     {
       "function": "CMD",
       "type": {
@@ -115,7 +143,7 @@
           }
         ]
       },
-      "default_value": "-i 0.5 -c 3 -W 4 -w 5",
+      "default_value": "-i 0.5 -c 3 -w 5",
       "options": [],
       "localized": ["name", "description"],
       "name": [
@@ -127,7 +155,7 @@
       "description": [
         {
           "language_code": "en_us",
-          "string": "Arguments passed to the <code>ping</code> command. Please be careful modifying these."
+          "string": "Arguments passed to the underlying <code>ping</code> or <code>fping</code> command. The default values are compatible with both modes and work well in most environments. Modify with care, and consult the relevant manual pages if advanced tuning is required."
         }
       ]
     },
@@ -159,6 +187,41 @@
         }
       ]
     },
+    {
+      "function": "FAKE_MAC",
+      "type": {
+        "dataType": "boolean",
+        "elements": [
+          {
+            "elementType": "input",
+            "elementOptions": [
+              {
+                "type": "checkbox"
+              }
+            ],
+            "transformers": []
+          }
+        ]
+      },
+      "default_value": false,
+      "options": [],
+      "localized": [
+        "name",
+        "description"
+      ],
+      "name": [
+        {
+          "language_code": "en_us",
+          "string": "Fake MAC"
+        }
+      ],
+      "description": [
+        {
+          "language_code": "en_us",
+          "string": "If enabled and the mode is set to <code>fping</code>, the plugin will also discover new devices not already in the database. Enabling this setting generates a fake MAC address from the IP address to track devices. This may cause inconsistencies if IPs change or devices are re-discovered with a different MAC. Static IPs are recommended. Device type and icon might not be detected correctly, and some plugins may fail if they rely on a valid MAC address. When unchecked, devices without a MAC address are skipped."
+        }
+      ]
+    },
     {
       "function": "RUN_SCHD",
       "type": {

front/plugins/icmp_scan/icmp.py

@@ -16,6 +16,7 @@ from logger import mylog, Logger  # noqa: E402 [flake8 lint suppression]
 from helper import get_setting_value  # noqa: E402 [flake8 lint suppression]
 from const import logPath  # noqa: E402 [flake8 lint suppression]
 from models.device_instance import DeviceInstance  # noqa: E402 [flake8 lint suppression]
+from utils.crypto_utils import string_to_mac_hash  # noqa: E402 [flake8 lint suppression]
 import conf  # noqa: E402 [flake8 lint suppression]
 from pytz import timezone  # noqa: E402 [flake8 lint suppression]
 
@@ -32,13 +33,39 @@ LOG_FILE = os.path.join(LOG_PATH, f'script.{pluginName}.log')
 RESULT_FILE = os.path.join(LOG_PATH, f'last_result.{pluginName}.log')
 
 
+def parse_scan_subnets(subnets):
+    """Extract subnet and interface from SCAN_SUBNETS"""
+    ranges = []
+    interfaces = []
+    for entry in subnets:
+        parts = entry.split("--interface=")
+        ranges.append(parts[0].strip())
+        if len(parts) > 1:
+            interfaces.append(parts[1].strip())
+    return ranges, interfaces
+
+
+def get_device_by_ip(ip, all_devices):
+    """Get existing device based on IP"""
+    for device in all_devices:
+        if device["devLastIP"] == ip:
+            return device
+
+    return None
+
+
 def main():
 
     mylog('verbose', [f'[{pluginName}] In script'])
 
     timeout = get_setting_value('ICMP_RUN_TIMEOUT')
     args = get_setting_value('ICMP_ARGS')
-    in_regex = get_setting_value('ICMP_IN_REGEX')
+    regex  = get_setting_value('ICMP_IN_REGEX')
+    mode = get_setting_value('ICMP_MODE')
+    fakeMac = get_setting_value('ICMP_FAKE_MAC')
+    scan_subnets = get_setting_value("SCAN_SUBNETS")
+
+    subnets, interfaces = parse_scan_subnets(scan_subnets)
 
     # Initialize the Plugin obj output file
     plugin_objects = Plugin_Objects(RESULT_FILE)
@@ -50,33 +77,13 @@ def main():
     all_devices = device_handler.getAll()
 
     # Compile the regex for efficiency if it will be used multiple times
-    regex_pattern = re.compile(in_regex)
+    regex_pattern = re.compile(regex)
 
-    # Filter devices based on the regex match
+    if mode == "ping":
-    filtered_devices = [
+        plugin_objects = execute_ping(timeout, args, all_devices, regex_pattern, plugin_objects)
-        device for device in all_devices
-        if regex_pattern.match(device['devLastIP'])
-    ]
 
-    mylog('verbose', [f'[{pluginName}] Devices to PING: {len(filtered_devices)}'])
+    elif mode == "fping":
-
+        plugin_objects = execute_fping(timeout, args, all_devices, plugin_objects, subnets, interfaces, fakeMac)
-    for device in filtered_devices:
-        is_online, output = execute_scan(device['devLastIP'], timeout, args)
-
-        mylog('verbose', [f"[{pluginName}] ip: {device['devLastIP']} is_online: {is_online}"])
-
-        if is_online:
-            plugin_objects.add_object(
-                # "MAC", "IP", "Name", "Output"
-                primaryId   = device['devMac'],
-                secondaryId = device['devLastIP'],
-                watched1    = device['devName'],
-                watched2    = output.replace('\n', ''),
-                watched3    = '',
-                watched4    = '',
-                extra       = '',
-                foreignKey  = device['devMac']
-            )
 
     plugin_objects.write_result_file()
 
@@ -88,27 +95,24 @@ def main():
 # ===============================================================================
 # Execute scan
 # ===============================================================================
-def execute_scan(ip, timeout, args):
+def execute_ping(timeout, args, all_devices, regex_pattern, plugin_objects):
     """
-    Execute the ICMP command on IP.
+    Execute ICMP command on filtered devices.
     """
 
-    icmp_args = ['ping'] + args.split() + [ip]
+    # Filter devices based on the regex match
+    filtered_devices = [
+        device for device in all_devices
+        if regex_pattern.match(device['devLastIP'])
+    ]
 
-    # Execute command
+    mylog('verbose', [f'[{pluginName}] Devices to PING: {len(filtered_devices)}'])
-    output = ""
 
-    try:
+    for device in filtered_devices:
-        # try runnning a subprocess with a forced (timeout)  in case the subprocess hangs
-        output = subprocess.check_output(
-            icmp_args,
-            universal_newlines=True,
-            stderr=subprocess.STDOUT,
-            timeout=(timeout),
-            text=True
-        )
 
-        mylog('verbose', [f'[{pluginName}] DEBUG OUTPUT : {output}'])
+        cmd = ["ping"] + args.split() + [device['devLastIP']]
+
+        output = ""
 
         # Parse output using case-insensitive regular expressions
         # Synology-NAS:/# ping -i 0.5 -c 3 -W 8 -w 9 192.168.1.82
@@ -128,31 +132,115 @@ def execute_scan(ip, timeout, args):
         # --- 192.168.1.92 ping statistics ---
         # 3 packets transmitted, 0 packets received, 100% packet loss
 
-        # TODO: parse output and return True if online, False if Offline (100% packet loss, bad address)
+        try:
-        is_online = True
+            output = subprocess.check_output(
+                cmd, universal_newlines=True, stderr=subprocess.STDOUT, timeout=timeout, text=True
+            )
+
+            mylog("verbose", [f"[{pluginName}] DEBUG OUTPUT : {output}"])
 
-        # Check for 0% packet loss in the output
-        if re.search(r"0% packet loss", output, re.IGNORECASE):
             is_online = True
-        elif re.search(r"bad address", output, re.IGNORECASE):
+            if re.search(r"0% packet loss", output, re.IGNORECASE):
-            is_online = False
+                is_online = True
-        elif re.search(r"100% packet loss", output, re.IGNORECASE):
+            elif re.search(r"bad address", output, re.IGNORECASE):
-            is_online = False
+                is_online = False
+            elif re.search(r"100% packet loss", output, re.IGNORECASE):
+                is_online = False
 
-        return is_online, output
+            if is_online:
 
-    except subprocess.CalledProcessError as e:
+                plugin_objects.add_object(
-        # An error occurred, handle it
+                    # "MAC", "IP", "Name", "Output"
-        mylog('verbose', [f'[{pluginName}] ⚠ ERROR - check logs'])
+                    primaryId   = device['devMac'],
-        mylog('verbose', [f'[{pluginName}]', e.output])
+                    secondaryId = device['devLastIP'],
+                    watched1    = device['devName'],
+                    watched2    = output.replace('\n', ''),
+                    watched3    = '',
+                    watched4    = '',
+                    extra       = '',
+                    foreignKey  = device['devMac']
+                )
 
-        return False, output
+            mylog('verbose', [f"[{pluginName}] ip: {device['devLastIP']} is_online: {is_online}"])
+
+        except subprocess.CalledProcessError as e:
+            mylog("verbose", [f"[{pluginName}] ⚠ ERROR - check logs"])
+            mylog("verbose", [f"[{pluginName}]", e.output])
+        except subprocess.TimeoutExpired:
+            mylog("verbose", [f"[{pluginName}] TIMEOUT - process terminated"])
+
+    return plugin_objects
+
+
+def execute_fping(timeout, args, all_devices, plugin_objects, subnets, interfaces, fakeMac):
+    """
+    Run fping command and return alive IPs
+    """
+    cmd = ["fping", "-a"]
+
+    if interfaces:
+        cmd += ["-I", ",".join(interfaces)]
+
+    # Build a lookup dict once
+    device_map = {d["devLastIP"]: d for d in all_devices if d.get("devLastIP")}
+
+    known_ips = list(device_map.keys())
+    online_ips = []
+
+    cmd += args.split()
+    cmd += subnets
+    cmd += known_ips
+
+    mylog("verbose", [f"[{pluginName}] fping cmd: {' '.join(cmd)}"])
+
+    try:
+        output = subprocess.check_output(
+            cmd,
+            stderr=subprocess.DEVNULL,
+            timeout=timeout,
+            text=True
+        )
+        online_ips = [line.strip() for line in output.splitlines() if line.strip()]
+
+    except subprocess.CalledProcessError:
+        online_ips = []
 
     except subprocess.TimeoutExpired:
-        mylog('verbose', [f'[{pluginName}] TIMEOUT - the process forcefully terminated as timeout reached'])
+        mylog("verbose", [f"[{pluginName}] fping timeout"])
-        return False, output
+        online_ips = []
 
-    return False, output
+    # process all online IPs
+    for onlineIp in online_ips:
+        if onlineIp in known_ips:
+            # use lookup dict instead of looping
+            device = device_map.get(onlineIp)
+            if device:
+                plugin_objects.add_object(
+                    primaryId   = device['devMac'],
+                    secondaryId = device['devLastIP'],
+                    watched1    = device['devName'],
+                    watched2    = 'mode:fping',
+                    watched3    = '',
+                    watched4    = '',
+                    extra       = '',
+                    foreignKey  = device['devMac']
+                )
+            else:
+                mylog("none", [f"[{pluginName}] ERROR reverse device lookup failed unexpectedly for {onlineIp}"])
+        elif fakeMac:
+            fakeMacFromIp = string_to_mac_hash(onlineIp)
+            plugin_objects.add_object(
+                primaryId   = fakeMacFromIp,
+                secondaryId = onlineIp,
+                watched1    = "(unknown)",
+                watched2    = 'mode:fping',
+                watched3    = '',
+                watched4    = '',
+                extra       = '',
+                foreignKey  = fakeMacFromIp
+            )
+        else:
+            mylog('verbose', [f"[{pluginName}] Skipping: {onlineIp}, as new IP and ICMP_FAKE_MAC setting not enabled"])
 
 
 # ===============================================================================

install/debian12/install_dependencies.debian12.sh

@@ -24,8 +24,8 @@ fi
 # Install dependencies
 apt-get install -y \
     tini snmp ca-certificates curl libwww-perl arp-scan perl apt-utils cron sudo gettext-base \
-    nginx-light php php-cgi php-fpm php-sqlite3 php-curl sqlite3 dnsutils net-tools \
+    nginx-light php php-cgi php-fpm php-sqlite3 php-curl sqlite3 dnsutils net-tools  \
-    python3 python3-dev iproute2 nmap python3-pip zip usbutils traceroute nbtscan avahi-daemon avahi-utils openrc build-essential git
+    python3 python3-dev iproute2 nmap fping python3-pip zip usbutils traceroute nbtscan avahi-daemon avahi-utils openrc build-essential git
 
 # alternate dependencies
 sudo apt-get install nginx nginx-core mtr php-fpm php8.2-fpm php-cli php8.2 php8.2-sqlite3 -y

install/proxmox/proxmox-install-netalertx.sh

@@ -156,7 +156,7 @@ fi
 apt-get install -y --no-install-recommends \
     tini snmp ca-certificates curl libwww-perl arp-scan perl apt-utils cron sudo \
     php8.4 php8.4-cgi php8.4-fpm php8.4-sqlite3 php8.4-curl sqlite3 dnsutils net-tools mtr \
-    python3 python3-dev iproute2 nmap python3-pip zip usbutils traceroute nbtscan \
+    python3 python3-dev iproute2 nmap fping python3-pip zip usbutils traceroute nbtscan \
     avahi-daemon avahi-utils build-essential git gnupg2 lsb-release \
     debian-archive-keyring python3-venv
 

install/ubuntu24/install.sh

@@ -62,7 +62,7 @@ apt-get install -y --no-install-recommends \
 
 # Install plugin dependencies
 apt-get install -y --no-install-recommends \
-  dnsutils mtr arp-scan snmp iproute2 nmap zip usbutils traceroute nbtscan avahi-daemon avahi-utils
+  dnsutils mtr arp-scan snmp iproute2 nmap fping zip usbutils traceroute nbtscan avahi-daemon avahi-utils
 
 # nginx-core install nginx and nginx-common as dependencies
 apt-get install -y --no-install-recommends \