Manual de Operaciones de RoamSwitch Sensor

La guía de instalación y operación de RoamSwitch Sensor, un sensor de red que, una vez colocado en su LAN, detecta nuevos dispositivos y suplantaciones en el mismo segmento, y ejecuta auditorías activas de vulnerabilidades contra cualquier endpoint que ya ejecute RoamSwitch (Mac / Linux Client / Server Edition). Distribuido mediante paquetes apt/dnf.

1. Descripción general y posicionamiento

RoamSwitch (Mac / Linux Client / Server Edition) es, en todos los casos, un agente residente en el host. Esta forma tiene dos puntos ciegos estructurales.

• El autodiagnóstico de un host aislado tiene un punto ciego fundamental: el riesgo de movimiento lateral —"cerrado hacia el exterior, pero totalmente expuesto desde otro dispositivo de la misma LAN"— nunca puede detectarlo un host que solo se observa a sí mismo.
• Algunos dispositivos nunca podrán ejecutar RoamSwitch: dispositivos IoT (cámaras de red, enchufes inteligentes, impresoras multifunción), dispositivos de invitados/BYOD, el propio equipo de red, dispositivos embebidos y más.

RoamSwitch Sensor es un nodo dedicado colocado en la LAN, con el objetivo de cerrar ambas brechas. Lo que realmente está implementado y verificado hoy se limita a dos cosas: auditorías activas de vulnerabilidades contra endpoints equipados con RoamSwitch en la misma LAN, y detección pasiva de la aparición de nuevos dispositivos y suplantaciones, impulsada por la propia tabla ARP de Sensor (como se indica en el §6, no es una función que escanee activamente y visualice cada dispositivo de la LAN). No está diseñado como un EDR, sino como un NDR ligero (Network Detection & Response) combinado con un escáner de vulnerabilidades de prueba de concepto desarrollado internamente.

La autodefensa se omite intencionalmente (una decisión de diseño deliberada). Si necesita proteger el propio host del Sensor frente a ataques, recomendamos instalar por separado RoamSwitch for Linux Server Edition en la misma máquina. Ambos se ejecutan como procesos totalmente independientes y coexisten sin conflicto.

2. Entorno de verificación actual

• SO compatible: Debian 12 (bookworm) o posterior / Ubuntu 22.04 o posterior (apt), familia Fedora/RHEL (dnf). Solo x86_64 (amd64); arm64 aún no es compatible.
• Hardware objetivo (plan futuro): para la operación real, contemplamos un dispositivo de bajo consumo apto para funcionamiento continuo, como un mini PC sin ventilador de la serie N100/N150, pero hoy no se ofrece una compilación o entrega dedicada orientada a esto.
• Ubicación en la red: debe estar conectado física o lógicamente al segmento de LAN supervisado (roamswitch-sensor.service se ejecuta en la red del host, necesario para observar directamente la tabla ARP). Además, debe funcionar con una dirección IP fija (asignación estática o reserva en el servidor DHCP) para que los endpoints puedan alcanzarlo y emparejarse o solicitar auditorías. Escucha en el puerto TCP 50543.
• Consumo de recursos: memoria residente de unas decenas de MB; la carga de CPU en reposo es extremadamente ligera.
• Opcional: nmap (se utiliza para los diagnósticos complementarios NSE; el resto de funciones opera con normalidad sin él).

3. Instalación y arranque

Instale el paquete roamswitch-sensor desde el repositorio oficial firmado. Tras la instalación, roamswitch-sensor.service (systemd) se habilita e inicia automáticamente.

3.1 APT (Ubuntu / Debian)

# 1. Registrar la clave de firma del repositorio
curl -fsSL https://lafine.net/apt/roamswitch-archive-keyring.asc \
  | sudo gpg --dearmor -o /usr/share/keyrings/roamswitch-archive-keyring.gpg

# 2. Añadir el repositorio
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. Instalar
sudo apt update && sudo apt install roamswitch-sensor

3.2 DNF / RPM (Fedora / RHEL)

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

# 2. Añadir el archivo de configuración del repositorio
sudo curl -fsSL -o /etc/yum.repos.d/roamswitch.repo https://lafine.net/rpm/fedora/roamswitch.repo

# 3. Instalar
sudo dnf install roamswitch-sensor

3.3 Comprobación del inicio

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

3.4 Ejecución de la CLI / TUI

La CLI (roamswitch-sensor) y la TUI interactiva (roamswitch-sensor-tui) pueden ejecutarse directamente tras la instalación.

sudo roamswitch-sensor status
sudo roamswitch-sensor-tui

4. Emparejamiento (método por código)

