CLI/Guía de operaciones sin cabeza

1. Componentes

Se ejecuta una implementación sin cabeza en el demonio + roamswitch CLI (más roamswitch-mcp si se desea). Todos los mecanismos de defensa autónomos funcionan sin ninguna GUI.

2. Daemon (servicios systemd)

Edición de cliente

sudo systemctl status  roamswitch.service      # Estado de funcionamiento
sudo systemctl enable  roamswitch.service      # Inicio automático al arrancar (habilitado en la instalación)
sudo systemctl restart roamswitch.service      # Reiniciar
journalctl -u roamswitch.service -f            # Seguir registros
journalctl -u roamswitch.service --since "1h ago"

Lo que hace el demonio cliente de forma autónoma al inicio y en cada ciclo (3 s):

• Identifica la MAC de la puerta de enlace conectada y aplica perfiles de nftables (open / balanced / lockdown) contra trusted_networks
• Detección de ransomware por comportamiento (fanotify + entropía de Shannon + canarios)
• Escaneo de malware en acceso (fanotify, opcionalmente ClamAV)
• Monitoreo de suplantación de ARP y fijación preventiva de ARP/NDP de puerta de enlace en redes no confiables
• Endurecimiento del kernel (sysctl / Yama / core dumps / /tmp noexec) por perfil
• Aplicación de DNS de protección contra amenazas (dns_enabled + dns_scope)
• Guardia de enlace (NFQUEUE) para interceptación de phishing
• Salida del estado de tiempo de ejecución a /run/roamswitch/state.json

Edición de servidor

sudo systemctl status  roamswitch-server.service      # Estado de funcionamiento
sudo systemctl restart roamswitch-server.service      # Reiniciar
journalctl -u roamswitch-server.service -f            # Seguir registros

3. Referencia de comandos CLI

Sintaxis básica: roamswitch <command> [options]. La ejecución sin argumentos tiene como valor predeterminado status. El idioma de salida sigue automáticamente la configuración regional del sistema operativo (LC_ALL / LC_MESSAGES / LANG).

Política de aislamiento (Air-Gap)

Liberar solo con un temporizador fijo permite que un atacante paciente espere, por lo que el desencadenante de un aislamiento se clasifica según su confianza (en ambas ediciones).

• Baja confianza (un Air-Gap manual, anomalías genéricas, eBPF Error / Warning e inferiores): se restaura por completo tras un temporizador corto (cliente: airgap_low_confidence_secs, 600 s de forma predeterminada; servidor: safety_timer_secs en guard.yaml, 300 s de forma predeterminada; 0 desactiva el temporizador).
• Alta confianza (manipulación del canario, reescritura masiva al estilo ransomware, suplantación ARP bajo lockdown, eBPF Critical / Emergency / Alert, activación repetida de la misma regla, etc.): nunca se restaura en silencio. Tras el temporizador se vuelve a comprobar la causa (PID congelado, canario, ARP, regla que se reactiva) y el aislamiento se libera con una notificación solo cuando se verifica que la causa ha desaparecido. Si no se puede confirmar, nadie lo ha reconocido y se alcanza el límite (cliente: airgap_hard_cap_secs; servidor: isolation_hard_cap_secs en server.conf; ambos 3600 s de forma predeterminada, 0 = sin límite), pasa al modo DEGRADED.
• El modo DEGRADED nunca se abre por temporizador (el cliente solo permite loopback; el servidor solo permite las rutas de administración de SSH de mantenimiento e IP de la lista blanca). Solo se libera mediante una nueva comprobación que verifique que la causa ha desaparecido, un reconocimiento explícito (servidor: roamswitch server ack) o una liberación manual (el botón de la interfaz gráfica / roamswitch emergency-restore). En el modo DEGRADED del cliente tampoco se levanta el rfkill del Wi-Fi, a menos que airgap_degraded_lift_rfkill sea true.
• Se cortan las conexiones establecidas distintas de las rutas de administración (servidor: todo excepto los puertos SSH de mantenimiento y las IP de la lista blanca, por lo que también se corta un canal C2 o una reverse shell que el atacante ya tenga abierta). Un Air-Gap manual es de baja confianza cuando procede del menú / la interfaz gráfica / roamswitch airgap enable sin contexto de advertencia, pero cuando se inicia desde el botón «bloquear ahora» de una advertencia de suplantación ARP hereda la confianza (alta) de esa advertencia, y la MAC de la puerta de enlace se vuelve a comprobar sin enviar tráfico hasta que coincide con la MAC de confianza en comprobaciones consecutivas (arp_recheck_consecutive comprobaciones que abarquen al menos arp_recheck_min_secs segundos). Cada transición se registra en la línea de tiempo de incidentes.

