ROAMSWITCH SERVER 1.1.0+ · Dernière mise à jour : 2026-09-18

Manuel d'utilisation de RoamSwitch Server Edition

Installation officielle, déploiement et référence opérationnelle pour Cloud VPS (AWS, GCP, Azure, Linode, DigitalOcean), les centres de données nus et les hôtes de conteneurs.

1. Présentation et exigences

RoamSwitch Server Edition est une suite autonome de surveillance de la défense et de l'intégrité sans tête (zéro dépendance graphique) conçue pour les serveurs Linux exposés à l'Internet public.

Contrairement à l'édition client qui change dynamiquement de profil en fonction de l'état du Wi-Fi, l'édition serveur applique Inbound Default Drop, la surveillance de l'intégrité des fichiers du chemin critique (FIM), l'atténuation préventive LPE du noyau (Frag Gap), la détection des menaces d'exécution eBPF, la prévention du verrouillage SSH et les alertes d'urgence multicanaux automatisées (Telegram / LINE / Webhook) .

Architecture zéro télémétrie
RoamSwitch ne transmet aucune télémétrie de diagnostic, métadonnées IP de l'hôte, hachages de fichiers ou journaux système aux serveurs externes. Les bibliothèques réseau externes sont absentes du binaire du démon, garantissant une confidentialité totale sur site.

Configuration système requise

2. Procédures d'installation

L'utilisation des référentiels officiels signés garantit une résolution automatique des dépendances et des mises à jour transparentes via votre gestionnaire de packages système standard.

