ROAMSWITCH SENSOR ・ Última actualización: 2026-10-27

Manual de Operaciones de RoamSwitch Sensor

Guía de implantación y operación de un sensor de red que, con solo colocarlo en la LAN, detecta la aparición de equipos nuevos en el mismo segmento y la suplantación. En los dispositivos con RoamSwitch instalado (Mac / Linux Client / Server Edition), también realiza auditorías activas de vulnerabilidades. Se distribuye como 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.

RoamSwitch Sensor es un nodo dedicado que se coloca en la LAN y cubre estas dos carencias. Está implementado lo siguiente: auditoría activa de vulnerabilidades de los equipos con RoamSwitch instalado, inventario de dispositivos mediante ARP y detección de suplantación, e información de referencia sobre comportamientos sospechosos mediante captura pasiva opcional (§6). Solo detecta e informa; no bloquea el tráfico.

Política de tráfico saliente (de forma predeterminada no se envían datos de dispositivos ni resultados de auditoría)
Sensor no es «Zero Telemetry». (1) Obtención de datos de detección: el mapa de CVE y otros datos se obtienen a diario (updates.fetch_cve_map, por defecto true; con false, sin conexión). No incluyen datos de dispositivos ni de auditoría. (2) Notificación y agregación a destinos definidos por el operador: solo se envían si se configuran.

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

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
Opt-in: extensión de visibilidad pasiva de la LAN
Para usar con un puerto espejo de switch (SPAN) o un puente transparente en línea, especifique el nombre de la interfaz de destino en la variable de entorno ROAMSWITCH_SENSOR_PASSIVE_CAPTURE_IFACE (configurada mediante systemctl edit roamswitch-sensor.service) para observar las cabeceras Ethernet/IPv4/IPv6 en esa interfaz y detectar nuevos dispositivos o contacto con IPs maliciosas conocidas (véase el §6.1). Desactivado por defecto.

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

Aparece un código de un solo uso de 8 caracteres (se excluyen 0/O/1/I/L). Caduca a los 10 minutos de emitirse. Comuníquelo enseguida al operador del equipo, junto con la huella del certificado TLS (SHA-256) que se fijará en el equipo.

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.

Cuando un código de emparejamiento ha caducado
Un código de emparejamiento caduca automáticamente 10 minutos después de emitirse y nunca puede canjearse dos veces. Intentar emparejar después de que haya caducado se rechaza. En ese caso, pida al operador del Sensor que emita uno nuevo con issue-code.

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

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
Cambiar control.tls a required
(1) Actualice todos los endpoints a una versión compatible con TLS y complete el emparejamiento TLS (o el re-pin) en cada uno → (2) confirme que roamswitch-sensor status ya no muestra una advertencia de conexión en texto plano → (3) ejecute sudo roamswitch-sensor config set control.tls required → reinicie el daemon. off normalmente no se usa, porque los endpoints Linux exigen TLS y ya no podrían conectarse.

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). A un puerto abierto que no muestra ningún banner le envía un único GET / HTTP/1.0 para distinguir el servicio (como máximo 32 puertos por auditoría).
  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).

También se examinan los servicios en puertos no estándar. Se aplican las mismas comprobaciones de solo lectura, por ejemplo, a Redis en el puerto 6380 o a SSH en el puerto 2222. Se identifican por el primer banner y la respuesta a un único GET / HTTP/1.0. La lista que declara el propio dispositivo (hasta 64 entradas cada vez) queda fuera de la firma, por lo que nunca amplía el alcance y se usa solo para elegir las comprobaciones.

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

Cuando aparece «Puertos abiertos: ninguno» y tampoco hay respuesta ARP, se muestra «Es posible que no llegue al equipo». Esto no significa «sin problemas». «nmap NSE: no ejecutado (nmap no está instalado)» y «no aplicable» significan cosas distintas.

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

Desde un equipo emparejado también se puede solicitar al Sensor una auditoría activa de vulnerabilidades. En la versión de Mac, con «Solicitar auditoría al Sensor» en la barra de menús; en la de Linux, con 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).

