ROAMSWITCH SERVER 1.1.0+ · Ultimo aggiornamento: 2026-09-18

Manuale operativo di RoamSwitch Server Edition

Installazione, distribuzione e riferimenti operativi ufficiali per Cloud VPS (AWS, GCP, Azure, Linode, DigitalOcean), data center bare metal e host container.

1. Panoramica e requisiti

RoamSwitch Server Edition è una suite di difesa autonoma e monitoraggio dell'integrità headless (zero dipendenze GUI) progettata per server Linux esposti a Internet pubblico.

A differenza dell'edizione client che cambia dinamicamente i profili in base allo stato Wi-Fi, l'edizione server applica Inbound Default Drop, monitoraggio dell'integrità dei file (FIM) del percorso critico, mitigazione LPE preventiva del kernel (Frag Gap), rilevamento delle minacce runtime eBPF, prevenzione del blocco SSH e avvisi di emergenza multicanale automatizzati (Telegram / LINE / Webhook).

Architettura di telemetria zero
RoamSwitch trasmette zero telemetria diagnostica, metadati IP dell'host, hash di file o registri di sistema a server esterni. Le librerie di rete esterne sono assenti dal binario del daemon, garantendo la completa riservatezza locale.

Requisiti di sistema

2. Procedure di installazione

L'utilizzo dei repository ufficiali firmati garantisce la risoluzione automatica delle dipendenze e aggiornamenti continui tramite il gestore di pacchetti di sistema standard.

2.1 APT (sistema operativo Ubuntu/Debian/Raspberry Pi)

# 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 [arch=amd64,arm64 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-server

2.2 DNF/RPM (Fedora/RHEL/AlmaLinux/Rocky Linux)

# 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-server

2.3 openSUSE (zypper)

sudo rpm --import https://lafine.net/rpm/RPM-GPG-KEY-roamswitch
sudo zypper addrepo https://lafine.net/rpm/opensuse/roamswitch.repo
sudo zypper refresh && sudo zypper install roamswitch-server
Pacchetto Mutua Esclusione (Conflitti)
L'edizione Client (roamswitch) e l'edizione Server (roamswitch-server) dichiarano conflitti di pacchetti reciproci. Seleziona sempre roamswitch-server negli ambienti server headless.

3. Configurazione iniziale e verifica del servizio

3.1 Stato del servizio

Dopo l'installazione, roamswitch-server.service si avvia immediatamente e viene abilitato all'avvio del sistema.

sudo systemctl status roamswitch-server.service

3.2 Procedura guidata di configurazione interattiva

Eseguire la procedura guidata di configurazione interattiva con il comando seguente per configurare in modo interattivo porte, IP di origine per la manutenzione, canali di notifica e azione di contenimento (premere Invio per accettare ciascun valore predefinito).

sudo roamswitch server setup
  1. Porte: inserire le porte di manutenzione SSH (predefinita 22) e le porte dei servizi pubblici (predefinite 80,443), separate da virgole.
  2. IP di origine per la manutenzione: specificare gli IP/CIDR del bastion SSH o di monitoraggio (es. 203.0.113.50/32); lasciare vuoto per consentire SSH da qualsiasi IP.
  3. Canali di notifica: abilitare bot Telegram, API di messaggistica LINE e/o un webhook generico (Slack / Discord / Teams).
  4. Risposta a un evento eBPF critico: scegliere isolate (isola l'host), freeze (blocca il processo) o alert_only (solo notifica). Dopo il salvataggio, viene chiesto di inviare una notifica di prova e riavviare il servizio.
  5. Aggiornamenti automatici dei dati CVE del kernel (predefinito n): scegliere se recuperare in modo anonimo, una volta al giorno da lafine.net, il database delle CVE del kernel usato dall'audit di isolamento dei container (senza query string, cookie o intestazioni identificative). Se lasciato disattivato, l'audit continua comunque a funzionare sulla baseline integrata. È l'unica eccezione alla politica zero-network-code di Server Edition ed è disattivato per impostazione predefinita (opt-in).
  6. Impostazioni di File Scan Guard: scegliere se abilitare la scansione antivirus per relay di posta, cartelle condivise e destinazioni di caricamento (§13) e impostare le directory di destinazione. Opzionale, disattivato per impostazione predefinita.
  7. Impostazioni di Resource Guard: abilitare la protezione da esaurimento delle risorse che rileva una crescita costante della RSS (memory leak/DoS) o cicli di crash nei servizi esposti in rete.
  8. Panoramica delle protezioni principali sempre attive: mostra le difese principali che funzionano sempre indipendentemente dalla procedura guidata — drop predefinito in ingresso, FIM, integrazione eBPF, ecc. (nessun input richiesto).
  9. Impostazioni di delega all'agente investigativo (investigation): scegliere se delegare automaticamente l'indagine preliminare — per eventi eBPF critici, o rilevamenti di manomissione di FIM Critical-Path/file di lock delle dipendenze, quando classificati come solo notifica — a una CLI di agente IA esterno (Claude Code / agy / Codex CLI / OpenCode, o un comando personalizzato) (§10.1). Disattivato per impostazione predefinita.
Nota sull'ID chat di Telegram
L'ID chat di un supergruppo è un numero negativo che inizia con -100 (es. -1001234567890). Verificare il valore corretto nel campo "chat":{"id":...} della risposta di curl -s "https://api.telegram.org/bot<token>/getUpdates".

3.3 Controllo di sicurezza del server in 30 elementi

sudo roamswitch status --server

Esegue un audit istantaneo di 30 controlli delle regole del firewall, della mitigazione del Frag Gap, delle restrizioni Yama LSM, delle autorizzazioni e dell'esposizione delle porte Docker, producendo un punteggio e un grado di sicurezza compreso tra 0 e 100 (da S a C).

4. Regole firewall e porte

Il file di configurazione /etc/roamswitch/server.conf richiede obbligatoriamente i permessi 0600 (lettura/scrittura solo per root) per proteggere le informazioni sensibili. Il formato è chiave=valore piatto; le intestazioni di sezione come [network] vengono ignorate.

# --- Firewall ---
ssh_ports=22                     # Porta di gestione SSH (mantenuta anche durante l'isolamento di emergenza)
allowed_ports=80,443             # Porte dei servizi pubblici
whitelist_ips=203.0.113.10/32    # IP/CIDR di origine per la manutenzione (vuoto = consenti tutto, in passato admin_source_ips)
protect_docker_ports=true        # Protezione DOCKER-USER (impedisce ai container di aggirare il firewall)
preserve_ssh_on_isolation=true   # Mantiene il percorso di gestione SSH anche durante l'isolamento di emergenza (false = blocco totale)

# --- Guardia di runtime eBPF ---
action_on_critical=isolate       # isolate | freeze (SIGSTOP+blocco rete) | alert_only
ebpf_socket_path=/run/roamswitch/events.sock

# --- Blocco Egress/C2 e DNS sinkhole ---
egress_ip_blocklist_enabled=true # Predefinito true. Innocuo finché non viene popolato un feed (non blocca nulla)
dns_sinkhole_enabled=false       # Predefinito false (per non compromettere DNS interni/configurazioni split-horizon)
dns_sinkhole_provider=quad9      # quad9 | cloudflare | adguard | cleanbrowsing

# --- Dati CVE di isolamento container (opt-in) ---
cve_kernel_map_updates_enabled=false # Predefinito false. L'unica eccezione di comunicazione esterna (una volta al giorno, anonima)

# --- Notifiche ---
telegram_enabled=false
telegram_bot_token=
telegram_chat_id=
line_enabled=false
webhook_enabled=false
webhook_url=

# --- Sistema ---
language=ja
fim_check_interval_secs=300      # In precedenza chiamato scan_interval

Dopo aver modificato il file direttamente, riavviare il servizio per applicare le modifiche (roamswitch-server non supporta il reload):

sudo roamswitch server restart

4.1 Policy per livello di gravità (guard.yaml, opzionale)

Se action_on_critical da solo non offre sufficiente granularità, creare /etc/roamswitch/guard.yaml (un modello è disponibile in /etc/roamswitch/guard.yaml.example). Se assente, viene sintetizzata automaticamente una policy equivalente a partire da action_on_critical in server.conf, senza impatti sulle installazioni esistenti.

policies:
  on_warning:
    action: log_and_notify
  on_critical:
    server_action: isolate_process
    kill_process: true
    fallback_to_host_isolation_after_retries: 3   # Passa automaticamente all'isolamento dell'host se lo stesso processo si ripresenta
  on_emergency:
    action: isolate_host_all
    kill_process: true

server_safeguards:
  maintenance_ssh_ports: [22]
  safety_timer_secs: 300   # Ripristina automaticamente dopo questi secondi dall'isolamento se non arriva alcun ack (0 disabilita)

Timer di sicurezza: una volta attivato un isolamento dell'host (Air-Gap), l'amministratore indaga e poi lo conferma con il comando seguente. Se non arriva conferma entro safety_timer_secs, RoamSwitch ripristina automaticamente l'accesso di rete affinché un falso positivo non lasci il server isolato a tempo indeterminato.

sudo roamswitch server ack

4.2 Blocco Egress/C2 e DNS sinkhole

Con egress_ip_blocklist_enabled=true (predefinito), le connessioni in uscita verso IP noti come malevoli vengono bloccate tramite nftables. Viene usato prima il feed in /var/lib/roamswitch/threatfeed/malicious_ips.txt (gestito dal meccanismo di aggiornamento), con fallback sul seed vuoto incluso nel pacchetto (/usr/share/roamswitch/threatfeed/) — quindi finché non viene popolato un feed, il valore predefinito true non blocca nulla.

Impostare dns_sinkhole_enabled=true forza la risoluzione tramite un resolver DNS di filtraggio (Quad9 / Cloudflare / AdGuard / CleanBrowsing), bloccando la risoluzione di domini noti come malevoli. È disattivato (false) per impostazione predefinita poiché può interferire con DNS interni o configurazioni split-horizon.

4.3 Protezione di rilevamento delle scansioni delle porte in ingresso

Rileva gli IP di origine che si sono connessi a numerose porte distinte in breve tempo, correlando le regole di log di nftables con journald (abilitato per impostazione predefinita). Le fonti di scansione ad alta affidabilità possono essere bloccate automaticamente per una durata prestabilita. Se utilizzato insieme a RoamSwitch Sensor (una funzione diversa dal §10.1 — le sonde di controllo completo delle porte di un Sensor associato vengono escluse come mitigazione dei falsi positivi), l'IP dello stesso Sensor viene escluso automaticamente.

# --- Rilevamento delle scansioni delle porte in ingresso (abilitato per impostazione predefinita) ---
port_scan_detect_enabled=true              # false per disattivare
port_scan_detect_min_distinct_ports=15     # Considerato una scansione quando le connessioni raggiungono questo numero di porte distinte
port_scan_detect_window_secs=300           # Finestra di aggregazione per il rilevamento (secondi)
port_scan_block_enabled=true               # Blocca automaticamente l'IP di origine della scansione rilevata
port_scan_block_duration_secs=600          # Durata del blocco automatico (secondi)

È possibile consultare la cronologia di rilevamento con il comando roamswitch port-scan.

5. Failsafe di prevenzione del blocco SSH

Il blocco accidentale tramite un'errata configurazione del firewall è un disastro operativo intollerabile. RoamSwitch Server Edition incorpora protezioni a più livelli:

6. Protezione del contenitore (Docker/Podman)

Il comportamento predefinito di Docker crea regole iptables personalizzate che aggirano i firewall host standard, esponendo le porte del contenitore (ad esempio -p 8080:8080) direttamente a Internet.

Quando protect_docker_ports=true (predefinito), RoamSwitch inserisce regole di ispezione in testa alla catena DOCKER-USER, così che il traffico diretto ai container rispetti anche la policy di allowed_ports e whitelist_ips, prevenendo in modo affidabile l'esposizione accidentale di, ad esempio, container di database di sviluppo.

Inoltre, una protezione in tempo reale monitora gli docker events e avvisa nel momento in cui un container viene avviato con --privileged o con un bind-mount di /var/run/docker.sock — un rischio di fuga dal container. Non richiede configurazione, è sempre attiva e si limita a notificare (nessun blocco automatico).

7. Monitoraggio dell'integrità dei file del percorso critico (FIM)

Monitora oltre 150 file binari essenziali (/bin/login, /usr/bin/sudo, /usr/sbin/sshd), configurazioni di autenticazione (/etc/shadow, /etc/pam.d/) e unità systemd utilizzando hash SHA-256.

7.1 Verifica manuale dell'hash

sudo roamswitch fim verify

7.2 Rilevamento basato su eventi (istantaneo)

I file monitorati vengono osservati singolarmente tramite fanotify (FAN_CLASS_NOTIF, eventi di scrittura completata), così una manomissione viene ri-sottoposta a hash e rilevata nell'istante in cui avviene, senza attendere la scansione periodica successiva. La scansione periodica (predefinita fim_check_interval_secs=300 secondi) resta come backstop per eventuali eventi non intercettati.

7.3 Sincronizzazione automatica di base sugli aggiornamenti del sistema operativo

Su Debian/Ubuntu, l'installazione dei pacchetti configura automaticamente l'hook DPkg::Post-Invoke in /etc/apt/apt.conf.d/99roamswitch-fim. Su Fedora/RHEL/Rocky/AlmaLinux/openSUSE, un'unità systemd.path (roamswitch-fim-update.path) che monitora /var/lib/rpm svolge lo stesso ruolo.

Su Debian/Ubuntu, /etc/apt/apt.conf.d/99roamswitch-fim collega un hook DPkg::Post-Invoke. Gli aggiornamenti legittimi dei pacchetti tramite sudo apt upgrade aggiornano automaticamente la baseline FIM, eliminando gli avvisi di falsi positivi.

sudo roamswitch fim update

8. eBPF Runtime Guard e integrazione Falco

Si collega agli eventi eBPF dello spazio kernel (Falco/Tetragon) per rilevare l'escalation dei privilegi del kernel Frag Gap, gli escape dei contenitori e le shell inverse non autorizzate.

8.1 Architettura anti-gonfiamento

Gli agenti di sicurezza tradizionali soffrono di gravi esplosioni di syslog e di usura del disco. RoamSwitch si connette direttamente a Falco tramite un socket di dominio UNIX dedicato (/run/roamswitch/events.sock):

8.2 Contenimento autonomo

Dopo aver rilevato un attacco critico, RoamSwitch emette immediatamente SIGSTOP per congelare il PID del processo offensivo e applica l'isolamento Air-Gap di nftables.

9. Avvisi di emergenza (Telegram / LINE / Webhook)

Invia avvisi immediati a canali di notifica esterni quando si verificano anomalie delle porte, manomissioni FIM o eventi di contenimento eBPF:

[notifications]
language = ja
# Telegram: token del bot e ID chat
telegram_bot_token = "123456789:ABCdefGHIjklMNOpqrSTUvwxYZ"
telegram_chat_id = "-1001234567890"

# LINE: token di accesso al canale Messaging API e ID utente
line_channel_access_token = "YOUR_LINE_ACCESS_TOKEN"
line_user_id = "U1234567890abcdef1234567890abcdef"

# Webhook generico (Slack, Discord, Teams, la propria piattaforma di monitoraggio)
webhook_url = "https://hooks.slack.com/services/T00/B00/XXXXX"

Anche senza configurare questi canali esterni, ogni avviso inviato viene comunque conservato localmente per gli ultimi 7 giorni. Consultalo con roamswitch notifications.

10. Integrazione agente AI/MCP (protocollo contesto modello)

RoamSwitch Server Edition include roamswitch-mcp, consentendo agli agenti AI (Claude, Gemini, Cursor) di monitorare l'integrità e la postura dell'infrastruttura.

Garanzia di sicurezza di sola lettura
Per evitare che attacchi di tipo "pronto-iniezione" compromettano l'infrastruttura, l'interfaccia MCP è rigorosamente di sola lettura. Gli agenti AI non possono aprire porte, rimuovere l'isolamento o alterare le configurazioni di sicurezza tramite MCP. La correzione richiede l'accesso autenticato alla shell TTY locale.

Esempio di configurazione (`claude_desktop_config.json`)

{
  "mcpServers": {
    "roamswitch": {
      "command": "/usr/bin/roamswitch-mcp",
      "args": []
    }
  }
}

10.1 Delega all'agente investigativo (investigation — delega dell'indagine automatizzata preliminare a un agente IA)