De fábrica, Sensor no confía en nada. El emparejamiento se realiza con un código de emparejamiento de un solo uso que emite el operador del Sensor. La relación de confianza —«Sensor puede ejecutar auditorías activas de vulnerabilidades contra este endpoint»— se establece simultáneamente en ambas direcciones con un único paso de emparejamiento (no existe un estado de confianza en una sola dirección).

Requisito previo: ejecute Sensor con una dirección IP fija (asignación estática o reserva en el servidor DHCP). Tras el emparejamiento, el endpoint siempre se conecta directamente a la dirección IP de Sensor confirmada en el momento del emparejamiento (ya no hay descubrimiento automático, ni por mDNS ni por ningún otro medio); si la IP de Sensor cambia después, será necesario volver a emparejar. El lado del endpoint puede mantener una IP dinámica.

4.1 Emitir un código de emparejamiento (lado de Sensor)

# Ejecutar en el lado de Sensor (o pulsar c en la TUI)
sudo roamswitch-sensor issue-code

Se emite un código de un solo uso de 8 caracteres (letras mayúsculas y dígitos, excluyendo los caracteres fácilmente confundibles 0/O/1/I/L). Caduca 10 minutos después de emitirse y solo puede canjearse una vez, así que transmítalo rápidamente al operador del endpoint por cualquier canal fuera de banda (de viva voz, chat, etc.).

4.2 Emparejamiento con el código (lado del endpoint)

# Lado del endpoint (roamswitch-linux)
sudo roamswitch sensor pair --addr <IP fija del Sensor> --code <código de emparejamiento>

En la edición Mac, la misma operación está disponible desde la interfaz gráfica mediante «🔍 Emparejamiento de RoamSwitch Sensor…» en la barra de menús, donde se introducen la dirección IP y el código de emparejamiento del Sensor.

Una vez completado el emparejamiento, toda auditoría activa de vulnerabilidades posterior y toda recuperación de resultados de auditoría se autentican con una firma Ed25519. Tanto el endpoint que conocía el código como el Sensor que lo emitió confían mutuamente a partir de ese momento.

4.3 Emparejamiento manual (registro directo de una clave pública ya conocida)

Si el operador del Sensor ya conoce, por otro medio, la clave pública y la dirección de un endpoint, también puede registrarlo directamente en el lado de Sensor sin intercambiar un código de emparejamiento (normalmente conviene usar el método por código del §4.2 y dejar que el endpoint se empareje por sí mismo). Puede consultar su propia clave pública y dirección con los siguientes comandos.

# Comprobar la clave pública/dirección propia en el lado del endpoint
sudo roamswitch sensor key

# Comprobar la clave pública/dirección/dirección MAC propia en el lado de Sensor
sudo roamswitch-sensor status

# Lado de Sensor
sudo roamswitch-sensor pair <clave pública completa> --addr <dirección IP> --confirm

5. Auditoría activa de vulnerabilidades

Sensor ejecuta diagnósticos de vulnerabilidad no destructivos y basados en pruebas contra los endpoints emparejados. Nunca realiza operaciones destructivas (escritura o eliminación de datos, detención de servicios).

sudo roamswitch-sensor scan <clave pública o su inicio>

La auditoría consta de cuatro fases.

1. Escaneo completo de puertos: detecta de forma exhaustiva todos los puertos TCP abiertos en el host de destino.
2. Diagnóstico de firmas conocidas: comprobaciones no destructivas y basadas en pruebas contra patrones de vulnerabilidad conocidos: exposición sin autenticación de Redis / dockerd / Memcached / MongoDB / Elasticsearch / CouchDB / Jenkins / VNC, diagnóstico de relay SMTP abierto (un método seguro que solo envía MAIL FROM/RCPT TO, nunca DATA), y diagnósticos de configuración CORS incorrecta, path traversal y redirección abierta en servidores de desarrollo, entre otros.
3. Captura genérica de banner: para los puertos abiertos no cubiertos por las firmas anteriores, obtiene la cadena de banner únicamente conectándose (no se envían datos).
4. Diagnóstico complementario nmap NSE: diagnóstico complementario de amplia cobertura de protocolos mediante nmap --script safe. Se ejecuta automáticamente en cuanto nmap está instalado en el host (si no lo está, no hace nada).

Cada ejecución de auditoría se registra en /var/lib/roamswitch-sensor/scan_history.json —independientemente de si se detectó algo, ya que un resultado limpio en ese momento también tiene valor de registro— y puede consultarse desde la CLI o la TUI.

roamswitch-sensor history
sudo roamswitch-sensor report <clave pública o su inicio> --out /tmp/report.md

