Manual de operaciones de RoamSwitch Server Edition

Instalación oficial, implementación y referencia operativa para Cloud VPS (AWS, GCP, Azure, Linode, DigitalOcean), centros de datos básicos y hosts de contenedores.

1. Descripción general y requisitos

RoamSwitch Server Edition es una suite de monitoreo de integridad y defensa autónoma sin cabeza (cero dependencias de GUI) diseñada para servidores Linux expuestos a la Internet pública.

A diferencia de la edición de cliente que cambia dinámicamente los perfiles según el estado de Wi-Fi, la edición de servidor aplica Inbound Default Drop, monitoreo de integridad de archivos (FIM) de ruta crítica, mitigación preventiva de LPE del kernel (Frag Gap), detección de amenazas en tiempo de ejecución de eBPF, prevención de bloqueo SSH y alertas de emergencia multicanal automatizadas (Telegram/LINE/Webhook).

Requisitos del sistema

• Distribuciones compatibles: Ubuntu 22.04/24.04 LTS, Debian 12+, AlmaLinux/Rocky Linux/RHEL 9+, Fedora 39+, openSUSE Leap 15.5+, Raspberry Pi OS (64 bits)
• Arquitecturas: x86_64 (amd64) o aarch64 (arm64)
• Kernel: Linux 5.10+ (se recomienda nftables, cgroups v2, eBPF BTF)
• Footprint: 20–30 MB de memoria residente, <0,1 % de CPU durante cargas de trabajo inactivas/normales

2. Procedimientos de instalación

El uso de repositorios oficiales firmados garantiza la resolución automática de dependencias y actualizaciones perfectas a través del administrador de paquetes del sistema estándar.

2.1 APT (sistema operativo Ubuntu/Debian/Raspberry Pi)

# 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 [arch=amd64,arm64 signed-by=/usr/share/keyrings/roamswitch-archive-keyring.gpg] https://lafine.net/apt stable main" \
  | sudo tee /etc/apt/sources.list.d/roamswitch.list

# 3. Instalar
sudo apt update && sudo apt install roamswitch-server

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

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

2.3 openSUSE (ziper)

sudo rpm --import https://lafine.net/rpm/RPM-GPG-KEY-roamswitch
sudo zypper addrepo https://lafine.net/rpm/opensuse/roamswitch.repo
sudo zypper refresh && sudo zypper install roamswitch-server

3. Configuración inicial y verificación del servicio

3.1 Estado del servicio

Después de la instalación, roamswitch-server.service se inicia inmediatamente y se habilita en el inicio del sistema.

sudo systemctl status roamswitch-server.service

3.2 Asistente de configuración interactivo

Ejecute el asistente de configuración interactivo con el siguiente comando para configurar de forma interactiva los puertos, las IP de origen de mantenimiento, los canales de notificación y la acción de contención (pulse Intro para aceptar cada valor predeterminado).

sudo roamswitch server setup

1. Puertos: introduzca los puertos de mantenimiento SSH (predeterminado 22) y los puertos de servicio públicos (predeterminado 80,443), separados por comas.
2. IP de origen de mantenimiento: indique las IP/CIDR del bastión SSH o de supervisión (p. ej. 203.0.113.50/32); déjelo en blanco para permitir SSH desde cualquier IP.
3. Canales de notificación: active el bot de Telegram, la API de mensajería de LINE y/o un webhook genérico (Slack / Discord / Teams).
4. Respuesta ante un evento crítico de eBPF: elija isolate (aislar el host), freeze (congelar el proceso) o alert_only (solo notificar). Tras guardar, se le pedirá enviar una notificación de prueba y reiniciar el servicio.
5. Actualizaciones automáticas de datos CVE del kernel (predeterminado n): elija si desea obtener de forma anónima, una vez al día desde lafine.net, la base de datos de CVE del kernel que usa la auditoría de aislamiento de contenedores (sin cadena de consulta, cookies ni cabeceras identificativas). Si se deja desactivado, la auditoría sigue funcionando con la línea base integrada. Esta es la única excepción a la política de cero código de red de Server Edition, y está desactivada por defecto (opt-in).
6. Configuración de File Scan Guard: elija si desea habilitar el análisis antivirus para relés de correo, carpetas compartidas y destinos de carga (§13), y defina los directorios objetivo. Opcional, desactivado por defecto.
7. Configuración de Resource Guard: active la protección de agotamiento de recursos que detecta un crecimiento sostenido de RSS (fugas de memoria/DoS) o bucles de fallos en servicios expuestos a la red.
8. Resumen de las protecciones principales siempre activas: muestra las defensas principales que se ejecutan permanentemente al margen del asistente: rechazo entrante predeterminado, FIM, integración eBPF, etc. (no requiere entrada).
9. Configuración de delegación al agente de investigación (investigation): elija si desea delegar automáticamente la investigación inicial — para eventos críticos de eBPF, o detecciones de manipulación de FIM de ruta crítica/archivos de bloqueo de dependencias, cuando se calificaron solo como notificación — a una CLI de agente de IA externo (Claude Code / agy / Codex CLI / OpenCode, o un comando personalizado) (§10.1). Desactivado por defecto.