5.2 Diferencias con la especificación, valores límite y pistas de una IA (opcional)

Diferencias con la especificación y valores límite (design_flaw.enabled; desactivado por defecto, requiere activación expresa) Solo afecta a los dispositivos emparejados que han dado su consentimiento. Busca documentos OpenAPI / Swagger e informa de las discrepancias entre lo declarado y las respuestas reales. Aplica a los parámetros de consulta valores seguros fijos e informa de anomalías como 5xx. Solo envía GET, como máximo 20 solicitudes por equipo. El orden es fijo; la IA no lo elige (el resumen oculta los secretos, hasta 240 caracteres por elemento).
Hacer que una IA redacte hipótesis (opcional) roamswitch-sensor design-hypotheses entrega solo el resumen de los registros a la herramienta de IA elegida y le hace redactar hipótesis sin confirmar. Se ejecuta con los permisos de quien lo lanza, y el resumen puede enviarse al proveedor. No se envía nada a los equipos.

6. Monitoreo ARP pasivo y visibilidad de LAN

Sensor identifica los dispositivos de la LAN de dos maneras. (1) Supervisión de la tabla ARP: la lee aproximadamente cada 10 segundos y detecta nuevos pares IP/MAC y cambios de MAC en IP conocidas (señal de suplantación). (2) Barrido ARP activo: con nmap -sn -PR examina cada hora la subred directamente conectada (hasta /22) y guarda el resultado en el inventario. Sin nmap, solo se aplica (1).

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 únicamente las cabeceras Ethernet/IPv4/IPv6 en ella y lo que los dispositivos anuncian de sí mismos (el contenido de los datos solo se lee en DNS, DHCP, mDNS, SSDP, WS-Discovery y LLDP) para hacer lo siguiente.

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

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

Después de añadir una variable de entorno, reinicie con sudo systemctl restart roamswitch-sensor. Solo con systemctl edit no se aplica al demonio en ejecución. Si se ha aplicado se comprueba en «Captura pasiva: recibiendo en eth0» de roamswitch-sensor status. Si sigue apareciendo «La captura pasiva está desactivada», no se ha reiniciado.

El búfer de recepción se cambia con capture.rcvbuf_mb (MiB; por defecto 4, 0 para el valor predeterminado del sistema). Como el único privilegio es CAP_NET_RAW, lo que supere net.core.rmem_max se recorta. Si aparece kernel_drops, suba rmem_max (por ejemplo: sudo sysctl -w net.core.rmem_max=8388608; para hacerlo permanente, use /etc/sysctl.d/) y suba también capture.rcvbuf_mb.

Una NIC normal frente a un puerto espejo
Incluso una única NIC ordinaria funciona para detectar nuevos dispositivos dentro del alcance del tráfico ARP/broadcast/multicast (verificado en hardware real en una LAN física). Sin embargo, observar el tráfico unicast general entre otros dos hosts de la LAN requiere un puerto espejo de switch (SPAN), o configurar Sensor como puente transparente en línea.

6.2 Inventario de dispositivos y notas de dispositivo

El inventario se puede ver con roamswitch-sensor device-inventory. Los equipos con una nota registrada mediante device-note figuran como «conocidos» y los no registrados como «por revisar». Los ID de VLAN observados también aparecen en la columna vlans de la exportación, entre otros lugares.

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.

6.4 Qué no ve el Sensor (cobertura)

La vigilancia pasiva, por sí sola, no distingue entre no oír nada y una red tranquila. El Sensor cuenta solo lo que pudo observar él mismo y no confunde lo que no ve con «sin eventos». No abre ninguna conexión ni socket nuevos. Está activado por defecto.

Ejemplos de causas que se cuentan: no se puede abrir la captura pasiva, una parada de 30 segundos o más, 5 fallos de recepción seguidos, 5 minutos sin tramas con el enlace también caído, descartes del kernel (últimos 10 minutos), tramas de más de 2048 bytes y tramas cuya cabecera no se puede leer. Una ronda en la que no se puede leer la tabla ARP se cuenta sin borrar la línea base.