5.1 Solicitud de auditoría desde el cliente (modelo pull)

Un endpoint emparejado también puede solicitar activamente una auditoría a Sensor. En la edición Mac, use «Solicitar auditoría al Sensor» en la barra de menús; en Linux, use el siguiente comando.

sudo roamswitch sensor request-audit

Después de que Sensor ejecute la auditoría, el endpoint consulta el resultado a partir de 5 minutos tras la solicitud, y luego cada 5 minutos hasta un máximo de 5 intentos (es decir, hasta 25 minutos en total). El resultado obtenido también se guarda localmente en el endpoint.

roamswitch sensor results

En la edición Mac, los resultados también aparecen en la lista «Resultados de auditoría» de la ventana de ajustes, o pueden leerse mediante la herramienta MCP get_sensor_audit_results, como entrada para que un agente de IA planifique una remediación. La recuperación de un resultado también puede rechazarse explícitamente, por ejemplo si el emparejamiento se revocó en el lado de Sensor (véase §10 P6).

6. Monitoreo ARP pasivo y visibilidad de LAN

Sensor toma periódicamente una instantánea de su propia tabla ARP (equivalente a /proc/net/arp) y, al compararla con la instantánea anterior, detecta dos tipos de eventos: una IP/MAC nueva nunca vista antes, y un cambio de dirección MAC para una IP ya conocida (un indicio, por ejemplo, de suplantación de la puerta de enlace). Nunca envía paquetes de forma activa y solo cubre los dispositivos con los que Sensor ya se ha comunicado de alguna manera (no es una función que descubra y enumere activamente todos los dispositivos de la LAN). No tiene capacidad para clasificar el tipo de dispositivo (por ejemplo, si es un dispositivo IoT); solo detecta un cambio de IP/MAC.

roamswitch-sensor arp-events

Los eventos detectados también pueden listarse desde la pestaña «ARP Events» de la TUI, que distingue dos tipos: «aparición de nuevo dispositivo» y «cambio de dirección MAC de una IP conocida (sospecha de suplantación)».

6.1 Extensión de visibilidad pasiva de la LAN (opt-in)

Mientras que el monitoreo ARP anterior solo cubre los dispositivos con los que Sensor se ha comunicado, establecer la variable de entorno ROAMSWITCH_SENSOR_PASSIVE_CAPTURE_IFACE en una interfaz de destino observa las cabeceras Ethernet/IPv4 en ella (sin inspección de carga útil) para detectar lo siguiente.

• Observación pasiva de nuevos dispositivos: dispositivos con los que Sensor nunca se ha comunicado directamente, no cubiertos solo por el monitoreo ARP. Se aprende a partir del tráfico de broadcast/multicast.
• Detección de contacto con IPs maliciosas conocidas: marca el tráfico cuya IP de destino coincide con el feed de amenazas local (mismo formato que el Egress Guard del propio RoamSwitch); solo detección, nunca se bloquea.

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. Referencia de comandos CLI

La CLI solo admite japonés e inglés (sigue la variable de entorno LANG).

8. Guía de uso de la TUI

La TUI interactiva (roamswitch-sensor-tui) admite 10 idiomas. Con la tecla Tab (Shift+Tab para retroceder) se cambia entre seis pestañas: De confianza (último estado de auditoría de cada endpoint) / Dispositivos (todos los dispositivos de la LAN, con notas) / Eventos ARP / Historial / Cambios (qué ha cambiado desde la auditoría anterior: hallazgos nuevos en rojo, resueltos en verde, posiblemente inalcanzable en amarillo) / Registro (quién aprobó o ejecutó qué y cuándo; arriba se muestra el resultado de la verificación de la cadena de hashes).

9. Modelo de confianza y diseño de seguridad

