Manuel d'exploitation RoamSwitch Sensor

Le guide d'installation et d'exploitation de RoamSwitch Sensor — un capteur réseau qui, une fois placé sur votre LAN, détecte les nouveaux appareils et l'usurpation sur le même segment, et exécute des audits actifs de vulnérabilités sur tout terminal déjà équipé de RoamSwitch (Mac / Linux Client / Server Edition). Distribué via des paquets apt/dnf.

1. Présentation & positionnement

RoamSwitch (Mac / Linux Client / Server Edition) est, dans tous les cas, un agent résidant sur l'hôte. Cette forme comporte deux angles morts structurels.

• L'auto-diagnostic d'un hôte isolé comporte un angle mort fondamental : le risque de mouvement latéral — « fermé vers l'extérieur, mais totalement exposé depuis un autre appareil du même LAN » — ne peut jamais être détecté par un hôte qui ne s'observe que lui-même.
• Certains appareils ne pourront jamais exécuter RoamSwitch : appareils IoT (caméras réseau, prises connectées, imprimantes multifonctions), appareils invités/BYOD, équipements réseau eux-mêmes, appareils embarqués, etc.

RoamSwitch Sensor est un nœud dédié placé sur le LAN, dans le but de combler ces deux angles morts. Ce qui est réellement implémenté et vérifié aujourd'hui se limite à deux choses : des audits actifs de vulnérabilités sur les terminaux équipés de RoamSwitch sur le même LAN, et la détection passive de l'apparition de nouveaux appareils et de l'usurpation, pilotée par la propre table ARP de Sensor (comme indiqué au §6, il ne s'agit pas d'une fonction qui scanne activement et rend visible chaque appareil du LAN). Il n'est pas conçu comme un EDR, mais comme un NDR léger (Network Detection & Response) combiné à un scanner de vulnérabilités à preuve d'exploitation développé en interne.

L'autodéfense n'est délibérément pas implémentée (un choix de conception assumé). Si vous devez protéger l'hôte du Sensor lui-même contre les attaques, nous recommandons d'installer séparément RoamSwitch for Linux Server Edition sur la même machine. Les deux s'exécutent en tant que processus totalement indépendants et coexistent sans conflit.

2. Environnement de vérification actuel

• OS pris en charge : Debian 12 (bookworm) ou ultérieur / Ubuntu 22.04 ou ultérieur (apt), famille Fedora/RHEL (dnf). Uniquement x86_64 (amd64) — arm64 n'est pas encore pris en charge.
• Matériel cible (plan futur) : pour une exploitation réelle, nous envisageons un appareil basse consommation adapté au fonctionnement continu, comme un mini PC sans ventilateur de la gamme N100/N150, mais aucune construction ni livraison dédiée à cet effet n'est proposée aujourd'hui.
• Emplacement réseau : doit être connecté physiquement ou logiquement au segment LAN surveillé (roamswitch-sensor.service s'exécute sur le réseau hôte — nécessaire pour observer directement la table ARP). Il doit en outre fonctionner avec une adresse IP fixe (attribution statique, ou réservation côté serveur DHCP) afin que les terminaux puissent le joindre pour s'appairer et demander des audits. Il écoute sur le port TCP 50543.
• Consommation de ressources : quelques dizaines de Mo de mémoire résidente ; charge CPU au repos extrêmement faible.
• Optionnel : nmap (utilisé pour les diagnostics complémentaires NSE ; toutes les autres fonctions fonctionnent normalement sans lui).

3. Installation & démarrage

Installez le paquet roamswitch-sensor depuis le dépôt officiel signé. Après l'installation, roamswitch-sensor.service (systemd) est automatiquement activé et démarré.

3.1 APT (Ubuntu / Debian)

# 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 [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-sensor

3.2 DNF / RPM (Fedora / RHEL)

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

3.3 Vérification du démarrage

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

3.4 Exécution du CLI / TUI

Le CLI (roamswitch-sensor) et le TUI interactif (roamswitch-sensor-tui) peuvent être exécutés directement après l'installation.

sudo roamswitch-sensor status
sudo roamswitch-sensor-tui

4. Appairage (méthode par code)

À sa sortie d'usine, Sensor ne fait confiance à rien. L'appairage se fait à l'aide d'un code d'appairage à usage unique émis par l'opérateur du Sensor. La relation de confiance — « Sensor est autorisé à exécuter des audits actifs de vulnérabilités contre ce terminal » — s'établit simultanément dans les deux sens en une seule étape d'appairage (il n'existe pas d'état de confiance à sens unique).

Prérequis : faites fonctionner Sensor avec une adresse IP fixe (attribution statique, ou réservation côté serveur DHCP). Une fois l'appairage effectué, le terminal se connecte désormais toujours directement à l'adresse IP de Sensor constatée lors de l'appairage (il n'y a plus de découverte automatique, via mDNS ou autre) ; si l'IP de Sensor change par la suite, un nouvel appairage sera nécessaire. Le terminal peut, lui, conserver une IP dynamique.

