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 que se coloca en la LAN para cerrar estas dos brechas. Lo que está implementado y verificado hoy es: auditorías activas de vulnerabilidades de los endpoints con RoamSwitch habilitado en la misma LAN; un inventario de dispositivos de la LAN construido a partir de un barrido ARP y de la monitorización de la tabla ARP, con detección de dispositivos nuevos y de suplantación; e información de referencia sobre comportamientos sospechosos (conexiones a IP maliciosas, indicios de participación en botnets, tunelización DNS y más) obtenida mediante captura pasiva opcional (opt-in) (véase §6). El Sensor solo detecta e informa; nunca bloquea tráfico. Está diseñado como un NDR (Network Detection & Response) ligero combinado con un escáner de vulnerabilidades propio basado en pruebas, no como un EDR.

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 que desea vigilar (roamswitch-sensor.service se ejecuta en la red del host porque necesita observar directamente la tabla ARP). Para aceptar solicitudes de emparejamiento y de auditoría de los endpoints, también debe funcionar con una dirección IP fija (asignación estática o reserva DHCP). Escucha en el puerto TCP 50543 (en todas las interfaces de forma predeterminada; cámbielo con control.bind_addr; TLS 1.3 se acepta en el mismo puerto; véase §4.4).
• Consumo de recursos: memoria residente de unas decenas de MB; la carga de CPU en reposo es extremadamente ligera.
• Recomendado: nmap (se usa para el barrido ARP, las comprobaciones complementarias NSE y la comprobación de MAC de las auditorías programadas). Sin él, las demás funciones siguen operativas, pero no se realiza ningún barrido ARP y el Sensor recurre a un funcionamiento pasivo que solo ve los dispositivos con los que él mismo se ha comunicado.

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; se excluyen los caracteres fáciles de confundir 0/O/1/I/L). Caduca a los 10 minutos y solo puede usarse una vez, así que transmítalo sin demora al operador del endpoint por cualquier canal fuera de banda (de viva voz, chat). También se muestra la huella digital (SHA-256) del certificado TLS del Sensor. El endpoint fija (pin) ese valor, así que comuníquelo junto con el código (siempre puede verlo con roamswitch-sensor pairing show o en la pantalla T de la TUI).

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

# Lado del endpoint (roamswitch-linux)
sudo roamswitch sensor pair --addr <SENSOR_IP> --code <CODE> --fingerprint <SHA256_FINGERPRINT>

En la edición para Mac puede hacer lo mismo en la interfaz gráfica desde el elemento de la barra de menús «🔍 Emparejamiento con RoamSwitch Sensor…», introduciendo la dirección IP del Sensor, el código de emparejamiento y la huella digital del certificado.

Una vez emparejados, todas las auditorías activas y recuperaciones de resultados posteriores se autentican con firmas Ed25519. Un endpoint Linux se comunica por TLS 1.3 únicamente con un Sensor cuyo certificado coincida con la huella digital que usted introdujo, y nunca recurre automáticamente a texto plano (§4.4). En este punto, el endpoint que conocía el código y el Sensor que lo emitió se consideran mutuamente de confianza.

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

4.4 Seguridad de la API de control (TCP 50543): TLS, huella digital, bloqueo

El emparejamiento, las solicitudes de auditoría y la recuperación de resultados pasan por la API de control del Sensor (TCP 50543). Se incorporan las siguientes protecciones.