• TOFU (Trust On First Use): el propio código de emparejamiento no es una prueba criptográfica de propiedad, sino que se confirma mediante el criterio del propio operador, que ha recibido el código emitido por el operador del Sensor por un canal fuera de banda (de viva voz, chat, etc.), de forma similar a la confirmación mutua explícita del emparejamiento Bluetooth. Desde el momento en que el emparejamiento tiene éxito, la legitimidad de cada sonda o solicitud posterior se verifica frente a la clave pública intercambiada en ese momento.
• Diseñado para encontrar brechas que permitirían una acción destructiva, sin realizar nunca una acción destructiva él mismo: toda auditoría activa de vulnerabilidades es no destructiva (nunca escribe ni elimina datos, ni detiene un servicio). Lo que sí detecta son las propias configuraciones incorrectas —como «se puede escribir sin autenticación» o «funciona como relay abierto»— que, de explotarse, permitirían una acción destructiva.
• Mitigación de falsos positivos (exclusión de la autoauditoría): se incorpora una exclusión por coincidencia de IP de origen para que la auditoría de todos los puertos realizada por el propio Sensor emparejado no sea confundida con reconocimiento por la protección de detección de escaneo de puertos entrantes (una función del lado de RoamSwitch). La IP se usa únicamente para esta coincidencia, solo para evitar un bloqueo automático, nunca para la determinación de confianza en sí.
• No se envía nada sin su configuración: la información de los dispositivos descubiertos, los resultados de las auditorías y los eventos ARP se guardan, por defecto, solo en el almacenamiento local del Sensor y nunca se envían a Lafine ni a servidores de terceros. Las notificaciones (webhook / syslog) y el envío al colector central descritos en el §11 solo van a destinos que su organización haya configurado.

10. Solución de problemas y preguntas frecuentes

P1. Al introducir un código de emparejamiento, se rechaza.

Tres causas probables: (1) han pasado más de 10 minutos desde su emisión y ha caducado (pida al operador del Sensor que emita uno nuevo con issue-code); (2) un error al escribir el código (los caracteres fácilmente confundibles 0/O/1/I/L se excluyen ya en el momento de la emisión, por lo que un código nunca los contiene); (3) la dirección IP indicada con --addr no coincide con la dirección IP fija actual de Sensor.

P2. El resultado del diagnóstico complementario NSE está vacío.

Una de estas dos causas: (1) nmap no está instalado en el contenedor; (2) sí se ejecutó, pero los scripts seguros aplicables a los puertos de destino realmente no produjeron ninguna salida. El diagnóstico complementario nmap NSE se ejecuta automáticamente en cuanto nmap está instalado en el host.

P3. ¿Cuánto tarda en completarse una auditoría?

Un escaneo completo de puertos por sí solo tarda unas decenas de segundos, pero en cuanto nmap está instalado en el host, se suma automáticamente el diagnóstico complementario NSE, lo que puede tardar hasta unos 2 minutos según el número de puertos abiertos del objetivo. La TUI muestra continuamente los segundos transcurridos durante la ejecución, por lo que puede seguir el progreso mientras espera.

P4. He emparejado, pero sigo sin poder ejecutar una auditoría.

Causas probables: (1) sensor_pairing_enabled: true no está establecido en el lado del endpoint (desactivado por defecto); (2) la dirección IP fija de Sensor cambió después del emparejamiento, por lo que el endpoint intenta alcanzar una dirección obsoleta (un nuevo emparejamiento lo soluciona); (3) el emparejamiento se eliminó en el lado de Sensor con unpair. Compruebe con roamswitch sensor list (lado del endpoint) y roamswitch-sensor list (lado de Sensor) que cada uno reconoce al otro.

P5. ¿Se puede usar Sensor junto con el propio RoamSwitch (Client/Server Edition)?

Sí. Dado que Sensor está diseñado sin funciones de autodefensa, recomendamos ejecutar también RoamSwitch for Linux Server Edition en la misma máquina. Ambos funcionan con procesos y almacenes de datos totalmente independientes, sin conflictos.

P6. roamswitch sensor results indica que el emparejamiento fue revocado.

El emparejamiento de este endpoint se eliminó en el lado de Sensor con unpair. Pida al operador del Sensor que emita un nuevo código de emparejamiento y vuelva a emparejar con roamswitch sensor pair --addr <ip> --code <code>.

11. Funciones de auditoría para organizaciones (opcionales)

Un conjunto de funciones para los equipos de seguridad de grandes organizaciones que necesitan evidencias de auditoría y una visión clara de lo que ha cambiado. Todas están desactivadas por defecto y nunca se envía nada a Lafine ni a terceros: cada destino de notificación o agregación lo define su organización. Los ajustes se cambian con sudo roamswitch-sensor config set <clave> <valor> (sin reiniciar el daemon; cada cambio queda registrado en el registro de operaciones); config show muestra los valores actuales.

11.1 Auditorías programadas y detección de cambios

Al poner schedule.enabled en true, todos los endpoints emparejados se auditan automáticamente (cada 24 horas por defecto: schedule.interval_hours; franja horaria local en la que pueden iniciarse: schedule.window_start_hour / window_end_hour, que puede cruzar la medianoche; concurrencia: schedule.max_parallel). Cada auditoría se compara con la anterior, y roamswitch-sensor diff muestra los hallazgos nuevos (regresiones), los resueltos y los puertos recién abiertos. Si de repente dejan de verse todos los puertos que antes estaban abiertos, se informa como posiblemente inalcanzable, no como «resuelto»: un equipo apagado no se distingue desde fuera de uno que ha cerrado todos sus puertos.

