DOCS: remote networks

Author: jokob-sk

docs/REMOTE_NETWORKS.md

@@ -1,63 +1,81 @@
 # Scanning Remote or Inaccessible Networks
 
-By design, local network scanners such as `arp-scan` use ARP (Address Resolution Protocol) to map IP addresses to MAC addresses on the local network. Since ARP operates at Layer 2 (Data Link Layer), it typically works only within a single broadcast domain, usually limited to a single router or network segment.
+> [!TIP]
+> If a device responds to `ping` but does not appear in NetAlertX, the most common cause is that the device is located on a different Layer-2 segment, behind a Wi-Fi extender, VPN, VLAN, or router. In these cases, `arp-scan` may not be able to discover it even though IP connectivity exists.
+
+By design, local network scanners such as `arp-scan` use ARP (Address Resolution Protocol) to map IP addresses to MAC addresses on the local network. Since ARP operates at Layer 2 (Data Link Layer), it **typically works only within a single broadcast domain**, usually limited to a single router or network segment.
 
 > [!NOTE]
-> Ping and `ARPSCAN` use different protocols so even if you can ping devices it doesn't mean `ARPSCAN` can detect them.
+> `ping` and `arp-scan` use different protocols so even if you can ping devices it doesn't mean the `ARPSCAN` plugin can detect them.
 
-To scan multiple locally accessible network segments, add them as subnets according to the [subnets](./SUBNETS.md) documentation. If `ARPSCAN` is not suitable for your setup, read on.
+To scan multiple **locally accessible network segments**, add them as subnets according to the [subnets](./SUBNETS.md) documentation. If `ARPSCAN` is not suitable for your setup, read on.
 
 ## Complex Use Cases
 
-The following network setups might make some devices undetectable with `ARPSCAN`. Check the specific setup to understand the cause and find potential workarounds to report on these devices.
+The following network setups can prevent the `ARPSCAN` plugin from discovering some devices. Review the relevant section below to understand the limitations and available workarounds.
 
 ### Wi-Fi Extenders
 
 Wi-Fi extenders often **block or proxy Layer-2 broadcast traffic**, which can prevent network scanning tools like `arp-scan` from detecting devices behind the extender. This can happen **even when the extender uses the same SSID and the same IP subnet** as the main network.
 
-Please note that being able to `ping` a device does **not** mean it is discoverable via `arp-scan`.
+> [!IMPORTANT]
+> Please note that being able to `ping` a device does **not** mean it is discoverable via `arp-scan`.
+>
+> * `arp-scan` relies on **Layer 2 (ARP broadcast)**
+> * ICMP (`ping`) operates at **Layer 3 (routed traffic)**
 
-* `arp-scan` relies on **Layer 2 (ARP broadcast)**
-* ICMP (`ping`) operates at **Layer 3 (routed traffic)**
+Devices behind extenders may respond to ping but remain undiscoverable via `arp-scan`.
 
-That’s why devices behind extenders may respond to ping but remain undiscoverable via `arp-scan`.
+#### Workaround: Wi-Fi Extenders
 
-> **Possible workaround**:
-> If the extender uses a separate subnet, scan that subnet directly. Otherwise, use DHCP-based discovery plugins or router integration instead of ARP. See the **Other Workarounds** section below for more details.
+If the extender uses a separate subnet, scan that subnet directly. See the [subnets](./SUBNETS.md) documentation for details. Otherwise, use DHCP-based discovery plugins or router integration instead of relying only on the `ARPSCAN` plugin. See the **Other Workarounds** section below for more details.
 
 ### VPNs
 
-ARP operates at Layer 2 (Data Link Layer) and works only within a local area network (LAN). VPNs, which operate at Layer 3 (Network Layer), route traffic between networks, preventing ARP requests from discovering devices outside the local network.
+The `arp-scan` utility operates at Layer 2 (Data Link Layer) and works only within a local area network (LAN). VPNs, which operate at Layer 3 (Network Layer), route traffic between networks, preventing ARP requests from discovering devices outside the local network.
 
 VPNs use virtual interfaces (e.g., `tun0`, `tap0`) to encapsulate traffic, bypassing ARP-based discovery. Additionally, many VPNs use NAT, which masks individual devices behind a shared IP address.
 