• TLS 1.3 y certificado fijado (pin): el ajuste control.tls (se aplica al reiniciar el daemon) puede ser off (solo texto plano), optional (el predeterminado: TLS 1.3 y texto plano heredado en el mismo puerto, con una advertencia cada vez que se acepta texto plano) o required (solo TLS 1.3). El certificado es autofirmado (ECDSA P-256) y la confianza se decide mediante un pin de su huella digital SHA-256, no por la caducidad ni el nombre. El pin nunca se obtiene por la red: el operador escribe en el endpoint el valor que se muestra en la pantalla del Sensor.
• Vinculación de la huella digital a la solicitud de emparejamiento: el endpoint firma con su propia clave privada la huella digital que fijó y la incluye en la solicitud de emparejamiento. Una solicitud que pasó por un ataque de intermediario con un certificado distinto falla con fingerprint_mismatch y el código de emparejamiento no se consume.
• Firmas a prueba de repetición (v2): las firmas de las solicitudes de auditoría y de recuperación de resultados usan el formato v2, que incluye una marca de tiempo (±300 s) y un nonce, de modo que se rechazan las repeticiones. Las firmas v1 heredadas no incluyen ninguno de los dos y pueden repetirse; control.allow_legacy_signatures (predeterminado true, pensado para el periodo de migración; cada uso registra una advertencia de obsolescencia) decide si se aceptan. Póngalo en false cuando todos los endpoints envíen v2.
• Bloqueo: adivinar códigos de emparejamiento bloquea una IP de origen durante 60 segundos tras 5 fallos en 10 minutos (se amplía exponencialmente si se repite, hasta 1 hora), y 20 fallos entre todos los orígenes activan un bloqueo global. Los fallos de firma se tratan con algo más de tolerancia (10 por IP de origen, 100 en total). Un bloqueo genera la notificación control_api_lockout.
• Dirección de escucha: restringir control.bind_addr (predeterminado 0.0.0.0, se aplica al reiniciar) a la dirección LAN del Sensor reduce la exposición. El daemon avisa mientras la dirección sea un comodín.
• Rotación del certificado: roamswitch-sensor tls rotate (en la pantalla T de la TUI, pulse R) regenera el certificado. Todos los pines de la huella digital anterior dejan de ser válidos, por lo que cada endpoint debe introducir el nuevo valor (sudo roamswitch sensor repin <public key> --fingerprint <value>). El emparejamiento en sí se conserva.

sudo roamswitch-sensor pairing show                       # mode, fingerprint, warnings
sudo roamswitch-sensor tls rotate                         # regenerate the certificate
sudo roamswitch sensor repin <PUBLIC_KEY> --fingerprint <NEW_FINGERPRINT>   # on each endpoint

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

El Sensor conoce los dispositivos de la LAN de dos maneras. (1) Monitorización de la tabla ARP: lee su propia tabla ARP (/proc/net/arp) aproximadamente cada 10 segundos y detecta «una IP/MAC nueva nunca vista» y «un cambio de dirección MAC para una IP conocida» (indicio de suplantación de la puerta de enlace y similares). (2) Un barrido ARP activo: nmap -sn -PR barre la subred conectada directamente (hasta un /22) y almacena la IP, la MAC, el nombre de host, el fabricante, el estado en línea, la primera/última vez visto y el historial de IP en el inventario de dispositivos. El barrido se ejecuta cada hora, bajo demanda (refresh / la tecla r de la TUI) y al iniciar la TUI; sin nmap solo queda el comportamiento pasivo (1). El fabricante y una clase de dispositivo (IoT o no, etc.) también se infieren del OUI de la MAC.

roamswitch-sensor arp-events

Los eventos detectados se muestran con roamswitch-sensor arp-events y en la pestaña «Eventos ARP» de la TUI (Enter para ver los detalles). Cada evento incluye su hora, una gravedad (de crítica a informativa; un cambio de MAC de la IP de la puerta de enlace es «crítica»), el razonamiento, la identidad de los dispositivos implicados y pasos concretos a seguir.

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

6.2 Inventario de dispositivos y notas de dispositivo

Consulte el inventario con roamswitch-sensor device-inventory (la pestaña «Dispositivos» de la TUI). Registrar una nota, como un nombre, una finalidad o una ubicación, con device-note (la tecla n en la TUI) marca el dispositivo como «identificado», mientras que los dispositivos sin nota se resaltan como «por revisar» (para conciliarlos con su registro de activos).

sudo roamswitch-sensor refresh
roamswitch-sensor device-inventory
sudo roamswitch-sensor device-note aa:bb:cc:dd:ee:ff "3F copier"

6.3 Información de referencia sobre comportamientos sospechosos (solo detección)

Con la captura pasiva (§6.1, opt-in) activada, se presenta la siguiente información de referencia. Todo es solo detección y visualización; el Sensor nunca bloquea tráfico.

• Comportamiento de dispositivos IoT (iot-events): conexiones de dispositivos clasificados a IP maliciosas conocidas o a puertos de administración (SSH/RDP/SMB, etc.). También se utiliza la identificación del modelo a partir de los propios anuncios mDNS/SSDP/DHCP de los dispositivos.
• Tráfico sospechoso (network-threats): conexiones a muchos destinos en una ventana de 30 segundos (indicio de escaneo o de salto intermedio), una avalancha de conexiones a un mismo destino (indicio de participación en un DDoS) e indicios de tunelización DNS/C2 (solo se usan las características estructurales de los nombres de consulta; no se almacenan los nombres de dominio).
• Avisos (iot-advisories): información de referencia sobre CVE públicos de productos de fabricantes IoT conocidos (incluida de forma estática; no hay actualización por la red).

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 y puede manejar todos los subcomandos de la CLI, todos los métodos IPC del daemon, todas las claves de configuración y el colector (pulse m para el menú de funciones). Con la tecla Tab (Shift+Tab para retroceder) se cambia entre seis pestañas principales: 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). Las vistas que no caben en 80 columnas (monitorización pasiva, comportamiento de IoT, tráfico sospechoso, avisos de IoT) se abren desde el menú m.