Recuperación de ransomware (instantáneas y restauración de archivos)

Los comandos siguientes pertenecen a roamswitch-ransomware-rollback (no son subcomandos de roamswitch). Su estado se guarda en /var/lib/roamswitch.

Ejemplos

sudo roamswitch status                 # Diagnóstico integral del cliente (27 elementos)
sudo roamswitch status --server        # Diagnóstico integral de Server Edition (34 elementos)
sudo roamswitch ports -a               # Todos los puertos en escucha
roamswitch guards                      # Estado de las protecciones
roamswitch audit-url https://examp1e-login.com
roamswitch audit-secrets ./deploy.env
roamswitch audit-secrets .                          # Escanear recursivamente el directorio actual
roamswitch audit-logs 72               # Analizar los registros de las últimas 72 horas
sudo roamswitch sharing on             # Detener automáticamente SSH/Samba/RDP en redes no confiables
sudo roamswitch fim verify             # Verificación de integridad de archivos FIM
sudo roamswitch fim update             # Actualizar línea base de FIM
sudo roamswitch emergency-restore      # Levantar por completo el bloqueo de emergencia y restaurar
sudo roamswitch airgap enable          # Bloqueo de emergencia
sudo roamswitch airgap disable         # Levantar
sudo roamswitch server ack             # Reconoce el aislamiento de emergencia (mantiene estricto un aislamiento FULL y libera uno en DEGRADED)
roamswitch canary                      # Historial de incidentes del canario
roamswitch vuln-status                 # Muestra el último resultado del escaneo y los días transcurridos (pass_age)
roamswitch port-anomaly                # Historial de incidentes del Port Anomaly Guard
roamswitch server ebpf                 # Estado de aislamiento e historial de incidentes del guardián eBPF
roamswitch server bans                 # Estado de la guardia contra fuerza bruta SSH y lista de los orígenes bloqueados
sudo roamswitch server unban 203.0.113.9   # Levantar un bloqueo de la guardia SSH (requiere root)
roamswitch notifications               # Historial de notificaciones de los últimos 7 días
roamswitch frozen                      # Listar procesos congelados
sudo roamswitch frozen resume 12345    # Liberar un falso positivo
sudo roamswitch sensor pair --addr 192.168.1.50 --code AB3DFGH2 --fingerprint 3F:45:89:E1:...:36:10  # Se empareja con Sensor mediante un código de emparejamiento
sudo roamswitch sensor key             # Muestra la clave pública/dirección propias de este endpoint
roamswitch port-scan                   # Historial de detección de escaneo de puertos
roamswitch timeline --json             # all incident-timeline records as JSON
roamswitch notifications --export n.jsonl   # JSON Lines
sudo roamswitch events search --since 2h --exe curl
sudo roamswitch forward status
sudo roamswitch server allowlist add "<rule>" mytool --exe /usr/local/bin/mytool
sudo roamswitch sensor repin <PUBLIC_KEY> --fingerprint <NEW_FINGERPRINT>
sudo roamswitch server tui

El daemon de la edición servidor se ejecuta como root, por lo que los comandos que necesitan leer el conjunto de reglas de nftables o identificar al propietario de un proceso (status / status --server / ports -a) devuelven resultados inexactos sin sudo (un falso veredicto de “inactivo”, o información de proceso faltante). Los comandos que modifican la configuración (sharing / fim update / airgap / emergency-restore, etc.) también requieren sudo. El resto de comandos, de solo lectura, funcionan correctamente sin él.