3.3 Auditoría de seguridad del servidor de 30 elementos

sudo roamswitch status --server

Realiza una auditoría instantánea de 30 comprobaciones de las reglas de firewall, la mitigación de Frag Gap, las restricciones y permisos de Yama LSM y la exposición del puerto Docker, lo que produce una puntuación y calificación de seguridad de 0 a 100 (S a C).

4. Reglas de puertos y firewall

El archivo de configuración /etc/roamswitch/server.conf exige permisos 0600 (lectura/escritura solo para root) para proteger la información sensible. El formato es clave=valor plano; las cabeceras de sección como [network] se ignoran.

# --- Firewall ---
ssh_ports=22                     # Puerto de administración SSH (se mantiene incluso durante el aislamiento de emergencia)
allowed_ports=80,443             # Puertos de servicio públicos
whitelist_ips=203.0.113.10/32    # IP/CIDR de origen de mantenimiento (vacío = permitir todo, antes admin_source_ips)
protect_docker_ports=true        # Protección DOCKER-USER (evita que los contenedores eludan el firewall)
preserve_ssh_on_isolation=true   # Conserva la vía de administración SSH incluso durante el aislamiento de emergencia (false = corte total)

# --- Guardia de tiempo de ejecución eBPF ---
action_on_critical=isolate       # isolate | freeze (SIGSTOP+corte de red) | alert_only
ebpf_socket_path=/run/roamswitch/events.sock

# --- Bloqueo de Egress/C2 y sumidero DNS ---
egress_ip_blocklist_enabled=true # Predeterminado true. Inofensivo hasta que se pueble un feed (no bloquea nada)
dns_sinkhole_enabled=false       # Predeterminado false (para no romper el DNS interno/configuraciones split-horizon)
dns_sinkhole_provider=quad9      # quad9 | cloudflare | adguard | cleanbrowsing

# --- Datos CVE de aislamiento de contenedores (opt-in) ---
cve_kernel_map_updates_enabled=false # Predeterminado false. La única excepción de comunicación externa (una vez al día, anónima)

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

# --- Sistema ---
language=ja
fim_check_interval_secs=300      # Antes llamado scan_interval

Si edita el archivo directamente, reinicie el servicio para aplicar los cambios (roamswitch-server no admite recarga):

sudo roamswitch server restart

4.1 Política por nivel de gravedad (guard.yaml, opcional)

Si action_on_critical por sí solo no ofrece suficiente granularidad, cree /etc/roamswitch/guard.yaml (hay una plantilla en /etc/roamswitch/guard.yaml.example). Si no existe, se sintetiza automáticamente una política equivalente a partir de action_on_critical en server.conf, por lo que las instalaciones existentes no se ven afectadas.

policies:
  on_warning:
    action: log_and_notify
  on_critical:
    server_action: isolate_process
    kill_process: true
    fallback_to_host_isolation_after_retries: 3   # Escala automáticamente al aislamiento del host si el mismo proceso se repite
  on_emergency:
    action: isolate_host_all
    kill_process: true

server_safeguards:
  maintenance_ssh_ports: [22]
  safety_timer_secs: 300   # Restaura automáticamente tras estos segundos después del aislamiento si no llega ack (0 desactiva)

