Merge pull request #1658 from netalertx/next_release

Next release

Author: jokob-sk

README.md

@@ -21,13 +21,13 @@
 </details>
 
 
-Centralized network visibility and continuous asset discovery.
+Centralized network visibility and continuous asset discovery for homelabs, IT teams, MSPs, and distributed environments.
 
-Monitor devices, detect change, and stay aware across distributed networks.
+Monitor devices, detect change, and maintain visibility across remote sites, VLANs, branch offices, and segmented networks from a single interface.
 
-NetAlertX provides a centralized "Source of Truth" (NSoT) for network infrastructure. Maintain a real-time inventory of every connected device, identify Shadow IT and unauthorized hardware to maintain regulatory compliance, and automate compliance workflows across distributed sites.
+NetAlertX provides a centralized "Source of Truth" (NSoT) for network infrastructure. Maintain a real-time inventory of connected devices, identify Shadow IT and unauthorized hardware, support compliance initiatives, and automate operational workflows across distributed customer environments.
 
-NetAlertX is designed to bridge the gap between simple network scanning and complex SIEM tools, providing actionable insights without the overhead.
+Designed to bridge the gap between simple network scanners and complex SIEM platforms, NetAlertX delivers actionable network intelligence and centralized monitoring without the operational overhead.
 
 
 ## Table of Contents