9. Modelo de confianza y diseño de seguridad

• Confirmación fuera de banda (no TOFU): el operador transmite al endpoint la huella digital del certificado que se muestra en la pantalla del Sensor y el código de emparejamiento, de viva voz, por chat o similar. El endpoint nunca obtiene el pin por la red (no es TOFU, que confía incondicionalmente en la primera conexión) y solo se comunica y se empareja con un Sensor cuyo certificado coincida con el valor introducido. Las claves públicas intercambiadas durante el emparejamiento verifican todas las sondas y solicitudes posteriores.
• 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í. Además, solo desde que este equipo solicita una auditoría a un Sensor hasta que llega el informe (unos 25 minutos como máximo si no llega ninguno), la edición para Mac redacta con un tono más calmado las detecciones procedentes de la dirección del Sensor y el aviso de «inundación de SYN» (que no tiene dirección de origen) como probablemente causados por la auditoría; la edición para Linux lo hace con el aviso de «inundación de SYN». Fuera de esa ventana el aviso fuerte sigue igual, y las auditorías que el Sensor inicia por su cuenta no están cubiertas.
• El tráfico saliente es limitado y de forma predeterminada no se envían datos de dispositivos: la información de los dispositivos descubiertos, los resultados de auditoría y los eventos ARP se almacenan por defecto solo en el almacenamiento local del propio Sensor y nunca se envían a Lafine ni a terceros. El único tráfico saliente es la descarga de datos de detección (el mapa de CVE y la base de datos NSE de nmap; puede detenerse con updates.fetch_cve_map y no contiene datos de dispositivos ni de auditoría) y las notificaciones (webhook, syslog) y los envíos al colector central del §11, que van solo a sus propios destinos y únicamente cuando usted los configura.

10. Solución de problemas y preguntas frecuentes

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

Hay cuatro causas probables: (1) el código caducó a los 10 minutos de emitirse (pida al operador del Sensor que emita uno nuevo con issue-code), (2) un error al teclear el código (los caracteres fáciles de confundir 0/O/1/I/L se excluyen al emitir los códigos, por lo que un código nunca los contiene), (3) la dirección IP indicada en --addr no coincide con la dirección IP fija actual del Sensor, (4) --fingerprint no coincide con el certificado del Sensor (pin_mismatch / fingerprint_mismatch; compruebe el valor con roamswitch-sensor pairing show. Los errores repetidos provocan un bloqueo y se devuelve rate_limited).

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) no se ha establecido sensor_pairing_enabled: true en el endpoint (desactivado de forma predeterminada), (2) la dirección IP fija del Sensor cambió después del emparejamiento y el endpoint ya no puede alcanzar la dirección antigua que conserva (vuelva a emparejar), (3) el emparejamiento se eliminó en el Sensor con unpair, (4) el Sensor regeneró su certificado (tls rotate), por lo que el pin del endpoint está obsoleto (introduzca la nueva huella digital con roamswitch sensor repin). Compruebe con roamswitch sensor list (endpoint) y roamswitch-sensor list (Sensor) que cada lado incluye 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> --fingerprint <SHA-256>.

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 FILE] [--endpoint KEY-PREFIX] [--since DATE]. La salida html es un único archivo: ábralo en un navegador y elija «Guardar como PDF» para obtener un PDF que pueda entregar. El CSV está protegido contra la inyección de fórmulas en hojas de cálculo. El inventario de dispositivos (inventory) tiene una columna que indica si RoamSwitch administra cada dispositivo (emparejado). Los archivos de salida solo pueden ser leídos por su propietario (0600), y la propia exportación queda registrada en el registro de auditoría. La tecla e de la TUI ofrece las mismas opciones en un formulario, y los informes y exportaciones se generan en el idioma de la interfaz (10 idiomas; la CLI está en japonés e inglés).

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).
• Con collector.send_unmanaged_devices (predeterminado true) el Sensor incluye en el resumen los dispositivos que no están emparejados (dispositivos no administrados). Cada dispositivo se clasifica como «host RoamSwitch sin emparejar» (cuando RoamSwitch aparece en su autoanuncio mDNS/SSDP; activar collector.probe_control_port también realiza un intento de conexión TCP al puerto de control 50543, desactivado de forma predeterminada) o «dispositivo desconocido», y solo se envían la MAC, el fabricante, la clase de dispositivo y la hora de la primera detección (nunca contenido del tráfico). En la TUI, O abre la pantalla de administración del colector.