Temporizador de seguridad: cuando se activa un aislamiento del host (Air-Gap), el administrador investiga y luego lo confirma con el siguiente comando. Si no llega confirmación en safety_timer_secs, RoamSwitch restaura automáticamente el acceso de red para que un falso positivo no deje el servidor desconectado indefinidamente.

sudo roamswitch server ack

4.2 Bloqueo de salida / C2 y sumidero DNS

Con egress_ip_blocklist_enabled=true (predeterminado), las conexiones salientes hacia IP conocidas como maliciosas se bloquean mediante nftables. Se usa primero el feed de /var/lib/roamswitch/threatfeed/malicious_ips.txt (gestionado por el mecanismo de actualización), recurriendo si no existe a la semilla vacía incluida en el paquete (/usr/share/roamswitch/threatfeed/); por tanto, mientras no se haya poblado un feed, el valor predeterminado true no bloquea nada.

Establecer dns_sinkhole_enabled=true fuerza la resolución a través de un resolutor DNS de filtrado (Quad9 / Cloudflare / AdGuard / CleanBrowsing), bloqueando la resolución de dominios conocidos como maliciosos. Está desactivado (false) de forma predeterminada porque puede afectar al DNS interno o a configuraciones split-horizon.

4.3 Protección de detección de escaneo de puertos entrantes

Detecta las IP de origen que se conectaron a numerosos puertos distintos en poco tiempo, correlacionando las reglas de registro de nftables con journald (activado por defecto). Las fuentes de escaneo de alta confianza pueden bloquearse automáticamente durante un periodo determinado. Cuando se usa junto con RoamSwitch Sensor (una función distinta del §10.1: las sondas de auditoría de todos los puertos de un Sensor emparejado se excluyen como mitigación de falsos positivos), la propia IP del Sensor queda excluida automáticamente.

# --- Detección de escaneo de puertos entrantes (activada por defecto) ---
port_scan_detect_enabled=true              # false para desactivar
port_scan_detect_min_distinct_ports=15     # Se considera un escaneo cuando las conexiones alcanzan esta cantidad de puertos distintos
port_scan_detect_window_secs=300           # Ventana de agregación para la detección (segundos)
port_scan_block_enabled=true               # Bloquea automáticamente la IP de origen del escaneo detectado
port_scan_block_duration_secs=600          # Duración del bloqueo automático (segundos)

Puede consultar el historial de detección con el comando roamswitch port-scan.

5. Prevención de bloqueo SSH a prueba de fallos

El bloqueo accidental debido a una mala configuración del firewall es un desastre operativo intolerable. RoamSwitch Server Edition incorpora protecciones de varios niveles:

• ESTABLECIDO/RELACIONADO Pase incondicional: Las sesiones activas nunca se cancelan durante las recargas de reglas.
• Preservación de SSH en Air-Gap: Incluso bajo contención de ataque hostil, preserve_ssh_on_isolation = true mantiene acceso administrativo de CIDR autorizados para investigación.
• Atomic nftables Cargando con Rollback: Los errores de sintaxis de reglas desencadenan instantáneamente una reversión sin tiempo de inactividad al conjunto de reglas verificado anterior.

6. Protección de contenedores (Docker/Podman)

El comportamiento predeterminado de Docker crea reglas de iptables personalizadas que evitan los firewalls de host estándar, exponiendo los puertos del contenedor (por ejemplo, -p 8080:8080) directamente a Internet.

Cuando protect_docker_ports=true (predeterminado), RoamSwitch inserta reglas de inspección al principio de la cadena DOCKER-USER, de modo que el tráfico destinado a contenedores también cumple la política de allowed_ports y whitelist_ips. Esto evita de forma fiable la exposición accidental de, por ejemplo, contenedores de bases de datos de desarrollo.

Además, un vigilante en tiempo real supervisa docker events y le notifica en el momento en que un contenedor se inicia con --privileged o con un montaje de /var/run/docker.sock — un riesgo de fuga de contenedor. No requiere configuración, está siempre activo y solo notifica (no bloquea automáticamente).

7. Monitoreo de la integridad del archivo de ruta crítica (FIM)

Supervisa más de 150 archivos binarios esenciales (/bin/login, /usr/bin/sudo, /usr/sbin/sshd), configuraciones de autenticación (/etc/shadow, /etc/pam.d/) y unidades systemd que utilizan hashes SHA-256.

7.1 Verificación manual de hash