2.1 APT (système d'exploitation Ubuntu / Debian / Raspberry Pi)

# 1. Enregistrer la clé de signature du dépôt
curl -fsSL https://lafine.net/apt/roamswitch-archive-keyring.asc \
  | sudo gpg --dearmor -o /usr/share/keyrings/roamswitch-archive-keyring.gpg

# 2. Ajouter le dépôt
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. Installer
sudo apt update && sudo apt install roamswitch-server

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

# 1. Importer la clé GPG
sudo rpm --import https://lafine.net/rpm/RPM-GPG-KEY-roamswitch

# 2. Ajouter le fichier de configuration du dépôt
sudo curl -fsSL -o /etc/yum.repos.d/roamswitch.repo https://lafine.net/rpm/fedora/roamswitch.repo

# 3. Installer
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
Forfait Exclusion Mutuelle (Conflits)
Les éditions Client (roamswitch) et Server (roamswitch-server) déclarent des conflits de packages réciproques. Sélectionnez toujours roamswitch-server sur les environnements de serveur sans tête.

3. Configuration initiale et vérification du service

3.1 État des services

Après l'installation, roamswitch-server.service démarre immédiatement et est activé au démarrage du système.

sudo systemctl status roamswitch-server.service

3.2 Assistant de configuration interactif

Exécutez l'assistant de configuration interactif ci-dessous pour configurer les ports, les IP source de maintenance, les canaux de notification et l'action de confinement de façon interactive (appuyez sur Entrée pour accepter chaque valeur par défaut).

sudo roamswitch server setup
  1. Ports : saisissez les ports de maintenance SSH (par défaut 22) et les ports de service publics (par défaut 80,443), séparés par des virgules.
  2. IP source de maintenance : indiquez les IP/CIDR du bastion SSH ou de supervision (ex. 203.0.113.50/32) ; laissez vide pour autoriser SSH depuis n'importe quelle IP.
  3. Canaux de notification : activez le bot Telegram, l'API Messaging LINE et/ou un webhook générique (Slack / Discord / Teams).
  4. Réaction à un événement eBPF critique : choisissez isolate (isoler l'hôte), freeze (geler le processus) ou alert_only (notification uniquement). Après l'enregistrement, il vous est proposé d'envoyer une notification de test et de redémarrer le service.
  5. Mises à jour automatiques des données CVE du noyau (par défaut n) : choisissez si la base de données CVE du noyau utilisée par l'audit d'isolation des conteneurs doit être récupérée anonymement depuis lafine.net une fois par jour (sans chaîne de requête, cookies ni en-têtes identifiants). L'audit continue de fonctionner sur la base intégrée si l'option reste désactivée. C'est la seule exception à la politique « zéro code réseau » de Server Edition, et elle est désactivée par défaut (opt-in).
  6. Paramètres du File Scan Guard : choisissez d'activer ou non l'analyse antivirus pour les relais de messagerie, les dossiers partagés et les destinations de téléversement (§13), et définissez les répertoires cibles. Facultatif, désactivé par défaut.
  7. Paramètres du Resource Guard : activez la garde d'épuisement des ressources qui détecte une croissance RSS soutenue (fuite mémoire/DoS) ou des boucles de plantage dans les services exposés au réseau.
  8. Présentation des protections principales toujours actives : affiche les défenses principales qui fonctionnent en permanence indépendamment de l'assistant — rejet entrant par défaut, FIM, intégration eBPF, etc. (aucune saisie requise).
  9. Paramètres de délégation à un agent d'investigation (investigation) : choisissez de déléguer ou non automatiquement l'investigation initiale — pour les événements eBPF critiques, ou les détections d'altération de FIM Critical-Path/fichiers de verrouillage de dépendances, lorsqu'elles n'ont donné lieu qu'à une notification — à une CLI d'agent IA externe (Claude Code / agy / Codex CLI / OpenCode, ou une commande personnalisée) (§10.1). Désactivé par défaut.
Remarque sur l'ID de chat Telegram
L'ID de chat d'un super-groupe est un nombre négatif qui commence par -100 (ex. -1001234567890). Vérifiez la valeur correcte dans le champ "chat":{"id":...} de la réponse de curl -s "https://api.telegram.org/bot<token>/getUpdates".

3.3 Audit de sécurité du serveur en 30 éléments

sudo roamswitch status --server

Effectue un audit instantané de 30 vérifications des règles de pare-feu, de l'atténuation Frag Gap, des restrictions Yama LSM, des autorisations et de l'exposition du port Docker, produisant un score et une note de sécurité de 0 à 100 (S à C).

4. Règles de pare-feu et de port

Le fichier de configuration /etc/roamswitch/server.conf est soumis à des permissions 0600 obligatoires (lecture/écriture root uniquement) pour protéger les informations sensibles. Le format est un clé=valeur à plat ; les en-têtes de section comme [network] sont ignorés.

# --- Pare-feu ---
ssh_ports=22                     # Port de gestion SSH (conservé même lors d'une isolation d'urgence)
allowed_ports=80,443             # Ports de service publics
whitelist_ips=203.0.113.10/32    # IP/CIDR source de maintenance (vide = tout autorisé, anciennement admin_source_ips)
protect_docker_ports=true        # Protection DOCKER-USER (empêche les conteneurs de contourner le pare-feu)
preserve_ssh_on_isolation=true   # Préserve la voie de gestion SSH même lors d'une isolation d'urgence (false = coupure totale)

# --- Garde d'exécution eBPF ---
action_on_critical=isolate       # isolate | freeze (SIGSTOP+coupure réseau) | alert_only
ebpf_socket_path=/run/roamswitch/events.sock

# --- Blocage Egress/C2 et sinkhole DNS ---
egress_ip_blocklist_enabled=true # Par défaut true. Sans effet tant qu'aucun flux n'est fourni (ne bloque rien)
dns_sinkhole_enabled=false       # Par défaut false (pour ne pas casser le DNS interne/les configurations split-horizon)
dns_sinkhole_provider=quad9      # quad9 | cloudflare | adguard | cleanbrowsing

# --- Données CVE d'isolation des conteneurs (opt-in) ---
cve_kernel_map_updates_enabled=false # Par défaut false. La seule exception de communication externe (une fois par jour, anonyme)

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

# --- Système ---
language=ja
fim_check_interval_secs=300      # Anciennement nommé scan_interval

Après une modification directe du fichier, redémarrez le service pour appliquer les changements (roamswitch-server ne prend pas en charge le rechargement) :

sudo roamswitch server restart

4.1 Politique par niveau de gravité (guard.yaml, optionnel)

Si action_on_critical seul n'offre pas assez de granularité, créez /etc/roamswitch/guard.yaml (un modèle est fourni dans /etc/roamswitch/guard.yaml.example). En son absence, une politique équivalente est automatiquement synthétisée à partir de action_on_critical dans server.conf, sans impact sur les déploiements existants.

policies:
  on_warning:
    action: log_and_notify
  on_critical:
    server_action: isolate_process
    kill_process: true
    fallback_to_host_isolation_after_retries: 3   # Bascule automatiquement vers l'isolation de l'hôte si le même processus se reproduit
  on_emergency:
    action: isolate_host_all
    kill_process: true

server_safeguards:
  maintenance_ssh_ports: [22]
  safety_timer_secs: 300   # Restaure automatiquement après ce nombre de secondes suivant l'isolation si aucun ack n'arrive (0 désactive)

Minuterie de sécurité : une fois qu'une isolation de l'hôte (Air-Gap) se déclenche, l'administrateur enquête puis l'acquitte avec la commande ci-dessous. Sans accusé de réception dans le délai safety_timer_secs, RoamSwitch restaure automatiquement l'accès réseau afin qu'un faux positif ne laisse pas le serveur coupé indéfiniment.

sudo roamswitch server ack

4.2 Blocage Egress / C2 et sinkhole DNS

Avec egress_ip_blocklist_enabled=true (par défaut), les connexions sortantes vers des IP connues comme malveillantes sont bloquées via nftables. Le flux /var/lib/roamswitch/threatfeed/malicious_ips.txt (géré par le mécanisme de mise à jour) est utilisé en priorité, avec repli sur le seed vide fourni avec le paquet (/usr/share/roamswitch/threatfeed/) — donc tant qu'aucun flux n'est réellement fourni, la valeur par défaut true ne bloque rien.

Activer dns_sinkhole_enabled=true force la résolution via un résolveur DNS filtrant (Quad9 / Cloudflare / AdGuard / CleanBrowsing), bloquant la résolution de domaines connus comme malveillants. La valeur par défaut est false, car cela peut casser le DNS interne ou les configurations split-horizon.

4.3 Garde de détection de scan de ports entrants

Détecte les IP source qui se sont connectées à de nombreux ports distincts en peu de temps, en corrélant les règles de journalisation nftables avec journald (activé par défaut). Les sources de scan à haute confiance peuvent être automatiquement bloquées pendant une durée définie. Utilisé avec RoamSwitch Sensor (une fonction différente du §10.1 — les sondes d'audit complet des ports d'un Sensor appairé sont exclues pour atténuer les faux positifs), l'IP du Sensor lui-même est automatiquement exclue.

# --- Détection de scan de ports entrants (activée par défaut) ---
port_scan_detect_enabled=true              # false pour désactiver
port_scan_detect_min_distinct_ports=15     # Jugé comme un scan lorsque les connexions atteignent ce nombre de ports distincts
port_scan_detect_window_secs=300           # Fenêtre d'agrégation pour la détection (secondes)
port_scan_block_enabled=true               # Bloque automatiquement l'IP source du scan détecté
port_scan_block_duration_secs=600          # Durée du blocage automatique (secondes)

Vous pouvez consulter l'historique de détection avec la commande roamswitch port-scan.

5. Sécurité intégrée de prévention du verrouillage SSH

Un verrouillage accidentel dû à une mauvaise configuration du pare-feu est un désastre opérationnel intolérable. RoamSwitch Server Edition intègre des protections à plusieurs niveaux :

6. Protection des conteneurs (Docker / Podman)

Le comportement par défaut de Docker crée des règles iptables personnalisées qui contournent les pare-feu hôtes standard, exposant les ports de conteneur (par exemple -p 8080:8080) directement à Internet.

Lorsque protect_docker_ports=true (par défaut), RoamSwitch insère des règles d'inspection en tête de la chaîne DOCKER-USER, afin que le trafic destiné aux conteneurs respecte aussi la politique allowed_ports et whitelist_ips. Cela empêche efficacement l'exposition accidentelle de conteneurs comme une base de données de développement.

De plus, une protection en temps réel surveille les docker events et vous avertit dès qu'un conteneur démarre en --privileged ou avec un montage de /var/run/docker.sock — un risque d'évasion de conteneur. Aucune configuration requise, toujours actif, et notification uniquement (pas de blocage automatique).

7. Surveillance de l'intégrité des fichiers du chemin critique (FIM)

Surveille plus de 150 binaires essentiels (/bin/login, /usr/bin/sudo, /usr/sbin/sshd), configurations d'authentification (/etc/shadow, /etc/pam.d/) et unités systemd à l'aide de hachages SHA-256.

7.1 Vérification manuelle du hachage

sudo roamswitch fim verify

7.2 Détection événementielle (instantanée)

Les fichiers surveillés sont individuellement observés via fanotify (FAN_CLASS_NOTIF, événements de fin d'écriture), de sorte qu'une altération est re-hachée et détectée à l'instant même où elle se produit, sans attendre le prochain scan périodique. Le scan périodique (par défaut fim_check_interval_secs=300 secondes) reste en place comme filet de sécurité pour les événements manqués.

7.3 Synchronisation de base automatique sur les mises à jour du système d'exploitation

Sur Debian/Ubuntu, l'installation d'un paquet configure automatiquement le hook DPkg::Post-Invoke dans /etc/apt/apt.conf.d/99roamswitch-fim. Sur Fedora/RHEL/Rocky/AlmaLinux/openSUSE, une unité systemd.path (roamswitch-fim-update.path) surveillant /var/lib/rpm joue le même rôle.

Sur Debian/Ubuntu, /etc/apt/apt.conf.d/99roamswitch-fim attache un hook DPkg::Post-Invoke. Les mises à jour légitimes des packages via sudo apt upgrade actualisent automatiquement la base de référence FIM, éliminant ainsi les fausses alertes positives.

sudo roamswitch fim update

8. Intégration eBPF Runtime Guard et Falco

S'accroche aux événements eBPF de l'espace noyau (Falco / Tetragon) pour détecter l'élévation des privilèges du noyau Frag Gap, les échappements de conteneurs et les shells inversés non autorisés.

8.1 Architecture anti-ballonnement

Les agents de sécurité traditionnels souffrent d’une grave explosion du syslog et de l’usure des disques. RoamSwitch se connecte directement à Falco via un socket de domaine UNIX dédié (/run/roamswitch/events.sock) :

8.2 Confinement autonome

Lors de la détection d'une attaque critique, RoamSwitch émet immédiatement SIGSTOP pour geler le PID du processus incriminé et applique l'isolation Air-Gap nftables.

9. Alertes d'urgence (Telegram / LINE / Webhook)

Envoie des alertes immédiates aux canaux de notification externes lorsque des anomalies de port, une falsification FIM ou des événements de confinement eBPF se produisent :

[notifications]
language = ja
# Telegram : jeton de bot et ID de chat
telegram_bot_token = "123456789:ABCdefGHIjklMNOpqrSTUvwxYZ"
telegram_chat_id = "-1001234567890"

# LINE : jeton d'accès au canal Messaging API et ID utilisateur
line_channel_access_token = "YOUR_LINE_ACCESS_TOKEN"
line_user_id = "U1234567890abcdef1234567890abcdef"

# Webhook générique (Slack, Discord, Teams, votre propre plateforme de supervision)
webhook_url = "https://hooks.slack.com/services/T00/B00/XXXXX"

Même sans configurer ces canaux externes, chaque alerte envoyée est également conservée localement pendant les 7 derniers jours. Consultez-la avec roamswitch notifications.

10. Intégration de l'agent AI / MCP (Protocole de contexte de modèle)

RoamSwitch Server Edition inclut roamswitch-mcp, permettant aux agents d'IA (Claude, Gemini, Cursor) de surveiller l'état et la posture de l'infrastructure.

Garantie de sécurité en lecture seule
Pour empêcher les attaques par injection rapide de compromettre l'infrastructure, l'interface MCP est strictement en lecture seule. Les agents IA ne peuvent pas ouvrir de ports, supprimer l'isolation ou modifier les configurations de sécurité via MCP. La correction nécessite un accès au shell TTY local authentifié.

Exemple de configuration (`claude_desktop_config.json`)

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

10.1 Délégation à un agent d'investigation (investigation — délégation de l'investigation automatisée initiale à un agent IA)

Alors que le roamswitch-mcp du §10 répond aux requêtes d'un client IA humain, la délégation investigation est un mécanisme distinct où le démon lui-même lance de manière autonome une CLI d'agent IA externe, déclenchée par un événement de détection. Elle cible les événements eBPF critiques jugés notification uniquement (n'ayant pas déclenché d'isolation automatique ni de gel de processus), ainsi que les détections d'altération de FIM Critical-Path et de fichiers de verrouillage de dépendances. Une fois activé, le démon génère d'abord un rapport de triage initial heuristique local (probabilité de faux positif, raisonnement, prochaines étapes suggérées), puis lance la CLI d'agent IA configurée en tant que sous-processus avec ce rapport joint, déléguant l'investigation et le résumé supplémentaires. Désactivé par défaut.

# À ajouter à /etc/roamswitch/guard.yaml (un fichier distinct de server.conf)
investigation:
  enabled: true
  command: "claude"                 # "claude" | "agy" | "codex" | "opencode" | toute commande personnalisée
  args: ["-p"]                      # Le prompt est automatiquement ajouté en tant que dernier argument
  timeout_secs: 180

Les mêmes paramètres peuvent également être configurés depuis l'assistant interactif de sudo roamswitch server setup (§3.2, dernière étape). Choisissez parmi les préréglages pour Claude Code (claude -p), agy (agy -p --dangerously-skip-permissions), Codex CLI (codex exec), OpenCode (opencode run), ou une commande personnalisée. Lors d'une nouvelle exécution, le préréglage correspondant est sélectionné automatiquement à partir de la configuration enregistrée.

Remarque sur l'injection de prompt
La délégation investigation transmet les détails de l'événement de détection — noms de processus, chemins de fichiers et autres chaînes qu'un attaquant peut partiellement contrôler — dans le cadre du prompt envoyé à l'agent IA. Configurer l'outil pour qu'il s'exécute dans un mode ignorant les vérifications d'autorisation, comme --dangerously-skip-permissions, augmente le risque qu'une saisie malveillante amène l'agent à effectuer des actions non voulues. L'assistant affiche cet avertissement lors de la sélection d'agy. Dans les environnements présentant un chemin d'entrée de journaux non fiable, nous recommandons une configuration d'outil qui n'ignore pas les vérifications d'autorisation.

La délégation investigation n'est jamais invoquée lorsque le réseau est coupé (par exemple lors d'un Air-Gap actif, ou de tout état équivalent à isolate_host_all).

11. Aide-mémoire des commandes CLI

Commande Privilèges Descriptif
sudo roamswitch status --server root Afficher le score de posture du serveur en 30 éléments et vérifier la répartition
sudo roamswitch ports root Auditer les ports d'écoute ouverts et les processus liés
sudo roamswitch fim verify root Vérifier l'intégrité SHA-256 des fichiers système du chemin critique
roamswitch notifications Utilisateur Affiche l'historique des notifications (toutes les alertes envoyées) des 7 derniers jours
sudo roamswitch server setup root Lancer l'assistant de configuration initiale interactif
sudo roamswitch fim update root Actualiser la base de données de base FIM SHA-256
sudo roamswitch server config set <key> <value> root Modifie et enregistre une seule clé de configuration (liste au §4)
sudo roamswitch airgap enable / disable root Déclenche / lève manuellement la coupure d'urgence Air-Gap
sudo roamswitch emergency-restore Racine Désarme toute isolation eBPF/pare-feu et restaure la base de référence initiale
roamswitch port-scan Utilisateur Affiche l'historique de détection de la garde de détection de scan de ports entrants (§4.3) (IP source, blocage automatique ou non, durée du blocage)
roamswitch sensor [key|list|pair|unpair|request-audit|results] Utilisateur/root Confiance mutuelle par code d'appairage avec RoamSwitch Sensor. pair --addr <ip> --code <code> pour s'appairer, request-audit pour demander un audit actif de vulnérabilités (récupérer le résultat avec results). Nécessite sensor_pairing_enabled: true (désactivé par défaut). Voir le manuel d'exploitation Sensor pour plus de détails

12. Dépannage et FAQ

T1. RoamSwitch déconnectera-t-il inopinément ma session SSH ?

Non. RoamSwitch autorise inconditionnellement les états de connexion ESTABLISHED/RELATED ainsi que ssh_ports (par défaut 22). Même lors d'une isolation d'urgence Air-Gap déclenchée par une attaque grave, preserve_ssh_on_isolation=true (par défaut) préserve votre session d'administration.

Q2. Comment puis-je récupérer l’accès en cas de verrouillage accidentel ?

Connectez-vous via la console web de votre fournisseur cloud (VNC / console série), puis exécutez sudo roamswitch emergency-restore pour lever l'isolation, ou sudo systemctl stop roamswitch-server pour arrêter le service.

Q3. Comment puis-je exposer les ports pour les services Web nouvellement ajoutés (par exemple Nginx) ?

Exécutez sudo roamswitch server config set allowed_ports 80,443,3000 (ou modifiez directement /etc/roamswitch/server.conf), puis sudo roamswitch server restart.

13. File Scan Guard (protection des relais de messagerie, dossiers partagés et points de dépôt de fichiers)

Fonctionnalité optionnelle pertinente uniquement si cet hôte possède un répertoire stockant des fichiers destinés à des tiers — un relais de messagerie, un partage Samba/NFS, un point de dépôt d'upload. Le moteur YARA intégré analyse en permanence clamav_scan_dirs sans dépendance externe ; activer clamav_enabled=true ajoute ClamAV comme second avis. Les menaces confirmées sont automatiquement mises en quarantaine dans /var/lib/roamswitch/quarantine et l'opérateur est averti.

# --- File Scan Guard (ClamAV, opt-in) ---
# Le moteur YARA intégré analyse toujours clamav_scan_dirs sans condition.
clamav_enabled=false             # true active une inspection supplémentaire via clamdscan
clamav_scan_dirs=                # Chemins absolus à analyser (séparés par des virgules)
clamav_scan_interval_secs=86400  # Intervalle d'analyse (secondes, minimum 3600)
clamav_freshclam_interval_secs=7200  # Intervalle de mise à jour automatique de la base de signatures (secondes, minimum 1800)

Également configurable via l'assistant interactif sudo roamswitch server setup ; vérifiez sa configuration et l'état de la quarantaine via l'outil MCP get_file_scan_guard_status.

14. Log Audit (détection et notification des anomalies de motifs de journaux)

Une analyse périodique de journalctl transforme les messages de journal en modèles afin de détecter de nouveaux motifs (des formes de journal jamais vues auparavant) et des anomalies de fréquence (un pic statistique, Z-score > 3,0). Ce mécanisme léger ne nécessite aucun démon supplémentaire ni dépendance externe, il est donc activé par défaut. Les détections sont envoyées via les mêmes canaux de notification que File Scan Guard et FIM (Telegram / LINE / Webhook). Toute clé API ou tout jeton susceptible d'apparaître dans une ligne de journal est automatiquement masqué avant d'être inclus dans la notification.

# --- Log Audit (activé par défaut) ---
log_audit_enabled=true           # false pour désactiver
log_audit_interval_secs=1800     # Intervalle d'analyse en secondes (minimum 300)

Peut également être configuré depuis l'assistant interactif sudo roamswitch server setup, et les derniers résultats de détection peuvent être consultés via la commande CLI roamswitch audit-logs ou l'outil MCP audit_security_logs.

← Livre blanc Server Edition Vers la page d'installation Linux →