Mentre roamswitch-mcp del §10 gestisce le query provenienti dal client IA di un essere umano, la delega investigation è un meccanismo separato in cui il demone stesso avvia autonomamente una CLI di agente IA esterno, attivata da un evento di rilevamento. Riguarda gli eventi eBPF critici classificati come solo notifica (che non hanno attivato l'isolamento automatico o il blocco del processo), oltre ai rilevamenti di manomissione di FIM Critical-Path e file di lock delle dipendenze. Una volta abilitata, il demone genera prima un report di triage preliminare euristico locale (probabilità di falso positivo, motivazione, prossimi passi suggeriti), quindi avvia la CLI di agente IA configurata come sottoprocesso con tale report allegato, delegando ulteriori indagini e riepilogo. Disattivato per impostazione predefinita.

# Da aggiungere a /etc/roamswitch/guard.yaml (un file separato da server.conf)
investigation:
  enabled: true
  command: "claude"                 # "claude" | "agy" | "codex" | "opencode" | qualsiasi comando personalizzato
  args: ["-p"]                      # Il prompt viene aggiunto automaticamente come ultimo argomento
  timeout_secs: 180

Le stesse impostazioni possono essere configurate anche dalla procedura guidata interattiva di sudo roamswitch server setup (§3.2, ultimo passaggio). Scegliere tra i preset per Claude Code (claude -p), agy (agy -p --dangerously-skip-permissions), Codex CLI (codex exec), OpenCode (opencode run), oppure un comando personalizzato. In una nuova esecuzione, il preset corrispondente viene selezionato automaticamente in base alla configurazione salvata.

Nota sull'iniezione di prompt
La delega investigation trasmette i dettagli dell'evento di rilevamento — nomi di processo, percorsi di file e altre stringhe che un aggressore potrebbe controllare parzialmente — come parte del prompt inviato all'agente IA. Configurare lo strumento per l'esecuzione in una modalità che salta i controlli dei permessi, come --dangerously-skip-permissions, aumenta il rischio che un input malevolo induca l'agente a compiere azioni non volute. La procedura guidata mostra questo avviso quando si seleziona agy. Negli ambienti con un percorso di input dei log non attendibile, si consiglia una configurazione dello strumento che non salti i controlli dei permessi.

La delega investigation non viene mai richiamata mentre la rete è isolata (ad esempio durante un Air-Gap attivo, o qualsiasi stato equivalente a isolate_host_all).

11. Foglio informativo dei comandi CLI

Comando Privilegi Descrizione
sudo roamswitch status --server root Visualizza il punteggio relativo alla postura del server di 30 elementi e controlla la suddivisione
sudo roamswitch ports root Controlla le porte di ascolto aperte e i processi associati
sudo roamswitch fim verify root Verificare l'integrità SHA-256 dei file di sistema del percorso critico
roamswitch notifications Utente Mostra la cronologia delle notifiche (tutti gli avvisi inviati) degli ultimi 7 giorni
sudo roamswitch server setup root Avvia la procedura guidata di configurazione iniziale interattiva
sudo roamswitch fim update root Aggiorna il database di base FIM SHA-256
sudo roamswitch server config set <key> <value> root Modifica e salva una singola chiave di configurazione (elenco al §4)
sudo roamswitch airgap enable / disable root Attiva/disattiva manualmente il blocco di emergenza Air-Gap
sudo roamswitch emergency-restore Radice Disattiva completamente l'isolamento eBPF/firewall e ripristina la baseline iniziale
roamswitch port-scan Utente Mostra la cronologia di rilevamento della protezione di rilevamento delle scansioni delle porte in ingresso (§4.3) (IP di origine, se bloccato automaticamente e durata del blocco)
roamswitch sensor [key|list|pair|unpair|request-audit|results] Utente/root Fiducia reciproca tramite codice di abbinamento con RoamSwitch Sensor. pair --addr <ip> --code <code> per abbinarsi, request-audit per richiedere un controllo attivo delle vulnerabilità (recuperare il risultato con results). Richiede sensor_pairing_enabled: true (disattivato per impostazione predefinita). Per i dettagli vedere il Manuale Operativo di Sensor

12. Risoluzione dei problemi e domande frequenti

Q1. RoamSwitch disconnetterà inaspettatamente la mia sessione SSH?

No. RoamSwitch consente incondizionatamente gli stati di connessione ESTABLISHED/RELATED e le ssh_ports (predefinita 22). Anche durante un isolamento di emergenza Air-Gap scatenato da un attacco grave, preserve_ssh_on_isolation=true (predefinito) mantiene attiva la sessione amministrativa.

Q2. Come posso riottenere l'accesso se bloccato accidentalmente?

Accedere tramite la console web del proprio provider cloud (VNC / console seriale) ed eseguire sudo roamswitch emergency-restore per disattivare l'isolamento, oppure sudo systemctl stop roamswitch-server per arrestare il servizio.

Q3. Come posso esporre le porte per i servizi web appena aggiunti (ad esempio Nginx)?

Eseguire sudo roamswitch server config set allowed_ports 80,443,3000 (oppure modificare direttamente /etc/roamswitch/server.conf), quindi sudo roamswitch server restart.

13. File Scan Guard (protezione di relay di posta, cartelle condivise e endpoint di upload)

Funzionalità opzionale rilevante solo se questo host dispone di una directory che conserva file destinati ad altri: un relay di posta, una condivisione Samba/NFS, un endpoint di upload di file. Il motore YARA integrato analizza sempre clamav_scan_dirs senza dipendenze esterne; impostando clamav_enabled=true si aggiunge ClamAV come seconda opinione. Le minacce confermate vengono automaticamente messe in quarantena in /var/lib/roamswitch/quarantine e l'operatore viene notificato.

# --- File Scan Guard (ClamAV, opt-in) ---
# Il motore YARA integrato analizza sempre clamav_scan_dirs incondizionatamente.
clamav_enabled=false             # true abilita il controllo aggiuntivo tramite clamdscan
clamav_scan_dirs=                # Percorsi assoluti da analizzare (separati da virgola)
clamav_scan_interval_secs=86400  # Intervallo di scansione (secondi, minimo 3600)
clamav_freshclam_interval_secs=7200  # Intervallo di aggiornamento automatico del database delle firme (secondi, minimo 1800)

Configurabile anche tramite la procedura guidata interattiva sudo roamswitch server setup; è possibile verificarne la configurazione e lo stato della quarantena con lo strumento MCP get_file_scan_guard_status.

14. Log Audit (rilevamento e notifica delle anomalie nei pattern dei log)

Una scansione periodica di journalctl trasforma i messaggi di log in modelli per rilevare pattern nuovi (forme di log mai viste prima) e anomalie di frequenza (un picco statistico, Z-score > 3.0). Si tratta di un meccanismo leggero che non richiede alcun daemon aggiuntivo né dipendenze esterne, quindi è abilitato per impostazione predefinita. Le rilevazioni vengono inviate tramite gli stessi canali di notifica di File Scan Guard e FIM (Telegram / LINE / Webhook). Eventuali chiavi API o token che potrebbero comparire in una riga di log vengono mascherati automaticamente prima di essere inclusi nella notifica.

# --- Log Audit (abilitato per impostazione predefinita) ---
log_audit_enabled=true           # false per disabilitare
log_audit_interval_secs=1800     # Intervallo di scansione in secondi (minimo 300)

Può anche essere configurato dalla procedura guidata interattiva sudo roamswitch server setup, e i risultati di rilevamento più recenti possono essere consultati tramite il comando CLI roamswitch audit-logs o lo strumento MCP audit_security_logs.

← Whitepaper di Server Edition Alla pagina di installazione Linux →