Next release

.devcontainer/scripts/setup.sh

@@ -15,7 +15,7 @@
 
 
 SOURCE_DIR=${SOURCE_DIR:-/workspaces/NetAlertX}
-PY_SITE_PACKAGES="${VIRTUAL_ENV:-/opt/venv}/lib/python3.12/site-packages"
+PY_SITE_PACKAGES="${VIRTUAL_ENV:-/opt/venv}/lib/python3.14/site-packages"
 
 LOG_FILES=(
   LOG_APP

CLAUDE.md

@@ -98,3 +98,6 @@ Procedural/how-to knowledge (running tests, resetting the DB, devcontainer manag
 - **No new PHP backend logic.** `front/` is being migrated away from PHP, so never add a new PHP endpoint or new server-side computation inside an existing PHP file. If a feature needs backend state or computation, add it to the Python server and expose it to the frontend through an existing read path (`app_state.json` via `query_json.php`, `table_settings.json`, a REST/GraphQL endpoint) - never re-derive logic in PHP that the Python side already knows or could easily expose. Editing existing PHP page logic (templating, bug fixes) is fine; this is about not growing the PHP surface area.
 - **A stateful UI feature (survives a reload, coordinates across tabs, reacts to a backend push) is a cross-cutting mechanism, not "just a UI feature."** Treat it like one before writing code: trace every existing consumer of the data it needs (e.g. everything that already reads `app_state.json`), not just the one file being edited. The visible surface looking small (a badge, an icon) says nothing about whether the state-propagation mechanism underneath already exists elsewhere.
 - **No JS/PHP test harness exists in `front/` — simulate before asking for a live test, every time, not after a live test fails.** Write a disposable Node/PHP script that runs the actual function(s) against realistic inputs (including inputs crossing from a different file than the one being edited) before calling a change ready to test. A diff review misses things a five-second script run catches - a renamed parameter still referenced by its old name, an ordering assumption that's wrong once two async steps are both in play.
+- **Bug and security fixes are test-first: write the failing test, run it and see it fail on the unfixed code, then fix.** Don't edit source and add tests afterward.
+- **Each user-editable config file has exactly one writer, and it must be CSRF-protected.** Read-only endpoints stay GET-only; never add a second write path. `requireCsrfToken()` reads `$_POST['csrf_token']`, so a raw-JSON-body endpoint cannot use it as-is. Loaders of user-editable JSON must tolerate a wrong top-level type and non-object entries rather than crash.
+- **Every PHP `session_start()` must be preceded by `session_set_cookie_params(['samesite' => 'Lax', 'httponly' => true])`.** A static test checks the known session-starting files, so add any new one to its list.

docs/DOCKER_INSTALLATION.md

@@ -51,6 +51,9 @@ See alternative [docker-compose examples](https://docs.netalertx.com/DOCKER_COMP
 
 ### Docker environment variables
 
+> [!NOTE]
+> If you see only 2 devices, you might need to run the container as root by setting a custom `PUID` and `PGID` as some systems don't support `--cap-add` properly, such as some Synology setups. See [running as root](https://docs.netalertx.com/FILE_PERMISSIONS/#running-as-root).
+
 | Variable | Description | Example/Default Value |
 | :------------- |:------------------------| -----:|
 | `PUID`      |Runtime UID override, set to `0` to run as root. |  `20211` |
@@ -127,8 +130,3 @@ You can read or watch several [community configuration guides](https://docs.neta
 
 | [![GitHub](https://i.imgur.com/emsRCPh.png)](https://github.com/sponsors/jokob-sk) | [![Buy Me A Coffee](https://i.imgur.com/pIM6YXL.png)](https://www.buymeacoffee.com/jokobsk) |
 | --- | --- |
-
-- Bitcoin: `1N8tupjeCK12qRVU2XrV17WvKK7LCawyZM`
-- Ethereum: `0x6e2749Cb42F4411bc98501406BdcD82244e3f9C7`
-
-> 📧 Email me at [support@netalertx.com](mailto:support@netalertx.com?subject=NetAlertX Donations) if you want to get in touch or if I should add other sponsorship platforms.

docs/SYNOLOGY_GUIDE.md

@@ -82,9 +82,18 @@ volumes:
 10. Navigate to `<Synology URL>:20211` (or your custom port).
 11. Read the [Subnets](./SUBNETS.md) and [Plugins](./PLUGINS_OVERVIEW.md) docs to complete your setup.
 
-## Solving permission issues
+## Solving permission issues (2 devices visible)
 
-  See also the [Permission overview guide](./FILE_PERMISSIONS.md).
+Some Synology setups don't support `--cap-add` properly. This usually results in seeing only 2 devices and the following error shows when running `ARPSCAN`:
+
+```bash
+You don't have permission to perform this capture on that device
+(socket: Operation not permitted)
+```
+
+To fix this you might need to set the container as ptiviledged `privileged: true` and run as root by setting a custom `PUID` and `PGID`.
+
+See [running as root](./FILE_PERMISSIONS.md) for more details.
 
 ### Configuring the permissions via SSH
 

front/php/server/query_json.php

@@ -42,38 +42,8 @@
         http_response_code(400);
         echo json_encode(["error" => "Missing 'file' parameter"]);
     }
-} elseif ($_SERVER['REQUEST_METHOD'] === 'POST') {
-    // Read the input JSON data
-    $inputData = file_get_contents("php://input");
-    $decodedData = json_decode($inputData, true);
-
-    if (json_last_error() !== JSON_ERROR_NONE) {
-        http_response_code(400);
-        echo json_encode(["error" => "Invalid JSON data"]);
-        exit;
-    }
-
-    // Check if file parameter is provided and is workflows.json
-    if (!isset($_GET['file']) || $_GET['file'] !== "workflows.json") {
-        http_response_code(400);
-        echo json_encode(["error" => "Invalid or missing file parameter"]);
-        exit;
-    }
-
-    $file = $_GET['file'];
-    $configRoot = getenv('NETALERTX_CONFIG') ?: '/data/config';
-    $filePath = rtrim($configRoot, '/') . "/" . basename($file);
-
-    // Save new workflows.json (replace existing content)
-    if (file_put_contents($filePath, json_encode($decodedData, JSON_PRETTY_PRINT))) {
-        http_response_code(200);
-        echo json_encode(["success" => "Workflows replaced successfully"]);
-    } else {
-        http_response_code(500);
-        echo json_encode(["error" => "Failed to update workflows.json"]);
-    }
-}
-else {
+} else {
+    header('Allow: GET');
     http_response_code(405);
     echo json_encode(["error" => "Method Not Allowed"]);
 }

front/php/templates/auth.php

@@ -1,5 +1,6 @@
 <?php
 if (session_status() == PHP_SESSION_NONE) {
+    session_set_cookie_params(['samesite' => 'Lax', 'httponly' => true]);
     session_start();
 }
 

front/php/templates/security.php

@@ -2,6 +2,7 @@
 
 // Start session if not already started
 if (session_status() == PHP_SESSION_NONE) {
+    session_set_cookie_params(['samesite' => 'Lax', 'httponly' => true]);
     session_start();
 }
 

install/production-filesystem/README.md

@@ -29,7 +29,7 @@ Temporary directory used during Docker image building:
 - Deleted after build to reduce image size
 - Only exists during container creation
 
-### `/opt/venv/lib/python3.12/site-packages/aiofreebox` - Certificate Storage
+### `/opt/venv/lib/python3.14/site-packages/aiofreebox` - Certificate Storage
 Contains SSL certificates required for secure communication with Freebox OS devices. The aiofreebox Python package uses these certificates to authenticate and establish encrypted connections when integrating with Freebox routers for network device discovery.
 
 Contains certificates for the aiofreebox package, which communicates with Freebox OS devices.

server/conf.py

@@ -22,6 +22,7 @@
 last_scan_run = ""
 last_version_check = ""
 arpscan_devices = []
+down_alert_cutoff = ""
 
 # ACTUAL CONFIGRATION ITEMS set to defaults
 

server/messaging/notification_sections.py

@@ -41,7 +41,10 @@
 #
 # Placeholders:
 #   {condition}          — optional WHERE clause appended by condition builder
-#   {alert_down_minutes} — runtime value, only used by down_devices
+#   {alert_down_cutoff}  — UTC 'YYYY-MM-DD HH:MM:SS' cutoff computed once per
+#                          get_notifications() call (also stored in
+#                          conf.down_alert_cutoff for the clear step), only
+#                          used by down_devices
 #
 # Every section here reads through Events_Devices, which LEFT JOINs Devices
 # onto Events - a device's pending event survives deleting the device (Events
@@ -85,7 +88,7 @@
         FROM Events_Devices AS down_events
         WHERE evePendingAlertEmail = 1
           AND down_events.eveEventType = 'Device Down'
-          AND eveDateTime < datetime('now', '-{alert_down_minutes} minutes')
+          AND eveDateTime < '{alert_down_cutoff}'
           AND down_events.devMac IS NOT NULL
           AND NOT EXISTS (
               SELECT 1

server/messaging/reporting.py

@@ -13,6 +13,7 @@
 import os
 import json
 import sys
+from datetime import timedelta
 from zoneinfo import ZoneInfo
 
 # Register NetAlertX directories
@@ -24,7 +25,7 @@
 )
 from logger import mylog  # noqa: E402 [flake8 lint suppression]
 from db.sql_safe_builder import create_safe_condition_builder  # noqa: E402 [flake8 lint suppression]
-from utils.datetime_utils import format_date_iso  # noqa: E402 [flake8 lint suppression]
+from utils.datetime_utils import format_date_iso, timeNowUTC, DATETIME_PATTERN  # noqa: E402 [flake8 lint suppression]
 from messaging.notification_sections import (  # noqa: E402 [flake8 lint suppression]
     SECTION_ORDER,
     SECTION_TITLES,
@@ -126,7 +127,13 @@ def get_notifications(db):
           AND eveMac IN (SELECT devMac FROM Devices WHERE devAlertDown = 0)
     """)
 
+    # Computed once and shared with NotificationInstance.clearPendingEmailFlag()
+    # via conf, so the clear step acts on exactly the events selected here.
     alert_down_minutes = int(get_setting_value("NTFPRCS_alert_down_time") or 0)
+    alert_down_cutoff = (
+        timeNowUTC(as_string=False) - timedelta(minutes=alert_down_minutes)
+    ).strftime(DATETIME_PATTERN)
+    conf.down_alert_cutoff = alert_down_cutoff
 
     sections = get_setting_value("NTFPRCS_INCLUDED_SECTIONS") or []
     mylog("verbose", ["[Notification] Included sections: ", sections])
@@ -158,7 +165,7 @@ def get_section_condition(section):
         return ""
 
     # SQL templates with placeholders for runtime values
-    # {condition} and {alert_down_minutes} are formatted at query time
+    # {condition} and {alert_down_cutoff} are formatted at query time
 
     # Initialize final structure
     final_json = {}
@@ -197,7 +204,7 @@ def get_section_condition(section):
             # Format template with runtime placeholders
             format_vars = {"condition": safe_condition}
             if section == "down_devices":
-                format_vars["alert_down_minutes"] = alert_down_minutes
+                format_vars["alert_down_cutoff"] = alert_down_cutoff
             if section == "events":
                 # 'Down Reconnected' has its own dedicated section; exclude it
                 # from events when that section is also active to prevent the
@@ -212,7 +219,7 @@ def get_section_condition(section):
             mylog("verbose", [f"[Notification] Error building condition for {section}: ", e])
             fallback_vars = {"condition": ""}
             if section == "down_devices":
-                fallback_vars["alert_down_minutes"] = alert_down_minutes
+                fallback_vars["alert_down_cutoff"] = alert_down_cutoff
             if section == "events":
                 if "down_reconnected" in sections:
                     fallback_vars["event_types"] = "'Connected', 'Disconnected','IP Changed'"

server/models/notification_instance.py

@@ -19,7 +19,7 @@
     getBuildTimeStampAndVersion,
 )
 from messaging.notification_sections import SECTION_ORDER
-from utils.datetime_utils import timeNowUTC, timeNowTZ, get_timezone_offset
+from utils.datetime_utils import timeNowUTC, timeNowTZ
 
 
 # -----------------------------------------------------------------------------
@@ -232,8 +232,10 @@ def setAllProcessed(self):
 
         self.save()
 
-    # Clear the Pending Email flag from all events and devices
     def clearPendingEmailFlag(self):
+        """Clear evePendingAlertEmail on reported Events and stamp
+        devLastNotification on their devices; 'Device Down' events are only
+        cleared once NTFPRCS_alert_down_time minutes have passed."""
 
         # Clean Pending Alert Events
         self.db.sql.execute("""
@@ -249,18 +251,20 @@ def clearPendingEmailFlag(self):
                 WHERE evePendingAlertEmail = 1
                 AND eveEventType !='Device Down' """)
 
-        # Clear down events flag after the reporting window passed
-        minutes = int(get_setting_value("NTFPRCS_alert_down_time") or 0)
-        tz_offset = get_timezone_offset()
+        # Clear down events flag using the exact UTC cutoff the down_devices
+        # selection query used (conf.down_alert_cutoff, set by
+        # get_notifications()), so an event that crossed the threshold after
+        # selection isn't cleared without ever being reported. eveDateTime is
+        # always UTC - applying a timezone offset here would desync the two (#1851).
         self.db.sql.execute(
             """
             UPDATE Events
             SET evePendingAlertEmail = 0
             WHERE evePendingAlertEmail = 1
                 AND eveEventType = 'Device Down'
-                AND eveDateTime < datetime('now', ?, ?)
+                AND eveDateTime < ?
                 """,
-            (f"-{minutes} minutes", tz_offset),
+            (conf.down_alert_cutoff,),
         )
 
         mylog("minimal", ["[Notification] Notifications changes: ", self.db.sql.rowcount])

server/plugins/internet_ip/script.py

@@ -144,9 +144,20 @@ def get_internet_IP(DIG_GET_IP_ARG):
 
 # -------------------------------------------------------------------------------
 def fallback_check_ip():
-    """Fallback mechanism using `curl ifconfig.me/ip`."""
+    """Retrieve the public IP via curl when the dig lookup found none.
+
+    Returns (IP, cmd_output), or no_internet_ip if the result is not a valid IPv4.
+    """
     try:
-        cmd_output = subprocess.check_output(['curl', '-s', 'ifconfig.me/ip'], text=True).strip()
+        # -4 is load-bearing: the check below accepts only IPv4, so an
+        # unforced request on a dual-stack host can return the public IPv6
+        # address and be discarded as invalid. Time limits keep a hung call
+        # from consuming the plugin runner's whole INTRNT_RUN_TIMEOUT budget.
+        cmd_output = subprocess.check_output(
+            ['curl', '-4', '-fsS', '--connect-timeout', '3', '--max-time', '8',
+             'https://ifconfig.me/ip'],
+            text=True, timeout=10
+        ).strip()
         if cmd_output and re.match(r"^\d{1,3}(\.\d{1,3}){3}$", cmd_output):
             mylog('verbose', [f'[{pluginName}] Fallback IP retrieved via curl: {cmd_output}'])
             return cmd_output, f'Fallback via curl: "{cmd_output}"'

server/plugins/nmap_dev_scan/config.json

@@ -399,7 +399,7 @@
           }
         ]
       },
-      "default_value": "sudo nmap -sn -PR -oX - ",
+      "default_value": "sudo nmap --privileged -sn -PR -oX - ",
       "options": [],
       "localized": [
         "name",
@@ -414,7 +414,7 @@
       "description": [
         {
           "language_code": "en_us",
-          "string": "Arguments to run nmap-scan with. Recommended and tested only with the setting: <br/> <code>sudo nmap -sn -PR -oX - </code>. <br/><br/> Note: The plugin attaches the interface and network mask, for example <code> -e eth1 192.168.1.0/24</code> and performs a separate scan for each interface specified in the <a onclick=\"toggleAllSettings()\" href=\"#SCAN_SUBNETS\"><code>SCAN_SUBNETS</code> setting</a>."
+          "string": "Arguments to run nmap-scan with. Recommended and tested only with the setting: <br/> <code>sudo nmap --privileged -sn -PR -oX - </code>. <br/><br/> Note: The plugin attaches the interface and network mask, for example <code> -e eth1 192.168.1.0/24</code> and performs a separate scan for each interface specified in the <a onclick=\"toggleAllSettings()\" href=\"#SCAN_SUBNETS\"><code>SCAN_SUBNETS</code> setting</a>."
         }
       ]
     },

server/workflows/manager.py

@@ -52,7 +52,7 @@ def _scan(node):
     # -------------------------------------------------------------------------
     # Loading
     def load_workflows(self):
-        """Load workflows from workflows.json, rejecting any with invalid tokens."""
+        """Load workflows from workflows.json, skipping non-object entries and any with invalid tokens."""
         try:
             workflows_json_path = fullConfFolder + "/workflows.json"
             with open(workflows_json_path, "r") as f:
@@ -61,8 +61,15 @@ def load_workflows(self):
             mylog("none", ["[WF] Failed to load workflows.json"])
             return []
 
+        if not isinstance(raw, list):
+            mylog("none", ["[WF] workflows.json must contain a list of workflows - ignoring file"])
+            return []
+
         valid = []
         for wf in raw:
+            if not isinstance(wf, dict):
+                mylog("none", ["[WF] Skipping workflows.json entry that is not an object"])
+                continue
             if self._validate_workflow_tokens(wf):
                 valid.append(wf)
             else: