ROAMSWITCH SERVER · Ultimo aggiornamento: 2026-10-24

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 autonoma di protezione della sicurezza e dell'integrità, completamente headless (nessuna dipendenza da GUI), per i server Linux costantemente esposti a Internet.

A differenza dell'edizione client, che cambia profilo in base alla rete Wi-Fi a cui ci si connette, l'edizione server ha come funzioni centrali «blocco predefinito del traffico in ingresso (Default Drop)», «monitoraggio delle manomissioni dei percorsi critici (FIM)», «blocco preventivo della LPE del kernel (Frag Gap)», «monitoraggio delle minacce runtime con eBPF», «failsafe contro il blocco di SSH» e «allarmi di emergenza autonomi verso Telegram / LINE / Webhook».

Principio Zero Telemetry (nessuna informazione su di te viene inviata; l'unica comunicazione esterna predefinita è la ricezione di dati firmati)
RoamSwitch non invia gli indirizzi IP, le informazioni sulle porte, gli hash dei file, i log di sistema né i risultati diagnostici del server a fornitori o cloud. Il daemon non include alcun client TLS / HTTP.

Esclusi gli aggiornamenti dei pacchetti, l'unico traffico in uscita predefinito è il recupero anonimo di dati firmati (cve_kernel_map_updates_enabled, attivo per impostazione predefinita). Riceve da lafine.net, tramite HTTPS GET, dati CVE firmati con Ed25519, regole web, KEV, EPSS e altro (manifest e KEV ogni giorno, dati CVE una volta a settimana). Non ci sono query string né cookie, e non viene inviata alcuna informazione sull'host oltre al User-Agent: RoamSwitch-Updater fisso. Se lo si disattiva, gli audit funzionano comunque con la baseline integrata, ma la corrispondenza CVE dei pacchetti del sistema Ubuntu mostra «dati CVE non recuperati».

Tutto il resto avviene solo se l'operatore lo attiva: notifiche (Telegram / LINE / Webhook), verifica delle firme npm, controlli DNS e RDAP dei propri domini (domain_check_domains), inoltro degli eventi a una destinazione della propria organizzazione (forward_enabled, disattivato per impostazione predefinita), abbinamento del Sensor, integrazione LLM di accessscope (solo con --llm) e mappa firmata delle dipendenze dei linguaggi (package_cve_map_languages_enabled, settimanale, solo ricezione). L'elenco delle eccezioni è nella sezione Zero Telemetry del documento di progettazione della sicurezza della Server Edition.

Requisiti di sistema

2. Procedure di installazione

Con il repository di pacchetti ufficiale e firmato, le dipendenze vengono risolte automaticamente e si può aggiornare in modo sicuro e automatico con il comando di aggiornamento del sistema.

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

Su Fedora, RHEL, AlmaLinux e Rocky Linux con SELinux attivo, l'installazione assegna initrc_exec_t al daemon (/usr/lib/roamswitch/roamswitch-server-daemon) e lo esegue con i privilegi di initrc_t. Senza l'etichetta viene eseguito come init_t e la lettura di authorized_keys e simili viene negata. Se semanage è presente, la regola persiste; altrimenti si usa solo chcon, quindi dopo una rietichettatura reinstallare il pacchetto. Il contesto si verifica con sudo ps -eZ | grep roamswitch-serv.

Pacchetto Mutua Esclusione (Conflitti)
L'edizione client (roamswitch) e l'edizione server (roamswitch-server) sono dichiarate reciprocamente esclusive (Conflicts) nei metadati del gestore di pacchetti, per evitare un'installazione doppia sullo stesso host. Per l'uso su server, specificare sempre roamswitch-server.

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

La prima volta, esegui poi sudo roamswitch server setup. Fino ad allora l'origine di manutenzione SSH, i canali di notifica, agent_users e le destinazioni della scansione dei file non sono impostati.

Quando il pacchetto viene aggiornato, il timer di aggiornamento (roamswitch-update.timer) viene attivato se è disattivato e se server.conf non ha disattivato gli aggiornamenti. Sulle macchine con gli aggiornamenti disattivati resta fermo.

3.2 Procedura guidata di configurazione interattiva

Con il comando seguente si avvia la configurazione guidata, che imposta in modo interattivo porte, IP di origine per la manutenzione, destinazioni delle notifiche e comportamento di contenimento (Invio per accettare il 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: IP o CIDR di un bastion SSH o del monitoraggio (ad es. 203.0.113.50/32). La procedura guidata richiede una risposta e non accetta un valore vuoto. Per consentire SSH da qualsiasi origine, digita ANYWHERE (in tal caso il percorso SSH di amministrazione resta aperto a tutto il mondo anche durante l'isolamento).
  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. Aggiornamento automatico dei dati CVE (predefinito y): scegliete se il database delle CVE del kernel usato dall’audit di isolamento dei container, le regole web, l'elenco KEV, i punteggi EPSS, i dati sulle vulnerabilità di Node.js e, sui server Ubuntu, i dati CVE dei pacchetti Ubuntu usati dal controllo CVE dei pacchetti di sistema vengano scaricati in forma anonima da lafine.net (il manifest firmato viene controllato ogni giorno, i dati CVE veri e propri circa una volta a settimana, l'elenco KEV ogni giorno e le regole web solo quando il manifest ha una versione più recente; solo HTTPS GET, senza query string né cookie, con uno User-Agent: RoamSwitch-Updater fisso come unico header che nomina il software, con firma Ed25519 verificata). Non viene inviato nulla su questo host. È l’unica comunicazione esterna attiva per impostazione predefinita nella Server Edition; rispondere n la ferma (l’audit stesso continua a funzionare con la baseline integrata, ma il controllo CVE dei pacchetti di sistema su un server Ubuntu segnalerà allora «nessun dato CVE locale»). Se è già disattivata in un server.conf esistente, anche la risposta predefinita resta n.
  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.

I passaggi successivi della procedura guidata controllano la situazione prima di porre le domande e segnalano ciò che manca.

Alla fine della procedura guidata mostra i comandi di verifica. Nell'edizione Server roamswitch guards non è disponibile, quindi verifica con i comandi seguenti.

sudo roamswitch status --server
sudo roamswitch doctor
sudo roamswitch detection-coverage
sudo roamswitch server config show
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 42 elementi

sudo roamswitch status --server

Esegue un audit istantaneo di 42 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). L'audit comprende anche il daemon.json di Docker (user namespace, icc, live-restore, no-new-privileges, ascolto TCP senza TLS; non applicabile sugli host senza Docker), l'ultima esecuzione del backup (oltre 7 giorni è un errore; non si verifica se il backup è ripristinabile) e la scadenza dei certificati TLS realmente serviti dal server web (meno di 30 giorni è un errore). La voce sull'esposizione della risoluzione dei nomi (server_name_resolution_exposure) non viene superata quando questo host funziona come risponditore LLMNR (UDP 5355) o NBNS (UDP 137). mDNS (UDP 5353) viene solo mostrato. 42 è il numero delle voci fisse; a seconda dell'host si aggiungono voci come l'effettivo funzionamento di ogni protezione. Le voci non applicabili sono escluse dal punteggio.

Vulnerabilità ad alta probabilità di sfruttamento (software installato) (server_package_cve_exposure). Confronta i pacchetti del sistema, il PHP presente nel PATH e altrove e i server GitLab con i dati sulle vulnerabilità presenti sul computer, cercando quelle non corrette che sono in KEV o hanno un EPSS pari o superiore a 0,9 (nessuna comunicazione di rete). Gli altri software fuori dalla gestione dei pacchetti e le vulnerabilità assenti dai dati non sono visibili. Nella diagnosi oraria viene inviato un avviso (con nome host e IP) quando una voce fallisce per la prima volta, compare un nuovo indicatore KEV o lo stato resta invariato per 24 ore. Non si notifica il ritorno a «superato».

Ogni voce di controllo è contrassegnata con la funzione/categoria del NIST CSF 2.0 (sempre, dove applicabile) per l'uso nei rapporti di conformità. I numeri dei controlli CIS Controls v8 sono aggiunti solo quando esiste una corrispondenza ad alta affidabilità.

Header di sicurezza e cookie del server web: richiede dall'host stesso la pagina principale (/) dei siti TLS di nginx, Apache e Caddy ed esamina solo gli header. Controlla HSTS (30 giorni o più), nosniff, la protezione dall'inclusione in frame e Secure e HttpOnly dei cookie; CSP e Referrer-Policy non vengono valutati. Non effettua connessioni esterne e non registra il corpo né i valori dei cookie.

SPF, DMARC, MTA-STS e scadenza dei propri domini: si attiva solo quando si indicano domini (fino a 5) in domain_check_domains. Controlla SPF e DMARC, se SPF consente l'invio a chiunque, se mancano almeno 30 giorni alla scadenza della registrazione e, se c'è un MX, MTA-STS (CAA e DNSSEC sono mostrati solo come riferimento).

La comunicazione esterna avviene solo in questo caso e si limita a queste 3 cose. (1) dig interroga il resolver di /etc/resolv.conf per TXT, CAA, DS e MX. (2) curl individua il registro dall'elenco pubblico dell'IANA (senza il nome di dominio) e invia il nome di dominio al server RDAP di quel registro. (3) curl legge /.well-known/mta-sts.txt sull'host mta-sts del dominio (certificato verificato, redirect non seguiti, senza cookie). I risultati sono memorizzati per 6 ore.

Le protezioni non attive vengono mostrate con il motivo. Si possono verificare con roamswitch detection-coverage, roamswitch doctor e con get_guard_status di MCP (effectiveState e inactiveReason). Escluse quelle dovute allo stato dell'installazione, vengono controllate ogni 5 minuti a partire da 2 minuti dopo l'avvio, e lo stesso motivo viene notificato una volta ogni 24 ore al canale di notifica urgente.

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 (solo TCP. UDP in allowed_udp_ports)
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. Il seed incluso nel pacchetto contiene solo i tre server di attacco pubblicati da JPCERT/CC; nient'altro viene bloccato finché non si installa un feed
metadata_watch_enabled=true      # Predefinito true. Avvisa quando un programma non root/container contatta i metadati cloud (solo registro, non blocca; rileva SSRF)
metadata_watch_allow_users=      # Account che usano legittimamente il servizio di metadati (nomi o id numerici, separati da virgole; root è sempre escluso)
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 (attivi per impostazione predefinita) ---
cve_kernel_map_updates_enabled=true # Predefinito true. L'unica comunicazione esterna attiva per impostazione predefinita (dati CVE del kernel firmati, regole web, l'elenco KEV, i punteggi EPSS, i dati sulle vulnerabilità di Node.js e, sui server Ubuntu, dati CVE dei pacchetti Ubuntu; manifest ogni giorno, dati CVE circa una volta a settimana, l'elenco KEV ogni giorno; anonima, solo ricezione, firma verificata). false la ferma

# --- Notifiche ---
telegram_enabled=false
telegram_bot_token=
telegram_chat_id=
line_enabled=false
webhook_enabled=false
webhook_url=
webhook_block_private_addresses=false   # opt-in SSRF guard
webhook_allow_addresses=

# --- Sistema ---
language=ja
fim_check_interval_secs=300      # In precedenza chiamato scan_interval
isolation_hard_cap_secs=3600     # Secondi prima che un isolamento ad alta affidabilità passi alla modalità DEGRADED (0 = mantieni fino al rilascio)

allowed_ports riguarda solo le porte TCP. L'UDP in ingresso (WireGuard, server DNS e NTP, 443/udp di HTTP/3 e simili) non viene accettato se non lo scrivi in allowed_udp_ports. Esempio: allowed_udp_ports=51820,443. Il valore predefinito è vuoto: tutto l'UDP, tranne le risposte a comunicazioni già stabilite, viene scartato.

Tutte le chiavi forward_* si trovano in /etc/roamswitch/server.conf.example. I valori non validi e le chiavi con errori di ortografia vengono ignorati, e compare un avviso in server config show e altrove. Se esiste /etc/roamswitch/server.json, server.conf non viene letto. Eseguire config show come root.

Se si modificano direttamente le impostazioni, riavviare il servizio per applicarle (roamswitch-server non supporta 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   # Secondi prima che un isolamento a bassa affidabilità venga ripristinato automaticamente (0 lo disattiva). Non si applica agli isolamenti ad alta affidabilità (vedere sotto)

Rilascio automatico dell'isolamento (per affidabilità): per non farsi battere da un attaccante che si limita ad aspettare, i trigger sono divisi per affidabilità. I trigger a bassa affidabilità (eBPF Error / Warning e inferiori, anomalie generiche delle porte, ecc.) vengono ripristinati completamente dopo safety_timer_secs (predefinito 300 secondi). Quelli ad alta affidabilità (manomissione dei canary, riscritture di massa, eBPF Critical / Emergency / Alert, ecc.) vengono rilasciati, con notifica, solo quando si conferma che la causa è scomparsa; se si raggiunge isolation_hard_cap_secs (predefinito 3600 secondi, 0 = nessun limite) senza ack, si passa alla modalità DEGRADED.

La modalità DEGRADED continua a bloccare le nuove comunicazioni diverse dal percorso di gestione e non si apre mai automaticamente con il passare del tempo. Si rilascia solo con una nuova conferma della scomparsa della causa, con un ack o con sudo roamswitch emergency-restore. In ogni isolamento le connessioni già stabilite diverse dal percorso di gestione (maintenance_ssh_ports e whitelist_ips) vengono interrotte, e ogni transizione viene notificata in 10 lingue.

sudo roamswitch server ack

roamswitch server ack riconosce un isolamento FULL mantenendolo rigido (l’operatore se ne è fatto carico, quindi nessun passaggio a DEGRADED e nessun rilascio automatico) e rilascia uno in DEGRADED.

4.2 Blocco Egress/C2 e DNS sinkhole

Con egress_ip_blocklist_enabled=true (predefinito), le connessioni in uscita verso IP malevoli noti vengono bloccate con nftables. L'elenco usa /var/lib/roamswitch/threatfeed/malicious_ips.txt se esiste, altrimenti il seed incluso (l'uno o l'altro). Il seed contiene solo i 3 indirizzi di server di attacco pubblicati da JPCERT/CC il 15 ottobre 2026 (210.149.87.120, 118.26.36.16, 69.10.51.162). Se una destinazione legittima viene bloccata, controllare la riga corrispondente.

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.

Con metadata_watch_enabled (attivo per impostazione predefinita), quando un programma non root o un container si connette per la prima volta a un indirizzo di metadati del cloud (come 169.254.169.254), inet roamswitch_metadata_watch lo registra nel log del kernel e il daemon notifica una volta al giorno per account. Non blocca la comunicazione. Una tecnica che usa un reindirizzamento 302 per puntare verso l'interno non è visibile nei log di accesso e viene rilevata da questo traffico in uscita. L'uso legittimo può essere escluso con metadata_watch_allow_users (non possibile per i container).

4.3 Protezione di rilevamento delle scansioni delle porte in ingresso

Rileva gli IP di origine che si connettono a molte porte diverse in poco tempo, incrociando le regole di log di nftables con journald (attivo per impostazione predefinita). Le origini identificate come scanner con alta affidabilità possono essere bloccate automaticamente per un certo periodo. Se usato insieme a RoamSwitch Sensor, l'IP del Sensor viene escluso automaticamente (questo rilevamento è distinto da §10.1; le sonde di audit su tutte le porte di un Sensor associato sono escluse per evitare falsi positivi).

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

4.4 Protezione di rilevamento dei tunnel DNS

Il DNS inviato dall'host stesso (porta 53, UDP / TCP) viene ispezionato con NFQUEUE. Si notifica quando le query con un'etichetta oltre 40 byte ed entropia superiore a 3,8, oppure con qtype TXT / NULL, raggiungono 10 in 60 secondi (300 secondi prima della notifica successiva). L'obiettivo è il tunneling DNS come iodine e dnscat2. È impostato con bypass, quindi non ostacola mai la risoluzione dei nomi, nemmeno se la guardia si ferma. È solo di notifica e non blocca automaticamente. dns_tunnel_detect_enabled ha effetto al riavvio.

# --- Rilevamento tunnel DNS (abilitato per impostazione predefinita) ---
dns_tunnel_detect_enabled=true              # false per disattivare

Viene monitorata anche la forza bruta sui sottodomini. Si notifica quando 40 o più nomi distinti sotto lo stesso dominio restituiscono tutti NXDOMAIN entro 60 secondi (una volta all'ora per dominio, con fino a 5 nomi di esempio; ATT&CK T1590.002). Per questo anche le risposte DNS UDP (porta di origine 53) vengono ricevute tramite NFQUEUE, ma con bypass: non viene inviato nulla e la risoluzione dei nomi non viene fermata.

Non vengono conteggiate le ricerche inverse, i nomi interni come .local e i domini in dns_tunnel_entropy_allowlist. L'interruttore è dns_tunnel_detect_enabled. Le risposte TCP, DoH e DoT, i container in altri namespace e l'IPv6 con header di estensione non sono visibili. È solo di notifica e non blocca.

4.5 Guardia contro la forza bruta SSH

I login falliti di sshd vengono contati per origine nel momento in cui sono scritti nel log (attivo per impostazione predefinita). Quando un'origine raggiunge 6 fallimenti in 600 secondi (predefinito), inet roamswitch_sshguard di nftables scarta solo le nuove connessioni verso SSH e interrompe anche le connessioni SSH già stabilite. Il divieto parte da 1 ora, si quadruplica a ogni ripetizione ed è limitato a 7 giorni. Le sessioni autenticate, i successi con chiave pubblica e le origini esentate non sono interessati. Non comunica con l'esterno ed esegue solo journalctl, nft e simili in locale.

Il log viene letto con journalctl -f e si usano solo le righe scritte da sshd. Senza journald segue /var/log/auth.log o /var/log/secure, ma poiché righe falsificate potrebbero far bloccare un terzo, lasciare ssh_guard_log_source al valore predefinito auto.

Conta i fallimenti di password, gli utenti inesistenti e simili, e non conta i fallimenti con chiave pubblica (Failed publickey). L'origine viene letta da from <IP> port <N> a fine riga, quindi un nome utente falsificato non può far bandire un terzo. IPv6 è gestito per /64 (in un /64 che contiene un indirizzo da proteggere, solo quell'indirizzo).

Origini che non vengono bandite: il gateway, i resolver DNS, l'host stesso, il loopback, whitelist_ips, ssh_guard_allow, le origini con una sessione aperta, le origini riuscite con chiave pubblica entro 30 giorni (ssh_guard_trust_key_days) e i Sensor associati. I fallimenti vengono solo registrati. Gli indirizzi privati non sono esentati (perché anche un dispositivo interno compromesso può essere un'origine).

Se fail2ban (con la jail sshd attiva) o CrowdSec (con il firewall bouncer in esecuzione) protegge già l'host, il blocco viene lasciato a loro e si fanno solo rilevamento e notifica (ssh_guard_yield_to_fail2ban, predefinito true). ssh_guard_block_enabled=false funziona allo stesso modo. Le notifiche vengono inviate solo per un divieto (il raggiungimento della soglia, se solo rilevamento) e per un login riuscito da un'origine con molti fallimenti (critico; la sessione non viene interrotta). Le origini oltre 10 all'ora vengono raggruppate in un solo messaggio.

L'elenco si mostra con roamswitch server bans (con --json, serve sudo) e un divieto si rimuove con sudo roamswitch server unban <IP | /64 IPv6 | --all>, che azzera anche il conteggio dei fallimenti. I divieti tornano dopo un riavvio, con il tempo residuo. roamswitch emergency-restore non li rimuove, mentre roamswitch recover e la disinstallazione eliminano l'intera tabella. Lo strumento MCP get_ssh_guard_incidents è di sola lettura. Si possono verificare e rimuovere anche nella TUI del Server, in «Forza bruta SSH» (come root; §17).

roamswitch server bans
sudo roamswitch server unban 203.0.113.9
sudo roamswitch server unban --all

Le impostazioni sono 10, tutte con il prefisso ssh_guard_ (§18.1). Se ne modifica una, per esempio, con sudo roamswitch server config set ssh_guard_max_failures 10 e la si applica con sudo roamswitch server restart. Imposta ssh_guard_enabled=false per fermare del tutto la guardia, oppure ssh_guard_block_enabled=false perché si limiti a rilevare e notificare. Anche la voce «Protezione dalla forza bruta SSH» della diagnostica a 42 voci risulta superata finché questa guardia è attiva e banna.

Limiti: i tentativi che falliscono solo con la chiave pubblica non vengono contati. Un attacco a forza bruta distribuito su molte origini viene contato per origine, quindi non viene fermato finché una singola origine non raggiunge la soglia. Il rimedio di fondo è disattivare l'autenticazione con password e consentire solo le chiavi pubbliche.

Limitazione delle origini (opt-in): con ssh_allow_only_enabled=true e IP o CIDR separati da virgole in ssh_allow_only_sources, le nuove connessioni SSH da qualsiasi altra origine vengono interrotte dal primo pacchetto nella tabella roamswitch_sshallow. Le connessioni già stabilite, il loopback e gli indirizzi propri dell'host passano. Per IPv6 servono voci IPv6. Se l'elenco è vuoto, o l'origine SSH attuale non è nell'elenco, le regole non vengono caricate (verifica con sudo roamswitch ssh-allow check). Se anche una sola voce non è leggibile, l'intero valore viene rifiutato. L'impostazione viene riletta ogni 30 secondi e sudo roamswitch ssh-allow disable rimuove subito le regole. emergency-restore lascia le regole, roamswitch recover le rimuove. È distinto dal blocco della forza bruta (ssh_guard_*). Se le impostazioni sono danneggiate e illeggibili, le regole non vengono tolte: restano in vigore gli ultimi valori letti correttamente. Quando non si può verificare, avvisa una volta, e anche ssh-allow status, la TUI e doctor lo mostrano.

4.6 Salvaguardia all'avvio (xdp-gate)

sudo roamswitch xdp-gate enable attiva un gate che protegge il periodo tra l'avvio e l'entrata in funzione del firewall. Se manca l'oggetto eBPF, si ferma senza cambiare nulla e ne mostra il motivo. I pacchetti standard non contengono questo oggetto.

All'attivazione abilita prima il timer di salvaguardia e poi il gate. In caso di errore ripristina lo stato precedente. Ha effetto dal riavvio successivo e, solo se il timer è attivo, rilascia il gate 60 secondi dopo l'avvio. Lo stato si verifica con sudo roamswitch xdp-gate status.

5. Failsafe di prevenzione del blocco SSH

L'incidente più grave nella gestione di un server remoto è il blocco di SSH dovuto a una configurazione errata del firewall. RoamSwitch Server Edition dispone di più livelli di protezione.

6. Protezione del contenitore (Docker/Podman)

Per impostazione predefinita, quando Docker pubblica una porta di un container (-p 8080:8080, ecc.), crea proprie regole iptables che aggirano (attraversano) il firewall standard dell'host ed espongono la porta direttamente al mondo intero. È un problema noto.

Con protect_docker_ports=true (predefinito), anche il traffico verso i container non arriva dall'esterno, tranne sulle porte di ssh_ports e allowed_ports. Le regole di controllo vengono inserite nella catena DOCKER-USER con iptables e nella tabella inet roamswitch_docker_guard con la modalità nftables di Docker 29 e successivi (e anche per IPv6, se l'IPv6 di Docker è attivo). La decisione usa la porta di destinazione prima del DNAT e riguarda solo il traffico dall'esterno. Il traffico in uscita dei container e quello tra container non sono influenzati. È un secondo livello di difesa: anche con false, il firewall con rifiuto predefinito continua a scartare dall'esterno le porte pubblicate. Per usare una porta dall'esterno, aggiunga la porta lato host a allowed_ports (allowed_udp_ports per UDP) ed esegua sudo roamswitch server restart.

La protezione è idempotente e si auto-ripristina ogni minuto: se dockerd si avvia dopo RoamSwitch, se un riavvio o ricaricamento di Docker riscrive le regole, o dopo un nft flush manuale o la perdita della tabella nftables, viene riapplicata, mentre una protezione già aggiornata viene lasciata intatta.

Osserva docker events e notifica subito dopo l'avvio di un container con --privileged o con /var/run/docker.sock montato (rischio di fuga). La guardia di esecuzione nei container (container_exec_guard_enabled, attiva per impostazione predefinita) legge i binari eseguiti nei container dal descrittore aperto, anche se eliminati, e li analizza con YARA. Sono coperti anche i container già in esecuzione. Entrambe si limitano a notificare e non bloccano automaticamente. Funziona anche con Docker 29.

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

File critici (binari critici come /bin/login, /usr/bin/sudo e /usr/sbin/sshd, configurazioni di autenticazione come /etc/shadow e /etc/sudoers, e unit di systemd) sono monitorati tramite SHA-256.

Nelle directory importanti (/etc/pam.d, /etc/sudoers.d, /etc/systemd/system, /root/.ssh, ecc.) viene rilevata anche la comparsa di nuovi file. Sono coperti anche gli authorized_keys di tutti gli account che possono accedere, /etc/ld.so.preload (la sua comparsa è un indizio di rootkit) e i binari di RoamSwitch stesso. Il rilevamento dei nuovi file richiede una baseline che includa questo ambito, quindi dopo l'aggiornamento eseguire una volta sudo roamswitch fim update. I file che un fim verify non root non riesce a leggere sono «saltati perché illeggibili», non trattati come manomissione.

7.1 Verifica manuale dell'hash

sudo roamswitch fim verify

7.2 Rilevamento basato su eventi (istantaneo)

I file monitorati vengono osservati con fanotify (FAN_CLASS_NOTIF) e l'hash viene confrontato non appena una scrittura termina. La scansione periodica (predefinito fim_check_interval_secs=300 secondi) è una protezione contro gli eventi persi. Vengono rilevate anche sostituzioni come sed -i, e la notifica include il processo che ha modificato il file e l'accesso SSH (§7.5).

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. Una manomissione trovata durante un aggiornamento viene conservata in /var/lib/roamswitch/fim_deferred.json e segnalata con lo scrittore alla fine dell'aggiornamento, anche se nel frattempo il daemon si riavvia.