4.1 Émettre un code d'appairage (côté Sensor)

# À exécuter côté Sensor (ou appuyer sur c dans le TUI)
sudo roamswitch-sensor issue-code

Un code à usage unique de 8 caractères est émis (lettres majuscules et chiffres, à l’exclusion des caractères facilement confondus 0/O/1/I/L). Il expire 10 minutes après son émission et ne peut être utilisé qu’une seule fois : transmettez-le donc rapidement à l’opérateur du terminal par un canal hors bande quelconque (de vive voix, par chat, etc.).

4.2 Appairage avec le code (côté terminal)

# Côté terminal (roamswitch-linux)
sudo roamswitch sensor pair --addr <adresse IP fixe du Sensor> --code <code d'appairage>

Dans l'édition Mac, la même opération est disponible via l'interface graphique, sous « 🔍 Appairage RoamSwitch Sensor… » dans la barre de menus, où vous saisissez l'adresse IP et le code d'appairage du Sensor.

Une fois l'appairage réussi, chaque audit actif de vulnérabilités et chaque récupération de résultat d'audit sont désormais authentifiés par une signature Ed25519. Le terminal qui connaissait le code et le Sensor qui l'a émis se font alors mutuellement confiance.

4.3 Appairage manuel (enregistrement direct d’une clé publique déjà connue)

Si l'opérateur du Sensor connaît déjà, par un autre canal, la clé publique et l'adresse d'un terminal, il peut aussi l'enregistrer directement côté Sensor sans échanger de code d'appairage (il est en principe préférable d'utiliser la méthode par code du §4.2 et de laisser le terminal s'appairer lui-même). Vous pouvez consulter votre propre clé publique et votre adresse avec les commandes suivantes.

# Vérifier sa propre clé publique/adresse côté terminal
sudo roamswitch sensor key

# Vérifier sa propre clé publique/adresse/adresse MAC côté Sensor
sudo roamswitch-sensor status

# Côté Sensor
sudo roamswitch-sensor pair <clé publique complète> --addr <adresse IP> --confirm

5. Audit actif des vulnérabilités

Sensor exécute des diagnostics de vulnérabilité non destructifs et à preuve d'exploitation sur les terminaux appairés. Il n'effectue jamais d'opération destructive (écriture ou suppression de données, arrêt de services).

sudo roamswitch-sensor scan <clé publique ou son début>

L'audit se compose de quatre phases.