Las auditorías desatendidas no rompen la garantía de que solo se auditan endpoints que han dado su consentimiento. La IP de un endpoint puede pasar a otro dispositivo por DHCP, así que el Sensor guarda la MAC que tenía el endpoint cuando se autenticó por última vez (emparejamiento o solicitud de auditoría firmada) y confirma, antes y después de cada auditoría programada, con una solicitud ARP real de nmap que sigue respondiendo la misma MAC en esa IP. Si no es así, la auditoría se omite (o se descarta su resultado) y se emite una notificación. Un scan manual también se rechaza si hay indicios de que la dirección ahora pertenece a otro dispositivo. Esta comprobación requiere nmap; los endpoints emparejados antes de esta función no se programan hasta que se vuelvan a emparejar o envíen una solicitud de auditoría firmada; solo se cubren los endpoints del mismo segmento L2.

11.2 Notificaciones (webhook y syslog)

Las regresiones, los dispositivos nuevos, la suplantación ARP, el tráfico sospechoso y más se envían a notify.webhook_urls (webhooks entrantes de Slack, Discord o Teams, o cualquier punto JSON genérico) y a notify.syslog.host / port / protocol (RFC 5424 sobre UDP o TCP). Se pueden acotar con notify.min_severity (info / medium / high / critical) y notify.cooldown_minutes (intervalo mínimo antes de reenviar el mismo evento). roamswitch-sensor notify-test comprueba cada destino.

11.3 Exportación de evidencias de auditoría

roamswitch-sensor export <scans|inventory|audit-log|all> --format csv|json|html [--out archivo] [--endpoint prefijo-de-clave] [--since fecha]. La salida html es un único archivo autónomo: ábralo en un navegador y elija «Guardar como PDF» para obtener un PDF que entregar a los auditores. El CSV está protegido contra la inyección de fórmulas en hojas de cálculo. La exportación del inventario de dispositivos incluye una columna que indica si cada dispositivo está bajo gestión de RoamSwitch (emparejado). Los archivos de salida solo los puede leer su propietario (0600), y la propia exportación queda registrada en el registro de operaciones.

11.4 Registro de operaciones y aprobaciones (a prueba de manipulaciones)

El emparejamiento, su anulación, el inicio y fin de las auditorías, los cambios de configuración y los accesos rechazados se registran junto con quién los realizó (UID / clave pública del endpoint / IP de origen). Cada línea contiene el SHA-256 de la anterior, de modo que cualquier edición o eliminación se detecta con roamswitch-sensor audit-log verify (código de salida 2 si algo falla). La lista se obtiene con roamswitch-sensor audit-log [--limit N]. Las URL de webhook suelen incluir un token, por lo que el registro de cambios de configuración nunca guarda sus valores. Una cadena de hashes por sí sola no revela que se hayan cortado las entradas más recientes, por eso la cabeza de la cadena (número de secuencia y hash) también se envía al colector (§11.6).

11.5 Retención

Configure retention.scan_history_days, retention.audit_log_days y retention.inventory_stale_days para que el historial de auditorías, las entradas del registro y los dispositivos que llevan tiempo sin verse se eliminen automáticamente (0 = no eliminar por antigüedad, valor por defecto). Los dispositivos con una nota nunca se retiran del inventario.

11.6 Agregar varios Sensors (colector central, opcional)

Cuando hay varios Sensors en varias sedes, ejecute roamswitch-sensor-collector (incluido en el paquete, desactivado por defecto) en un host aparte para recoger los resúmenes firmados de cada uno.

# 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

• Solo se aceptan solicitudes firmadas (Ed25519) de Sensors registrados (enroll); además, la marca de tiempo rechaza las repeticiones.
• TLS es obligatorio siempre que sea accesible desde fuera de la LAN. Indique --bind 0.0.0.0:8443 --tls-cert … --tls-key … en COLLECTOR_ARGS de /etc/default/roamswitch-sensor-collector, o use --allow-plain-http detrás de un proxy inverso que termine TLS. Escuchar en algo distinto de 127.0.0.1 sin TLS se rechaza al arrancar.
• El panel está protegido por un token y ofrece filtrado por sede, eventos por gravedad y exportación CSV. Resalta los Sensors que han dejado de responder y aquellos cuyo registro de auditoría parece truncado, retrocedido o bifurcado (se despeja con clear-anomaly <clave-pública> tras investigarlo).