sudo roamswitch fim verify

7.2 Detección basada en eventos (instantánea)

Los archivos supervisados se vigilan individualmente mediante fanotify (FAN_CLASS_NOTIF, eventos de finalización de escritura), por lo que una manipulación se vuelve a verificar y se detecta en el instante en que ocurre, sin esperar al siguiente análisis periódico. El análisis periódico (predeterminado fim_check_interval_secs=300 segundos) sigue actuando como respaldo ante eventos no capturados.

7.3 Sincronización automática de referencia en actualizaciones del sistema operativo

En Debian/Ubuntu, la instalación de paquetes configura automáticamente el gancho DPkg::Post-Invoke en /etc/apt/apt.conf.d/99roamswitch-fim. En Fedora/RHEL/Rocky/AlmaLinux/openSUSE, una unidad systemd.path (roamswitch-fim-update.path) que vigila /var/lib/rpm cumple la misma función.

En Debian/Ubuntu, /etc/apt/apt.conf.d/99roamswitch-fim adjunta un gancho DPkg::Post-Invoke. Las actualizaciones legítimas de paquetes a través de sudo apt upgrade actualizan automáticamente la línea base FIM, eliminando alertas de falsos positivos.

sudo roamswitch fim update

8. Integración de Falco y Runtime Guard de eBPF

Se conecta a eventos eBPF del espacio del kernel (Falco/Tetragon) para detectar la escalada de privilegios del kernel de Frag Gap, escapes de contenedores y shells inversos no autorizados.

8.1 Arquitectura anti-inflación

Los agentes de seguridad tradicionales sufren graves explosiones de syslog y desgaste del disco. RoamSwitch se conecta directamente a Falco a través de un socket de dominio UNIX dedicado (/run/roamswitch/events.sock):

• El paquete /etc/falco/config.d/99-roamswitch-optimized.yaml transmite eventos directamente al demonio sin E/S de disco.
• /etc/logrotate.d/roamswitch-falco garantiza una rotación diaria limpia para cualquier salida de archivo alternativo.

8.2 Contención autónoma

Al detectar un ataque crítico, RoamSwitch emite inmediatamente SIGSTOP para congelar el PID del proceso infractor y aplica el aislamiento Air-Gap de nftables.

9. Alertas de emergencia (Telegram / LINE / Webhook)

Envía alertas inmediatas a canales de notificación externos cuando ocurren anomalías en los puertos, manipulación de FIM o eventos de contención de eBPF:

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

# LINE: token de acceso al canal de Messaging API e ID de usuario
line_channel_access_token = "YOUR_LINE_ACCESS_TOKEN"
line_user_id = "U1234567890abcdef1234567890abcdef"

# Webhook genérico (Slack, Discord, Teams, su propia plataforma de monitorización)
webhook_url = "https://hooks.slack.com/services/T00/B00/XXXXX"

Incluso sin configurar estos canales externos, cada alerta enviada también se conserva localmente durante los últimos 7 días. Consúltela con roamswitch notifications.

10. Integración de agente AI/MCP (protocolo de contexto modelo)

RoamSwitch Server Edition incluye roamswitch-mcp, lo que permite a los agentes de IA (Claude, Gemini, Cursor) monitorear el estado y la postura de la infraestructura.

Ejemplo de configuración (`claude_desktop_config.json`)

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

10.1 Delegación al agente de investigación (investigation: delegación de la investigación automatizada inicial a un agente de IA)

Mientras que el roamswitch-mcp del §10 atiende consultas del cliente de IA de una persona, la delegación investigation es un mecanismo independiente en el que el propio demonio lanza de forma autónoma una CLI de agente de IA externo, activada por un evento de detección. Se dirige a eventos críticos de eBPF calificados como solo notificación (que no desencadenaron aislamiento automático ni congelación de procesos), además de detecciones de manipulación de FIM de ruta crítica y archivos de bloqueo de dependencias. Al activarse, el demonio primero genera un informe de triaje inicial heurístico local (probabilidad de falso positivo, razonamiento, próximos pasos sugeridos) y luego lanza la CLI de agente de IA configurada como subproceso con ese informe adjunto, delegando la investigación adicional y el resumen. Desactivado por defecto.