11.7 Descarga de datos de detección (updates.fetch_cve_map)

El Sensor descarga cada día del servicio de actualizaciones el mapa de CVE firmado (los datos de vulnerabilidades conocidas que usan las comprobaciones activas) y la base de datos NSE de nmap. Este tráfico no contiene datos de dispositivos ni de auditoría. Para funcionar totalmente sin conexión, ejecute sudo roamswitch-sensor config set updates.fetch_cve_map false (el cambio surte efecto desde el siguiente ciclo sin reiniciar, y a partir de entonces solo se usan los datos incluidos).

11.8 Referencia de claves de configuración

Consulte los valores actuales con roamswitch-sensor config show y cámbielos con config set <key> <value> [<key> <value> …] (varias claves se guardan de forma atómica; el editor de configuración C de la TUI también las cambia). Solo las claves marcadas con «Sí» en la columna Reinicio necesitan reiniciar el daemon (sudo systemctl restart roamswitch-sensor).

12. Detección de DHCP e IPv6 no autorizados

Detecta otro router, o el equipo de un atacante, introducido en la red que se hace pasar por el legítimo para controlar por dónde va el tráfico de los clientes. Solo detecta y avisa; el Sensor nunca bloquea tráfico. Está activado por defecto y no requiere captura pasiva. Los resultados aparecen en roamswitch-sensor network-threats, la pestaña Amenazas de la TUI (desde m), las notificaciones (dhcp_rogue_server, ipv6_rogue_router, ndp_spoof, ipv6_unknown_device), el registro de operaciones y las exportaciones.

12.1 Servidores DHCP no autorizados (IPv4 y DHCPv6)

Cada hora (y en cada roamswitch-sensor refresh) el Sensor envía un paquete DHCP discover (un SOLICIT en DHCPv6) desde una dirección MAC aleatoria y cuenta todos los servidores que responden. No envía ningún REQUEST, así que no toma ninguna concesión. Las respuestas DHCP que ve la captura pasiva pasan por el mismo juicio. El primer servidor que oye se aprende como legítimo y cualquier servidor que aparezca después se notifica. Un servidor que reparte una puerta de enlace o un DNS que el legítimo no reparte decide adónde envían su tráfico los clientes que aceptan su concesión, y es el nivel más grave, critical. Si varios servidores responden a la vez en la primera sonda, el Sensor no puede saber cuál es el auténtico: no aprende ninguno y los notifica todos.

12.2 IPv6 (anuncios de router no autorizados, suplantación NDP, dispositivos solo IPv6)

Anuncios de router no autorizados: cualquiera en la LAN puede decir que es un router IPv6. El Sensor combina la tabla de vecinos y las rutas por defecto del kernel, los anuncios de router que ve la captura pasiva y las respuestas a su propia solicitud de router, y avisa si algo distinto de la puerta de enlace IPv4 por defecto actúa como router (añada el auténtico a ipv6.allowed_routers para tratarlo como legítimo; una red cuyo router IPv6 es un dispositivo distinto de su puerta de enlace IPv4 es un caso normal, añádalo entonces). Los anuncios cuyo límite de saltos no es 255 son falsificados o enrutados y se ignoran. Suplantación NDP: avisa cuando el dueño de una dirección IPv6 cambia a otra MAC (high si es la dirección de un router). Dispositivos solo IPv6: un dispositivo que nunca aparece en ARP pero sí en la tabla de vecinos se notifica después de que un barrido ARP haya tenido ocasión de encontrarlo. El inventario de dispositivos (columna CSV ipv6, ipv6_addrs en JSON) también recoge direcciones IPv6.

12.3 Quién cuenta como legítimo y los ajustes

