FE: Implement pause/resume functionality for automatic scans with API…

.github/skills/code-standards/SKILL.md

@@ -98,6 +98,15 @@ from db_test_helpers import make_db, DummyDB, insert_device, minutes_ago
 
 If a helper you need doesn't exist yet, add it to `db_test_helpers.py` — not locally in the test file.
 
+## Stubbing Modules in Standalone-Capable Tests
+
+If a test stubs NetAlertX modules into `sys.modules` so a script can be imported
+outside the container (see `test/plugins/test_ntfy_custom_headers.py`), pop each
+stubbed name back out of `sys.modules` right after the one-time import that needed
+it. Otherwise the fake module leaks into every other test file collected in the
+same pytest session and shadows the real module (see `testing-workflow` skill for
+the full pattern and reproduction steps).
+
 ## MAC Literals in Tests — ALWAYS Lowercase
 
 **MANDATORY:** Every MAC address literal used in test fixtures, parametrize decorators, assertions, or comments must be lowercase hex:

.github/skills/testing-workflow/SKILL.md

@@ -59,3 +59,49 @@ docker buildx build -t netalertx-test .
 ```
 
 This takes ~30 seconds unless venv stage changes (~90s).
+
+## Pitfall: `sys.modules` Stubbing Leaks Across Test Files
+
+Some plugin tests (e.g. `test/plugins/test_ntfy_custom_headers.py`) stub NetAlertX
+modules (`conf`, `helper`, `models.notification_instance`, etc.) via
+`sys.modules[name] = fake_module` so the plugin script can be imported standalone,
+outside the container. Because `sys.modules` is a single process-wide cache shared
+by the whole pytest session, a fake module inserted by one test file silently
+shadows the real module for every other test file collected afterwards — pytest
+imports all test files during collection, before any test runs, so this can happen
+regardless of alphabetical/directory order.
+
+Symptom: `AttributeError: <module 'models.notification_instance'> does not have
+the attribute 'get_setting_value'` (or similar) in an unrelated test file, where
+the module repr has no `from '<path>'` suffix — a giveaway that a stub, not the
+real module, was resolved.
+
+Fix pattern: track which module names your stub actually inserted, and pop them
+back out of `sys.modules` immediately after the one-time import that needed them
+(the already-imported script keeps its bound names regardless):
+
+```python
+_stubbed_module_names = []
+
+def _stub(name, **attrs):
+    if name not in sys.modules:
+        mod = types.ModuleType(name)
+        for k, v in attrs.items():
+            setattr(mod, k, v)
+        sys.modules[name] = mod
+        _stubbed_module_names.append(name)
+
+# ... _stub(...) calls, then the one-time import ...
+import ntfy
+
+for _name in _stubbed_module_names:
+    sys.modules.pop(_name, None)
+```
+
+Reproduce cross-file pollution locally by running the suspect file together with
+the affected one in a single pytest invocation (order matters less than you'd
+think — collection happens for all files first):
+
+```bash
+pytest test/plugins/test_ntfy_custom_headers.py test/backend/test_notification_templates.py -v
+```

README.md

@@ -27,7 +27,6 @@ NetAlertX gives you a real-time source of truth for connected devices, helps ide
 
 Use NetAlertX to spot shadow IT, unauthorized hardware, IPAM drift, and other changes that matter to service teams. With multi-site sync, reporting, workflows, and webhooks, it helps MSPs stay ahead of problems without the overhead of a full NMS or SIEM.
 
-
 ## Table of Contents
 
 - [Quick Start](#quick-start)

front/deviceDetailsEdit.php

@@ -110,7 +110,7 @@ function getDeviceData() {
             // columns to hide
             hiddenFields = ["NEWDEV_devScan", "NEWDEV_devPresentLastScan"]
             // columns to disable/readonly - conditional depending if a new dummy device is created
-            disabledFields = mac == "new" ? ["NEWDEV_devLastNotification", "NEWDEV_devFirstConnection", "NEWDEV_devLastConnection"] : ["NEWDEV_devLastNotification", "NEWDEV_devFirstConnection", "NEWDEV_devLastConnection", "NEWDEV_devMac", "NEWDEV_devLastIP", "NEWDEV_devPrimaryIPv6", "NEWDEV_devPrimaryIPv4", "NEWDEV_devSyncHubNode", "NEWDEV_devFQDN"];
+            disabledFields = mac == "new" ? ["NEWDEV_devLastNotification", "NEWDEV_devFirstConnection", "NEWDEV_devLastConnection", "NEWDEV_devFQDN", "NEWDEV_devPrimaryIPv4", "NEWDEV_devPrimaryIPv6", "NEWDEV_devSyncHubNode"] : ["NEWDEV_devLastNotification", "NEWDEV_devFirstConnection", "NEWDEV_devLastConnection", "NEWDEV_devMac", "NEWDEV_devLastIP", "NEWDEV_devPrimaryIPv6", "NEWDEV_devPrimaryIPv4", "NEWDEV_devSyncHubNode", "NEWDEV_devFQDN"];
 
             // Fields that are tracked by authoritative handler and can be locked/unlocked
             const trackedFields = {

front/js/network-tabs.js

@@ -13,7 +13,7 @@ function renderNetworkTabs(nodes) {
                       (node.devAlertDown == 1 ? "text-red" : "text-gray50"));
 
     const portLabel = node.node_ports_count ? ` (${node.node_ports_count})` : '';
-    const icon = atob(node.devIcon);
+    const icon = safeAtob(node.devIcon);
     const id = node.devMac.replace(/:/g, '_');
 
     html += `