# Añadir a /etc/roamswitch/guard.yaml (un archivo distinto de server.conf)
investigation:
  enabled: true
  command: "claude"                 # "claude" | "agy" | "codex" | "opencode" | cualquier comando personalizado
  args: ["-p"]                      # El prompt se añade automáticamente como el último argumento
  timeout_secs: 180

Los mismos ajustes también pueden configurarse desde el asistente interactivo de sudo roamswitch server setup (§3.2, último paso). Elija entre los preajustes de Claude Code (claude -p), agy (agy -p --dangerously-skip-permissions), Codex CLI (codex exec), OpenCode (opencode run), o un comando personalizado. Al volver a ejecutarlo, se selecciona automáticamente el preajuste correspondiente según la configuración guardada.

La delegación investigation nunca se invoca mientras la red está desconectada (por ejemplo, durante un Air-Gap activo, o cualquier estado equivalente a isolate_host_all).

11. Hoja de referencia de comandos CLI

12. Solución de problemas y preguntas frecuentes

P1. ¿RoamSwitch desconectará inesperadamente mi sesión SSH?

No. RoamSwitch permite incondicionalmente los estados de conexión ESTABLISHED/RELATED, así como ssh_ports (predeterminado 22). Incluso durante un aislamiento de emergencia Air-Gap desencadenado por un ataque grave, preserve_ssh_on_isolation=true (predeterminado) mantiene activa su sesión de administración.

P2. ¿Cómo recupero el acceso si me quedo bloqueado accidentalmente?

Inicie sesión a través de la consola web de su proveedor de nube (VNC / consola serie) y ejecute sudo roamswitch emergency-restore para desactivar el aislamiento, o sudo systemctl stop roamswitch-server para detener el servicio.

P3. ¿Cómo expongo puertos para servicios web recién agregados (por ejemplo, Nginx)?

Ejecute sudo roamswitch server config set allowed_ports 80,443,3000 (o edite directamente /etc/roamswitch/server.conf) y después sudo roamswitch server restart.

13. File Scan Guard (protección de relés de correo, carpetas compartidas y puntos de subida)

Función opcional relevante solo si este host tiene un directorio que almacena archivos para otros: un relé de correo, un recurso compartido Samba/NFS, un punto de subida de archivos. El motor YARA integrado siempre analiza clamav_scan_dirs sin dependencias externas; al activar clamav_enabled=true se añade ClamAV como segunda opinión. Las amenazas confirmadas se ponen en cuarentena automáticamente en /var/lib/roamswitch/quarantine y se notifica al operador.

# --- File Scan Guard (ClamAV, opt-in) ---
# El motor YARA integrado siempre analiza clamav_scan_dirs de forma incondicional.
clamav_enabled=false             # true habilita la inspección adicional mediante clamdscan
clamav_scan_dirs=                # Rutas absolutas a analizar (separadas por comas)
clamav_scan_interval_secs=86400  # Intervalo de análisis (segundos, mínimo 3600)
clamav_freshclam_interval_secs=7200  # Intervalo de actualización automática de la base de firmas (segundos, mínimo 1800)

También configurable desde el asistente interactivo sudo roamswitch server setup; puede comprobar su configuración y el estado de la cuarentena con la herramienta MCP get_file_scan_guard_status.

14. Log Audit (detección y notificación de anomalías de patrones de registro)

Un análisis periódico de journalctl convierte los mensajes de registro en plantillas para detectar patrones nuevos (formas de registro nunca vistas) y anomalías de frecuencia (un pico estadístico, Z-score > 3.0). Es un mecanismo ligero que no requiere ningún demonio adicional ni dependencia externa, por lo que está habilitado de forma predeterminada. Las detecciones se envían a través de los mismos canales de notificación que File Scan Guard y FIM (Telegram / LINE / Webhook). Cualquier clave API o token que pueda aparecer en una línea de registro se enmascara automáticamente antes de incluirse en la notificación.

# --- Log Audit (habilitado de forma predeterminada) ---
log_audit_enabled=true           # false para deshabilitar
log_audit_interval_secs=1800     # Intervalo de exploración en segundos (mínimo 300)

También se puede configurar desde el asistente interactivo sudo roamswitch server setup, y los últimos resultados de detección se pueden consultar mediante el comando CLI roamswitch audit-logs o la herramienta MCP audit_security_logs.