1. Analyse complète des ports : détecte de façon exhaustive tous les ports TCP ouverts sur l'hôte cible.
2. Diagnostic de signatures connues : vérifications non destructives et à preuve d'exploitation de schémas de vulnérabilité connus — exposition non authentifiée de Redis / dockerd / Memcached / MongoDB / Elasticsearch / CouchDB / Jenkins / VNC, diagnostic de relais ouvert SMTP (une méthode sûre qui n'envoie que MAIL FROM/RCPT TO, jamais DATA), et diagnostics de mauvaise configuration CORS, de traversée de répertoires et de redirection ouverte sur les serveurs de développement, entre autres.
3. Récupération générique de bannière : pour les ports ouverts non couverts par les signatures ci-dessus, récupère la chaîne de bannière par simple connexion (aucune donnée n'est envoyée).
4. Diagnostic complémentaire nmap NSE : diagnostic complémentaire à large couverture de protocoles via nmap --script safe. S'exécute automatiquement dès que nmap est installé sur l'hôte (sans effet dans le cas contraire).

Chaque exécution d'audit est enregistrée dans /var/lib/roamswitch-sensor/scan_history.json — que quelque chose ait été détecté ou non, car un résultat propre à ce moment-là a aussi une valeur d'archive — et peut être consultée via le CLI ou le TUI.

roamswitch-sensor history
sudo roamswitch-sensor report <clé publique ou son début> --out /tmp/report.md

5.1 Demande d’audit depuis le client (modèle pull)

Un terminal appairé peut aussi demander activement un audit à Sensor. Dans l’édition Mac, utilisez « Demander un audit au Sensor » dans la barre de menus ; sous Linux, utilisez la commande suivante.

sudo roamswitch sensor request-audit

Une fois l’audit exécuté par Sensor, le terminal interroge le résultat à partir de 5 minutes après la demande, puis toutes les 5 minutes, jusqu’à 5 tentatives (soit 25 minutes maximum au total). Tout résultat récupéré est également enregistré localement sur le terminal.

roamswitch sensor results

Dans l’édition Mac, les résultats apparaissent aussi dans la liste « Résultats d’audit » de la fenêtre de réglages, ou peuvent être lus via l’outil MCP get_sensor_audit_results, comme donnée d’entrée pour un agent IA élaborant un plan de remédiation. La récupération d’un résultat peut aussi être explicitement refusée, par exemple si l’appairage a été révoqué côté Sensor (voir §10 Q6).

6. Surveillance ARP passive & visibilité LAN

Sensor prend périodiquement un instantané de sa propre table ARP (équivalent à /proc/net/arp) et, en le comparant à l'instantané précédent, détecte deux types d'événements : une nouvelle adresse IP/MAC jamais vue auparavant, et un changement d'adresse MAC pour une IP déjà connue (signe, par exemple, d'une usurpation de passerelle). Il n'envoie jamais de paquets de façon active et ne couvre que les appareils avec lesquels Sensor a déjà communiqué d'une manière ou d'une autre (ce n'est pas une fonction qui découvre et énumère activement chaque appareil du LAN). Il n'a aucune capacité à classer le type d'appareil (par exemple, s'il s'agit d'un appareil IoT) — il détecte uniquement un changement d'IP/MAC.

roamswitch-sensor arp-events

Les événements détectés peuvent aussi être listés depuis l'onglet « ARP Events » du TUI, qui distingue deux types : « nouvel appareil apparu » et « adresse MAC d'une IP connue modifiée (suspicion d'usurpation) ».

6.1 Extension de la visibilité LAN passive (opt-in)

Alors que la surveillance ARP ci-dessus ne couvre que les appareils avec lesquels Sensor a lui-même communiqué, définir la variable d'environnement ROAMSWITCH_SENSOR_PASSIVE_CAPTURE_IFACE sur une interface cible permet d'observer les en-têtes Ethernet/IPv4 sur celle-ci (sans inspection de la charge utile) pour détecter ce qui suit.

• Observation passive des nouveaux appareils : appareils avec lesquels Sensor n'a jamais communiqué directement, non couverts par la seule surveillance ARP. Appris à partir du trafic broadcast/multicast.
• Détection du contact avec des IP malveillantes connues : signale le trafic dont l'IP de destination correspond au flux de menaces local (même format que l'Egress Guard de RoamSwitch lui-même) — détection uniquement, jamais bloqué.

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

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

7. Référence des commandes CLI

Le CLI ne prend en charge que le japonais et l'anglais (il suit la variable d'environnement LANG).

8. Guide d'utilisation du TUI