front/js/scan_control.js

@@ -0,0 +1,46 @@
+//--------------------------------------------------------------
+// Pause / Resume automatic scans button
+// Default pause duration (minutes) used for the single-click header button
+function renderPauseResumeButton(pauseUntil) {
+  const icon = document.getElementById('pause-resume-icon');
+  const link = document.getElementById('pause-resume-button');
+  if (!icon || !link) return;
+
+  const isPaused = !!pauseUntil;
+  icon.className = isPaused ? 'fa-solid fa-play' : 'fa-solid fa-pause';
+  link.title = isPaused
+    ? getString('Header_ResumeScans_Tooltip')
+    : getString('Header_PauseScans_Tooltip');
+}
+
+// Updated whenever the SSE state manager receives a state_update event (see sse_manager.js)
+document.addEventListener('nax:pauseStateUpdate', (e) => {
+  renderPauseResumeButton(e.detail.pauseUntil);
+});
+
+function togglePauseScans() {
+  const PAUSE_SCANS_DEFAULT_MINUTES = getSetting("UI_SCAN_PAUSE");
+  const icon = document.getElementById('pause-resume-icon');
+  const isPaused = icon && icon.classList.contains('fa-play');
+  const apiBase = getApiBase();
+  const apiToken = getSetting("API_TOKEN");
+  const endpoint = isPaused ? '/scan/resume' : '/scan/pause';
+  const success_msg = isPaused ? getString("Scans_Resumed") : getString("Scans_Paused");
+  const payload = isPaused ? {} : { minutes: PAUSE_SCANS_DEFAULT_MINUTES };
+
+  $.ajax({
+    url: `${apiBase}${endpoint}`,
+    method: "POST",
+    contentType: "application/json",
+    headers: { "Authorization": `Bearer ${apiToken}` },
+    data: JSON.stringify(payload),
+    error: function(xhr, status, error) {
+      console.error("[Header] Error toggling scan pause:", status, error);
+      showMessage(error, 5000, "modal_red");
+    },
+    success:function() {
+      showMessage(success_msg);
+    },
+  });
+}
+

front/js/sse_manager.js

@@ -186,6 +186,13 @@ class NetAlertXStateManager {
         }));
       }
 