Lo que no puede hacer Cuenta solo lo que el propio Sensor puede observar. No distingue un caso en que la recepción es correcta pero las tramas que llegan están sesgadas, como un puerto espejo mal configurado. Cuando no ha habido tramas en 5 minutos pero el enlace está activo (capture_silent, info), dice claramente que no puede distinguir «tranquilo» de «no oye».

7. Referencia de comandos CLI

Comando Descripción
roamswitch-sensor status Muestra la clave pública, la IP y la dirección MAC del propio Sensor, el número de endpoints emparejados, los eventos ARP y las solicitudes de auditoría pendientes, y el estado de TLS de la API de control
roamswitch-sensor issue-code Emite un código de emparejamiento de un solo uso (válido durante 10 minutos); también muestra la huella digital del certificado del Sensor
roamswitch-sensor list Muestra la lista de endpoints emparejados
roamswitch-sensor pair <public-key> [--addr <IP>] [--name <name>] --confirm Empareja manualmente un endpoint indicando directamente su clave pública y dirección (normalmente es más sencillo usar issue-code y dejar que el endpoint se empareje por sí mismo)
roamswitch-sensor unpair <public-key> Elimina un emparejamiento
roamswitch-sensor scan <public-key> Ejecuta una auditoría activa de vulnerabilidades contra un endpoint emparejado
roamswitch-sensor history [public-key] Muestra el historial de auditoría (omita la clave pública para ver todos los endpoints)
roamswitch-sensor report <public-key> [--out <file>] Exporta el resultado de auditoría más reciente como informe Markdown
roamswitch-sensor arp-events Muestra los eventos ARP detectados (dispositivos nuevos, sospecha de suplantación)
roamswitch-sensor pairing show / tls show Muestra el estado de TLS de la API de control (modo, huella digital, advertencia de conexión en texto plano, IP de escucha, si se aceptan las firmas v1 heredadas); pairing show y tls show son equivalentes
roamswitch-sensor tls rotate Regenera el certificado TLS (todos los pines de la huella digital anterior dejan de ser válidos; los endpoints deben volver a fijarla)
roamswitch-sensor refresh Vuelve a escanear la LAN ahora (barrido ARP) y actualiza el inventario de dispositivos
roamswitch-sensor device-inventory Muestra el inventario de dispositivos (todos los dispositivos observados en la LAN, su estado en línea y su nota)
roamswitch-sensor device-note <MAC> [note] Registra una nota para un dispositivo (omita la nota para eliminarla)
roamswitch-sensor passive-events / iot-events / network-threats / iot-advisories Muestra los eventos de la captura pasiva (dispositivos nuevos y conexiones a IP maliciosas / comportamiento de IoT / tráfico sospechoso / avisos de IoT)
roamswitch-sensor lan-overview [--json]
roamswitch-sensor network-threats --json [--limit N] [--min-severity …]
Muestra el estado general de la LAN (número de dispositivos, VLAN, número de amenazas, etc.) y una lista de amenazas. --json genera JSON (--limit es como máximo 500). Ambos son de solo lectura y pueden ejecutarse sin ser root. PersonalSOC y la versión de MCP para Linux los leen.
roamswitch-sensor config [show | set <clave> <valor>] Muestra o cambia la configuración (auditorías programadas, notificaciones, retención, colector, API de control, descarga de datos de detección, idioma). control.bind_addr y control.tls surten efecto al reiniciar el daemon; las demás no necesitan reinicio (§11.8)
roamswitch-sensor diff [clave pública] Mostrar qué ha cambiado desde la auditoría anterior (hallazgos nuevos, resueltos, puertos recién abiertos, posiblemente inalcanzable)
roamswitch-sensor export <scans|inventory|audit-log|unmanaged|all> … Escribir las evidencias de auditoría como CSV / JSON / HTML imprimible
roamswitch-sensor audit-log [verify] Mostrar el registro de operaciones y aprobaciones; verify detecta manipulaciones de la cadena de hashes
roamswitch-sensor notify-test Enviar una notificación de prueba a los destinos configurados (webhook / syslog) para verificar la conexión
roamswitch-sensor audit-unmanaged <IP|MAC> --confirm
roamswitch-sensor unmanaged-audits
Auditoría ligera de dispositivos sin RoamSwitch (solo comprobaciones de conexión). audit-unmanaged <IP o MAC> --confirm lanza una a mano, unmanaged-audits [--detail] lista los resultados (§13)
roamswitch-sensor design-hypotheses [鍵] --llm 名前 Pide a la herramienta de IA elegida pistas sin verificar a partir del último resultado de design_flaw (§5.2). --llm, --model, --timeout, --show-prompt
roamswitch-sensor lockdown [status | on | off] Muestra si el Sensor está bloqueado (status), lo bloquea (on --reason TEXTO) o lo libera (off). Bloqueado, detiene emparejamientos, auditorías, envíos y notificaciones (§14)
roamswitch-sensor decommission --confirm Borra las claves y los datos de este Sensor y lo bloquea (no se puede deshacer). Se conserva el registro de auditoría y se listan los endpoints que estaban emparejados con él y cómo desemparejarlos (§14)

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) está en 10 idiomas y permite hacer todo lo que permiten la CLI y la configuración (m muestra la lista de funciones). Las 6 pestañas principales (emparejados, configuración de red, eventos ARP, historial de auditorías, diferencias, registro de operaciones) se cambian con Tab. Las diferencias muestran lo nuevo en rojo, lo resuelto en verde y lo posiblemente inaccesible en amarillo.