Con dhcp.allowed_servers y ipv6.allowed_routers (MAC o IP), todo lo demás que responda se notifica; si se dejan vacíos, se aprende el primero que se encuentre. dhcp.active_probe y ipv6.active_probe (por defecto true) desactivan las sondas activas, y ipv6.enabled desactiva toda la vigilancia IPv6. La escucha de la API de control (50543) en IPv6 se añade con control.listen_ipv6 (por defecto false, se aplica al reiniciar); una dirección IPv6 global puede ser accesible desde Internet si el router no tiene cortafuegos IPv6, por eso no está activada por defecto. Los límites de conexión y los bloqueos cuentan IPv6 por /64. Un endpoint que se conectó desde una dirección de enlace local no se recuerda como destino de auditoría, porque no se puede volver a llamar sin un identificador de ámbito.

13. Auditoría ligera de dispositivos sin RoamSwitch (opcional)

La auditoría activa de vulnerabilidades del §5 solo abarca los endpoints emparejados que han aceptado. Para impresoras, cámaras, NAS y otros dispositivos que nunca se emparejaron pero cuyos servicios expuestos se quiere conocer, existe una comprobación aparte y mucho más limitada. Los diagnósticos profundos al estilo de OpenVAS, los intentos de inicio de sesión, la explotación de vulnerabilidades, nmap NSE y los escaneos de todo el rango de puertos solo se hacen a los endpoints que han aceptado.

13.1 Qué hace

Solo hace una conexión TCP a 54 puertos fijos (Telnet, FTP, RDP, VNC, SMB, Redis, MongoDB, API de Docker, MQTT, RTSP, etc.), lee el banner que un servicio envía por sí mismo en los puertos abiertos (más un HEAD / a los puertos web) y añade una nota cuando el fabricante ha publicado vulnerabilidades (tabla de avisos IoT). Un resultado dice «a este servicio se llega desde la LAN», nunca «esto es vulnerable»; cada hallazgo indica que no se comprobó si la autenticación está activada.

13.2 Activarla

Para activar unmanaged_audit.enabled, defina primero unmanaged_audit.authorization (quién lo aprobó: un nombre, número de ticket o referencia de política) y unmanaged_audit.allowed_cidrs (los rangos que se pueden auditar; se rechazan los rangos IPv4 más amplios que /16 e IPv6 más amplios que /48). Las ejecuciones programadas se hacen cada interval_hours (168 por defecto) dentro de la ventana de schedule. Una ejecución manual necesita --confirm como segundo consentimiento.

sudo roamswitch-sensor config set unmanaged_audit.authorization "IT policy 2026-07, approved by A. Suzuki"
sudo roamswitch-sensor config set unmanaged_audit.allowed_cidrs 192.168.10.0/24
sudo roamswitch-sensor config set unmanaged_audit.exclude 192.168.10.1
sudo roamswitch-sensor config set unmanaged_audit.enabled true
sudo roamswitch-sensor audit-unmanaged 192.168.10.40 --confirm
roamswitch-sensor unmanaged-audits --detail

13.3 Salvaguardas

Nada fuera de allowed_cidrs, ningún dispositivo de unmanaged_audit.exclude (IP, rango o MAC), ningún endpoint emparejado ni el propio Sensor se examina jamás. Antes y después de una ejecución, la MAC del dispositivo en esa dirección se confirma con una consulta en vivo (ARP en IPv4, que requiere nmap; solicitud de vecino en IPv6); si ha cambiado, la ejecución se detiene o el resultado se descarta y se envía una notificación. El texto de authorization se escribe en el registro de operaciones en cada ejecución y aparece en las exportaciones (export unmanaged, JSON, informe HTML), de modo que se puede mostrar quién aprobó la auditoría.

13.4 Comprobación del producto (¿tiene vulnerabilidades del KEV de la CISA? Opt-in)

Al activar unmanaged_audit.product_check (desactivado por defecto), la auditoría ligera lee el nombre del producto de la página web que un dispositivo devuelve normalmente e indica si ese producto tiene vulnerabilidades del catálogo KEV de la CISA. Solo se envía un GET / a los puertos web que aceptaron la conexión (80, 8080, 8181, 443, 8443, 10443), las redirecciones que el propio dispositivo indica hacia la misma dirección (como máximo dos) y la lectura del emisor y el sujeto del certificado HTTPS. No se envían inicios de sesión, intentos de contraseña, rutas adivinadas ni nada que explote una vulnerabilidad. El límite es de 12 solicitudes por dispositivo, separadas 150 ms. Las condiciones de consentimiento (enabled, authorization, allowed_cidrs, exclude, exclusión de dispositivos emparejados y nueva comprobación de la MAC) son exactamente las de los §13.2–13.3; si la auditoría ligera está desactivada, no se envía nada aunque product_check esté activado.