Le TUI interactif (roamswitch-sensor-tui) prend en charge 10 langues. La touche Tab (Shift+Tab pour revenir) permet de passer d'un onglet à l'autre parmi six : Approuvé (dernier état d'audit de chaque point d'accès) / Appareils (tous les appareils du LAN, avec notes) / Événements ARP / Historique / Changements (ce qui a changé depuis l'audit précédent — nouvelles détections en rouge, résolues en vert, injoignable probable en jaune) / Journal (qui a approuvé ou exécuté quoi, et quand ; le résultat de la vérification de la chaîne de hachage est affiché en haut).

9. Modèle de confiance & conception de sécurité

• TOFU (Trust On First Use) : le code d'appairage lui-même n'est pas une preuve cryptographique de possession — il est confirmé par le jugement propre de l'opérateur, qui a reçu le code émis par l'opérateur du Sensor via un canal hors bande (de vive voix, par chat, etc.), à l'image de la confirmation mutuelle explicite de l'appairage Bluetooth. Dès qu'un appairage réussit, la légitimité de chaque sonde ou demande ultérieure est vérifiée par rapport à la clé publique échangée à ce moment-là.
• Conçu pour découvrir les failles qui permettraient une action destructive, sans jamais en exécuter une lui-même : chaque audit actif de vulnérabilités est non destructif (il n'écrit ni ne supprime jamais de données, et n'arrête jamais de service). Ce qui est détecté, ce sont les erreurs de configuration elles-mêmes — comme « inscriptible sans authentification » ou « fonctionne comme relais ouvert » — qui, si exploitées, permettraient une action destructive.
• Atténuation des faux positifs (exclusion de l'auto-audit) : une exclusion par correspondance d'IP source est intégrée afin que l'audit complet des ports effectué par un Sensor appairé lui-même ne soit pas confondu avec une reconnaissance par la garde de détection de scan de ports entrants (une fonction côté RoamSwitch). L'IP n'est utilisée que pour cette correspondance, uniquement pour éviter un blocage automatique — jamais pour la détermination de confiance elle-même.
• Rien n'est envoyé sans votre configuration : les informations sur les appareils découverts, les résultats d'audit et les événements ARP sont, par défaut, stockés uniquement dans le stockage local du Sensor et ne sont jamais envoyés à Lafine ni à un serveur tiers. Les notifications (webhook / syslog) et l'envoi au collecteur central décrits au §11 ne vont qu'aux destinations que votre organisation a configurées.

10. Dépannage & FAQ

Q1. La saisie d'un code d'appairage est rejetée.

Trois causes probables : (1) plus de 10 minutes se sont écoulées depuis son émission et le code a expiré — demandez à l'opérateur du Sensor d'en émettre un nouveau avec issue-code ; (2) une erreur de saisie du code (les caractères facilement confondus 0/O/1/I/L sont exclus dès l'émission, un code ne peut donc jamais les contenir) ; (3) l'adresse IP indiquée avec --addr ne correspond pas à l'adresse IP fixe actuelle du Sensor.

Q2. Le résultat du diagnostic complémentaire NSE est vide.

L'une de ces deux causes : (1) nmap n'est pas installé dans le conteneur ; (2) l'exécution a eu lieu, mais les scripts sûrs applicables aux ports cibles n'ont réellement produit aucune sortie. Le diagnostic complémentaire nmap NSE s'exécute automatiquement dès que nmap est installé sur l'hôte.

Q3. Combien de temps prend un audit complet ?

Une simple analyse complète des ports prend environ quelques dizaines de secondes, mais dès que nmap est installé sur l'hôte, le diagnostic complémentaire NSE s'y ajoute automatiquement et peut prendre jusqu'à environ 2 minutes selon le nombre de ports ouverts de la cible. Le TUI affiche en continu les secondes écoulées pendant l'exécution, vous pouvez donc suivre la progression en attendant.

Q4. J'ai appairé, mais je n'arrive toujours pas à lancer d'audit.

Causes probables : (1) sensor_pairing_enabled: true n'est pas défini côté terminal (désactivé par défaut) ; (2) l'adresse IP fixe du Sensor a changé après l'appairage, si bien que le terminal tente de joindre une adresse obsolète (un nouvel appairage résout ce problème) ; (3) l'appairage a été supprimé côté Sensor avec unpair. Vérifiez avec roamswitch sensor list (côté terminal) et roamswitch-sensor list (côté Sensor) que chacun reconnaît bien l'autre.

Q5. Sensor peut-il être utilisé en parallèle de RoamSwitch lui-même (Client/Server Edition) ?

Oui. Sensor étant conçu sans fonction d'autodéfense, nous recommandons d'installer également RoamSwitch for Linux Server Edition sur la même machine. Les deux fonctionnent avec des processus et des stockages de données totalement indépendants, sans conflit.

Q6. roamswitch sensor results indique que l’appairage a été révoqué.

L’appairage de ce terminal a été supprimé côté Sensor avec unpair. Demandez à l’opérateur du Sensor d’émettre un nouveau code d’appairage, puis réappairez avec roamswitch sensor pair --addr <ip> --code <code>.

11. Fonctions d'audit à l'échelle d'une organisation (optionnelles)

Un ensemble de fonctions pour les équipes de sécurité des grandes organisations qui ont besoin de preuves d'audit et d'une vue claire de ce qui a changé. Toutes sont désactivées par défaut, et rien n'est jamais envoyé à Lafine ni à un tiers : chaque destination de notification ou d'agrégation est choisie par votre organisation. Les réglages se modifient avec sudo roamswitch-sensor config set <clé> <valeur> (sans redémarrer le démon ; chaque modification est consignée dans le journal des opérations) ; config show affiche les valeurs actuelles.

11.1 Audits planifiés et détection des changements

En mettant schedule.enabled à true, tous les points d'accès appairés sont audités automatiquement (toutes les 24 heures par défaut : schedule.interval_hours ; plage horaire locale dans laquelle un audit peut démarrer : schedule.window_start_hour / window_end_hour, éventuellement à cheval sur minuit ; parallélisme : schedule.max_parallel). Chaque audit est comparé au précédent, et roamswitch-sensor diff affiche les nouvelles détections (régressions), les détections résolues et les ports nouvellement ouverts. Si tous les ports auparavant ouverts deviennent soudain invisibles, cela est signalé comme injoignable probable et non comme « résolu » : un hôte éteint ne se distingue pas, de l'extérieur, d'un hôte ayant fermé tous ses ports.

Les audits sans surveillance ne remettent pas en cause la garantie que seuls les points d'accès consentants sont audités. L'IP d'un point d'accès peut être attribuée à un autre appareil par le DHCP ; le Sensor conserve donc l'adresse MAC qu'avait le point d'accès lors de sa dernière authentification (appairage ou demande d'audit signée) et vérifie, avant et après chaque audit planifié, par une véritable requête ARP de nmap, que la même MAC répond toujours à cette IP. Sinon, l'audit est ignoré (ou son résultat écarté) et une notification est émise. Un scan manuel est lui aussi refusé s'il existe des indices que l'adresse appartient désormais à un autre appareil. Cette vérification exige nmap ; les points d'accès appairés avant cette fonction ne sont planifiés qu'après un nouvel appairage ou l'envoi d'une demande d'audit signée ; seuls les points d'accès du même segment L2 sont couverts.

11.2 Notifications (webhook et syslog)

Régressions, nouveaux appareils, usurpation ARP, trafic suspect, etc. sont envoyés à notify.webhook_urls (webhooks entrants de Slack, Discord ou Teams, ou tout point de réception JSON générique) et à notify.syslog.host / port / protocol (RFC 5424 sur UDP ou TCP). On peut restreindre avec notify.min_severity (info / medium / high / critical) et notify.cooldown_minutes (délai minimal avant de renvoyer le même événement). roamswitch-sensor notify-test vérifie chaque destination.

11.3 Export des preuves d'audit

roamswitch-sensor export <scans|inventory|audit-log|all> --format csv|json|html [--out fichier] [--endpoint préfixe-de-clé] [--since date]. La sortie html est un fichier unique et autonome : ouvrez-la dans un navigateur et choisissez « Enregistrer au format PDF » pour obtenir un PDF à remettre aux auditeurs. Le CSV est protégé contre l'injection de formules dans les tableurs. L'export de l'inventaire des appareils comprend une colonne indiquant si chaque appareil est géré par RoamSwitch (appairé). Les fichiers produits ne sont lisibles que par leur propriétaire (0600), et l'export lui-même est consigné dans le journal des opérations.

11.4 Journal des opérations et des approbations (infalsifiable)

Appairage, désappairage, début et fin des audits, modifications de configuration et accès refusés sont enregistrés avec leur auteur (UID / clé publique du point d'accès / IP source). Chaque ligne contient le SHA-256 de la précédente ; toute modification ou suppression est donc détectée par roamswitch-sensor audit-log verify (code de sortie 2 en cas de problème). La liste s'obtient avec roamswitch-sensor audit-log [--limit N]. Les URL de webhook contiennent souvent un jeton ; le journal des changements de configuration n'en conserve donc jamais la valeur. Une chaîne de hachage seule ne révèle pas que les entrées les plus récentes ont été coupées ; la tête de chaîne (numéro de séquence et hachage) est donc aussi envoyée au collecteur (§11.6).

11.5 Conservation

Renseignez retention.scan_history_days, retention.audit_log_days et retention.inventory_stale_days pour supprimer automatiquement l'ancien historique d'audit, les anciennes entrées du journal et les appareils non vus depuis longtemps (0 = aucune suppression par ancienneté, valeur par défaut). Les appareils ayant une note ne sont jamais retirés de l'inventaire.

11.6 Agréger plusieurs Sensors (collecteur central, optionnel)

Lorsque plusieurs Sensors fonctionnent sur plusieurs sites, exécutez roamswitch-sensor-collector (fourni dans le paquet, désactivé par défaut) sur un hôte distinct pour collecter les synthèses signées de chacun.

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

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

• Seules les requêtes signées (Ed25519) des Sensors enregistrés (enroll) sont acceptées ; l'horodatage permet en outre de rejeter les rejeux.
• TLS est obligatoire dès que le service est joignable depuis l'extérieur du LAN. Placez --bind 0.0.0.0:8443 --tls-cert … --tls-key … dans COLLECTOR_ARGS de /etc/default/roamswitch-sensor-collector, ou utilisez --allow-plain-http derrière un reverse proxy qui termine TLS. Écouter sur autre chose que 127.0.0.1 sans TLS est refusé au démarrage.
• Le tableau de bord est protégé par un jeton et propose un filtrage par site, les événements par gravité et l'export CSV. Il met en évidence les Sensors devenus silencieux ainsi que ceux dont le journal d'audit semble tronqué, revenu en arrière ou bifurqué (à lever avec clear-anomaly <clé-publique> après enquête).