Tecla Acción
TabCambia de pestaña
↑↓ / j kSelecciona un elemento
cEmite un código de emparejamiento (válido durante 10 minutos). La pantalla muestra el comando que debe ejecutarse en el endpoint, sudo roamswitch sensor pair --addr <this Sensor’s IP> --code <code> --fingerprint <fingerprint>, con los valores reales ya rellenados
uElimina un emparejamiento
sEjecuta una auditoría activa de vulnerabilidades contra el endpoint seleccionado
a(Pestaña Dispositivos de red) Auditoría ligera del dispositivo seleccionado, tras una pantalla de confirmación (§13). Los resultados están en la pestaña «No gestionados» del menú
KBloquea o libera este Sensor tras una pantalla de confirmación; un aviso rojo permanece al pie de cada pantalla mientras esté bloqueado. La baja está en el menú (§14)
n(Pestaña Dispositivos) Añadir una nota —nombre, uso, ubicación— al dispositivo seleccionado; un dispositivo con nota se considera identificado
rVolver a escanear la LAN ahora (barrido ARP; por defecto se ejecuta automáticamente cada hora)
eExporta evidencias de auditoría (CSV de los resultados de escaneo, del inventario de dispositivos y del registro de auditoría; un informe HTML; JSON). Un formulario permite elegir el contenido, el formato, el endpoint, la fecha de inicio y el destino; los archivos se generan en el idioma de la interfaz (10 idiomas). El destino predeterminado es ~/.local/state/roamswitch-sensor/; los archivos se crean nuevos y solo el propietario puede leerlos (nunca se sobrescribe un archivo existente), y la propia exportación queda registrada en el registro de auditoría
pEmparejamiento manual (introduzca la clave pública y la dirección, luego una pantalla de confirmación y después se ejecuta). El formulario muestra la huella digital TLS del Sensor que el endpoint fija
TEstado de TLS y del emparejamiento (modo, huella digital, advertencia de conexión en texto plano, IP de escucha, si se aceptan las firmas v1 heredadas). R regenera el certificado (con una pantalla de confirmación que explica el impacto)
CEditor de configuración (muestra y cambia todas las claves de configuración; las URL de webhook siempre aparecen enmascaradas; las claves que requieren reinicio están marcadas)
NPrueba de notificación (muestra el éxito o el fallo por destino; las URL aparecen enmascaradas)
mMenú de funciones (monitorización pasiva, comportamiento de IoT, tráfico sospechoso, avisos de IoT, estado i, administración del colector y más)
OAdministración del colector (solo en un host que tenga el directorio de datos del colector): registrar, revocar y listar Sensors, el token de lectura y borrar una anomalía del registro de auditoría. n define el destino de las alertas del propio colector
f / l / v(Pestaña Historial) filtrar por endpoint. (Pestaña Registro) l cambia cuántas filas se muestran y v vuelve a verificar la cadena de hashes
EnterMostrar el detalle de la fila seleccionada (historial, cambios, eventos ARP, dispositivos, registro)
w(En una vista de detalle) escribe el informe en un archivo en el destino que elija (generado en el idioma de la interfaz)
LElige el idioma de la interfaz (se guarda en el ajuste language, por lo que también se aplica a las notificaciones y registros generados por el daemon)
qSale

9. Modelo de confianza y diseño de seguridad

10. Solución de problemas y preguntas frecuentes

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

Hay cuatro causas posibles. (1) Han pasado más de 10 minutos desde la emisión (vuelva a emitirlo con issue-code). (2) Un error de escritura. (3) La IP de --addr es distinta de la IP fija del Sensor. (4) --fingerprint es distinto del certificado (compruébelo con roamswitch-sensor pairing show). Si los errores continúan, se produce un bloqueo con rate_limited.

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

La causa es una de estas dos. (1) nmap no está instalado en el contenedor. (2) Se ejecutó, pero en realidad no hubo salida de ningún script seguro correspondiente a los puertos objetivo. El diagnóstico complementario nmap NSE se ejecuta automáticamente si nmap está instalado en el host.

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

El escaneo de todos los puertos por sí solo tarda unas decenas de segundos. Si nmap está instalado en el host, el diagnóstico complementario NSE se añade automáticamente y puede tardar hasta unos 2 minutos, según el número de puertos abiertos del objetivo. La TUI sigue mostrando los segundos transcurridos durante la ejecución, así que puede seguir el progreso.

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

Hay cuatro causas posibles. (1) No se ha configurado sensor_pairing_enabled: true en el dispositivo (desactivado por defecto). (2) La IP fija del Sensor ha cambiado (hay que volver a emparejar). (3) Se ejecutó unpair en el Sensor. (4) Se regeneró el certificado y el pin del dispositivo quedó obsoleto (roamswitch sensor repin). Compruebe en las listas de ambos lados el registro del 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

Si schedule.enabled se pone en true, se auditan periódicamente todos los equipos emparejados (cada 24 horas por defecto). La diferencia con la auditoría anterior se puede comprobar con roamswitch-sensor diff. Cuando todos los puertos que estaban abiertos dejan de verse, no se puede distinguir de un equipo apagado, por lo que se trata como posiblemente inaccesible.

Ni siquiera las auditorías desatendidas rompen la garantía de auditar solo los equipos que han dado su consentimiento. Se guarda la MAC del momento en que el equipo se autenticó por última vez y, antes y después de la auditoría, se comprueba mediante ARP de nmap que la misma MAC responde en esa IP. Si difiere, no se audita (o se descarta el resultado) y se notifica.

Los equipos de otra VLAN quedan excluidos por defecto. Con schedule.allow_routed_endpoints (desactivado por defecto), se comprueba, entre otras cosas, que una solicitud firmada haya llegado desde la misma dirección dentro de schedule.routed_proof_minutes (por defecto 30 minutos, de 5 a 1440).

Los motivos por los que no se ejecuta (sin nmap, un equipo sin dirección, un equipo sin vinculación de identidad) aparecen como advertencia en «Alcance visible» de status. Si hay un destino de notificación, se envía un coverage_gap una vez y, al corregirse, un coverage_restored. Durante el bloqueo y fuera del horario, no se genera advertencia y se muestra una línea en status.

11.2 Notificaciones (webhook y syslog)

