From 1f2205ff273834e060a0ae458e1423df62a71c84 Mon Sep 17 00:00:00 2001 From: "Jokob @NetAlertX" <96159884+jokob-sk@users.noreply.github.com> Date: Tue, 26 May 2026 21:59:11 +0000 Subject: [PATCH 1/6] Refactor sync endpoint tests to use monkeypatch for environment variables and remove unused imports --- test/api_endpoints/test_sync_endpoint.py | 15 ++++++--------- 1 file changed, 6 insertions(+), 9 deletions(-) diff --git a/test/api_endpoints/test_sync_endpoint.py b/test/api_endpoints/test_sync_endpoint.py index da88b591..baf999d2 100644 --- a/test/api_endpoints/test_sync_endpoint.py +++ b/test/api_endpoints/test_sync_endpoint.py @@ -9,8 +9,6 @@ Covers: import os import sys -from unittest.mock import patch - import pytest INSTALL_PATH = os.getenv("NETALERTX_APP", "/app") @@ -18,7 +16,6 @@ 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,13 +72,13 @@ 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( + 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"}, @@ -93,13 +90,13 @@ def test_sync_post_json_body_is_accepted(client, api_token, tmp_path): 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( + 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"}, From 014e8ffff0b7e519fc9b30a1f1b2c994b4ea1e6f Mon Sep 17 00:00:00 2001 From: "Jokob @NetAlertX" <96159884+jokob-sk@users.noreply.github.com> Date: Tue, 26 May 2026 21:59:54 +0000 Subject: [PATCH 2/6] linting --- test/api_endpoints/test_sync_endpoint.py | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/test/api_endpoints/test_sync_endpoint.py b/test/api_endpoints/test_sync_endpoint.py index baf999d2..fafc34ca 100644 --- a/test/api_endpoints/test_sync_endpoint.py +++ b/test/api_endpoints/test_sync_endpoint.py @@ -79,10 +79,10 @@ def test_sync_post_json_body_is_accepted(client, api_token, tmp_path, monkeypatc 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"}, - ) + "/sync", + headers=auth_headers(api_token), + json={"data": "test_payload", "plugin": "TESTPLUGIN", "node_name": "TestNode"}, + ) assert resp.status_code == 200 data = resp.get_json() @@ -97,10 +97,10 @@ def test_sync_post_json_body_writes_encoded_file(client, api_token, tmp_path, mo 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"}, - ) + "/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 From d3af1bea2aac0e5c74dbcbea4711c1783d7bfbca Mon Sep 17 00:00:00 2001 From: "Jokob @NetAlertX" <96159884+jokob-sk@users.noreply.github.com> Date: Tue, 26 May 2026 22:06:24 +0000 Subject: [PATCH 3/6] desc --- front/plugins/sync/config.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/front/plugins/sync/config.json b/front/plugins/sync/config.json index b5db98ea..48c41f7e 100755 --- a/front/plugins/sync/config.json +++ b/front/plugins/sync/config.json @@ -625,7 +625,7 @@ "description": [ { "language_code": "en_us", - "string": "Controls how the hub handles devices received from nodes.

copy-new (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.

carbon-copy: All devices are upserted on every sync — the node is fully authoritative and its values overwrite all hub fields on every sync, including fields with USER or LOCKED source. Do not customize devices on the hub.

hub-defaults: 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.

copy-new (default): New devices inherit settings from the node. Later syncs only fill empty hub fields.
Recommended: manage devices on the hub after first sync.

carbon-copy: Node settings overwrite all hub fields on every sync.
Recommended: do not customize devices on the hub.

hub-defaults: Nodes only report device presence. The hub applies its own defaults and settings.
Recommended: manage devices on the hub." } ] }, From fccb0b6bdcb6da381050b520e8f19d3a64d800a2 Mon Sep 17 00:00:00 2001 From: "Jokob @NetAlertX" <96159884+jokob-sk@users.noreply.github.com> Date: Tue, 26 May 2026 22:18:48 +0000 Subject: [PATCH 4/6] docs links --- docs/ADVISORY_MULTI_NETWORK.md | 2 +- docs/API_SYNC.md | 2 +- docs/REMOTE_NETWORKS.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/ADVISORY_MULTI_NETWORK.md b/docs/ADVISORY_MULTI_NETWORK.md index ab77ca89..01cf9911 100644 --- a/docs/ADVISORY_MULTI_NETWORK.md +++ b/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. +* **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`](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] diff --git a/docs/API_SYNC.md b/docs/API_SYNC.md index f7b6e4c8..94cc8669 100755 --- a/docs/API_SYNC.md +++ b/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). diff --git a/docs/REMOTE_NETWORKS.md b/docs/REMOTE_NETWORKS.md index c2c20f5f..cb41e2dc 100755 --- a/docs/REMOTE_NETWORKS.md +++ b/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 From cc4dd46d1782a0fc9a3219c560056c60c72fd324 Mon Sep 17 00:00:00 2001 From: "Jokob @NetAlertX" <96159884+jokob-sk@users.noreply.github.com> Date: Tue, 26 May 2026 22:56:34 +0000 Subject: [PATCH 5/6] docs --- README.md | 21 +++- docs/ADVISORY_MULTI_NETWORK.md | 2 +- docs/ADVISORY_MULTI_SITE_MONITORING.md | 147 +++++++++++++++++++++++++ front/plugins/sync/README.md | 6 +- mkdocs.yml | 7 +- 5 files changed, 172 insertions(+), 11 deletions(-) create mode 100644 docs/ADVISORY_MULTI_SITE_MONITORING.md diff --git a/README.md b/README.md index 388db71d..7afa9ba1 100755 --- a/README.md +++ b/README.md @@ -21,13 +21,13 @@ -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 diff --git a/docs/ADVISORY_MULTI_NETWORK.md b/docs/ADVISORY_MULTI_NETWORK.md index 01cf9911..be2cd877 100644 --- a/docs/ADVISORY_MULTI_NETWORK.md +++ b/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`](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. +* **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] diff --git a/docs/ADVISORY_MULTI_SITE_MONITORING.md b/docs/ADVISORY_MULTI_SITE_MONITORING.md new file mode 100644 index 00000000..031199ca --- /dev/null +++ b/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 diff --git a/front/plugins/sync/README.md b/front/plugins/sync/README.md index fa465a70..3361dd87 100755 --- a/front/plugins/sync/README.md +++ b/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 | |---|---|---|---|---| diff --git a/mkdocs.yml b/mkdocs.yml index 28d1ccc2..3ff3e355 100755 --- a/mkdocs.yml +++ b/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_GLASSS.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 From 1094ef3ff797aea88cb241dc21c51b07b1fc0d3c Mon Sep 17 00:00:00 2001 From: "Jokob @NetAlertX" <96159884+jokob-sk@users.noreply.github.com> Date: Tue, 26 May 2026 23:11:41 +0000 Subject: [PATCH 6/6] docs --- mkdocs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mkdocs.yml b/mkdocs.yml index 3ff3e355..398bdcee 100755 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -65,7 +65,7 @@ nav: - Workflow Examples: WORKFLOW_EXAMPLES.md - Docker Swarm: DOCKER_SWARM.md - Best practice guides: - - NOC / Eyes-on-glass dashboard: ADVISORY_EYES_ON_GLASSS.md + - 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: