Manuale Operativo di RoamSwitch Sensor

La guida all'installazione e alla gestione di RoamSwitch Sensor, un sensore di rete che, una volta collocato nella LAN, rileva nuovi dispositivi e spoofing nello stesso segmento, ed esegue controlli attivi delle vulnerabilità su qualsiasi endpoint già dotato di RoamSwitch (Mac / Linux Client / Server Edition). Distribuito tramite pacchetti apt/dnf.

1. Panoramica e posizionamento

RoamSwitch (Mac / Linux Client / Server Edition) è, in ogni caso, un agente residente sull'host. Questa forma presenta due punti ciechi strutturali.

• L'autodiagnosi di un singolo host presenta un punto cieco fondamentale: il rischio di movimento laterale — "chiuso verso l'esterno, ma completamente esposto da un altro dispositivo sulla stessa LAN" — non può mai essere rilevato da un host che osserva solo se stesso.
• Alcuni dispositivi non potranno mai eseguire RoamSwitch: dispositivi IoT (telecamere di rete, prese intelligenti, stampanti multifunzione), dispositivi ospiti/BYOD, le stesse apparecchiature di rete, dispositivi embedded e altro ancora.

RoamSwitch Sensor è un nodo dedicato collocato nella LAN, con l'obiettivo di colmare entrambe le lacune. Ciò che è realmente implementato e verificato oggi si limita a due cose: controlli attivi delle vulnerabilità sugli endpoint dotati di RoamSwitch nella stessa LAN, e rilevamento passivo della comparsa di nuovi dispositivi e dello spoofing, guidato dalla tabella ARP dello stesso Sensor (come indicato al §6, non si tratta di una funzione che scansiona attivamente e rende visibile ogni dispositivo della LAN). Non è progettato come un EDR, ma come un NDR leggero (Network Detection & Response) combinato con uno scanner di vulnerabilità a prova di sfruttamento sviluppato internamente.

L'autodifesa non è implementata intenzionalmente (una scelta progettuale deliberata). Se è necessario proteggere l'host del Sensor stesso dagli attacchi, si consiglia di installare separatamente RoamSwitch for Linux Server Edition sulla stessa macchina. I due funzionano come processi completamente indipendenti e coesistono senza conflitti.

2. Ambiente di verifica attuale

• SO supportato: Debian 12 (bookworm) o successivo / Ubuntu 22.04 o successivo (apt), famiglia Fedora/RHEL (dnf). Solo x86_64 (amd64) — arm64 non è ancora supportato.
• Hardware di destinazione (piano futuro): per l'uso reale prevediamo un dispositivo a basso consumo adatto al funzionamento continuo, come un mini PC senza ventola della serie N100/N150, ma oggi non viene fornita alcuna build o consegna dedicata a questo scopo.
• Posizionamento in rete: deve essere collegato fisicamente o logicamente al segmento LAN monitorato (roamswitch-sensor.service viene eseguito sulla rete host — necessario per osservare direttamente la tabella ARP). Deve inoltre funzionare con un indirizzo IP fisso (assegnazione statica, o riserva lato server DHCP) affinché gli endpoint possano raggiungerlo per l'abbinamento e le richieste di controllo. Resta in ascolto sulla porta TCP 50543.
• Consumo di risorse: memoria residente dell'ordine di decine di MB; il carico CPU a riposo è estremamente contenuto.
• Opzionale: nmap (utilizzato per le diagnosi supplementari NSE; tutte le altre funzioni operano normalmente anche senza).

3. Installazione e avvio

Installare il pacchetto roamswitch-sensor dal repository ufficiale firmato. Dopo l'installazione, roamswitch-sensor.service (systemd) viene abilitato e avviato automaticamente.

3.1 APT (Ubuntu / Debian)

# 1. Registrare la chiave di firma del repository
curl -fsSL https://lafine.net/apt/roamswitch-archive-keyring.asc \
  | sudo gpg --dearmor -o /usr/share/keyrings/roamswitch-archive-keyring.gpg

# 2. Aggiungere il repository
echo "deb [signed-by=/usr/share/keyrings/roamswitch-archive-keyring.gpg] https://lafine.net/apt stable main" \
  | sudo tee /etc/apt/sources.list.d/roamswitch.list

# 3. Installare
sudo apt update && sudo apt install roamswitch-sensor

3.2 DNF / RPM (Fedora / RHEL)

# 1. Importare la chiave GPG
sudo rpm --import https://lafine.net/rpm/RPM-GPG-KEY-roamswitch

# 2. Aggiungere il file di configurazione del repository
sudo curl -fsSL -o /etc/yum.repos.d/roamswitch.repo https://lafine.net/rpm/fedora/roamswitch.repo

# 3. Installare
sudo dnf install roamswitch-sensor

3.3 Verifica dell'avvio

systemctl status roamswitch-sensor.service
sudo roamswitch-sensor status

3.4 Esecuzione di CLI / TUI

La CLI (roamswitch-sensor) e la TUI interattiva (roamswitch-sensor-tui) possono essere eseguite direttamente dopo l'installazione.

sudo roamswitch-sensor status
sudo roamswitch-sensor-tui

4. Abbinamento (metodo a codice)

Di fabbrica, Sensor non si fida di nulla. L'abbinamento avviene tramite un codice di abbinamento monouso rilasciato dall'operatore del Sensor. Il rapporto di fiducia — «Sensor può eseguire controlli attivi delle vulnerabilità su questo endpoint» — si stabilisce simultaneamente in entrambe le direzioni con un unico passaggio di abbinamento (non esiste uno stato di fiducia in una sola direzione).

Prerequisito: eseguire Sensor con un indirizzo IP fisso (assegnazione statica, o riserva lato server DHCP). Dopo l'abbinamento, l'endpoint si connette sempre direttamente all'indirizzo IP di Sensor confermato al momento dell'abbinamento (non esiste più alcuna scoperta automatica, né tramite mDNS né altrimenti); se l'IP di Sensor cambia in seguito, sarà necessario un nuovo abbinamento. Il lato endpoint può continuare a usare un IP dinamico.

4.1 Rilasciare un codice di abbinamento (lato Sensor)

# Eseguire sul lato Sensor (oppure premere c nella TUI)
sudo roamswitch-sensor issue-code

Viene rilasciato un codice monouso di 8 caratteri (lettere maiuscole e cifre, esclusi i caratteri facilmente confondibili 0/O/1/I/L). Scade 10 minuti dopo il rilascio e può essere usato una sola volta: comunicarlo quindi tempestivamente all’operatore dell’endpoint tramite un qualsiasi canale fuori banda (a voce, in chat, ecc.).

4.2 Abbinamento tramite codice (lato endpoint)

# Lato endpoint (roamswitch-linux)
sudo roamswitch sensor pair --addr <IP fisso del Sensor> --code <codice di abbinamento>

Nell'edizione Mac, la stessa operazione è disponibile tramite l'interfaccia grafica da «🔍 Associazione RoamSwitch Sensor…» nella barra dei menu, dove si inseriscono l'indirizzo IP e il codice di abbinamento del Sensor.

Una volta completato l'abbinamento, ogni successivo controllo attivo delle vulnerabilità e ogni recupero dei risultati vengono autenticati con una firma Ed25519. Sia l'endpoint che conosceva il codice, sia il Sensor che lo ha rilasciato, si fidano reciprocamente da quel momento in poi.

4.3 Associazione manuale (registrazione diretta di una chiave pubblica già nota)

Se l'operatore del Sensor conosce già, tramite un altro canale, la chiave pubblica e l'indirizzo di un endpoint, può anche registrarlo direttamente sul lato Sensor senza scambiare un codice di abbinamento (normalmente è preferibile usare il metodo a codice del §4.2 e lasciare che l'endpoint si abbini da solo). È possibile consultare la propria chiave pubblica e il proprio indirizzo con i seguenti comandi.

# Verificare la propria chiave pubblica/indirizzo sul lato endpoint
sudo roamswitch sensor key

# Verificare la propria chiave pubblica/indirizzo/indirizzo MAC sul lato Sensor
sudo roamswitch-sensor status

# Lato Sensor
sudo roamswitch-sensor pair <chiave pubblica completa> --addr <indirizzo IP> --confirm

5. Controllo attivo delle vulnerabilità

Sensor esegue diagnosi delle vulnerabilità non distruttive e basate su prove sugli endpoint associati. Non esegue mai operazioni distruttive (scrittura o cancellazione di dati, arresto di servizi).

sudo roamswitch-sensor scan <chiave pubblica o il suo inizio>

Il controllo si compone di quattro fasi.

1. Scansione completa delle porte: rileva in modo esaustivo tutte le porte TCP aperte sull'host di destinazione.
2. Diagnosi delle firme note: verifiche non distruttive e basate su prove contro pattern di vulnerabilità noti — esposizione non autenticata di Redis / dockerd / Memcached / MongoDB / Elasticsearch / CouchDB / Jenkins / VNC, diagnosi di open relay SMTP (un metodo sicuro che invia solo MAIL FROM/RCPT TO, mai DATA) e diagnosi di configurazione CORS errata, path traversal e open redirect su server di sviluppo, tra le altre.
3. Acquisizione generica del banner: per le porte aperte non coperte dalle firme sopra indicate, recupera la stringa del banner semplicemente connettendosi (non viene inviato alcun dato).
4. Diagnosi supplementare nmap NSE: diagnosi supplementare ad ampia copertura di protocolli tramite nmap --script safe. Viene eseguita automaticamente non appena nmap è installato sull'host (altrimenti non fa nulla).

Ogni esecuzione di controllo viene registrata in /var/lib/roamswitch-sensor/scan_history.json — indipendentemente dal fatto che sia stato rilevato qualcosa, poiché anche un risultato pulito in quel momento ha valore documentale — e può essere consultata da CLI o TUI.

roamswitch-sensor history
sudo roamswitch-sensor report <chiave pubblica o il suo inizio> --out /tmp/report.md

5.1 Richiesta di un controllo dal lato client (modello pull)

Un endpoint abbinato può anche richiedere attivamente un controllo a Sensor. Nell’edizione Mac, usare «Richiedi controllo al Sensor» nella barra dei menu; su Linux, usare il comando seguente.

sudo roamswitch sensor request-audit

Dopo che Sensor ha eseguito il controllo, l’endpoint interroga il risultato a partire da 5 minuti dopo la richiesta, poi ogni 5 minuti per un massimo di 5 tentativi (quindi fino a 25 minuti in totale). Il risultato ottenuto viene salvato anche localmente sull’endpoint.

roamswitch sensor results

Nell’edizione Mac, i risultati compaiono anche nell’elenco «Risultati dei controlli» della finestra delle impostazioni, oppure possono essere letti tramite lo strumento MCP get_sensor_audit_results, come input per un agente IA che pianifica una remediation. Il recupero di un risultato può anche essere esplicitamente rifiutato, ad esempio se l’abbinamento è stato revocato sul lato Sensor (vedere §10 D6).

6. Monitoraggio ARP passivo e visibilità della LAN

Sensor esegue periodicamente uno snapshot della propria tabella ARP (equivalente a /proc/net/arp) e, confrontandolo con lo snapshot precedente, rileva due tipi di eventi: un nuovo IP/MAC mai visto prima, e una modifica dell'indirizzo MAC per un IP già noto (un segnale, ad esempio, di spoofing del gateway). Non invia mai pacchetti in modo attivo e copre solo i dispositivi con cui Sensor ha già in qualche modo comunicato (non è una funzione che scopre ed elenca attivamente ogni dispositivo della LAN). Non ha alcuna capacità di classificare il tipo di dispositivo (ad esempio, se si tratta di un dispositivo IoT) — rileva solo una modifica di IP/MAC.

roamswitch-sensor arp-events

Gli eventi rilevati possono essere elencati anche dalla scheda «ARP Events» della TUI, che distingue due tipi: «nuovo dispositivo comparso» e «indirizzo MAC di un IP noto modificato (sospetto spoofing)».

6.1 Estensione della visibilità passiva della LAN (opt-in)

Mentre il monitoraggio ARP sopra descritto copre solo i dispositivi con cui Sensor ha comunicato, impostando la variabile d'ambiente ROAMSWITCH_SENSOR_PASSIVE_CAPTURE_IFACE su un'interfaccia di destinazione si osservano le intestazioni Ethernet/IPv4 su di essa (senza ispezione del payload) per rilevare quanto segue.

• Osservazione passiva di nuovi dispositivi: dispositivi con cui Sensor non ha mai comunicato direttamente, non coperti dal solo monitoraggio ARP. Appresi dal traffico broadcast/multicast.
• Rilevamento del contatto con IP dannosi noti: segnala il traffico la cui destinazione IP corrisponde al feed di minacce locale (stesso formato dell'Egress Guard di RoamSwitch stesso) — solo rilevamento, mai bloccato.

sudo systemctl edit roamswitch-sensor.service
# [Service]
# Environment=ROAMSWITCH_SENSOR_PASSIVE_CAPTURE_IFACE=eth0

sudo systemctl restart roamswitch-sensor.service
roamswitch-sensor passive-events

7. Guida rapida ai comandi CLI

La CLI supporta solo giapponese e inglese (segue la variabile d'ambiente LANG).

8. Guida operativa della TUI

La TUI interattiva (roamswitch-sensor-tui) supporta 10 lingue. Con il tasto Tab (Shift+Tab per tornare indietro) si passa tra sei schede: Attendibile (ultimo stato di audit di ogni endpoint) / Dispositivi (tutti i dispositivi della LAN, con note) / Eventi ARP / Cronologia / Variazioni (cosa è cambiato dall'audit precedente: nuovi rilevamenti in rosso, risolti in verde, probabilmente irraggiungibile in giallo) / Registro (chi ha approvato o eseguito cosa e quando; in alto è mostrato l'esito della verifica della catena di hash).

9. Modello di fiducia e progettazione della sicurezza

• TOFU (Trust On First Use): il codice di abbinamento in sé non è una prova crittografica di proprietà, ma viene confermato dal giudizio dell'operatore, che ha ricevuto il codice rilasciato dall'operatore del Sensor tramite un canale fuori banda (a voce, in chat, ecc.), in modo simile alla conferma reciproca esplicita dell'abbinamento Bluetooth. Dal momento in cui l'abbinamento riesce, la legittimità di ogni sonda o richiesta successiva viene verificata rispetto alla chiave pubblica scambiata in quel momento.
• Progettato per individuare falle che consentirebbero un'azione distruttiva, senza mai eseguirne una esso stesso: ogni controllo attivo delle vulnerabilità è non distruttivo (non scrive né cancella mai dati, né arresta servizi). Ciò che rileva sono le configurazioni errate stesse — come «scrivibile senza autenticazione» o «funziona come open relay» — che, se sfruttate, consentirebbero un'azione distruttiva.
• Mitigazione dei falsi positivi (esclusione dell'auto-controllo): è integrata un'esclusione basata sulla corrispondenza dell'IP di origine, in modo che il controllo completo delle porte eseguito da un Sensor associato non venga scambiato per un'attività di ricognizione dalla protezione di rilevamento delle scansioni delle porte in ingresso (una funzione lato RoamSwitch). L'IP viene usato solo per questa corrispondenza, unicamente per evitare un blocco automatico, mai per la determinazione della fiducia stessa.
• Nulla viene inviato se non lo configurate voi: le informazioni sui dispositivi individuati, i risultati degli audit e gli eventi ARP sono memorizzati, per impostazione predefinita, solo nell'archiviazione locale del Sensor e non vengono mai inviati a Lafine né a server di terzi. Le notifiche (webhook / syslog) e l'invio al collector centrale descritti nel §11 vanno solo alle destinazioni configurate dalla vostra organizzazione.

10. Risoluzione dei problemi e FAQ

D1. L'inserimento di un codice di abbinamento viene rifiutato.

Tre cause probabili: (1) sono trascorsi più di 10 minuti dal rilascio e il codice è scaduto (chiedere all'operatore del Sensor di rilasciarne uno nuovo con issue-code); (2) un errore di digitazione nel codice (i caratteri facilmente confondibili 0/O/1/I/L sono esclusi già al momento del rilascio, quindi un codice non li contiene mai); (3) l'indirizzo IP indicato con --addr non corrisponde all'attuale indirizzo IP fisso di Sensor.

D2. Il risultato della diagnosi supplementare NSE è vuoto.

Una di queste due cause: (1) nmap non è installato nel container; (2) è stato eseguito, ma gli script sicuri applicabili alle porte di destinazione non hanno effettivamente prodotto alcun output. La diagnosi supplementare nmap NSE viene eseguita automaticamente non appena nmap è installato sull'host.

D3. Quanto tempo richiede il completamento di un controllo?

Una semplice scansione completa delle porte richiede circa qualche decina di secondi, ma non appena nmap è installato sull'host, si aggiunge automaticamente la diagnosi supplementare NSE, che può richiedere fino a circa 2 minuti a seconda del numero di porte aperte del bersaglio. La TUI continua a mostrare i secondi trascorsi durante l'esecuzione, così è possibile seguire l'avanzamento mentre si attende.

D4. Ho associato, ma non riesco ancora a eseguire un controllo.

Cause probabili: (1) sensor_pairing_enabled: true non è impostato sul lato endpoint (disattivato per impostazione predefinita); (2) l'indirizzo IP fisso di Sensor è cambiato dopo l'abbinamento, per cui l'endpoint tenta di raggiungere un indirizzo obsoleto (un nuovo abbinamento risolve il problema); (3) l'abbinamento è stato rimosso sul lato Sensor con unpair. Verificare con roamswitch sensor list (lato endpoint) e roamswitch-sensor list (lato Sensor) che ciascuno riconosca l'altro.

D5. Sensor può essere utilizzato insieme a RoamSwitch stesso (Client/Server Edition)?

Sì. Poiché Sensor è progettato senza funzioni di autodifesa, si consiglia di eseguire anche RoamSwitch for Linux Server Edition sulla stessa macchina. I due funzionano con processi e archivi dati completamente indipendenti, senza conflitti.

D6. roamswitch sensor results segnala che l’abbinamento è stato revocato.

L’abbinamento di questo endpoint è stato rimosso sul lato Sensor con unpair. Chiedere all’operatore del Sensor di rilasciare un nuovo codice di abbinamento, quindi riabbinare con roamswitch sensor pair --addr <ip> --code <code>.

11. Funzioni di audit per le organizzazioni (opzionali)

Un insieme di funzioni per i team di sicurezza delle grandi organizzazioni che hanno bisogno di evidenze di audit e di un quadro chiaro di ciò che è cambiato. Tutte sono disattivate per impostazione predefinita e non viene mai inviato nulla a Lafine né a terzi: ogni destinazione di notifica o aggregazione è scelta dalla vostra organizzazione. Le impostazioni si modificano con sudo roamswitch-sensor config set <chiave> <valore> (senza riavviare il demone; ogni modifica viene registrata nel registro delle operazioni); config show mostra i valori correnti.

11.1 Audit pianificati e rilevamento delle variazioni

Impostando schedule.enabled su true, tutti gli endpoint abbinati vengono sottoposti ad audit automaticamente (ogni 24 ore per impostazione predefinita: schedule.interval_hours; fascia oraria locale in cui un audit può iniziare: schedule.window_start_hour / window_end_hour, anche a cavallo della mezzanotte; parallelismo: schedule.max_parallel). Ogni audit viene confrontato con il precedente e roamswitch-sensor diff mostra i nuovi rilevamenti (regressioni), quelli risolti e le porte appena aperte. Se tutte le porte prima aperte diventano improvvisamente invisibili, il caso è segnalato come probabilmente irraggiungibile, non come «risolto»: un host spento non si distingue dall'esterno da uno che ha chiuso tutte le porte.

Gli audit non presidiati non intaccano la garanzia che vengano sottoposti ad audit solo gli endpoint consenzienti. L'IP di un endpoint può essere assegnato a un altro dispositivo dal DHCP; il Sensor memorizza quindi il MAC che l'endpoint aveva all'ultima autenticazione (abbinamento o richiesta di audit firmata) e verifica, prima e dopo ogni audit pianificato, con una vera richiesta ARP di nmap che a quell'IP risponda ancora lo stesso MAC. In caso contrario l'audit viene saltato (o il suo risultato scartato) e viene inviata una notifica. Anche uno scan manuale viene rifiutato se vi sono indizi che l'indirizzo appartenga ormai a un altro dispositivo. Il controllo richiede nmap; gli endpoint abbinati prima di questa funzione non vengono pianificati finché non si riabbinano o inviano una richiesta di audit firmata; sono coperti solo gli endpoint dello stesso segmento L2.

11.2 Notifiche (webhook e syslog)

Regressioni, nuovi dispositivi, ARP spoofing, traffico sospetto e altro vengono inviati a notify.webhook_urls (webhook in ingresso di Slack, Discord o Teams, oppure qualsiasi endpoint JSON generico) e a notify.syslog.host / port / protocol (RFC 5424 su UDP o TCP). Si possono restringere con notify.min_severity (info / medium / high / critical) e notify.cooldown_minutes (intervallo minimo prima di reinviare lo stesso evento). roamswitch-sensor notify-test verifica ogni destinazione.

11.3 Esportazione delle evidenze di audit

roamswitch-sensor export <scans|inventory|audit-log|all> --format csv|json|html [--out file] [--endpoint prefisso-chiave] [--since data]. L'output html è un unico file autonomo: aprilo in un browser e scegli «Salva come PDF» per ottenere un PDF da consegnare ai revisori. Il CSV è protetto dall'iniezione di formule nei fogli di calcolo. L'esportazione dell'inventario dei dispositivi include una colonna che indica se ciascun dispositivo è gestito da RoamSwitch (abbinato). I file prodotti sono leggibili solo dal proprietario (0600) e l'esportazione stessa viene registrata nel registro delle operazioni.

11.4 Registro di operazioni e approvazioni (a prova di manomissione)

Abbinamento, rimozione dell'abbinamento, avvio e completamento degli audit, modifiche di configurazione e accessi rifiutati vengono registrati insieme a chi li ha eseguiti (UID / chiave pubblica dell'endpoint / IP di origine). Ogni riga contiene lo SHA-256 della precedente, quindi qualsiasi modifica o cancellazione viene rilevata da roamswitch-sensor audit-log verify (codice di uscita 2 in caso di problemi). L'elenco si ottiene con roamswitch-sensor audit-log [--limit N]. Gli URL dei webhook contengono spesso un token, perciò il registro delle modifiche di configurazione non ne conserva mai i valori. Una catena di hash da sola non rivela che le voci più recenti siano state troncate; per questo la testa della catena (numero di sequenza e hash) viene inviata anche al collector (§11.6).

11.5 Conservazione

Impostate retention.scan_history_days, retention.audit_log_days e retention.inventory_stale_days per eliminare automaticamente la cronologia degli audit, le voci del registro e i dispositivi non visti da tempo (0 = nessuna eliminazione per età, valore predefinito). I dispositivi con una nota non vengono mai rimossi dall'inventario.

11.6 Aggregare più Sensor (collector centrale, opzionale)

Quando più Sensor operano in più sedi, eseguite roamswitch-sensor-collector (incluso nel pacchetto, disattivato per impostazione predefinita) su un host separato per raccogliere i riepiloghi firmati di ciascuno.

# On the collector host (a separate host from the Sensor is recommended)
sudo systemctl enable --now roamswitch-sensor-collector   # listens on 127.0.0.1:8443 by default
sudo roamswitch-sensor-collector token                     # read token for the dashboard
sudo roamswitch-sensor-collector enroll <Sensor public key> --name Tokyo --site Tokyo

# On each Sensor
sudo roamswitch-sensor config set collector.url https://collector.example.org:8443
sudo roamswitch-sensor config set collector.enabled true

• Vengono accettate solo richieste firmate (Ed25519) dei Sensor registrati (enroll); il timestamp respinge inoltre i replay.
• TLS è obbligatorio ogni volta che il servizio è raggiungibile dall'esterno della LAN. Indicate --bind 0.0.0.0:8443 --tls-cert … --tls-key … in COLLECTOR_ARGS di /etc/default/roamswitch-sensor-collector, oppure usate --allow-plain-http dietro un reverse proxy che termina TLS. L'ascolto su un indirizzo diverso da 127.0.0.1 senza TLS viene rifiutato all'avvio.
• La dashboard è protetta da un token e offre filtro per sede, eventi per gravità ed esportazione CSV. Evidenzia i Sensor che non rispondono più e quelli il cui registro di audit sembra troncato, riportato indietro o biforcato (da rimuovere con clear-anomaly <chiave-pubblica> dopo l'indagine).