In questo modo, quando un amministratore esegue sudo apt upgrade (oppure dnf upgrade / zypper update) e un binario viene aggiornato in modo legittimo, RoamSwitch lo rileva automaticamente e risincronizza in silenzio la baseline degli hash (evitando falsi allarmi). Per applicare un aggiornamento manualmente, eseguire quanto segue.

sudo roamswitch fim update

Alla prima creazione della baseline, se la gestione dei pacchetti (apt/dpkg, dnf/rpm, zypper, pacman) è al lavoro, attende fino a 120 secondi. Anche subito dopo apt install, non scambia i file temporanei di dpkg (come *.dpkg-new) per una manomissione (dalla 1.11.18). Se non termina entro 120 secondi, registra un avviso e la crea comunque.

7.4 Honeytoken (esche di credenziali)

All'avvio del daemon vengono collocati in /root 3 tipi di esche (honeytoken): .aws/credentials, .ssh/id_rsa e .docker/config.json. Un file reale già esistente non viene mai sovrascritto. Quando inotify rileva la lettura di uno di questi file, viene considerata una ricerca di credenziali (MITRE ATT&CK T1552) e si genera subito una notifica Critical e una voce nella timeline dell'incidente.

È attiva per impostazione predefinita. Si può cambiare con honeytokens_enabled (false interrompe la collocazione e il monitoraggio; le esche già collocate restano) e honeytokens_home (predefinito /root). I comandi docker di RoamSwitch usano una directory vuota per DOCKER_CONFIG, quindi non attivano le esche. Le esche vengono collocate anche nella home degli agent_users di server.conf (§20). Con lo strumento MCP get_honeytoken_status si possono leggere lo stato e gli ultimi 50 accessi (sola lettura).

Quando un'esca riceve un accesso reale, vengono aggiunte esche correlate (.aws/config per .aws/credentials, .ssh/config per .ssh/id_rsa, ecc.). Al massimo 2 per volta e 6 in totale. Se in /root compaiono file sconosciuti, è il comportamento previsto.

7.5 Percorso di intrusione (chi ha fatto la modifica e tramite quale accesso SSH)

Le notifiche di modifica dei file (FIM dei percorsi critici e FIM dei lock file) includono il processo che ha effettuato la modifica (account, eseguibile, comando) e l'accesso SSH (IP e porta di origine, orario, metodo di autenticazione, impronta della chiave) (attivo per impostazione predefinita; fim_intrusion_context_enabled). Per i processi di breve durata, si cattura /proc/<pid> nel momento stesso in cui si legge l'evento e, se non riesce, si ricorre al registratore di esecuzione. Funziona anche con la guardia SSH disattivata e non invia nulla all'esterno.

Per la valutazione si usano solo i valori segnalati dal kernel (/proc/<pid>/exe, loginuid, session-N.scope del cgroup). I valori che un processo può modificare, come comm, vengono solo mostrati; dichiararsi sshd non basta per essere considerato un accesso SSH. La notifica distingue trovato, «Nessun accesso SSH trovato» e «Impossibile determinare il percorso di accesso» e viene sempre emessa, anche se il recupero fallisce.

/etc/ssh/sshd_config: modified
  Processo: root (ha effettuato l'accesso come admin) / /usr/bin/tee / comando: tee /etc/ssh/sshd_config (pid 4121)
  Accesso SSH: la sessione aperta da admin da 203.0.113.25:51544 alle 2026-10-17 03:12:08 (autenticazione: publickey, chiave SHA256:AbCdEf0123456789)

/etc/sudoers: modified
  Non è stato possibile determinare il percorso di accesso (la modifica è stata trovata dalla scansione periodica, quindi il processo responsabile non è noto)

Vengono rilevate, tramite un contrassegno posto sulla directory, anche le modifiche che collocano un nuovo file con lo stesso nome, come install, sed -i, cp e mv nella stessa directory. Limite: un file portato con mv da un'altra directory non viene notato fino alla scansione periodica (fim_check_interval_secs) e il processo che lo ha scritto non è noto.

Oltre alla notifica, la registrazione resta nella timeline (tipo fim) e in /var/lib/roamswitch/fim_intrusions.json (solo root, ultime 100 voci), e verify_fim di MCP la mostra in recentIntrusionContext (solo come root). Il verdetto di manomissione non cambia. Limite: non viene allegata alle notifiche di persistence_watch. Si conoscono il processo che ha modificato e l'accesso; il punto d'ingresso dell'intrusione (come la vulnerabilità sfruttata) non è noto. Si disattiva con fim_intrusion_context_enabled=false.

7.6 Inventario dei file SUID / SGID

Trova nuovi file SUID in posizioni fuori dall'elenco fisso di FIM e SUID aggiunti in seguito. Ogni suid_watch_interval_secs (predefinito 600 secondi) percorre i file system locali e registra modo, proprietario, dimensione e SHA-256 degli eseguibili SUID e SGID (attivo per impostazione predefinita; suid_watch_enabled). Li confronta con l'elenco iniziale in /var/lib/roamswitch/suid_baseline.json e notifica una sola volta, come Critical, un file nuovo, l'assegnazione di SUID o una modifica di modo, proprietario o contenuto (ATT&CK T1548.001).

La modifica di un file che appartiene a un pacchetto (dpkg -S, rpm -qf, ecc.) e il cui ctime non è successivo all'ultimo aggiornamento del database dei pacchetti non viene notificata e confluisce nel riferimento. Un chmod u+s successivo a un aggiornamento viene notificato. Si verifica con sudo roamswitch fim verify e si accetta con sudo roamswitch fim update.

Limite: non percorre i livelli dei container (come /var/lib/docker), gli snap né i mount di rete, FUSE, overlay e squashfs. Non vede un bit impostato e rimosso durante un percorso, né le modifiche fatte mentre un gestore di pacchetti è in esecuzione (rinviato fino a 3 volte). Un percorso che supera i 300 secondi viene scartato per quel ciclo.

7.7 Rilevamento della cancellazione dei log

Controlla la cancellazione dei log (ATT&CK T1070.002). Ogni 30 secondi memorizza inode e dimensione di auth.log, syslog, wtmp e simili, e notifica come Critical quando uno si è ridotto (da 1024 byte o più), è scomparso o è stato sostituito (attivo per impostazione predefinita; log_tamper_watch_enabled). Per il journal, notifica quando il totale degli archivi scende da 4 MiB o più a meno di un quinto (ad esempio journalctl --vacuum-time=1s).

La rotazione dei log è esclusa (un altro file che inizia con lo stesso nome ha lo stesso inode o è stato modificato entro 120 secondi, oppure il file di stato di logrotate è stato aggiornato entro 120 secondi). Limite: non vede la riscrittura di wtmp, btmp o lastlog senza cambiare la dimensione, lo svuotamento seguito da riscrittura fino alla dimensione originale, né le modifiche mentre il demone è fermo.

7.8 Monitoraggio dell'entropia anti-ransomware (entropy_watch_enabled)

Trova la cifratura di file dove non si possono collocare esche (dati applicativi, document root). Esamina i primi 256 KiB dei file in entropy_watch_dirs (se vuoto, /var/www, /srv, posizioni dei database e così via; fino a 32) e notifica quando lo stesso scrittore scrive 20 file dall'aspetto casuale in 5 secondi. Controlla anche lo schema che elimina l'originale e quello che sovrascrive con rename. entropy_watch_enabled è attivo per impostazione predefinita e si limita a notificare.

È costruito per non fermare la produzione. Non usa fanotify bloccante; legge al massimo entropy_watch_max_files_per_sec file al secondo (da 5 a 2000, predefinito 50), solo i primi 256 KiB, e se si supera passa a «parzialmente attivo». Lo scrittore viene fermato (SIGSTOP) solo con entropy_watch_freeze=true o, in una radice dei documenti con entropy_docroot_action=freeze_writer, quando un servizio web sostituisce file esistenti; i protected_processes non vengono fermati, e roamswitch frozen resume li riprende.

Su una VM Ubuntu 24.04, la cifratura di 150 file è stata rilevata al 20° file (1 notifica), cp -r, tar e simili hanno dato 0 notifiche, e a 434 file al secondo la CPU era circa il 2% di un core. Le ultime 50 voci restano in /var/lib/roamswitch/entropy_incidents.json (le righe di comando non vengono salvate) e sono lette da get_ransomware_entropy_guard_status di MCP.

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

Per evitare il «syslog bloat» e la pressione sul disco che affliggono gli strumenti di sicurezza convenzionali, RoamSwitch si collega a Falco direttamente tramite il socket di dominio UNIX /run/roamswitch/events.sock. Il socket è creato accessibile solo a root (0600), quindi solo Falco eseguito come root può scriverci (non serve alcuna configurazione aggiuntiva dei permessi).

8.2 Contenimento autonomo

Quando rileva l'esecuzione di codice malevolo o traffico sospetto, il daemon invia subito SIGSTOP al PID di quel processo per congelarne l'esecuzione e blocca il traffico con regole nftables (Air-Gap).

8.3 Conservazione automatica delle prove forensi (Forensic Evidence Capture)

Quando la protezione runtime eBPF contiene un processo (lo congela con SIGSTOP e ne interrompe la rete), crea automaticamente un pacchetto di conservazione delle prove (con l'impostazione predefinita del §4.1, a livello equivalente a Critical; a livello equivalente a Emergency, prima dell'isolamento). Contiene una cattura di pacchetti limitata a circa 30 secondi (omessa se manca tshark) e uno snapshot di /proc/<pid>, in cui i valori dei nomi che contengono KEY/TOKEN/SECRET/PASSWORD in environ diventano [REDACTED]. manifest.json registra lo SHA-256 di tutti i file.

In un contenimento che termina con la forza, lo snapshot di /proc viene salvato prima della terminazione (fino a 3 secondi). Un --pid manuale segue lo stesso ordine, e --no-packets omette i pacchetti.

Vengono salvati in /var/lib/roamswitch/incident-evidence/<timestamp>-<ID>/. I pacchetti non vengono eliminati automaticamente. Per eliminare i pacchetti vecchi oltre il periodo di conservazione (predefinito 30 giorni) ed evitare di appesantire il disco, esegui quanto segue:

sudo roamswitch-incident-capture prune [--keep-days N]

Senza attendere il contenimento, puoi anche creare uno snapshot manuale in qualsiasi momento:

sudo roamswitch-incident-capture snapshot [--pid PID] [--reason TEXT] [--trigger-event-id ID] [--json]

Le rilevazioni che hanno salvato un pacchetto di prove sono collegate nella timeline. roamswitch timeline mostra la riga di salvataggio sotto la rilevazione con └─, aggiungendo il nome del pacchetto e lo SHA-256 del manifest. --json e get_incident_timeline di MCP includono evidence_refs (fino a 8 voci; solo nomi e SHA-256, mai il contenuto) e altro. Collega solo quando l'ID che ha fatto scattare l'evento è noto e non unisce mai per vicinanza temporale. Per uno snapshot manuale, si può passare con --trigger-event-id ID.

8.4 Misurazione della rapidità dell'isolamento e heartbeat del percorso degli avvisi

La precisione e la rapidità dell'isolamento eBPF dipendono dalle regole del sensore (Falco o Tetragon). In effetti, le regole standard di Falco 0.45.0 (29 in tutto) non ne includono nessuna che rilevi una reverse shell sull'host: le regole per le reverse shell valgono solo per i container e alcune vengono scartate dalla condizione priority: warning di RoamSwitch. RoamSwitch non dà per scontata la bontà delle regole; compensa in tre modi: misura quanto dura l'isolamento, verifica regolarmente che il percorso degli avvisi sia vivo e rileva da sé le reverse shell.

Misura del ritardo di isolamento: per ogni incidente eBPF, detect_to_receive_ms (dalla rilevazione alla ricezione), receive_to_action_ms (dalla ricezione all'azione) e detect_to_action_ms (totale) vengono registrati in ebpf_incidents.json e in get_ebpf_incidents di MCP, e anche la notifica di isolamento del processo riporta «N millisecondi dalla rilevazione all'azione». Misurato su una VM Ubuntu 24.04 (Falco 0.45.0, modern eBPF), il totale è stato di 42–64 millisecondi (1–2 fino alla ricezione, 41–62 fino all'isolamento e SIGKILL) e l'Air-Gap dell'host di 109 millisecondi, entro l'obiettivo di 150 millisecondi. Tetragon non ha detect_to_receive_ms.

L'heartbeat (ebpf_heartbeat_interval_secs; predefinito 600 secondi, 0 disattiva, da 60 a 86400 se attivo) apre un percorso usa e getta utilizzabile solo da root e misura il tempo che l'allarme della regola inclusa 96-roamswitch-heartbeat.yaml impiega a tornare da Falco. Avvisa solo quando non torna due volte di seguito (la nuova verifica è dopo 1 minuto), al massimo una volta ogni 24 ore. Le righe di heartbeat vengono scartate senza passare per isolamento o notifica, e non viene inviato nulla all'esterno. Il round trip misurato è stato di 2–6 millisecondi; senza la regola ha avvisato dopo circa 164 secondi, e dopo il ripristino è tornato normale in circa 75 secondi.

Lo stato è conservato in /var/lib/roamswitch/ebpf_heartbeat.json e viene letto dal campo heartbeat dello strumento MCP get_ebpf_incidents e dalla diagnostica K-04 (agente runtime eBPF; il numero di voci diagnostiche resta 42). Anche se Falco è in esecuzione, K-04 non passa se l'heartbeat non torna. Limiti: si verifica un solo andata e ritorno di una sola regola (le chiamate di sistema della famiglia open); non si può sapere se un'altra regola sia rotta per conto suo. Ciò che si rompe tra due controlli (10 minuti per impostazione predefinita) non si vede fino al successivo. Non viene eseguito per Tetragon. Su un host in cui Falco non è in esecuzione o manca il file della regola, non si controlla nulla e non si avvisa di nulla (se ne occupa la notifica esistente «guardia arrestata»). Falco scrive una riga di avviso nel syslog a ogni controllo (144 righe al giorno con l'impostazione predefinita).

8.5 Rilevamento delle reverse shell (proprio di RoamSwitch)

Indipendentemente dalle regole di Falco, ogni 2 secondi legge /proc e cerca shell e interpreti (bash, python, ecc.) il cui input e output standard sono collegati a una sola connessione TCP verso l'esterno. Ciò che viene visto due volte di seguito è segnalato una volta per processo. Le destinazioni con indirizzi privati contano solo con reverse_shell_watch_include_private=true; loopback e connessioni accettate non vengono esaminati.

Su una VM Ubuntu 24.04 ha rilevato il /dev/tcp di bash, python, perl, nc -e e socat exec: in circa 2,4 secondi, e non ha rilevato ssh, ssh con ProxyCommand, git over ssh né un client nc.

Una rilevazione entra nello stesso percorso degli allarmi di Falco (allowlist, guard.yaml, ecc.) come evento eBPF Critical RoamSwitch Reverse Shell, e per impostazione predefinita isola e termina (kill) il processo. Una reverse shell di proprietà di root fa fallire l'isolamento per processo, quindi si arriva all'Air-Gap dell'intero host. I falsi positivi si gestiscono con reverse_shell_watch_notify_only=true (predefinito false; solo notifica Warning) oppure con sudo roamswitch server allowlist add "RoamSwitch Reverse Shell" <nome del processo>. reverse_shell_watch_enabled è true per impostazione predefinita e reverse_shell_watch_include_private è false.

I processi dell'elenco integrato (init, sshd, RoamSwitch stesso, ecc.) e di protected_processes in server.conf (separati da virgole) non vengono fermati con SIGSTOP né terminati con SIGKILL dalla protezione; vengono solo registrati e notificati. Un nome ha effetto solo quando l'eseguibile si trova in una posizione di sistema come /usr/ o /bin/; una falsificazione con lo stesso nome in /tmp non è protetta. Il software installato altrove va scritto con percorso assoluto e reso di proprietà di root. Quando il percorso non è leggibile, protegge il nome.

roamswitch server allowlist test <rule> <process> [--exe percorso] non cambia nulla e mostra se il caso rientra nell'allowlist o nella protezione da congelamento e kill. Ha effetto dopo sudo roamswitch server restart.

Le voci di server allowlist hanno una scadenza, e una voce scaduta conta come inesistente per la protezione (l'elenco la conserva come «Scaduta: il permesso non è in vigore»). Le voci precedenti all'introduzione della scadenza continuano a valere come «Senza scadenza (voce vecchia)» e vengono notificate una volta al giorno. Il demone Server controlla ogni 5 minuti e notifica una volta 7 giorni prima della scadenza e una volta alla scadenza. Riportare indietro l'orologio non annulla una scadenza (il contrassegno è /var/lib/roamswitch/allowlist_clock; non è una difesa contro un attaccante con root). Solo una persona aggiunge voci; né la protezione né MCP lo fanno. I blocchi non hanno scadenza. Nella TUI di Server, il tasto e proroga di 30 giorni.

Limiti: il filtro avviene per nome (nome del processo e dell'eseguibile), perciò un binario fatto in casa con un nome diverso da quello di una shell o di un interprete che leghi input e output standard a un socket non viene trovato. Le connessioni via loopback (come il ritorno di ssh -R) e quelle più brevi di 2 secondi non si vedono, né si vedono i processi non visibili dallo spazio dei processi dell'host. Il client Linux ha lo stesso rilevamento e si limita a notificare.

Vengono controllati anche due casi in cui lo standard I/O non è collegato a una connessione. Il primo è una connessione in uscita di un interprete, di openssl s_client, nc o simili, collegata in modo bidirezionale a una shell interattiva senza -c tramite pipe, FIFO o pty. Genera solo una notifica e una registrazione come Warning (né isolamento né kill, indipendentemente da guard.yaml; i processi che sono anche in ascolto sono esclusi). Il secondo è un socket UDP connesso, che è Critical, come per TCP.

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

Quando si verifica un incidente grave (esposizione non autorizzata di una porta, manomissione rilevata da FIM, minaccia rilevata da eBPF, isolamento di emergenza attivato), la situazione viene subito inviata alle piattaforme di notifica esterne.

[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. Gli avvisi registrati da ora in poi appaiono nella lingua di visualizzazione di chi esegue roamswitch notifications. Le destinazioni li ricevono nella lingua language di server.conf.

Se non c'è nessun canale di notifica, oppure se è attivo ma token, destinatario o URL sono vuoti, i rilevamenti urgenti non arrivano a nessuno. Il registro resta solo in journalctl e in roamswitch notifications. Se non c'è alcun percorso, la voce «percorso delle notifiche urgenti» della diagnosi risulta non superata e il punteggio scende. Vale anche quando non usi le notifiche e lavori solo con la Server TUI.

roamswitch notifications è il registro delle notifiche emesse. Non indica se siano arrivate. Per verificare la consegna usa sudo roamswitch server test-notify, che invia un vero messaggio di prova ai canali configurati.

Per le notifiche (Telegram, LINE, Webhook), una risposta 2xx vale come inviata; 408, 429, 5xx e gli errori di connessione vengono ritentati; gli altri 4xx no. I tentativi avvengono subito, 3 volte (a intervalli di 1 e 5 secondi). Se la consegna fallisce ancora, la notifica viene inserita in /var/lib/roamswitch/pending_deliveries.json (di proprietà di root, 0600, massimo 50 voci) e reinviata ogni 5 minuti, poi abbandonata dopo 24 ore o 24 tentativi. Le notifiche reinviate portano un'indicazione come «[Invio ritardato]» (in base a language). Nel log non vengono scritti token, segreti negli URL (user:pass@) né Authorization.

Quando una protezione non riesce a leggere il proprio input per 2 minuti o più, oppure viene registrata una perdita (rotazione dei log, overflow della coda, ecc.), vengono avvisate anche le destinazioni di notifica indicate sopra (al massimo una volta al giorno per la stessa protezione e lo stesso tipo). In quel periodo il rilevamento potrebbe non funzionare. Conteggio e orario restano in collectors di get_guard_status e in /run/roamswitch/collectors.json.

Quando il Server stesso termina in modo anomalo: se il daemon termina in modo anomalo (un crash, una terminazione per OOM, SIGKILL) e systemd lo riavvia, lo segnala alle destinazioni qui sopra dopo il riavvio (resta anche nello storico delle notifiche e nella cronologia). Se continua a cadere, gli avvisi vengono riuniti in uno all'ora con il numero di volte. Non arriva nulla dopo systemctl stop o restart, un aggiornamento dei pacchetti, un riavvio del sistema o un'interruzione di corrente. Se smette di rispondere, systemd lo riavvia dopo 30 secondi (WatchdogSec=30), e anche questo viene segnalato. La causa si vede con il comando sudo journalctl -u roamswitch-server --since "…" indicato nell'avviso.

Rifiuto delle destinazioni Webhook interne (opt-in): con webhook_block_private_addresses=true (predefinito false), l'invio viene rifiutato quando la destinazione è loopback, privata (10/8, 172.16/12, 192.168/16), link-local (169.254/16), ULA (fc00::/7) o CGNAT (100.64/10). Per un nome host, viene rifiutato se anche uno solo dei risultati della risoluzione corrisponde, e vengono valutate anche le notazioni alternative. Poiché la connessione è fissata sul risultato della risoluzione, si previene anche il DNS rebinding. Le destinazioni legittime si consentono con webhook_allow_addresses, e l'inoltro degli eventi ha la stessa impostazione. Se è impostata una variabile d'ambiente del proxy HTTP, questo controllo non si applica.

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.

Progettazione senza strumenti che modifichino le impostazioni
Anche se nei log di un'applicazione web o simili si mescola un prompt injection malevolo, un agente IA non può essere sfruttato per aprire il firewall o revocare l'isolamento: tra gli strumenti accessibili tramite MCP non ce n'è nessuno che modifichi impostazioni, difese, porte o dispositivi. La maggior parte degli strumenti legge soltanto; le uniche scritture sono quelle di tre strumenti che aggiornano i propri file di registrazione. Modificare le policy o sbloccare un processo congelato richiede l'esecuzione esplicita di un comando in un TTY locale (terminale SSH).

Se un risultato diagnostico contiene stringhe che terzi possono riscrivere (testo dei log, ecc.), viene aggiunta l'avvertenza «dati esterni non attendibili». Se c'è una formulazione simile a istruzioni per un'IA, viene aggiunto anche un WARNING con solo il tipo e il numero. get_detection_coverage restituisce, per ogni tecnica, se è rilevabile, i punti ciechi e se la protezione responsabile è in funzione (l'edizione si sceglie con isServer).

Tutti gli strumenti MCP hanno annotazioni. readOnlyHint è false solo per run_active_vuln_scan, audit_security_logs e run_npm_audit_signatures, che aggiornano i propri file di registrazione; openWorldHint è true solo per run_npm_audit_signatures, disattivato per impostazione predefinita. Le query DNS e RDAP dei domini avvengono solo per quanto scritto in domain_check_domains, vuoto per impostazione predefinita. get_vulnerability_scan_history restituisce ciò che le sonde lasciano sul bersaglio (sideEffects), e run_active_vuln_scan restituisce evidenceKind, che indica se un riscontro è confermato o è solo una corrispondenza di versione.

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 serve per le interrogazioni umane, l'integrazione investigation fa avviare al daemon, in modo autonomo, una CLI di agente IA esterno a partire da un rilevamento. Riguarda gli eventi eBPF gravi che si sono fermati a una notifica e i rilevamenti di manomissione di FIM e dei lock file. La CLI viene avviata con il rapporto di prima valutazione prodotto dal daemon, e le si affidano l'indagine aggiuntiva e il riepilogo. È disattivata 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

Si può configurare anche nella procedura guidata sudo roamswitch server setup (§3.2). Lo strumento è un preset per Claude Code (claude -p), agy (agy -p --dangerously-skip-permissions), Codex CLI (codex exec) o OpenCode (opencode run), oppure un comando qualsiasi. Rieseguendola, viene selezionata l'impostazione salvata.

Nota sull'iniezione di prompt
L'integrazione investigation passa i dettagli dell'evento rilevato (comprese stringhe che un attaccante può controllare in parte) all'agente IA come stringa JSON troncata. Non è possibile creare un falso campo di istruzione, ma resta la possibilità che il contenuto venga letto come istruzione.

Per questo non può essere eseguita come root; una configurazione senza un utente normale in run_as non viene salvata dalla procedura guidata e il daemon non la avvia. Saltare i controlli dei permessi con --dangerously-skip-permissions o simili aumenta il rischio. In ambienti in cui entrano log non attendibili, consigliamo una configurazione che non li salti.

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 Mostra il punteggio di sicurezza del server a 42 voci e lo stato (--json stampa lo stesso report come JSON)
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 dell’ultima settimana (ogni avviso inviato); sono supportati --json e --export FILE
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 §18)
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 con un Sensor tramite codice di associazione. Si associa con pair --addr <IP> --code <codice> --fingerprint <SHA-256>, si aggiorna il pin dopo la rigenerazione del certificato con repin e si richiede un audit con request-audit (risultati con results). Richiede sensor_pairing_enabled: true (OFF per impostazione predefinita). Dettagli nel manuale operativo del Sensor
roamswitch server tui Utente/root Avvia la TUI che copre ogni funzione (sola lettura per gli utenti normali, controllo completo come root; §17)
sudo roamswitch server ack root Riconosce l’isolamento di emergenza corrente (mantiene rigido un isolamento FULL e rilascia uno in DEGRADED; §4.1)
roamswitch server ebpf Utente Mostra lo stato di contenimento corrente della protezione runtime eBPF e la cronologia degli incidenti rilevati
roamswitch server bans [--json] Utente/root Mostra la guardia contro la forza bruta SSH (§4.5): il suo stato e le origini bannate al momento con il tempo residuo. Supporta --json. L'elenco dei ban è leggibile solo da root
sudo roamswitch server unban <IP | IPv6 /64 | --all> root Rimuove un ban della guardia SSH e azzera il contatore dei fallimenti di quell'origine (indica un'origine IPv6 con il suo /64; --all rimuove tutti i ban)
sudo roamswitch server allowlist [list|add <rule> <process> [--exe <path>] [--days N] <reason...>|renew <rule> <process> [--days N]|remove <rule> <process>] root Gestisce la lista di elementi consentiti della guardia eBPF (consentire i falsi positivi). add richiede un motivo e ha una scadenza di --days N (da 1 a 365, predefinito 30). Collegare la voce a un percorso con --exe impedisce l'elusione tramite falsificazione del nome. renew reimposta la scadenza e list mostra scadenza, giorni rimanenti, chi l'ha aggiunta e il motivo
roamswitch server allowlist test <rule> <process> [--exe <path>] Utente/root Mostra, senza modificare nulla, se la coppia regola/processo è nell'elenco consentiti e se il processo è protetto da congelamento e terminazione (incluso protected_processes). --pid PID sostituisce nome e percorso. Quando una voce scaduta è il motivo per cui le guardie agiscono, lo segnala.
roamswitch frozen [list|resume <PID>|resume all] Utente/root Elenca i processi che le protezioni mantengono in SIGSTOP e rilascia uno che era un falso positivo (SIGCONT); resume all li rilascia tutti
sudo roamswitch events search|tree|export|verify|status root Cerca nel registratore delle esecuzioni (--since 2h --pid --exe --user --parent --text --json), stampa un albero dei processi, esporta, verifica la catena di hash e mostra lo stato (§15)
sudo roamswitch forward status|test|queue root Mostra lo stato dell’inoltro degli eventi, invia un evento di test ed elenca la coda di ritentativi (§16)
roamswitch timeline / notifications [--json] [--export FILE] Utente Mostra la timeline unificata degli incidenti (sperimentale) o la cronologia delle notifiche; --json stampa un array JSON e --export FILE scrive JSON Lines. Sotto un rilevamento che ha salvato un pacchetto di prove, la riga del salvataggio è disegnata con └─ e viene mostrato il nome del pacchetto. Con --json, parent_event_id, root_event_id ed evidence_refs compaiono solo nelle righe che hanno un collegamento.
roamswitch audit-agent-setup [--json | --format text|json|sarif] Utente Controlla in sola lettura le voci pericolose nei file di istruzioni, negli skill e nella memoria degli agenti IA e nelle impostazioni di OpenClaw (solo la cartella home; nessuna comunicazione di rete). Le segnalazioni portano tag OWASP LLM e ATT&CK e possono essere prodotte con --json o --format sarif (SARIF 2.1.0). Legge anche ~/.claude/settings.json e le impostazioni di Gemini CLI, Codex, Cursor e OpenCode (.gemini/settings.json, .codex/hooks.json, .codex/config.toml, .cursor/hooks.json, opencode.json, .opencode/plugins/) per gli hook che si eseguono già all'apertura, oltre alle impostazioni MCP di Codex e OpenCode.
roamswitch detection-coverage [--server | --client] [--json | --format json|navigator] Utente elenca, per ogni tecnica MITRE ATT&CK che un intruso usa per indebolire le difese, cancellare le tracce o restare sull'host, se RoamSwitch può accorgersene (detects / partial / none), che cosa non vede e se la protezione responsabile è in funzione adesso (attiva / spenta / parzialmente attiva / sconosciuto). Legge solo la tabella propria del codice e le impostazioni locali: non si esegue nulla e non si invia nulla. I test verificano che il codice dietro ogni affermazione esista ancora; una tecnica non elencata non è stata valutata. L'edizione Client elenca 38 tecniche (31 partial, 7 none) e l'edizione Server 38 (25 partial, 13 none); nessuna è valutata detects. Si sceglie con --server / --client (predefinito: l'edizione installata). --json stampa lo stesso JSON dello strumento MCP get_detection_coverage. Si può eseguire anche dalla schermata Strumenti della TUI Server. --format navigator stampa la stessa tabella come livello di MITRE ATT&CK Navigator (layer 4.5): rilevato in verde, parziale in giallo, non visto in rosso; le tecniche non valutate restano senza colore.
roamswitch vuln-accept <ECOSYSTEM> <PACKAGE> <CVE-ID> --version VERSION --reason TEXT [--days N] | --list | --revoke ... Utente Una persona registra un'“accettazione” a tempo per un rilevamento della corrispondenza CVE dei pacchetti. roamswitch vuln-accept <ecosistema> <pacchetto> <CVE-ID> --version VERSION --reason MOTIVO [--days GIORNI] (il motivo è obbligatorio; 90 giorni per impostazione predefinita, massimo 365 giorni), --list, --revoke. I rilevamenti accettati restano nei risultati e sono conteggiati separatamente da “richiede azione”. Alla scadenza tornano allo stato precedente e restano nella cronologia delle notifiche. Vale solo per la versione indicata e non può essere accettata da MCP
roamswitch sigma-check [RULE.yml] [--against-exec-history] [--json] Utente/root Verifica se le regole Sigma inserite in /etc/roamswitch/sigma.d (un sottoinsieme di process_creation) vengono caricate. --against-exec-history le prova sugli eventi exec registrati (il log exec è leggibile solo da root). Le regole che non è stato possibile caricare compaiono con il motivo. Vengono letti solo i file di proprietà di root e non scrivibili da altri. Una corrispondenza nel registratore exec genera solo notifica, voce nella cronologia e inoltro, senza bloccare nulla. Nessuna connessione di rete
roamswitch doctor [--json] Utente/root Verifica se il dispositivo può sostenere le difese di RoamSwitch (non modifica nulla e non effettua comunicazioni). Controlla la presenza degli strumenti necessari (nft, systemctl, ecc.), se questi e i file di RoamSwitch sono scrivibili da utenti diversi da root, i risultati di dpkg --verify / rpm -V, i certificati CA installati manualmente e se il daemon, ufw, fail2ban e simili sono in esecuzione. --json produce JSON. Codice di uscita 1 se c'è anche un solo errore (0 se ci sono solo avvisi). Disponibile anche da “Strumenti” nella TUI di Server.
roamswitch scan-frontend <FOLDER> Utente/root Cerca nei file front-end pubblicati chiavi API, chiavi private e simili (stesso rilevamento di audit-secrets), JWT e source map (.map). Legge dist, build, public e simili, e se non esistono legge la cartella stessa (audit-secrets <cartella> non guarda dist e build). I valori sono mostrati solo con i primi 4 caratteri e la lunghezza; codice di uscita 1 se viene trovato qualcosa. I limiti sono 5 MB per file, 200 MB in totale e 20.000 file, e i collegamenti simbolici non vengono seguiti.

12. Risoluzione dei problemi e domande frequenti

Q1. RoamSwitch disconnetterà inaspettatamente la mia sessione SSH?

No. In condizioni normali le connessioni stabilite e ssh_ports (predefinito 22) sono sempre consentite e, anche durante un isolamento di emergenza Air-Gap, con preserve_ssh_on_isolation=true (predefinito) restano attivi la porta SSH di manutenzione e la sessione di gestione dall'IP di amministrazione (le altre connessioni stabilite vengono interrotte). Il difetto delle versioni Server 1.10.4 e precedenti, per cui SSH non passava durante l'isolamento, è stato corretto nella 1.10.5.

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. allowed_ports riguarda le porte TCP. Per accettare UDP, scrivilo in allowed_udp_ports.

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.

Il servizio può scrivere solo in posizioni come l'interno di /var/www, /srv, /root, /opt e /etc/roamswitch; all'esterno, il posizionamento delle esche e la quarantena delle scansioni dei file falliscono. Per altre posizioni, aggiungere ReadWritePaths=-/percorso sotto [Service] con sudo systemctl edit roamswitch-server e riavviare. roamswitch doctor avvisa delle posizioni in cui non si può scrivere.

Un file trovato da YARA o ClamAV ma che non è stato possibile mettere in quarantena viene notificato con il nome del file e il motivo.

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

Analizza periodicamente journalctl, raggruppa i messaggi di log in modelli e rileva nuovi schemi (forme di log mai viste prima) e anomalie di frequenza (picchi statistici, Z-score > 3.0). È un meccanismo leggero che non richiede demoni aggiuntivi né dipendenze esterne, quindi è attivo per impostazione predefinita. Quando rileva qualcosa, notifica le stesse destinazioni di File Scan Guard e FIM (Telegram / LINE / Webhook). Le chiavi API e i token che i log possono contenere vengono oscurati automaticamente prima di entrare nel corpo della 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)

Si può configurare anche con la procedura guidata interattiva sudo roamswitch server setup. Gli ultimi risultati di rilevamento si possono consultare con il comando roamswitch audit-logs o con lo strumento MCP audit_security_logs.

AccessScope, strumento di diagnosi dei log di accesso (strumento separato): i deb / rpm della Server Edition includono il comando accessscope, che diagnostica in sola lettura i log di accesso del server web e di SSH (nessuna app grafica). L'analisi non usa né un LLM né la rete. L'analisi con LLM è facoltativa e disattivata per impostazione predefinita (si consiglia di eseguirla come utente senza privilegi). accessscope scan --auto esegue la diagnosi e accessscope discover elenca la posizione dei log (pagina di AccessScope). Anche PersonalSOC e PathScope (personalsoc, pathscope) dello stesso pacchetto non comunicano da soli, e l'analisi con LLM di PersonalSOC viene eseguita solo con --llm.

15. Registratore delle esecuzioni e regole di correlazione (locale, solo notifica)

Registra l'esecuzione dei processi tramite il proc connector di netlink (eseguibile, argomenti, genealogia dei processi padre, UID, cwd, ID del container, SHA-256; attivo per impostazione predefinita). Il registro è conservato in /var/lib/roamswitch/exec_log, accessibile solo a root, come JSON Lines con catena di hash (0600, predefinito 200 MB / 14 giorni) e non viene inviato all'esterno. Rileva soltanto la manomissione (events verify) e non la impedisce. La CPU è mantenuta entro un budget (predefinito 3%).

Il registro in scrittura è protetto da una riga checkpoint ogni 10 secondi; ciò che segue (fino a circa 10 secondi) non può essere verificato e verify ne mostra il numero.

Cercate ed esportate in locale (il registro è accessibile solo a root, quindi normalmente è necessario sudo).

sudo roamswitch events status
sudo roamswitch events search --since 2h --exe curl
sudo roamswitch events tree 4242
sudo roamswitch events export --since 1d > exec-events.jsonl
sudo roamswitch events verify

Regole di correlazione da EXR-001 a EXR-016 (solo notifica, ciascuna con un ID di tecnica MITRE ATT&CK): EXR-001 una shell generata da un servizio web / EXR-002 esecuzione da /tmp, da un file eliminato o da memfd / EXR-003 esecuzione subito dopo un download / EXR-004 una one-liner di un interprete che usa base64 o eval / EXR-005 ottenimento di uid 0 senza setuid / EXR-006 esecuzione di un binario appena collocato da cron o systemd / EXR-007 esecuzione dopo la modifica di ld.so.preload. Ogni regola ha un valore predefinito volutamente silenzioso e non isola mai da sola. Silenziate le singole regole con exec_rules_disabled (ad esempio EXR-003,EXR-004) e regolate gli utenti monitorati da EXR-001 con exec_rule_service_users. EXR-016 segnala i tunnel -R e -D di un ssh senza terminale (Medium, T1572, mai usata per l'isolamento, nemmeno con opt-in). Quando una sessione sshd apre un ascolto (il lato che ha ricevuto ssh -R), viene segnalato anche questo, come High. Un account e una porta noti si escludono con sudo roamswitch server allowlist add ssh-remote-listen <account>:<porta> <motivo>.

EXR-008 eliminazione di snapshot (btrfs, LVM) da parte di qualcosa che non sia uno strumento di gestione noto / EXR-009 ricerca di 8 o più tipi di strumenti di attacco entro 30 secondi / EXR-010 un interprete di script avvia 3 o più tipi di strumenti di attacco entro 2 minuti / EXR-011 forma di reverse shell da riga di comando (gravità Alta) / EXR-012 un processo non root sotto un servizio avvia gdb, strace o ltrace con un PID (gravità Media). EXR-011 ed EXR-012 sono valutati dal testo del comando, quindi non isolano nemmeno se exec_rules_isolation_optin è impostato a true.

EXR-013 notifica quando un processo avviato da un servizio (come nginx), o in esecuzione con quell'account, viene eseguito con LD_PRELOAD o LD_AUDIT che puntano a una libreria esterna al sistema (gravità Alta), oppure con LD_LIBRARY_PATH che punta a /tmp o simili (Media; non avvia l'isolamento). Riguarda la tecnica che aggira disable_functions di PHP con putenv("LD_PRELOAD=…") e mail(). root e gli utenti connessi sono esclusi. Si registrano solo i valori di queste 3 variabili (fino a 200 caratteri); le altre variabili d'ambiente non vengono lette. A EXR-009 ed EXR-010 sono stati aggiunti chisel, mimikatz e altri, ed EXR-010 ora copre anche i programmi in /home, /root e /tmp.

EXR-014 notifica quando un processo figlio di un agente IA (claude, codex, ecc.) esegue un comando che invia credenziali o valori segreti all'esterno (High per i file, Medium per i soli valori), ed EXR-015 quando le credenziali vengono lette e inviate all'esterno entro 5 minuti (Medium) (entrambi T1048, solo notifica). Sono visibili solo i comandi del processo figlio; non sono visibili le letture degli strumenti integrati, la comunicazione di python o node stessi e gli agenti il cui processo si chiama node.

Solo quando exec_rules_isolation_optin (predefinito false) è impostato esplicitamente a true, le regole di gravità alta sono trattate come inneschi di isolamento ad alta affidabilità (§4.1). Per impostazione predefinita le regole si limitano a notificare. Si possono consultare anche con gli strumenti MCP in sola lettura search_exec_events / get_process_tree.

16. Inoltro degli eventi (SIEM / syslog / webhook, opt-in)

Gli eventi di rilevamento possono essere inoltrati a destinazioni della propria organizzazione indicate dall'operatore. È disattivato per impostazione predefinita. Non viene inviato nulla finché non si imposta forward_enabled=true e non si configura almeno una destinazione, e non è incorporata alcuna destinazione di fornitori. Vengono inoltrati la cronologia degli incidenti, lo storico delle notifiche, la guardia eBPF, le transizioni di stato dell'isolamento e gli avvisi di FIM, canary e regole di esecuzione; il log grezzo di esecuzione in sé non viene inoltrato. Le destinazioni sono di 3 tipi.

Gli eventi non inviati (TCP / TLS / Webhook) vanno in una coda di reinvio su disco (0600, limitata da forward_queue_max_mb, predefinito 20, e forward_queue_max_age_hours, predefinito 72) e vengono reinviati con backoff esponenziale, anche dopo un riavvio. La gravità minima da inviare si imposta con forward_min_severity (predefinito low). Per non bloccare il percorso critico, l'invio avviene in un thread dedicato; se la coda trabocca, si scartano prima gli elementi più vecchi.

Per verificare lo stato, provare la connettività e controllare la coda di reinvio, usare i comandi seguenti (dopo aver modificato le impostazioni, riavviare il servizio).

# /etc/roamswitch/server.conf
forward_enabled=true
forward_syslog_url=tls://siem.example.org:6514
forward_syslog_format=rfc5424
forward_tls_ca_file=/etc/ssl/certs/corp-ca.pem
forward_min_severity=medium

sudo roamswitch server restart
sudo roamswitch forward status
sudo roamswitch forward test
sudo roamswitch forward queue

17. TUI del server (un’interfaccia da terminale per ogni funzione)

roamswitch-server-tui (avviabile anche con roamswitch server tui) è una TUI che permette di usare, via SSH e solo con la tastiera, tutte le funzioni di Server Edition sparse tra i verbi della CLI e i due file di configurazione (server.conf e guard.yaml) (funziona in 80x24, 10 lingue). Se si aggiunge un verbo della CLI o una chiave di configurazione senza l'operazione corrispondente nella TUI, i test di sviluppo falliscono.

Avviatela con:

sudo roamswitch-server-tui    # full control
roamswitch-server-tui         # read-only
roamswitch server tui         # same as roamswitch-server-tui

18. Riferimento delle chiavi di configurazione (server.conf / guard.yaml)

roamswitch-server non supporta il reload, quindi qualsiasi chiave richiede un riavvio per avere effetto (sudo roamswitch server restart). server.conf si modifica con roamswitch server config set <chiave> <valore> o con l'editor del §17, guard.yaml con l'editor o a mano.

Come eccezione, ssh_allow_only_enabled e ssh_allow_only_sources hanno effetto senza riavvio, circa 30 secondi dopo il salvataggio. Se server.conf o una riga di valore non si può leggere, al posto dei valori predefiniti valgono gli ultimi valori letti correttamente (/var/lib/roamswitch/server.conf.last-good, leggibile solo da root), e CLI e TUI mostrano che alcune impostazioni non si sono potute verificare. Prima del salvataggio successivo, il file danneggiato viene conservato come server.conf.corrupt-….

18.1 server.conf (131 chiavi)

Chiave Tipo / valori Predefinito Riavvio
languagesystem | ja | en | zh-hans | zh-hant | ko | de | fr | es | it | ptjaSì
ssh_portsport list22Sì
allowed_portsport list80,443Sì
allowed_udp_portsport list—Sì
whitelist_ipslist—Sì
preserve_ssh_on_isolationbooltrueSì
telegram_enabledboolfalseSì
telegram_bot_tokenstring—Sì
telegram_chat_idstring—Sì
line_enabledboolfalseSì
line_channel_access_tokenstring—Sì
line_user_idstring—Sì
webhook_enabledboolfalseSì
webhook_urlURL—Sì
webhook_block_private_addressesboolfalseSì
webhook_allow_addressesCIDR list—Sì
action_on_criticalisolate | freeze | alert_onlyisolateSì
ebpf_socket_pathabs path/run/roamswitch/events.sockSì
ebpf_heartbeat_interval_secs0 (off) | int 60–86400600Sì
isolation_hard_cap_secsint ≥ 03600Sì
protected_processeslist—Sì
fim_check_interval_secsint ≥ 10300Sì
fim_intrusion_context_enabledbooltrueSì
protect_docker_portsbooltrueSì
dns_sinkhole_enabledboolfalseSì
dns_sinkhole_providerquad9 | cloudflare | adguard | cleanbrowsingquad9Sì
egress_ip_blocklist_enabledbooltrueSì
metadata_watch_enabledbooltrueSì
metadata_watch_allow_userslist—Sì
cve_kernel_map_updates_enabledbooltrueSì
clamav_enabledboolfalseSì
clamav_scan_dirsabs path list—Sì
clamav_scan_interval_secsint ≥ 360086400Sì
clamav_freshclam_interval_secsint ≥ 18007200Sì
lockfile_watch_dirsabs path list—Sì
domain_check_domainsdomain list (max 5)—Sì
npm_audit_signatures_enabledboolfalseSì
log_audit_enabledbooltrueSì
log_audit_interval_secsint ≥ 3001800Sì
resource_guard_enabledbooltrueSì
resource_guard_rss_sample_interval_secsint ≥ 1060Sì
resource_guard_rss_window_secsint ≥ 3001800Sì
resource_guard_rss_min_samplesint ≥ 310Sì
resource_guard_rss_min_growth_pctint ≥ 1050Sì
resource_guard_rss_recovery_drop_pctint ≥ 110Sì
resource_guard_rss_min_kbint ≥ 020000Sì
resource_guard_crash_loop_window_secsint ≥ 60300Sì
resource_guard_crash_loop_min_restartsint ≥ 23Sì
resource_guard_correlation_window_secsint ≥ 60600Sì
resource_guard_zombie_min_countint ≥ 020Sì
resource_guard_load_min_normalizedfloat ≥ 0.00.5Sì
resource_guard_load_enabledbooltrueSì
resource_guard_cpu_enabledbooltrueSì
resource_guard_cpu_sample_interval_secsint ≥ 060Sì
resource_guard_cpu_window_secsint ≥ 0600Sì
resource_guard_cpu_min_samplesint ≥ 08Sì
resource_guard_cpu_pct_thresholdfloat 0.0–1000.080.0Sì
container_exec_guard_enabledbooltrueSì
port_scan_detect_enabledbooltrueSì
port_scan_detect_min_distinct_portsint ≥ 015Sì
port_scan_detect_window_secsint ≥ 0300Sì
port_scan_block_enabledbooltrueSì
port_scan_block_duration_secsint ≥ 0600Sì
ssh_guard_enabledbooltrueSì
ssh_guard_block_enabledbooltrueSì
ssh_guard_max_failuresint 2–10006Sì
ssh_guard_window_secsint 10–86400600Sì
ssh_guard_ban_secsint 60–25920003600Sì
ssh_guard_ban_max_secsint 60–31536000604800Sì
ssh_guard_allowIP/CIDR list—Sì
ssh_guard_log_sourceauto | journal | abs pathautoSì
ssh_guard_yield_to_fail2banbooltrueSì
ssh_guard_trust_key_daysint 0–365030Sì
ssh_allow_only_enabledboolfalseNo (circa 30 s)
ssh_allow_only_sourcesIP/CIDR list—No (circa 30 s)
agent_usersname list—Sì
agent_egress_allowaddr[:port] list—Sì
agent_setup_watch_secsint 0, 30–86400300Sì
prn_recordboolfalseSì
prn_retention_hoursint 1–16824Sì
prn_max_mibint 16–4096256Sì
dns_tunnel_detect_enabledbooltrueSì
reverse_shell_watch_enabledbooltrueSì
reverse_shell_watch_include_privateboolfalseSì
reverse_shell_watch_notify_onlyboolfalseSì
suid_watch_enabledbooltrueSì
suid_watch_interval_secs60 – 86400600Sì
log_tamper_watch_enabledbooltrueSì
sensor_pairing_enabledboolfalseSì
sensor_colocatedboolfalseSì
forward_enabledboolfalseSì
forward_syslog_urlURL—Sì
forward_syslog_formatrfc5424 | cefrfc5424Sì
forward_syslog_framingoctet | lfoctetSì
forward_tls_ca_fileabs path—Sì
forward_file_pathabs path—Sì
forward_file_max_mbint 1–1000050Sì
forward_file_keepint 1–1005Sì
forward_file_groupnome del gruppo | gid—Sì
forward_webhook_urlURL—Sì
forward_webhook_secretstring—Sì
forward_webhook_secret_fileabs path—Sì
forward_webhook_block_private_addressesboolfalseSì
forward_webhook_allow_addressesCIDR list—Sì
forward_min_severityinfo | low | medium | high | criticallowSì
forward_queue_max_mbint 1–1000020Sì
forward_queue_max_age_hoursint 1–876072Sì
exec_recorder_enabledbooltrueSì
exec_recorder_retention_mbint 1–100000200Sì
exec_recorder_retention_daysint 1–365014Sì
exec_recorder_hash_chainbooltrueSì
exec_recorder_hash_exebooltrueSì
exec_recorder_cpu_budget_pctint 1–503Sì
exec_rules_enabledbooltrueSì
exec_rules_disabledstring—Sì
exec_rule_service_usersstring—Sì
exec_rule_window_secsint 5–3600120Sì
exec_rules_isolation_optinboolfalseSì
config_regression_notice_enabledbooltrueSì
honeytokens_enabledbooltrueSì
honeytokens_homeabs path/rootSì
harden_userns_enabledbooltrueSì
dns_tunnel_entropy_allowlistlist—Sì
fleet_forwarding_allowed_hostslist—Sì
fleet_forwarding_allow_plaintextboolfalseSì
entropy_watch_enabledbooltrueSì
entropy_watch_dirslist (max 32)—Sì
entropy_watch_freezeboolfalseSì
entropy_docroot_actionnotify | freeze_writernotifySì
entropy_watch_max_files_per_secint 5–200050Sì
package_cve_map_languages_enabledboolfalseSì

18.2 guard.yaml (37 chiavi)

Chiave Tipo / valori Predefinito Riavvio
sensor.typefalco | tetragonfalcoSì
sensor.transportstringunix_socketSì
sensor.socket_pathabs path/run/roamswitch/events.sockSì
sensor.reconnect_interval_msint 100–36000001000Sì
policies.on_warning.actionlog_and_notify | isolate_process | isolate_host_alllog_and_notifySì
policies.on_warning.server_actionlog_and_notify | isolate_process | isolate_host_all—Sì
policies.on_warning.kill_processboolfalseSì
policies.on_warning.freeze_processboolfalseSì
policies.on_warning.fallback_to_host_isolation_after_retriesint 0–1000—Sì
policies.on_error.actionlog_and_notify | isolate_process | isolate_host_allisolate_processSì
policies.on_error.server_actionlog_and_notify | isolate_process | isolate_host_all—Sì
policies.on_error.kill_processboolfalseSì
policies.on_error.freeze_processboolfalseSì
policies.on_error.fallback_to_host_isolation_after_retriesint 0–1000—Sì
policies.on_critical.actionlog_and_notify | isolate_process | isolate_host_allisolate_processSì
policies.on_critical.server_actionlog_and_notify | isolate_process | isolate_host_all—Sì
policies.on_critical.kill_processbooltrueSì
policies.on_critical.freeze_processboolfalseSì
policies.on_critical.fallback_to_host_isolation_after_retriesint 0–10003Sì
policies.on_emergency.actionlog_and_notify | isolate_process | isolate_host_allisolate_host_allSì
policies.on_emergency.server_actionlog_and_notify | isolate_process | isolate_host_all—Sì
policies.on_emergency.kill_processbooltrueSì
policies.on_emergency.freeze_processboolfalseSì
policies.on_emergency.fallback_to_host_isolation_after_retriesint 0–1000—Sì
server_safeguards.allow_established_connectionsbooltrueSì
server_safeguards.maintenance_ssh_portsport list22Sì
server_safeguards.whitelist_cidrslist—Sì
server_safeguards.whitelist_dns_serverslist—Sì
server_safeguards.safety_timer_secsint ≥ 0300Sì
adaptive_security.enabledbooltrueSì
adaptive_security.untrusted_network_actions.elevate_falco_profilestring—Sì
adaptive_security.untrusted_network_actions.auto_enable_userns_restrictionboolfalseSì
investigation.enabledboolfalseSì
investigation.commandabs path—Sì
investigation.argslist—Sì
investigation.run_asstring—Sì
investigation.timeout_secsint 1–86400180Sì

19. Rilevamento di web shell e codice iniettato (Web Rules)

Rileva web shell PHP, JavaScript, JSP e ASP e codice iniettato sui server web, PHP camuffato da immagine e l'abuso di .htaccess (Linux 1.11.23 e successivi). Non serve alcuna configurazione: trova automaticamente le document root dalla configurazione di Apache, nginx e Caddy e analizza un file subito dopo che è stato scritto e chiuso. Usa fanotify solo per le notifiche, quindi non blocca gli altri processi. Esegue inoltre una scansione periodica ogni 6 ore e ClamAV non è necessario.

Il comportamento si imposta in /etc/roamswitch/web_rules.conf (proprietario root, modo 0644; un file scrivibile da altri viene ignorato). Applica una modifica con sudo roamswitch server restart. Un modello si ottiene con roamswitch web-rules example conf.

ChiaveSignificato (predefinito)
quarantineLivello di quarantena automatica. off non mette mai in quarantena, critical solo critical, high critical e high (predefinito: critical). Un risultato high con il livello critical si limita a notificare e a far partire l'hook; il file non viene toccato.
account_actionIndica se revocare la shell di login del proprietario di un file rilevato. off / revoke_shell / lock (predefinito: off). Contano solo i risultati critical o high messi in quarantena. Non si tocca mai root, gli UID sotto account_min_uid, gli utenti connessi né l'utente del demone. La shell precedente viene registrata e sudo roamswitch web-rules unlock-account <utente> la ripristina.
account_min_uidaccount_min_uid: l'UID più basso su cui può agire la risposta sugli account (1000 per impostazione predefinita; non scende sotto 100).
scan_dirs, auto_docroots, watch, scan_interval_secsscan_dirs (percorsi assoluti separati da virgole), auto_docroots (predefinito true; false ferma il rilevamento automatico dalla configurazione del web server), watch (predefinito true; false disattiva il controllo delle scritture e lascia solo la scansione periodica) e scan_interval_secs (predefinito 21600, minimo 3600).
# /etc/roamswitch/web_rules.conf
quarantine=critical
account_action=off
account_min_uid=1000
#scan_dirs=/srv/sites/a,/srv/sites/b
auto_docroots=true
watch=true
scan_interval_secs=21600

Anche i file di sessione PHP (file che iniziano con sess_) vengono esaminati con lo stesso percorso. Le posizioni sono session.save_path in php.ini e nei pool FPM, /var/lib/php/sessions, /var/lib/php/session, /tmp, /var/tmp e le cartelle temporanee private delle unit php, apache, httpd e nginx che usano PrivateTmp=. Vengono letti solo i file direttamente in queste cartelle. Se compaiono insieme un indicatore di session.upload_progress e un tag di apertura, è php-session-upload-progress-code (critical); con il solo tag di apertura è php-session-code (high).

Con account_action=lock la login shell del proprietario di un file rilevato viene revocata, e anche il traffico in uscita dell'account viene bloccato con nftables (tabella roamswitch_web_account_block), perché una web shell in esecuzione non si ferma revocando la shell. Per un account in ascolto su un indirizzo pubblico vengono bloccate solo le nuove connessioni in uscita (il loopback è consentito). Con account_stop_processes=on (disattivato per impostazione predefinita) i processi dell'account vengono fermati con SIGSTOP (esclusi protected_processes e gli elementi protetti dal sistema). unlock-account ripristina tutto in una volta.

Quando rileva qualcosa, notifica il nome della regola e se il file è stato messo in quarantena (Telegram, LINE, Webhook). Per un semplice controllo si usa sudo roamswitch web-scan <cartella> (--quarantine per la quarantena) oppure la schermata «Strumenti» della TUI di Server. Le regole personalizzate vanno in /etc/roamswitch/rules.d/*.json e lo script successivo al rilevamento è /etc/roamswitch/hooks/post-detection (vengono eseguiti solo quelli sicuri di proprietà di root, senza shell, e interrotti dopo 30 secondi). Le regole vengono aggiornate con l'aggiornamento giornaliero in sola ricezione. Disattivando cve_kernel_map_updates_enabled non avviene alcuna comunicazione e funziona con le regole incluse.

roamswitch web-rules status mostra il numero e l'elenco delle document root monitorate al momento. Con 0 voci, il rilevamento delle web shell non controlla nulla. Scrivi le cartelle in scan_dirs di web_rules.conf. Le app dietro un reverse proxy e le configurazioni nginx non standard possono non essere trovate automaticamente. Con 0 voci, all'avvio compare anche un avviso, una sola volta.

20. Account che eseguono agenti IA (agent_users)

Una funzione per eseguire agenti IA (Claude Code, Codex CLI e simili) con un account dedicato (Linux 1.12.7 e successivi). Corrisponde alle voci realizzabili su un solo server tra le 10 pratiche della guida alla risposta agli incidenti con agenti IA pubblicata da NIST, NSA e CISA il 16 ottobre 2026. Con un account dedicato, l’agente non può riscrivere i file di root né le regole del firewall.

Si configura con tre chiavi di server.conf. Per applicarle serve un riavvio (sudo roamswitch server restart).

ChiaveSignificato (predefinito)
agent_usersGli account che eseguono agenti (nomi o uid numerici, separati da virgole; vuoto per impostazione predefinita). root viene rifiutato. I nomi inesistenti e gli account senza cartella home vengono ignorati, con un avviso all'avvio.
agent_egress_allowDove può connettersi agent_users (vuoto per impostazione predefinita = nessun limite): ADDR, ADDR/PREFIX, ADDR:PORT, ADDR/PREFIX:PORT, oppure [ADDR]:PORT per IPv6. I nomi non sono ammessi. Con almeno una voce, ogni altro nuovo pacchetto in uscita di quegli account viene scartato. Un'autorizzazione generale senza porta come 0.0.0.0/0 viene rifiutata (0.0.0.0/0:443 è accettata).
agent_setup_watch_secsSecondi tra due controlli dei file di istruzioni, skill e definizioni MCP di ogni account rispetto alla baseline tenuta da root (predefinito 300; 0 = disattivato; da 30 a 86400).
# /etc/roamswitch/server.conf
agent_users=agent
agent_egress_allow=10.0.0.5:3128
agent_setup_watch_secs=300

Lista di consentiti in uscita: la tabella nftables inet roamswitch_agent_egress (hook output, priorità -145) lascia passare, del traffico dell’account di destinazione, solo il loopback, le connessioni stabilite e le destinazioni dell’elenco (con porta, in TCP e UDP), e scarta il resto con una voce di log rs_agent_egress_drop: (fino a 10 al minuto). Il traffico scartato viene raccolto ogni 60 secondi e notificato una volta all’ora per account e destinazione. L’elenco è confrontato per indirizzo e non può essere ristretto per nome. Si usa per consentire un solo proxy (agent_egress_allow=10.0.0.5:3128) oppure con intervalli di rete.

Baseline in possesso di root: lo stato verificato dei file di istruzioni (CLAUDE.md, AGENTS.md e simili), delle skill e delle definizioni dei server MCP è memorizzato solo come SHA-256 in /var/lib/roamswitch/agent_setup/<account>.json (di proprietà di root, 0600). L’account non può né riscriverla né eliminarla. La si crea e la si aggiorna come root con il comando seguente, aggiungendo --accept-with-findings quando restano rilevamenti.

sudo roamswitch audit-agent-setup --user agent             # check only
sudo roamswitch audit-agent-setup --user agent --accept    # make this state the baseline

Il daemon rileva le modifiche ai file di configurazione con inotify entro circa 1 secondo e recupera ciò che gli è sfuggito con un confronto ogni agent_setup_watch_secs. Confronta con la baseline la home e le copie di lavoro direttamente sotto di essa (cartelle che contengono uno tra .git, .mcp.json, CLAUDE.md o AGENTS.md, fino a 50), notifica una modifica o un’aggiunta una sola volta e la registra nella timeline dell’incidente. Per un account senza baseline, controlla all’avvio e ogni 5 minuti e lo notifica con il comando per crearla (al massimo una volta ogni 24 ore per account).

Credenziali esca: le esche del §7.4 vengono collocate anche nella home di ogni account di agent_users, con un sorvegliante per account. Le esche sotto /root non possono essere aperte da un agente che gira con un altro account.

Cosa non può fare: l'elenco consentito guarda solo i socket degli account indicati, quindi un agente che può diventare root, o che fa connettere al suo posto un servizio di root, non viene fermato. UDP non attende risposta, quindi chi invia non si accorge di uno scarto. L'edizione Mac e l'edizione Client Linux non hanno questa funzione.

Non inserire account usati da persone con login interattivo. Negli account senza .ssh/id_rsa viene collocata una chiave falsa. ssh la prova come chiave predefinita, quindi può causare falsi allarmi.

Il servizio vede /home in sola lettura. Per questo le esche non vengono collocate senza un drop-in che aggiunge ReadWritePaths=-/home/<account>. Il passaggio 13 di sudo roamswitch server setup lo scrive dopo la tua conferma (/etc/systemd/system/roamswitch-server.service.d/agent-users.conf).

Passaggi di configurazione: (1) Impostare agent_users. (2) Eseguire sudo roamswitch server restart. (3) Controllare con sudo roamswitch audit-agent-setup --user NAME. (4) Leggere il risultato e creare la baseline con --accept. (5) Confermare con roamswitch detection-coverage. Finché la baseline non viene creata, le modifiche di quell'account non vengono sorvegliate. Le modifiche successive alla creazione vengono notificate entro circa 1 secondo.

Le posizioni controllate sono solo ~/.claude, ~/.codex, ~/.cursor, ~/.gemini (compreso antigravity-cli), ~/.agents, ~/.openclaw e le copie di lavoro direttamente sotto la home. Altrove non vengono eseguiti né il controllo né il rilevamento delle modifiche. Anche lo stato vuoto può diventare una baseline.

21. Guardia di accesso web e varco web (rilevare e bloccare la scansione di identificativi)

Rileva, nel log degli accessi del server web, numeri di pratica, numeri d'ordine o ID utente sostituiti uno dopo l'altro. Gli strumenti d'attacco che usano l'IA dividono il lavoro su molti IP, quindi i conteggi per IP e lo User-Agent non mostrano nulla. Si osserva il modo in cui i numeri vengono richiesti, che una persona che usa il sito non produce. I log degli accessi di nginx e Apache vengono trovati automaticamente e letti mentre vengono scritti.

Vengono controllate quattro cose. (1) Una richiesta di un numero riservato (canary, mai assegnato). (2) Cinque risposte 404 per numeri inesistenti da un singolo client. (3) Un client che chiede 20 o più numeri diversi sullo stesso endpoint. (4) Più client che percorrono i numeri nell'ordine di arrivo (riconosciuto dopo 100 valori; poi un nuovo client che chiede i numeri successivi viene individuato alla prima richiesta). Un indirizzo dietro cui compaiono tre o più browser diversi (CDN, proxy aziendale, indirizzo condiviso di un operatore) non viene mai bloccato.

Il comportamento si imposta in /etc/roamswitch/web_guard.conf (di proprietà di root). Il valore predefinito è mode=warn (solo notifica e registro; nulla viene bloccato). Le modifiche si applicano entro 30 secondi.

ChiaveSignificato (predefinito)
modemode: off / warn / block (predefinito: warn). block blocca per ban_secs secondi le nuove connessioni verso le porte 80/443 di una sorgente corrispondente. Non vengono bloccati la lista consentita (whitelist_ips), il gateway, il DNS, questo stesso host e gli indirizzi condivisi in cui si vedono tre o più tipi di browser. Anche gli indirizzi privati non vengono bloccati per impostazione predefinita (si bloccano con ban_private=yes).
ban_secs, window_secs, not_found_limit, distinct_limit, ban_privateban_secs (predefinito 3600), window_secs (predefinito 600), not_found_limit (predefinito 5), distinct_limit (predefinito 20), ban_private (predefinito no).
canarycanary: un intervallo di numeri che non assegni mai, con il suo endpoint (quante righe vuoi). Esempi: canary=/loan/status?receiptNo=2026100090-2026100099, canary=/api/orders/{n}=5000001-5000009. Un client che ne chiede uno viene individuato alla prima richiesta.
gate_*gate_budget_floor (predefinito 30), gate_budget_factor (predefinito 3), gate_learn_secs (predefinito 3600), gate_socket (predefinito /run/roamswitch/webgate.sock): impostazioni del varco web (vedi sotto).
recon_notify, summary_hourrecon_notify (predefinito summary) stabilisce come viene segnalata l'esplorazione della struttura del sito: summary è un riepilogo al giorno, immediate un messaggio per client, off nessun messaggio. summary_hour (da 0 a 23, predefinito 9) è l'ora in cui parte il riepilogo (ora locale del server). Blocco, log e registrazione dell'incidente non cambiano con nessuna delle due chiavi.
# /etc/roamswitch/web_guard.conf
mode=warn
canary=/loan/status?receiptNo=2026100090-2026100099
#ban_secs=3600
#ban_private=no

Il rilevamento di una scansione di identificativi invia una notifica (Telegram, LINE, Webhook): un messaggio per endpoint (percorso e parametro del numero) per passaggio. Indica il motivo e se il client è stato bloccato o solo segnalato. Un blocco (mode=block) si toglie con roamswitch emergency-restore. Per limitarsi a osservare, lascia mode=warn.

Il Web Gate (roamswitch-webgate) è un componente opzionale posto davanti a nginx che protegge solo i punti che ricevono numeri. Contro gli attacchi che cambiano continuamente IP, tiene per ogni punto un budget al minuto di richieste di numeri nuovi (impara il volume normale per 1 ora dopo l'avvio, poi consente 3 volte il massimo normale al minuto, almeno 30). Oltre il budget, i numeri sconosciuti ricevono 429 e le quattro valutazioni precedenti ricevono 403 fin dalla prima richiesta.

Funziona solo su un socket Unix, non esce in rete e lascia passare le richieste quando è fermo. Si avvia con sudo systemctl enable --now roamswitch-webgate e si aggiunge la configurazione nginx stampata da roamswitch web-gate-config /loan/status (questo comando non modifica nulla). Finché mode=warn, si limita a registrare.

sudo systemctl enable --now roamswitch-webgate
roamswitch web-gate-config /loan/status --proxy http://127.0.0.1:8080
sudo nginx -t && sudo nginx -s reload

Anche se il gate si ferma, nginx continua a far passare le richieste, quindi non te ne accorgi. Verifica che sia in funzione con i comandi seguenti. Il gate aggiorna /run/roamswitch/webgate.status ogni 10 secondi e, se il suo ts è più vecchio di 60 secondi, il demone del server notifica. Se dopo un riavvio dimentichi enable, lo vedi con is-enabled.

systemctl is-active roamswitch-webgate
systemctl is-enabled roamswitch-webgate
sudo cat /run/roamswitch/webgate.status

In una prova locale (forza bruta simulata, 5 richieste al secondo), 700 richieste con numeri consecutivi hanno portato al blocco di tutti gli IP a 100 richieste, anche distribuite su 9 IP (i nuovi IP successivi venivano bloccati alla prima richiesta). Con il gate si è fermato a 30. Un attacco che cambia IP ogni volta e interroga a caso è stato limitato dal gate a 30 al minuto (senza il gate non viene fermato). Un attacco lento al volume normale non può essere fermato, e la contromisura di fondo è l'autorizzazione per utente nell'applicazione. roamswitch web-id-check 'http://127.0.0.1/loan/status?receiptNo={n}' --start 202610060001 permette di verificare se il contenuto viene restituito per numero senza accesso (invia solo GET per un massimo di 10 numeri consecutivi).

Viene inviata una notifica anche quando i worker di nginx, Apache o PHP-FPM terminano tre volte in cinque minuti per un segnale di crash (SIGSEGV, SIGABRT e simili) (si legge il log degli errori). Il processo master sostituisce ogni worker, quindi questo non conta mai come riavvio del servizio. Indica un tentativo di sfruttare una vulnerabilità o un bug del programma. Una notifica per server all'ora; nulla viene fermato o bloccato.

Anche l'attività che sonda la struttura del sito viene individuata dallo stesso log di accesso (un rilevamento distinto dalla forza bruta sugli identificativi). Una sorgente viene conteggiata per window_secs (predefinito 600 secondi) in base a 5 motivi. (1) path_walk: 12 o più tipi di percorsi inesistenti (404), esclusi i percorsi che contengono identificativi. (2) asset_harvest: 40 o più richieste di .js, .css e simili senza Referer. (3) api_probe: 20 o più tipi di percorsi diversi sotto /api/ con 401, 403 o 404. (4) param_fuzz: 30 o più query diverse sullo stesso percorso, con più della metà in 4xx. (5) probe_walk: 6 o più tipi di percorsi segreti o di configurazione come .env e .git o di schermate di amministrazione, oppure 12 o più tipi di percorsi segreti diversi (indipendentemente dalla risposta). (5) individua la scansione dei siti che rispondono 200 a qualsiasi percorso.

Le impostazioni si scrivono nello stesso /etc/roamswitch/web_guard.conf. Sono recon=off|warn|block (predefinito warn), cinque limiti (come path_walk_limit, da 3 a 10000; il valore predefinito di probe_walk_limit è 6) e le esclusioni exempt_path=/health (corrispondenza del prefisso) e exempt_ua=uptimerobot (corrispondenza parziale, minuscole, 3 caratteri o più). Il blocco avviene solo quando mode=block e recon=block, e gli indirizzi condivisi in cui si vedono tre o più tipi di browser non vengono bloccati.

La notifica è, per impostazione predefinita, un riepilogo una volta al giorno. Alla prima verifica a partire da summary_hour (predefinito le 9, ora locale del server) invia il numero di sorgenti, il numero di rilevamenti e blocchi e le 10 sorgenti più frequenti (nei giorni senza rilevamenti non viene inviato nulla). recon_notify=immediate notifica per sorgente, e recon_notify=off non invia notifiche. Blocco, log e registrazioni degli incidenti non cambiano. Il conteggio resta in /var/lib/roamswitch/web_recon_summary.json (fino a 500 sorgenti). Escludere le scansioni di motori di ricerca e monitoraggio con exempt_ua o exempt_path. Il Web Gate non può vedere il Referer né i codici di risposta, quindi non controlla questi quattro.

In test propri, veri log di accesso scritti da nginx in Docker sono stati fatti passare attraverso il parser e la guardia reali. Un client che scorre il sito con python-requests è stato rilevato come path_walk al 12° 404, come asset_harvest al 40° JavaScript (70° in totale), come api_probe alla 20ª API (110ª) e come param_fuzz alla 30ª query (145ª). L’uso normale di un browser, con 120 richieste (20 pagine, 60 JavaScript con Referer, 40 ricerche), non ha prodotto alcun rilevamento. È stato misurato solo questo intervallo.

Per verificare se l’ambiente è adatto al blocco, si usa roamswitch web-guard-check [--hours N] (root; non modifica nulla). Dal log di accesso e dalla configurazione del server web, il comando esamina tra l’altro la quota di richieste provenienti da indirizzi privati o condivisi e la presenza delle impostazioni che ripristinano l’indirizzo del visitatore (RemoteIPHeader, real_ip_header e set_real_ip_from). Il risultato è «adatto», «efficace solo in parte», «non adatto» o «non determinabile (meno di 200 richieste)»; se non è adatto, il codice di uscita è 1. Se una CDN o un proxy non inoltra l’indirizzo del visitatore, tutti appaiono come un unico indirizzo e il blocco ferma molte persone. Un indirizzo in cui meno di una richiesta su 5 ha successo (2xx, 304) non è considerato condiviso, anche se cambia lo User-Agent.

Un avviso che si limita a notificare (escluso il riepilogo giornaliero) porta un'indicazione solo quando lo stato e questo controllo divergono: come attivare il blocco quando è disattivato ma il controllo dice «adatto», e come fermarlo quando è attivo ma il controllo dice «non adatto» (il controllo è calcolato dai log e riutilizzato per sei ore). Negli altri casi l'avviso dice soltanto che nulla è stato bloccato. Gli indirizzi bloccati si liberano con roamswitch unban <IP> (--all per tutti), che toglie sia i blocchi della guardia SSH sia quelli della guardia di accesso web.

22. Registrazione di byte casuali (prn_record, con scadenza)

Il ransomware genera le chiavi dei file all'interno della macchina colpita, a partire dal generatore di numeri casuali del sistema operativo. Con prn_record=true, i numeri casuali restituiti da getrandom e dalle letture di /dev/urandom e /dev/random (8 byte o più, fino ai primi 128 byte) vengono registrati con una scadenza. È il materiale che gli strumenti di decifratura (come Memento di KDDI Research) usano per rigenerare le chiavi. RoamSwitch non decifra. È disattivato per impostazione predefinita e non è presente nella versione Mac né nella versione client Linux.

ChiaveSignificato (predefinito)
prn_recordprn_record: registra i byte casuali (predefinito false). Disattivandolo si cancella quanto registrato all'avvio del demone.
prn_retention_hoursprn_retention_hours: per quanto tempo si conserva un record (da 1 a 168 ore, 24 predefinito).
prn_max_mibprn_max_mib: massimo spazio su disco per il registro (MiB, da 16 a 4096, 256 predefinito).
# /etc/roamswitch/server.conf
prn_record=true
prn_retention_hours=24
prn_max_mib=256

I registri non vengono conservati oltre la loro scadenza. Quelli più vecchi di prn_retention_hours vengono sovrascritti con zeri ed eliminati file per file ogni 10 minuti (con un ritardo massimo di 10 minuti). Se si supera prn_max_mib, vengono eliminati prima i più vecchi, quindi il tempo di conservazione può solo accorciarsi, mai allungarsi. I valori fuori intervallo vengono rifiutati e un orologio sbagliato non prolunga la scadenza. Mentre il demone è fermo, /usr/lib/tmpfiles.d/roamswitch-prn.conf elimina una volta al giorno i file su cui non si scrive da 7 giorni (il tempo massimo di conservazione) (systemd 247 e successivi).

La registrazione avviene con fentry/fexit sulle funzioni casuali del kernel (get_random_bytes_user, urandom_read_iter, random_read_iter), quindi le altre letture e chiamate di sistema non subiscono alcun carico. Nelle misurazioni, la differenza su 1 milione di letture è rimasta nel margine di errore e un record ha richiesto circa 1,2 microsecondi e circa 67 byte (Linux 7.0, aarch64). Sui kernel in cui fentry non è disponibile (x86-64 precedente alla 5.5, arm64 precedente alla 6.0) e in casi simili, notifica indicando il motivo. Con RS_PRN_HOOK=syscall può registrare tramite un tracepoint, al prezzo di rallentare leggermente tutte le chiamate di sistema.

Il registro si trova in /var/lib/roamswitch/prn/ (0700, file 0600, di root) e non compare in notifiche, pacchetti di prove, MCP né inoltro degli eventi. Non si vedono: un percorso che restituisce byte casuali senza chiamata di sistema (glibc 2.41 e successive che usano il vDSO per getrandom()) e RDRAND eseguito nello spazio utente. Su x86-64 il parametro del kernel vdso=0 disattiva il percorso vDSO.

Lo stato si vede con sudo roamswitch-prn-recorder status. sudo roamswitch-prn-recorder export --output FILE [--since-hours N] [--pid PID] scrive i registri non scaduti in formato JSON Lines memento.prn/v1 in un nuovo file 0600. La scadenza non si applica al file esportato, quindi eliminatelo in modo sicuro quando avete finito. sudo roamswitch-prn-recorder purge elimina subito tutti i registri.

Il registro contiene anche i segreti delle sessioni TLS e SSH dell'host. Se root viene preso, le chiavi del traffico entro il limite possono essere ricostruite. Non impostare scadenza e dimensione oltre il necessario.

23. Strumenti separati inclusi (AccessScope, PersonalSOC, PathScope)

I pacchetti deb e rpm della Server Edition installano in /usr/bin/ i comandi di tre strumenti separati da RoamSwitch (AccessScope, PersonalSOC e PathScope). Le app con finestra e WebKitGTK non sono incluse. La licenza è Apache License 2.0 e gli strumenti non rientrano nel contratto di licenza con l'utente finale (EULA) di RoamSwitch. Si aggiornano con l'aggiornamento del pacchetto RoamSwitch.

ComandoCosa fa
accessscopeTrova i tentativi di attacco nei log di accesso del server web e di SSH, con le righe di log come prova. È in sola lettura, e la diagnosi non usa né un LLM né la rete. accessscope discover elenca le posizioni dei log, accessscope scan --auto esegue la diagnosi e accessscope fleet riunisce più host. Per i dettagli, vedere il manuale d'uso di AccessScope.
personalsocControlla i log di questo host e i rilevamenti di RoamSwitch (MCP) e ne ricava un elenco di rilevamenti o un report. Si esegue come root, ad esempio con sudo personalsoc scan. personalsoc scan --report produce un report Markdown, mentre --format json e --format sarif producono un output per le macchine. --fail-on high termina con il codice 3 in caso di rilevamento high. Solo se si aggiunge --llm, il riepilogo e le righe di prova vengono passati al comando LLM scelto (fuori dall'ambito di Zero Telemetry). Per i dettagli, vedere il manuale d'uso di PersonalSOC.
pathscopeTrova i percorsi dagli utenti normali fino a root e ai dati sensibili e indica l'ordine in cui correggerli. È in sola lettura e non chiama alcun LLM. pathscope analizza i percorsi dall'utente attuale a root. pathscope --baseline=precedente.json --fail-on=new termina con il codice 1 se i percorsi sono aumentati. sudo pathscope --check-agent-users analizza insieme gli account di agent_users. Per i dettagli, vedere il manuale d'uso di PathScope.

Le app con finestra (accessscope-app, personalsoc-app e pathscope-gui) sono incluse solo nei pacchetti della Client Edition.

← Whitepaper di Server Edition Alla pagina di installazione Linux →