+      // 6. Dispatch pause state update for the header Pause/Resume button
+      if (appState["pause_until"] !== undefined) {
+        document.dispatchEvent(new CustomEvent('nax:pauseStateUpdate', {
+          detail: { pauseUntil: appState["pause_until"] }
+        }));
+      }
+
       // console.log("[NetAlertX State] UI updated via jQuery");
     } catch (e) {
       console.error("[NetAlertX State] Failed to update state display:", e);

front/js/ui_components.js

@@ -971,6 +971,9 @@ function renderDeviceLink(data, container, useName = false) {
   // Build and return badge parts
   const badge = badgeFromDevice(device);
 
+  // Decode once (with a safe fallback) and reuse for both the chip and hover preview
+  const decodedIcon = safeAtob(device.devIcon);
+
   // badge class and hover-info class to container
   $(container)
     .addClass(`${badge.cssClass} hover-node-info`)
@@ -989,14 +992,14 @@ function renderDeviceLink(data, container, useName = false) {
       'data-alertdown': device.devAlertDown,
       'data-sleeping': device.devIsSleeping || 0,
       'data-archived': device.devIsArchived || 0,
-      'data-isnew':    device.devIsNew       || 0,
-      'data-icon': device.devIcon
+      'data-isnew':    device.devIsNew      || 0,
+      'data-icon': decodedIcon
     });
 
   return `
     <a href="${badge.url}" target="_blank">
       <span class="custom-chip">
-        <span class="iconPreview">${atob(device.devIcon)}</span>
+        <span class="iconPreview">${decodedIcon}</span>
         ${useName ? encodeSpecialChars(device.devName) : data.text}
         <span>
           (${badge.iconHtml})
@@ -1006,6 +1009,17 @@ function renderDeviceLink(data, container, useName = false) {
   `;
 }
 