Un producto solo se nombra cuando todas sus marcas en pantalla aparecen en la misma respuesta. Se informa como afectado (high) únicamente si se puede leer la versión que muestra el propio dispositivo y un CVE tiene un rango NVD que la incluye. Si no se puede leer la versión, queda como aviso (medium): este producto tiene vulnerabilidades listadas en el KEV, no se pudo leer la versión, así que no está confirmado si está afectado. Nunca se afirma que el dispositivo sea vulnerable. Hoy solo MikroTik RouterOS muestra su versión, por lo que los demás productos reciben normalmente el aviso «sin confirmar». Se cubren Fortinet FortiGate, Ivanti Connect Secure, Citrix NetScaler, Cisco (la VPN SSL de ASA y la interfaz web de IOS XE), UniFi OS, GeoVision, TerraMaster, Check Point Security Gateway y MikroTik RouterOS; los dispositivos Aruba no tienen entrada en el KEV y no se cubren. Las marcas se basan en firmas de detección públicas y no se han comprobado en dispositivos reales; una marca que no coincide tiende a no detectar nada. Una copia del KEV se incluye con el producto y solo se actualiza, cuando product_check y updates.fetch_cve_map están ambos activados, descargando cada 24 horas un archivo del feed público de la CISA (no se envía nada de su LAN).

14. Si se pierde, roban o da de baja

Un Sensor guarda la lista de vulnerabilidades halladas en cada endpoint, las direcciones de los endpoints emparejados y su clave de firma. Los endpoints emparejados también lo tratan como un escáner autorizado, de modo que un Sensor robado conectado a la misma LAN podría hacerse pasar por uno. Lo siguiente lo impide.

14.1 Revocación en el colector y bloqueo

Tras roamswitch-sensor-collector revoke <clave pública> --reason TEXTO, los envíos de ese Sensor se rechazan con 403 sensor_revoked (solo se da a solicitudes con firma válida, así que únicamente lo sabe quien tiene la clave). Un Sensor revocado lo averigua en su próximo envío y se detiene solo (bloqueo). Bloqueada, la API de control solo responde sensor_locked_down, y se detienen los emparejamientos, las auditorías (programadas y manuales), los envíos al colector, las notificaciones y el sondeo de la red. El bloqueo se guarda en un archivo, así que sobrevive a un reinicio, y si ese archivo no se puede leer el Sensor sigue bloqueado. Los datos se conservan; con roamswitch-sensor lockdown off (K en la TUI) se libera cuando se está seguro de que vuelve a estar en manos de confianza. Si sigue revocado en el colector, se bloquea de nuevo en su próximo envío. revoke muestra además los endpoints que estaban emparejados con ese Sensor y cómo desemparejar cada uno.

14.2 Borrado, baja y detección sin conexión

Con security.on_revoked en wipe, un Sensor revocado sobrescribe con ceros y borra sus claves, su clave TLS, los ajustes (incluidas las URL de webhook), la lista de endpoints emparejados, los resultados de auditoría y el inventario de dispositivos. Solo se conserva el registro de operaciones, como prueba. lockdown (por defecto) lo detiene y conserva los datos, y none solo avisa. Para dar de baja manualmente un Sensor que se tiene a mano, use roamswitch-sensor decommission --confirm (bloquear y borrar; no se puede deshacer). Poner security.lockdown_after_offline_days en un número de días hace que un Sensor que no pudo contactar con el colector durante ese tiempo se detenga solo, como salvaguarda de uno robado y usado en otra red; solo se aplica si el envío al colector está activado y ha tenido éxito al menos una vez, y el valor por defecto es 0 (desactivado).

14.3 Lo que esto no puede hacer

Los endpoints que estaban emparejados con el Sensor siguen confiando en él hasta que cada uno elimine el emparejamiento. Un Sensor no puede avisar a sus endpoints, así que en cada endpoint de la lista que muestran revoke y decommission ejecute roamswitch sensor unpair <clave pública de este Sensor> en Linux, o Ajustes > Sensor > Desemparejar en Mac. Un Sensor que se llevan apagado o sin conectarlo a la red nunca recibe la orden de detenerse; ahí la protección real es el cifrado del disco (LUKS y similares). Sobrescribir no garantiza un borrado completo en almacenamiento flash ni en sistemas de archivos de copia en escritura.