Envía regresiones, nuevos dispositivos, suplantación ARP, etc. a notify.webhook_urls y notify.syslog.host (RFC 5424, UDP o TCP). Se pueden filtrar con notify.min_severity y el intervalo de reenvío, y la conectividad se comprueba con roamswitch-sensor notify-test.

status muestra el destino de notificación y el resultado de la última entrega. Mientras fallen las entregas se muestra un aviso, así que compruébelo con roamswitch-sensor notify-test. Cuando tiene éxito, el aviso desaparece.

11.3 Exportación de evidencias de auditoría

roamswitch-sensor export <scans|inventory|audit-log|all> --format csv|json|html [--out archivo] [--endpoint inicio de la clave pública] [--since fecha]. El html se puede guardar como PDF desde un navegador. El CSV está protegido contra la inyección de fórmulas. La salida tiene permisos 0600 y la propia exportación también queda en el registro de operaciones. En la TUI, la tecla e permite las mismas opciones.

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

El emparejamiento, las auditorías, los cambios de configuración y los accesos denegados se registran junto con quien los realizó. Cada línea forma una cadena de hashes que incluye el SHA-256 de la línea anterior, y la manipulación se detecta con roamswitch-sensor audit-log verify (código de salida 2 si hay anomalía). No se conservan los valores de las URL de webhook. Como protección ante el borrado del final, el principio 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
# On the collector host: where the collector's own alerts go
echo 'https://hooks.example.org/…' | sudo roamswitch-sensor-collector notify set --add-webhook - --min-severity high
sudo roamswitch-sensor-collector notify set --syslog-host 192.0.2.10 --syslog-protocol tcp
sudo roamswitch-sensor-collector notify show   # a Webhook URL is shown up to its host only
sudo roamswitch-sensor-collector notify test

Cuando el colector no ha podido leer su historial (scans.jsonl, events.jsonl), cuenta lo que no pudo leer para que no se confunda con «sin datos». Una línea dañada se omite por sí sola, y las líneas cuya fecha no se puede leer no se eliminan en la limpieza. El resultado aparece en storage_health de /api/overview, en el panel y en el registro de inicio. No se realiza ninguna comunicación nueva.

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

Clave Tipo / valores Predeterminado Reinicio
sitestring(empty)No
languageja | en | ko | zh-Hans | zh-Hant | de | fr | es | it | pt-PT(empty = system locale)No
schedule.enabledboolfalseNo
schedule.interval_hoursint24No
schedule.window_start_hourint 0–23(unset = always)No
schedule.window_end_hourint 0–23(unset = always)No
schedule.max_parallelint 1–81No
schedule.allow_routed_endpointsboolfalseNo
schedule.routed_proof_minutesint 5–144030No
notify.webhook_urlsURL list(empty)No
notify.min_severityinfo | medium | high | criticalmediumNo
notify.cooldown_minutesint30No
notify.syslog.hoststring(empty = off)No
notify.syslog.portint514No
notify.syslog.protocoludp | tcpudpNo
retention.scan_history_daysint (0 = never prune)0No
retention.audit_log_daysint (0 = never prune)0No
retention.inventory_stale_daysint (0 = never prune)0No
collector.enabledboolfalseNo
collector.urlURL(empty)No
collector.push_interval_minutesint15No
collector.send_unmanaged_devicesbooltrueNo
collector.send_unmanaged_auditsboolfalseNo
collector.probe_control_portboolfalseNo
control.bind_addrIP address0.0.0.0Sí
control.tlsoff | optional | requiredoptionalSí
control.allow_legacy_signaturesbooltrueNo
updates.fetch_cve_mapbooltrueNo
control.listen_ipv6boolfalseSí
capture.rcvbuf_mbint 0–256 (MiB, 0 = system default)4Sí
dhcp.active_probebooltrueNo
dhcp.allowed_serversMAC / IP list(empty = learn the first)No
ipv6.enabledbooltrueNo
ipv6.active_probebooltrueNo
ipv6.allowed_routersMAC / IP list(empty = trust the IPv4 gateway)No
unmanaged_audit.enabledbool (needs authorization + allowed_cidrs first)falseNo
unmanaged_audit.authorizationstring(empty)No
unmanaged_audit.allowed_cidrsCIDR list (IPv4 ≤ /16 and IPv6 ≤ /48 refused)(empty)No
unmanaged_audit.excludeIP / CIDR / MAC list(empty)No
unmanaged_audit.interval_hoursint168No
unmanaged_audit.max_parallelint 1–42No
unmanaged_audit.product_checkbool (needs unmanaged_audit.enabled)falseNo
unmanaged_audit.noauth_checkbool (needs unmanaged_audit.enabled)falseNo
design_flaw.enabledboolfalseNo
design_flaw.llm.toolclaude | opencode | codex | agy | (empty)(empty)No
design_flaw.llm.modelstring(empty)No
design_flaw.llm.timeout_secsint (0 or 5–600)0No
security.on_revokedlockdown | wipe | nonelockdownNo
security.lockdown_after_offline_daysint (0 = off)0No