+// ------------------------------------------
+// Base64-decode a devIcon value, tolerating missing/empty/malformed input
+function safeAtob(value) {
+  if (!value) return '';
+  try {
+    return atob(value);
+  } catch (e) {
+    return '';
+  }
+}
+
 // ------------------------------------------
 // Display device info on hover (attach only once)
 function initHoverNodeInfo() {
@@ -1063,7 +1077,7 @@ function initHoverNodeInfo() {
 
       const html = `
         <div>
-          <b> <div class="iconPreview">${atob(icon)}</div> </b><b class="devName"> ${encodeSpecialChars(name)}</b><br>
+          <b> <div class="iconPreview">${icon || ''}</div> </b><b class="devName"> ${encodeSpecialChars(name)}</b><br>
         </div>
         <hr/>
         <div class="line">

front/php/templates/header.php

@@ -54,6 +54,7 @@
   <script src="js/db_methods.js?v=<?php include 'php/templates/version.php'; ?>"></script>
   <script src="js/settings_utils.js?v=<?php include 'php/templates/version.php'; ?>"></script>
   <script src="js/device.js?v=<?php include 'php/templates/version.php'; ?>"></script>
+  <script src="js/scan_control.js?v=<?php include 'php/templates/version.php'; ?>"></script>
 
   <!-- iCheck -->
 
@@ -208,11 +209,17 @@ function update_servertime() {
           <li>
             <a id="fullscreen-button" href='#' role="button" span class='fa fa-arrows-alt' onclick='toggleFullscreen()'></a>
           </li>
+          <!-- Pause / Resume automatic scans -->
+          <li>
+            <a id="pause-resume-button" href="#" role="button" title="<?= lang('Header_PauseScans_Tooltip') ?>" onclick="togglePauseScans(); return false;">
+              <i id="pause-resume-icon" class="fa-solid fa-pause"></i>
+            </a>
+          </li>
           <!-- Notifications -->
           <li>
             <a id="notifications-button" href='userNotifications.php' role="button" span class='fa-solid fa-bell'></a>
             <span  id="unread-notifications-bell-count" title="" class="badge bg-red unread-notifications-bell" >0</span>
-          </li>
+          </li>         
           <!-- Server Status -->
           <li>
             <a onclick="setCache('activeMaintenanceTab', 'tab_Logging_id')" href="maintenance.php#tab_Logging">
@@ -482,16 +489,14 @@ function update_servertime() {
 
   function toggleFullscreen() {
 
-   if (document.fullscreenElement) {
-     document.exitFullscreen();
+    if (document.fullscreenElement) {
+      document.exitFullscreen();
+      }
+    else {
+      document.documentElement.requestFullscreen();
     }
-   else {
-     document.documentElement.requestFullscreen();
-	}
    }
 
-  //--------------------------------------------------------------
-
   // Update server time in the header
   update_servertime()
 

front/php/templates/language/ar_ar.json

@@ -387,6 +387,8 @@
     "HRS_TO_KEEP_NEWDEV_name": "مدة الاحتفاظ بالأجهزة الجديدة",
     "HRS_TO_KEEP_OFFDEV_description": "عدد الساعات للاحتفاظ بالأجهزة غير المتصلة",
     "HRS_TO_KEEP_OFFDEV_name": "مدة الاحتفاظ بالأجهزة غير المتصلة",
+    "Header_PauseScans_Tooltip": "",
+    "Header_ResumeScans_Tooltip": "",
     "LOADED_PLUGINS_description": "المكونات الإضافية المحملة",
     "LOADED_PLUGINS_name": "المكونات الإضافية المحملة",
     "LOG_LEVEL_description": "مستوى السجلات",
@@ -645,6 +647,8 @@
     "SCAN_SUBNETS_description": "الشبكات الفرعية للفحص",
     "SCAN_SUBNETS_name": "شبكات الفحص",
     "SYSTEM_TITLE": "عنوان النظام",
+    "Scans_Paused": "",
+    "Scans_Resumed": "",
     "Setting_Override": "تجاوز الإعدادات",
     "Setting_Override_Description": "وصف تجاوز الإعدادات",
     "Settings_Metadata_Toggle": "إظهار/إخفاء البيانات الوصفية للإعداد المحدد.",

front/php/templates/language/ca_ca.json

@@ -387,6 +387,8 @@
     "HRS_TO_KEEP_NEWDEV_name": "Eliminar nous dispositius després de",
     "HRS_TO_KEEP_OFFDEV_description": "Això és un paràmetre de manteniment <b>ELIMINANT dispositius</b>. Si s'activa (<code>0</code> està desactivat), els dispositius que estan <b>Offline</b> i el seu temps <b>Last Offline</b> es més vell que les hores especificades en aquest paràmetre, s'esborraran. Faci servir aquest paràmetre si vol auto-eliminar <b>Dispositius Offline</b> després de <code>X</code> hores sense connexió.",
     "HRS_TO_KEEP_OFFDEV_name": "Eliminar dispositius fora de línia després",
+    "Header_PauseScans_Tooltip": "",
+    "Header_ResumeScans_Tooltip": "",
     "LOADED_PLUGINS_description": "Quins Plugins carregar. Afegir plugins podria alentir l'aplicació. Llegir més sobre quins connectors necessiten estar habilitats, els tipus, o les opcions d'escaneig dins del <a target=\"_blank\" href=\"https://docs.netalertx.com/PLUGINS\">documents de connectors</a>. Els connectors descarregats perdran els vostres paràmetres. Només <code>desactivats</code> es poden eliminar els connectors.",
     "LOADED_PLUGINS_name": "Connectors carregats",
     "LOG_LEVEL_description": "Aquest paràmetre permetrà un registre més detallat. Útil per a la depuració d'esdeveniments d'escriptura a la base de dades.",
@@ -645,6 +647,8 @@
     "SCAN_SUBNETS_description": "La majoria dels escàners en xarxa (ARP-SCAN, NMAP, NSLOOKUP, DIG) es basen en l'exploració d'interfícies de xarxa específiques i subxarxes. Comproveu la <a href=\"https://docs.netalertx.com/SUBNETS\" target=\"_blank\">documentació de subxarxes</a> per ajudar en aquesta configuració, especialment VLANs, i quines VLANs són compatibles, o com esbrinar la màscara de xarxa i la seva interfície. <br/> <br/> Una alternativa als escàners en xarxa és activar alguns altres escàners / importadors de dispositius que no requereixin NetAlert<sup>X</sup> per tenir accés a la xarxa (UNIFI, dhcp. leases, PiHole, etc.). <br/> <br/> Nota: El temps d'exploració en si mateix depèn del nombre d'adreces IP per verificar, així que s'ha establir amb cura amb la màscara i la interfície de xarxa adequats.",
     "SCAN_SUBNETS_name": "Xarxes per escanejar",
     "SYSTEM_TITLE": "Informació de sistema",
+    "Scans_Paused": "",
+    "Scans_Resumed": "",
     "Setting_Override": "Valor de sobreescriptura",
     "Setting_Override_Description": "Activant aquesta opció anul·larà un valor predeterminat de l'aplicació amb el valor especificat.",
     "Settings_Metadata_Toggle": "Mostrar/amagar metadades per a la configuració donada.",

front/php/templates/language/cs_cz.json

@@ -387,6 +387,8 @@
     "HRS_TO_KEEP_NEWDEV_name": "Odstranit nová zařízení po",
     "HRS_TO_KEEP_OFFDEV_description": "Toto je nastavení údržby <b>ODSTRANĚNÍ zařízení</b>. Pokud je povoleno (<code>0</code> zakázáno), zařízení <b>Offline</b> a data jejich <b>Posledního připojení</b> starší, než uvedené hodiny v tomto nastavení, budou odstraněna. Toto nastavení použijte, pokud chcete automaticky mazat <b>Offline zařízení</b> po uplynutí <code>X</code> hodin offline.",
     "HRS_TO_KEEP_OFFDEV_name": "Odstranit offline zařízení po",
+    "Header_PauseScans_Tooltip": "",
+    "Header_ResumeScans_Tooltip": "",
     "LOADED_PLUGINS_description": "Které zásuvné moduly načíst. Přidávání modulů může aplikaci zpomalit. Přečtěte si více o tom, které, které je třeba, aby byly povolené, o jejich typech nebo o předvolbách skenování v <a target=\"_blank\" href=\"https://docs.netalertx.com/PLUGINS\">dokumentaci k zásuvným modulům</a>. Odpojené moduly ztratí vaše nastavení. Odpojit je možné pouze <code>deaktivované</code> moduly.",
     "LOADED_PLUGINS_name": "Načtené moduly",
     "LOG_LEVEL_description": "Toto nastavení zapne podrobnější zaznamenávání událostí. To je užitečné pro ladění událostí zapisujících do databáze.",
@@ -645,6 +647,8 @@
     "SCAN_SUBNETS_description": "Většina skenerů sítí (ARP-SCAN, NMAP, NSLOOKUP, DIG) spoléhá na skenování konkrétních síťových rozhraní a podsítí. Podívejte se do <a href=\"https://docs.netalertx.com/SUBNETS\" target=\"_blank\">dokumentace k podsítím</a> ohledně pokynů k tomuto uspořádání, zejména VLAN sítím, ohledně toho, které VLAN sítě jsou podporovány nebo jak nastavit masku sítě na svém rozhraní. <br/> <br/> Alternativou ke skenerům na sítích je zapnout nějaké jiné skenery/importéry rozhraní, které nezávisí na tom, aby NetAlert<sup>X</sup> mělo přístup k síti (UNIFI, dhcp.leases, PiHole, atd.). <br/> <br/> Pozn.: Doba skenování jako taková závisí na počtu IP adres, které zkontrolovat, takže toto nastavte pečlivě s příslušnou maskou sítě a rozhraním.",
     "SCAN_SUBNETS_name": "Sítě ke skenování",
     "SYSTEM_TITLE": "Informace o systému",
+    "Scans_Paused": "",
+    "Scans_Resumed": "",
     "Setting_Override": "Přebít hodnotu",
     "Setting_Override_Description": "Zapnutí této předvolby přebije výchozí hodnotu z aplikace hodnotou, uvedenou výše.",
     "Settings_Metadata_Toggle": "Zobrazit/skrýt metadata pro dané nastavení.",

front/php/templates/language/de_de.json

@@ -391,6 +391,8 @@
     "HRS_TO_KEEP_NEWDEV_name": "Neue Geräte löschen nach",
     "HRS_TO_KEEP_OFFDEV_description": "",
     "HRS_TO_KEEP_OFFDEV_name": "Offline-Geräte löschen nach",
+    "Header_PauseScans_Tooltip": "",
+    "Header_ResumeScans_Tooltip": "",
     "LOADED_PLUGINS_description": "",
     "LOADED_PLUGINS_name": "Geladene Plugins",
     "LOG_LEVEL_description": "Diese Einstellung aktiviert die erweiterte Protokollierung. Nützlich fürs Debuggen von in die Datenbank geschriebenen Events.",
@@ -706,6 +708,8 @@
     "SMTP_USER_description": "The user name used to login into the SMTP server (sometimes a full email address).",
     "SMTP_USER_name": "SMTP user",
     "SYSTEM_TITLE": "Systeminformationen",
+    "Scans_Paused": "",
+    "Scans_Resumed": "",
     "Setting_Override": "Wert überschreiben",
     "Setting_Override_Description": "",
     "Settings_Metadata_Toggle": "Metadaten für die angegebene Einstellung anzeigen/ausblenden.",