RoamSwitch Icon RoamSwitch by Lafine Systems Design
Operations Manual (Sensor)
Edition macOS Linux Sensor

A Dedicated Sensor Node for Your LAN: “RoamSwitch Sensor”

RoamSwitch Sensor is a dedicated LAN node that audits the RoamSwitch endpoints on the same LAN (Mac / Linux Client / Server Edition) from the outside. It checks what a host looks like to another machine on the LAN (open ports, services exposed without authentication, footholds for lateral movement), which the host can never see through its own self-diagnosis. It also provides a device inventory of the LAN and ARP spoofing detection.

RoamSwitch Sensor: a dedicated LAN sensor node with ARP sweep and passive ARP monitoring, IoT risk classification, active vulnerability audit of paired RoamSwitch endpoints, and pairing-code (Ed25519, fixed IP) pairing

🛡️ Active Vulnerability Audit (paired endpoints only)

Full port scan → known-signature checks (unauthenticated Redis/dockerd/Memcached/MongoDB/Elasticsearch/CouchDB/Jenkins/VNC exposure, SMBv1 and missing SMB signing, RDP without NLA, SMTP open-relay, etc.) → generic banner grab → nmap NSE supplementary scan — four phases, entirely non-destructive.

📋 Network Composition (Active ARP Sweep)

Finds the devices on your LAN with an ARP sweep. It builds an inventory of IP, MAC, hostname, vendor, online status, first/last seen and IP history, and lets you record a free-text name or purpose per device. Devices with no note are highlighted as needing attention, so the list doubles as an asset-inventory check. Without nmap installed it falls back to a passive mode that lists only devices the Sensor has itself communicated with.

👁️ ARP Events with “What to Do Next”

New-device appearances and MAC changes on a known IP (a sign of ARP spoofing) are shown with a timestamp, a severity (critical to info), the reasons behind it, who is involved and concrete steps to verify. A MAC change on the gateway IP is rated critical. With the opt-in passive capture enabled it also detects one device sending ARP requests for many IPs (internal reconnaissance).

🔎 Awareness of Other LAN Devices & Suspicious Behavior (Detection Only)

Shows, as reference information, MAC vendor and device category, model identification from mDNS/SSDP/DHCP self-announcements, connections to known-malicious IPs or admin ports, signs of botnet or DDoS participation (contacting many destinations), and signs of DNS tunneling/C2. Most of this needs the opt-in passive-capture setup (e.g. a mirror port), and the Sensor never blocks traffic.

🔑 Pairing-Code Pairing (Ed25519, fixed IP, certificate pin)

Trusts nothing by default. Entering the 10-minute, single-use pairing code the Sensor operator issued, together with the Sensor’s fixed IP address and the certificate fingerprint shown on the Sensor’s screen, establishes mutual trust in both directions in a single step. Public keys are exchanged automatically, so you never need to know them in advance. No cloud account or registration required.

🔐 Control-API Hardening (TLS 1.3, certificate pin, replay protection)

Control traffic with endpoints (TCP 50543) is accepted over TLS 1.3 (control.tls: off / optional (default) / required). The certificate is self-signed; trust comes from the fingerprint shown on the Sensor’s screen, which the endpoint pins — it is never fetched over the network. Audit-request signatures use the v2 format with a timestamp and nonce, so replays are refused, and pairing-code guessing and signature failures lock out the source IP. Whether legacy v1 signatures are accepted and which IP the API listens on are configurable too.

🖥️ A 10-Language TUI That Covers Every Feature

The interactive TUI reaches every CLI subcommand, every daemon IPC method and every configuration key (a config editor, TLS status and certificate rotation, manual pairing, a notification test), collector operations and every event view (including passive monitoring, IoT behaviour, suspicious traffic and advisories) in 10 languages. The CLI is Japanese and English. Audit reports and exports can be produced in 10 languages too.

📅 Scheduled Audits and Change Detection (opt-in)

Automatically audits every paired endpoint on a schedule and shows what changed since the previous audit — new findings, resolved ones and newly open ports. If every port that was open is suddenly not visible, it is reported as suspected unreachable, not as fixed. Even unattended, the Sensor confirms before and after each audit that the endpoint's MAC address is still the one it authenticated with, and skips the audit if the IP address has gone to a different device. Off by default; you set the interval and the time window.

📣 Notifications and Audit Evidence (opt-in)

Send regressions, new devices, ARP spoofing and more to webhooks (Slack, Discord, Teams and others) and syslog (RFC 5424). Pairing, unpairing, audits and configuration changes are recorded with who did them in a tamper-evident operation log (a hash chain), and audit results, the device inventory and the log can be exported as CSV, JSON or an HTML report (save it as PDF from a browser). Every notification destination is one you configure; by default no device data or audit results are sent anywhere. Detection data (the CVE map and the nmap NSE database) is fetched daily from the update service; you can turn that off with updates.fetch_cve_map, and that traffic carries no device or audit data.

🗂️ Aggregating Several Sensors (Central Collector, opt-in)

For organizations with Sensors at several sites, a central collector that gathers signed summaries is included (disabled by default). It provides a per-site dashboard and CSV export, and detects a Sensor’s audit log being truncated or rewound. Devices without RoamSwitch (unmanaged devices) can be included in the summary classified as an “unpaired RoamSwitch host” or an “unknown device” (collector.send_unmanaged_devices; never any traffic content). It accepts only signed requests from Sensors you have enrolled, and refuses to be exposed beyond the LAN without TLS.

If the Sensor itself needs to be hardened against attack, we recommend installing RoamSwitch for Linux Server Edition separately on the same machine — the two run as fully independent processes.

Audit Report Example

An example of the report written by roamswitch-sensor export all --format html (the e key in the TUI). It is a single HTML file: open it in a browser and choose “Save as PDF” to get a PDF you can hand to auditors.

All machine names, MAC addresses, IP addresses and keys shown are fictional. The report body can be produced in any of 10 languages; a Japanese and an English example are shown here.

See the Full Verification Guide →