-> **Possible workaround**: Configure the VPN to bridge networks instead of routing to enable ARP, though this depends on the VPN setup and security requirements.
+#### Workaround: VPNs 
+
+In some cases, configuring the VPN in bridge mode instead of routed mode can allow ARP traffic to pass. Whether this is possible depends on the VPN technology and your security requirements.
+
+### VLANs
+
+VLANs create separate Layer-2 broadcast domains. Devices on a different VLAN may be reachable via routing and respond to `ping`, but they typically cannot be discovered by `arp-scan`.
+
+#### Workaround: VLANs
+
+Configure the VLAN subnet in the [subnets](./SUBNETS.md) settings if the network is locally accessible, or use one of the alternative discovery methods described below.
 
 ## Other Workarounds
 
 The following workarounds should work for most complex network setups.
 
-### Supplementing Plugins
+### Workaround: Supplementing Plugins
 
-You can use supplementary plugins that employ alternate methods. Protocols used by the `SNMPDSC` or `DHCPLSS` plugins are widely supported on different routers and can be effective as workarounds. Check the [plugins list](./PLUGINS.md) to find a plugin that works with your router and network setup.
+Using supplementing plugins that employ alternate discovery methods is one of the easiest ways to extend your scan coverage. Protocols used by the `SNMPDSC` or `DHCPLSS` plugins are widely supported on different routers and can be effective as workarounds. Check the [plugins list](./PLUGINS.md) to find a plugin that works with your router and network setup.
 
-### Multiple NetAlertX Instances
+### Workaround: Multiple NetAlertX Instances if you have servers in all networks
 
 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`](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.
+> 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
+### Workaround: Manual Entry for devices you can `ping`
 
-If you don't need to discover new devices and only need to report on their status (`online`, `offline`, `down`), you can manually enter devices and check their status using the [`ICMP` plugin](https://github.com/netalertx/NetAlertX/blob/main/front/plugins/icmp_scan/), which uses the `ping` command internally.
+If you don't need to discover new devices in unreachable networks, and only need to report on their status (`online`, `offline`, `down`), you can manually enter devices, with their actual IP address, and check their status using the [`ICMP` plugin](https://github.com/netalertx/NetAlertX/blob/main/front/plugins/icmp_scan/), which uses the `ping` command internally.
+
+> [!TIP]
+> For more information on how to add devices manually (or dummy devices), refer to the [Device Management](./DEVICE_MANAGEMENT.md) documentation.
 
-For more information on how to add devices manually (or dummy devices), refer to the [Device Management](./DEVICE_MANAGEMENT.md) documentation.
+Dummy devices can also be used to segment your network topology, or to represent an unmanaged device. These devices usually can't be scanned, but you can still make them appear online by using the `Force Status` field on the device to force a specific status.
 
-To create truly dummy devices, you can use a loopback IP address (e.g., `0.0.0.0` or `127.0.0.1`) or the `Force Status` field so they appear online.
+### Workaround: NMAP and Fake MAC Addresses for devices with a static IP
 
-### NMAP and Fake MAC Addresses
+Scanning remote networks with NMAP is possible (via the `NMAPDEV` plugin), but since it cannot retrieve the MAC address, you need to enable the `NMAPDEV_FAKE_MAC` setting. This will generate a fake MAC address based on the IP address, allowing you to track devices. 
 
-Scanning remote networks with NMAP is possible (via the `NMAPDEV` plugin), but since it cannot retrieve the MAC address, you need to enable the `NMAPDEV_FAKE_MAC` setting. This will generate a fake MAC address based on the IP address, allowing you to track devices. However, this can lead to inconsistencies, especially if the IP address changes or a previously logged device is rediscovered. If this setting is disabled, only the IP address will be discovered, and devices with missing MAC addresses will be skipped.
+Because the generated MAC address is derived from the IP address, changing the IP can cause the device to appear as a new device or create duplicate records. If this setting is disabled, only the IP address will be discovered, and devices with missing MAC addresses will be skipped.
 
-Check the [NMAPDEV plugin](https://github.com/netalertx/NetAlertX/tree/main/front/plugins/nmap_dev_scan) for details
+Check the [NMAPDEV plugin](https://github.com/netalertx/NetAlertX/tree/main/front/plugins/nmap_dev_scan) for details.