@@ -98,6 +98,10 @@ build your own scanners with the [Plugin system](https://docs.netalertx.com/PLUG
 
 The [workflows module](https://docs.netalertx.com/WORKFLOWS) automates IT governance by enforcing device categorization and cleanup policies. Whether you need to assign newly discovered devices to a specific Network Node, auto-group devices from a given vendor, unarchive a device if detected online, or automatically delete devices, this module provides the flexibility to tailor the automations to your needs.
 
+### MSP & Multi-Site Monitoring
+
+NetAlertX enables centralized monitoring across remote sites and isolated environments through Sync Nodes for VLANs and branch offices, providing unified visibility of assets across multiple networks. It supports [NOC-style wallboard dashboards](https://docs.netalertx.com/ADVISORY_EYES_ON_GLASS/), [Prometheus metrics export](https://docs.netalertx.com/API_METRICS/), workflow automation for device governance, and distributed discovery with centralized alerting for scalable network operations.
+
 
 ## Documentation
 <!--- --------------------------------------------------------------------- --->
@@ -126,6 +130,15 @@ Compliance & Hardening:
 
 See [Security Best Practices](https://github.com/netalertx/NetAlertX/security) for more details.
 
+## Designed for MSPs, NOCs & Distributed Networks
+
+NetAlertX supports centralized monitoring across VLANs, branch offices, customer environments, isolated networks, and remote sites.
+
+Using [Sync Nodes](https://docs.netalertx.com/ADVISORY_MULTI_SITE_MONITORING), distributed collectors securely send device inventory and network visibility data back to a central hub, enabling unified monitoring, alerting, and asset tracking across all locations.
+
+This provides MSPs and NOCs with a single operational view of many independent networks, without requiring direct access or centralized scanning infrastructure.
+
+Common deployments include MSP wallboards, NOC dashboards, multi-site inventory monitoring, and remote office discovery.
 
 ## FAQ
 

docs/ADVISORY_MULTI_NETWORK.md

@@ -8,7 +8,7 @@ Effective multi-network monitoring starts with understanding how NetAlertX "sees
 * **B. Plan Subnet & Scan Interfaces:** Explicitly configure each accessible segment in `SCAN_SUBNETS` with the corresponding interfaces.
 * **C. Remote & Inaccessible Networks:** For networks unreachable via ARP, use these strategies:
 * **Alternate Plugins:** Supplement discovery with [SNMPDSC](SNMPDSC) or [DHCP lease imports](https://docs.netalertx.com/PLUGINS/?h=DHCPLSS#available-plugins).
-* **Centralized Multi-Tenant Management using Sync Nodes:** Run secondary NetAlertX instances on isolated networks and aggregate data using the **SYNC plugin**. Use the [`SYNC_BEHAVIOR`](../front/plugins/sync/README.md#hub-device-write-behavior-sync_behavior) setting on the hub to control whether the hub inherits device config from nodes or manages it independently.
+* **Sync Hub for MSP & Multi-Site Deployments:** Run secondary NetAlertX instances on isolated networks and aggregate data using the **SYNC plugin**. Use the [`SYNC_BEHAVIOR`](https://github.com/netalertx/NetAlertX/tree/main/front/plugins/sync/README.md#hub-device-write-behavior-sync_behavior) setting on the hub to control whether the hub inherits device config from nodes or manages it independently.
 * **Manual Entry:** For static assets where only ICMP (ping) status is needed.
 
 > [!TIP]

docs/ADVISORY_MULTI_SITE_MONITORING.md

@@ -0,0 +1,147 @@
+# MSP & Multi-Site Monitoring with NetAlertX
+
+NetAlertX supports centralized monitoring across remote sites, customer environments, branch offices, VLANs, and isolated networks using distributed Sync Nodes.
+
+Deploy lightweight NetAlertX instances inside remote or segmented networks, then securely aggregate device inventory and network visibility data into a central hub for unified monitoring, alerting, and asset management.
+
+![Sync Hub Setup Diagram](https://raw.githubusercontent.com/netalertx/NetAlertX/refs/heads/main/front/plugins/sync/sync_hub.png)
+
+---
+
+## Common MSP & Multi-Site Use Cases
+
+### Managed Service Providers (MSPs)
+
+Monitor multiple customer environments from a centralized dashboard while keeping scanning local to each customer site.
+
+Typical deployments include:
+
+* Customer branch offices
+* Retail stores
+* Warehouses
+* Small business environments
+* Segmented enterprise VLANs
+
+### Network Operations Centers (NOCs)
+
+Create centralized "Eyes on Glass" monitoring dashboards using synchronized remote collectors.
+
+Common NOC setups include:
+
+* [Wallboard dashboards](./ADVISORY_EYES_ON_GLASS.md)
+* Dedicated "Down Devices" views
+* Site-(node)specific monitoring filters
+* [Prometheus/Grafana integrations](./API_METRICS.md)
+
+### Isolated or Restricted Networks
+
+Some environments cannot be scanned directly due to:
+
+* VLAN isolation
+* Firewalls
+* VPN segmentation
+* Layer 2 limitations
+* Remote WAN locations
+
+[Sync Nodes](./REMOTE_NETWORKS.md) solve this by running discovery locally and forwarding only inventory and monitoring data to the hub.
+
+---
+
+# Architecture Overview
+
+NetAlertX supports distributed monitoring using two primary roles:
+
+| Role     | Purpose                                                     |
+| -------- | ----------------------------------------------------------- |
+| **Hub**  | Centralized monitoring, alerting, dashboards, and inventory |
+| **Node** | Remote collector performing local network discovery         |
+
+Each node scans its local network and synchronizes device data back to the hub.
+
+---
+
+# Sync Modes
+
+NetAlertX supports both PUSH and PULL synchronization models.
+
+| Mode     | Description                                        |
+| -------- | -------------------------------------------------- |
+| **PUSH** | Nodes send inventory data directly to the hub      |
+| **PULL** | The hub retrieves inventory data from remote nodes |
+
+PUSH mode is typically recommended for MSP deployments because remote customer environments often block inbound access.
+
+---
+
+# Device Ownership Models (`SYNC_BEHAVIOR`) in PULL mode
+
+The hub can operate in different synchronization ownership modes depending on your operational requirements.
+
+| Mode           | Best For                                                             |
+| -------------- | -------------------------------------------------------------------- |
+| `copy-new`     | MSP environments where the hub becomes the long-term source of truth |
+| `carbon-copy`  | Fully managed remote appliances where nodes remain authoritative     |
+| `hub-defaults` | Centralized inventory management with hub-defined policies           |
+
+This flexibility allows NetAlertX to support both:
+
+* centrally managed environments
+* distributed autonomous sites
+
+---
+
+# Example Deployment
+
+## Multi-Site MSP Deployment
+
+```text
+Customer Site A ─┐
+Customer Site B ─┼──► Central NetAlertX Hub
+Customer Site C ─┘
+```
+
+Each customer site runs a lightweight NetAlertX node locally.
+
+The central hub:
+
+* aggregates inventory
+* handles alerting
+* provides dashboards
+* exports metrics
+* integrates with Grafana or external systems
+
+---
+
+# Recommended MSP Features
+
+For best results in multi-site environments:
+
+* Configure descriptive `SYNC_node_name` values
+* Use Workflows to auto-tag devices by location/site
+* Use predefined "Down Devices" dashboards
+* Enable Prometheus metrics export
+* Use UI Filters to create site-specific views
+* Configure notification throttling to reduce alert fatigue
+
+---
+
+# Related Documentation
+
+* [Remote Networks](./REMOTE_NETWORKS.md)
+* [Sync Hub Plugin](../front/plugins/sync/README.md)
+* [Workflows](./WORKFLOWS.md)
+* [Metrics API](./API_METRICS.md)
+* [Eyes on Glass / NOC Dashboard](./ADVISORY_EYES_ON_GLASS.md)
+
+---
+
+# Summary
+
+NetAlertX enables lightweight, centralized monitoring across distributed networks without the operational overhead of traditional enterprise monitoring platforms.
+
+By combining distributed Sync Nodes with centralized dashboards, alerting, and workflows, NetAlertX can function as:
+
+* a multi-site monitoring platform
+* an MSP inventory dashboard
+* a lightweight NOC monitoring solution
+* a centralized network visibility platform for segmented environments

docs/API_SYNC.md

@@ -135,5 +135,5 @@ The `SYNC_BEHAVIOR` setting controls how the hub writes devices received from no
 | `carbon-copy` | | All MACs every sync (UPSERT) |
 | `hub-defaults` | | None — hub pipeline handles it |
 
-For full details and per-mode behaviour, see [SYNC plugin README — Hub Device-Write Behavior](../front/plugins/sync/README.md#hub-device-write-behavior-sync_behavior).
+For full details and per-mode behaviour, see [SYNC plugin README — Hub Device-Write Behavior](https://github.com/netalertx/NetAlertX/tree/main/front/plugins/sync/README.md#hub-device-write-behavior-sync_behavior).
 

docs/REMOTE_NETWORKS.md

@@ -46,7 +46,7 @@ You can use supplementary plugins that employ alternate methods. Protocols used
 If you have servers in different networks, you can set up separate NetAlertX instances on those subnets and synchronize the results into one instance using the [`SYNC` plugin](https://github.com/netalertx/NetAlertX/tree/main/front/plugins/sync).
 
 > [!TIP]
-> The [`SYNC_BEHAVIOR`](../front/plugins/sync/README.md#hub-device-write-behavior-sync_behavior) setting controls how the hub handles newly discovered devices from nodes - whether it inherits node config, overwrites on every sync, or applies its own NEWDEV defaults.
+> The [`SYNC_BEHAVIOR`](https://github.com/netalertx/NetAlertX/tree/main/front/plugins/sync/README.md#hub-device-write-behavior-sync_behavior) setting controls how the hub handles newly discovered devices from nodes - whether it inherits node config, overwrites on every sync, or applies its own NEWDEV defaults.
 
 ### Manual Entry
 

front/plugins/sync/README.md

@@ -1,4 +1,4 @@
-## Overview
+## Overview: Sync Hub for MSP & Multi-Site Deployments
 
 The synchronization plugin is designed to synchronize data across multiple instances of the app. It supports the following data synchronization modes:
 
@@ -53,7 +53,7 @@ The plugin operates in three different modes based on the configuration settings
 - **Schedule** `[n,h]`: `SYNC_RUN_SCHD`
 - **Encryption Key** `[n,h]`: `SYNC_encryption_key`
 - **Nodes to Pull From** `[h]`: `SYNC_nodes` + `GRAPHQL_PORT` of the source nodes
-- **Hub Behavior** `[h]`: `SYNC_BEHAVIOR` — controls how the hub writes devices received from nodes (see [below](#hub-device-write-behavior-sync_behavior))
+- **Hub Behavior** `[h]`: `SYNC_BEHAVIOR` - controls how the hub writes devices received from nodes (see [below](#hub-device-write-behavior-sync_behavior))
 
 ### Usage
 
@@ -73,7 +73,7 @@ The plugin operates in three different modes based on the configuration settings
 
 ### Hub Device-Write Behavior (`SYNC_BEHAVIOR`)
 
-The `SYNC_BEHAVIOR` setting — configured on the **hub only** — controls how the hub writes devices received from nodes.
+The `SYNC_BEHAVIOR` setting - configured on the **hub only** - controls how the hub writes devices received from nodes.
 
 | Value | Default? | Devices written | Source of truth | Recommended when |
 |---|---|---|---|---|

front/plugins/sync/config.json

@@ -625,7 +625,7 @@
       "description": [
         {
           "language_code": "en_us",
-          "string": "Controls how the hub handles devices received from nodes.<br><br><b>copy-new</b> (default): New devices are inserted using the node's existing configuration (name, alert settings, etc.). Subsequent node-side changes only update empty fields on the hub. Recommended: customize devices on the hub after first discovery.<br><br><b>carbon-copy</b>: All devices are upserted on every sync — the node is fully authoritative and its values overwrite <i>all</i> hub fields on every sync, including fields with <code>USER</code> or <code>LOCKED</code> source. Do not customize devices on the hub.<br><br><b>hub-defaults</b>: The hub skips the direct INSERT and creates new devices through its own pipeline, applying NEWDEV defaults. The hub is the source of truth; nodes contribute presence data only. Recommended: manage all device settings on the hub."
+          "string": "Controls how the hub handles devices from nodes.<br><br><b>copy-new</b> (default): New devices inherit settings from the node. Later syncs only fill empty hub fields.<br><i>Recommended: manage devices on the hub after first sync.</i><br><br><b>carbon-copy</b>: Node settings overwrite all hub fields on every sync.<br><i>Recommended: do not customize devices on the hub.</i><br><br><b>hub-defaults</b>: Nodes only report device presence. The hub applies its own defaults and settings.<br><i>Recommended: manage devices on the hub.</i>"
         }
       ]
     },

mkdocs.yml

@@ -64,9 +64,10 @@ nav:
         - Workflows: WORKFLOWS.md
         - Workflow Examples: WORKFLOW_EXAMPLES.md
         - Docker Swarm: DOCKER_SWARM.md
-      - Best practice advisories:
-        - Eyes on glass: ADVISORY_EYES_ON_GLASS.md
-        - Multi-network monitoring: ADVISORY_MULTI_NETWORK.md
+      - Best practice guides:
+        - NOC / Eyes-on-glass dashboard: ADVISORY_EYES_ON_GLASS.md
+        - Multi-network (VLAN / routing) monitoring: ADVISORY_MULTI_NETWORK.md
+        - Multi-site (MSP / customer / branch) monitoring: ADVISORY_MULTI_SITE_MONITORING.md
       - Help:
         - Common issues: COMMON_ISSUES.md
         - Random MAC: RANDOM_MAC.md

test/api_endpoints/test_sync_endpoint.py

@@ -9,16 +9,13 @@
 
 import os
 import sys
-from unittest.mock import patch
-
 import pytest
 
 INSTALL_PATH = os.getenv("NETALERTX_APP", "/app")
 sys.path.extend([f"{INSTALL_PATH}/front/plugins", f"{INSTALL_PATH}/server"])
 
 from helper import get_setting_value  # noqa: E402
 from api_server.api_server_start import app  # noqa: E402
-import api_server.sync_endpoint as sync_endpoint  # noqa: E402
 
 
 @pytest.fixture(scope="session")
@@ -75,35 +72,35 @@ def test_sync_post_form_encoded_returns_415(client, api_token):
     assert resp.status_code == 415
 
 
-def test_sync_post_json_body_is_accepted(client, api_token, tmp_path):
+def test_sync_post_json_body_is_accepted(client, api_token, tmp_path, monkeypatch):
     """JSON body must pass validation and return 200."""
     plugins_dir = tmp_path / "log" / "plugins"
     plugins_dir.mkdir(parents=True)
 
-    with patch.object(sync_endpoint, "INSTALL_PATH", str(tmp_path)):
-        resp = client.post(
-            "/sync",
-            headers=auth_headers(api_token),
-            json={"data": "test_payload", "plugin": "TESTPLUGIN", "node_name": "TestNode"},
-        )
+    monkeypatch.setenv("NETALERTX_PLUGINS_LOG", str(plugins_dir))
+    resp = client.post(
+        "/sync",
+        headers=auth_headers(api_token),
+        json={"data": "test_payload", "plugin": "TESTPLUGIN", "node_name": "TestNode"},
+    )
 
     assert resp.status_code == 200
     data = resp.get_json()
     assert data is not None
     assert "message" in data
 
 
-def test_sync_post_json_body_writes_encoded_file(client, api_token, tmp_path):
+def test_sync_post_json_body_writes_encoded_file(client, api_token, tmp_path, monkeypatch):
     """A successful POST must persist an encoded file in the plugins log dir."""
     plugins_dir = tmp_path / "log" / "plugins"
     plugins_dir.mkdir(parents=True)
 
-    with patch.object(sync_endpoint, "INSTALL_PATH", str(tmp_path)):
-        client.post(
-            "/sync",
-            headers=auth_headers(api_token),
-            json={"data": "encrypted_blob", "plugin": "ARPSCAN", "node_name": "Node1"},
-        )
+    monkeypatch.setenv("NETALERTX_PLUGINS_LOG", str(plugins_dir))
+    client.post(
+        "/sync",
+        headers=auth_headers(api_token),
+        json={"data": "encrypted_blob", "plugin": "ARPSCAN", "node_name": "Node1"},
+    )
 
     written = list(plugins_dir.glob("last_result.ARPSCAN.encoded.Node1.*.log"))
     assert len(written) == 1