12. Detección de DHCP e IPv6 no autorizados

Detecta ataques en los que un router u otro dispositivo introducido se hace pasar por legítimo y secuestra la ruta de comunicación de los equipos. Solo detecta y notifica; no bloquea el tráfico. Está activado por defecto y no requiere captura pasiva. Los resultados aparecen en roamswitch-sensor network-threats, la TUI, las notificaciones, los registros y las exportaciones.

12.1 Servidores DHCP no autorizados (IPv4 y DHCPv6)

Cada hora envía un solo DHCP discover desde una MAC aleatoria y cuenta todos los servidores que responden. No envía REQUEST ni toma ninguna dirección en préstamo. Aprende el primer servidor como legítimo y avisa de los que aparecen después. Los que reparten otra puerta de enlace u otro DNS son critical.

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

Anuncios de router no autorizados: si un dispositivo distinto de la puerta de enlace IPv4 actúa como router IPv6, se notifica (en una configuración normal, regístrelo en ipv6.allowed_routers). Se ignoran los anuncios cuyo límite de saltos no es 255. Suplantación NDP: se avisa cuando se intercambia la MAC de una dirección IPv6 (high si es un router). Dispositivos visibles solo por IPv6: se informa de los dispositivos que aparecen únicamente en la tabla de vecinos.

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

Si se configuran dhcp.allowed_servers y ipv6.allowed_routers, se informa de toda respuesta de cualquier otro (si están vacíos, se aprende el primero). ipv6.enabled permite desactivar la supervisión de IPv6. La escucha IPv6 de la API de control (50543) se añade con control.listen_ipv6 (por defecto false). El IPv6 global puede ser alcanzable desde internet, por lo que está desactivado por defecto.

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

La auditoría activa de vulnerabilidades del §5 solo se dirige a los equipos emparejados y que han dado su consentimiento. Si se quiere comprobar «qué está abierto al exterior» en impresoras, cámaras, NAS, etc. sin emparejar, se puede usar una comprobación distinta y mucho más limitada. Los diagnósticos profundos como OpenVAS, los intentos de inicio de sesión, la explotación de vulnerabilidades, nmap NSE y los análisis de todos los puertos solo se realizan en los equipos que han dado su consentimiento.

13.1 Qué hace

Consiste solo en comprobaciones de conexión TCP a 55 puertos fijos, la lectura del banner que un puerto abierto envía por sí mismo (un único HEAD / en servicios web) y notas sobre vulnerabilidades ya publicadas. El resultado es «accesible desde la LAN», no «vulnerable». La comprobación del producto y la de autenticación son opciones independientes que hay que activar (desactivadas por defecto).

13.2 Activarla

Antes de activarlo, configure unmanaged_audit.authorization (quien aprueba) y unmanaged_audit.allowed_cidrs (el rango; se rechaza si es más amplio que /16 en IPv4 o /48 en IPv6). La ejecución programada es, por defecto, cada 168 horas; la manual requiere --confirm.

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

Los equipos fuera de allowed_cidrs, los de unmanaged_audit.exclude, los dispositivos emparejados y el propio Sensor no se examinan nunca, bajo ninguna circunstancia. La MAC se comprueba antes y después; si es de otro equipo, se cancela o se descarta el resultado. El texto de authorization queda en el registro en cada ejecución.

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

unmanaged_audit.product_check (desactivado por defecto) lee el nombre del producto en la interfaz web de un equipo e indica si tiene una vulnerabilidad de CISA KEV. Solo envía GET / y redirecciones (como máximo 2) a los puertos web (80, 8080, 8181, 443, 8443, 10443). Por diseño, no envía inicios de sesión, intentos de contraseña, rutas adivinadas ni entradas que exploten vulnerabilidades. Como máximo 12 solicitudes por equipo, con 150 ms de intervalo.

Un producto solo se nombra cuando todos sus indicadores aparecen en la misma respuesta. Si la versión que informa el equipo tiene un CVE en un rango afectado del NVD, se notifica como «afectado» (high); si no se puede leer la versión, como aviso «sin confirmar» (medium), y no se afirma que sea vulnerable. Solo MikroTik RouterOS muestra una versión legible. Entre los productos compatibles están Fortinet FortiGate, Ivanti Connect Secure y Citrix NetScaler. Los indicadores se basan en firmas de detección públicas y no se han verificado en equipos reales.

La copia de KEV viene incluida. Solo cuando product_check y updates.fetch_cve_map están ambos activados, se descarga cada 24 horas un archivo del feed público de CISA (no se envía ninguna información de la LAN).

Comprobación de si responde sin autenticación (unmanaged_audit.noauth_check; desactivada por defecto, requiere activación expresa) Envía una única solicitud de solo lectura a cada uno de los siguientes puertos, y solo si estaban abiertos: Redis (6379, PING), Memcached (11211), Docker API (2375), Elasticsearch (9200), etcd (2379), CouchDB (5984), kubelet (10250), ZooKeeper (2181), Ollama (11434). No escribe, no cambia la configuración, no envía AUTH, no envía ni adivina contraseñas y no inicia sesión.

MongoDB, MySQL y similares no se examinan, porque un intento podría equivaler a un inicio de sesión. El resultado es uno de estos: «respondió sin autenticación», «requiere autenticación», «rechazado» o «no se pudo determinar». Solo se ejecuta con el mismo consentimiento que la auditoría ligera. Úsela únicamente en equipos que administre.

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

Cuando se revoca un Sensor con roamswitch-sensor-collector revoke <clave pública> --reason motivo, sus envíos se rechazan con 403 sensor_revoked. Un Sensor que se entera de la revocación se detiene por sí mismo (bloqueo) y detiene la auditoría, el envío, las notificaciones y el sondeo. La detención se mantiene tras reiniciar y los datos permanecen. Solo cuando se tenga la certeza de que el Sensor está en manos de su propietario puede levantarse con roamswitch-sensor lockdown off.

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

Con security.on_revoked en wipe, al revocar se sobrescriben con ceros y se eliminan las claves, la clave TLS, la configuración (incluida la URL del Webhook), la lista de dispositivos, los resultados de auditoría y el inventario de equipos. Solo se conservan, como evidencia, los registros de operaciones y aprobaciones. El valor por defecto, lockdown, solo detiene el Sensor. Con security.lockdown_after_offline_days (0 por defecto = desactivado), un Sensor que no puede enviar durante mucho tiempo también se detiene por sí mismo.

14.3 Lo que esto no puede hacer

Los dispositivos siguen confiando en este Sensor hasta que cada uno lo desvincule, y el Sensor no puede avisarles. En cada dispositivo mostrado, ejecute roamswitch sensor unpair <clave pública de este Sensor> en Linux, o Ajustes > Sensor > Desemparejar en Mac. Un Sensor sustraído apagado no recibe la orden de detención, así que el cifrado del disco (LUKS, etc.) es la defensa real. El borrado por sobrescritura no garantiza un borrado completo en flash ni en CoW.

← Manual de Operaciones de Server Edition A la página de instalación de la edición Linux →