4. Archivos de configuración

Edición del cliente (~/.config/roamswitch/config.json)

El demonio se ejecuta como root y escanea /home/*/.config/roamswitch/config.json, utilizando el primer archivo válido que encuentra (o /root/.config/roamswitch/config.json en entornos solo root).

Edición de servidor (/etc/roamswitch/server.conf)

La edición de servidor usa un archivo de configuración en formato INI protegido con permisos 0600 (solo root). El tipo, los valores permitidos, el valor predeterminado y si requiere reinicio de cada clave figuran en Manual de operaciones del servidor §18. Cambie las claves con roamswitch server config show|get|set o en el editor de configuración de roamswitch server tui (las 146 claves de server.conf y guard.yaml). La edición de servidor no admite recargar su configuración, así que aplique los cambios con sudo roamswitch server restart.

Equipos compartidos: modo solo administrador

En un equipo compartido por varias personas, sudo touch /etc/roamswitch/admin-only activa el modo solo administrador. Los cambios que afectan a todo el equipo (cortafuegos, DNS, VPN, USB, refuerzo del kernel y de los montajes, radios, confianza de Sensor, etc.) quedan limitados a root o a los usuarios del grupo sudo, wheel o roamswitch. Las acciones ligadas a sus propios archivos y procesos (aislamiento, kill, freeze, análisis) funcionan como antes. /etc/roamswitch/admin-only solo cuenta si pertenece a root y los demás no pueden escribirlo (un usuario no puede crearlo para cambiar de modo). Está desactivado por defecto (sin archivo).

5. Registros y archivos de estado de tiempo de ejecución

Llamar a IPC directamente (avanzado)

El demonio acepta JSON delimitado por nueva línea en /run/roamswitch/roamswitch.sock:

# Forzar cambio de perfil (edición cliente)
printf '{"id":1,"method":"set_security_level","params":{"level":"lockdown"}}\n' \
  | sudo socat - UNIX-CONNECT:/run/roamswitch/roamswitch.sock

# Reconciliar ahora el bloqueo ARP de la puerta de enlace
printf '{"id":1,"method":"reconcile_gateway_lock","params":null}\n' \
  | sudo socat - UNIX-CONNECT:/run/roamswitch/roamswitch.sock

6. Estado programático (MCP)

roamswitch-mcp expone herramientas de solo lectura a través de JSON-RPC en stdio (get_security_report / verify_security_findings / get_exposed_ports / get_guard_status / audit_url_safety / audit_secrets / audit_security_logs / audit_mcp_configs / audit_agent_setup / get_app_help / get_quarantine_status / get_file_scan_guard_status / verify_fim / get_port_anomaly_incidents / get_ebpf_incidents / get_resource_guard_incidents / get_port_scan_incidents / get_ssh_guard_incidents / get_canary_status / get_vulnerability_scan_history / get_notification_history / search_exec_events / get_process_tree / get_incident_timeline / get_fleet_status / get_vpn_status / get_link_guard_status / get_air_gap_status / get_sharing_services_status / get_bluetooth_guard_status / get_usb_guard_status / run_active_vuln_scan / run_package_cve_scan / run_package_cve_scan_languages / run_package_lifecycle_script_scan / run_typosquat_scan / run_npm_audit_signatures / get_sensor_audit_results).

No se conecta a hosts externos y habla localmente con el socket del demonio o llama directamente a roamswitch-core. get_security_report y verify_security_findings tampoco envían nada a la LAN (la puerta de enlace solo se lee de la caché ARP y de otra información local). Consulte Guía de configuración de MCP

• Página del producto RoamSwitch para Linux
• Documento técnico sobre seguridad del cliente
• Documento técnico sobre seguridad del servidor
• Manual de operaciones del servidor
• Guía de integración de MCP y asistente AI
• Preguntas frecuentes