Guia de operações CLI/headless

1. Componentes

Uma implantação headless é executada no daemon + roamswitch CLI (mais roamswitch-mcp se desejado). Todos os mecanismos de defesa autônomos funcionam sem qualquer GUI.

2. Daemon (serviços systemd)

Edição Cliente

sudo systemctl status  roamswitch.service      # Estado de funcionamento
sudo systemctl enable  roamswitch.service      # Início automático no arranque (ativado na instalação)
sudo systemctl restart roamswitch.service      # Reiniciar
journalctl -u roamswitch.service -f            # Acompanhar registos
journalctl -u roamswitch.service --since "1h ago"

O que o daemon cliente faz de forma autônoma na inicialização e em cada ciclo (3 s):

• Identifica o gateway MAC conectado e aplica perfis nftables (open / balanced / lockdown) em trusted_networks
• Detecção comportamental de ransomware (fanotify + entropia de Shannon + canários)
• Verificação de malware no acesso (fanotify, opcionalmente ClamAV)
• Monitoramento de falsificação de ARP e fixação preventiva de gateway ARP/NDP em redes não confiáveis
• Endurecimento do kernel (sysctl/Yama/core dumps//tmp noexec) por perfil
• Aplicação de DNS de proteção contra ameaças (dns_enabled + dns_scope)
• Link guard (NFQUEUE) para interceptação de phishing
• Saída do estado de tempo de execução para /run/roamswitch/state.json

Edição de servidor

sudo systemctl status  roamswitch-server.service      # Estado de funcionamento
sudo systemctl restart roamswitch-server.service      # Reiniciar
journalctl -u roamswitch-server.service -f            # Acompanhar registos

3. Referência de comando CLI

Sintaxe básica: roamswitch <command> [options]. Executar sem argumentos tem como padrão status. O idioma de saída segue automaticamente a localidade do sistema operacional (LC_ALL/LC_MESSAGES/LANG).

Política de isolamento (Air-Gap)

Libertar apenas com um temporizador fixo permite que um atacante paciente espere, pelo que o desencadeador de um isolamento é classificado por confiança (em ambas as edições).

• Baixa confiança (um Air-Gap manual, anomalias genéricas, eBPF Error / Warning e inferiores): totalmente restaurado após um temporizador curto (cliente: airgap_low_confidence_secs, 600 s por predefinição; servidor: safety_timer_secs em guard.yaml, 300 s por predefinição; 0 desativa o temporizador).
• Alta confiança (adulteração de canary, reescrita em massa ao estilo ransomware, ARP spoofing sob lockdown, eBPF Critical / Emergency / Alert, disparo repetido da mesma regra e afins): nunca é restaurado em silêncio. Após o temporizador, a causa (PID congelado, canary, ARP, regra que volta a disparar) é reverificada e o isolamento é libertado, com uma notificação, apenas quando a causa é verificada como eliminada. Se isso não puder ser confirmado, ninguém o tiver reconhecido e o limite for atingido (cliente: airgap_hard_cap_secs; servidor: isolation_hard_cap_secs em server.conf; ambos 3600 s por predefinição, 0 = sem limite), passa para o modo DEGRADED.
• O modo DEGRADED nunca abre por temporizador (o cliente permite apenas loopback; o servidor permite apenas os caminhos de gestão de SSH de manutenção e de IPs da lista de permissões). Só é libertado por uma reverificação que confirme a eliminação, por um reconhecimento explícito (servidor: roamswitch server ack) ou por uma libertação manual (o botão da GUI / roamswitch emergency-restore). No modo DEGRADED do cliente, o rfkill do Wi-Fi também não é levantado, a menos que airgap_degraded_lift_rfkill seja true.
• As ligações estabelecidas que não sejam dos caminhos de gestão são cortadas (servidor: tudo exceto as portas SSH de manutenção e os IPs da lista de permissões, pelo que um canal C2 ou uma reverse shell que o atacante já tenha aberto também é cortado). Um Air-Gap manual é de baixa confiança quando vem do menu / GUI / roamswitch airgap enable sem contexto de aviso, mas quando é iniciado a partir do botão «bloquear agora» de um aviso de ARP spoofing herda a confiança (alta) desse aviso, e o MAC do gateway é reverificado, sem enviar tráfego, até coincidir com o MAC de confiança em verificações consecutivas (arp_recheck_consecutive verificações que abranjam pelo menos arp_recheck_min_secs segundos). Cada transição fica registada na cronologia de incidentes.

Recuperação de ransomware (snapshots e restauro de ficheiros)

Os comandos seguintes pertencem a roamswitch-ransomware-rollback (não são subcomandos de roamswitch). O seu estado é guardado em /var/lib/roamswitch.

Exemplos

sudo roamswitch status                 # Diagnóstico completo do cliente (27 itens)
sudo roamswitch status --server        # Diagnóstico completo do Server Edition (34 itens)
sudo roamswitch ports -a               # Todas as portas em escuta
roamswitch guards                      # Estado das proteções
roamswitch audit-url https://examp1e-login.com
roamswitch audit-secrets ./deploy.env
roamswitch audit-secrets .                          # Analisar recursivamente o diretório atual
roamswitch audit-logs 72               # Analisar registos das últimas 72 horas
sudo roamswitch sharing on             # Parar automaticamente SSH/Samba/RDP em redes não fiáveis
sudo roamswitch fim verify             # Verificação de integridade de ficheiros FIM
sudo roamswitch fim update             # Atualizar a linha de base do FIM
sudo roamswitch emergency-restore      # Levantar totalmente o bloqueio de emergência e restaurar
sudo roamswitch airgap enable          # Bloqueio de emergência
sudo roamswitch airgap disable         # Levantar
sudo roamswitch server ack             # Reconhecer o isolamento de emergência (mantém um isolamento FULL estrito, liberta um DEGRADED)
roamswitch canary                      # Histórico de incidentes do canário
roamswitch vuln-status                 # Mostra o último resultado da verificação e os dias decorridos (pass_age)
roamswitch port-anomaly                # Histórico de incidentes do Port Anomaly Guard
roamswitch server ebpf                 # Estado de isolamento e histórico de incidentes da guarda eBPF
roamswitch server bans                 # Estado da guarda contra força bruta SSH e lista das origens bloqueadas
sudo roamswitch server unban 203.0.113.9   # Levantar um bloqueio da guarda SSH (requer root)
roamswitch notifications               # Histórico de notificações dos últimos 7 dias
roamswitch frozen                      # Listar processos congelados
sudo roamswitch frozen resume 12345    # Libertar um falso positivo
sudo roamswitch sensor pair --addr 192.168.1.50 --code AB3DFGH2 --fingerprint 3F:45:89:E1:...:36:10  # Empareia com o Sensor usando um código de emparelhamento
sudo roamswitch sensor key             # Mostra a chave pública/endereço próprios deste endpoint
roamswitch port-scan                   # Histórico de detecção de varredura de portas
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

O daemon da edição servidor é executado como root, pelo que os comandos que precisam de ler o conjunto de regras nftables ou identificar o proprietário de um processo (status / status --server / ports -a) devolvem resultados incorretos sem sudo (um falso veredito de “inativo”, ou informação de processo em falta). Os comandos que alteram a configuração (sharing / fim update / airgap / emergency-restore, etc.) também precisam de sudo. Todos os outros comandos, apenas de leitura, funcionam corretamente sem ele.

4. Arquivos de configuração

Edição Cliente (~/.config/roamswitch/config.json)

O daemon é executado como root e verifica /home/*/.config/roamswitch/config.json, usando o primeiro arquivo válido que encontrar (ou /root/.config/roamswitch/config.json em ambientes somente root).

Edição de servidor (/etc/roamswitch/server.conf)

A edição servidor usa um ficheiro de configuração em formato INI protegido com permissões 0600 (apenas root). O tipo, os valores permitidos, a predefinição e a necessidade de reinício de cada chave estão no Manual de Operações do Servidor §18. Altere as chaves com roamswitch server config show|get|set ou no editor de configuração de roamswitch server tui (todas as 146 chaves de server.conf e guard.yaml). A edição servidor não suporta o recarregamento da configuração, por isso aplique as alterações com sudo roamswitch server restart.

Computadores partilhados: modo só para administradores

Num computador partilhado por várias pessoas, sudo touch /etc/roamswitch/admin-only ativa o modo só para administradores. As alterações que afetam todo o computador (firewall, DNS, VPN, USB, reforço do kernel e das montagens, rádios, confiança do Sensor e semelhantes) ficam então limitadas ao root ou aos utilizadores do grupo sudo, wheel ou roamswitch. As ações ligadas aos seus próprios ficheiros e processos (isolamento, kill, freeze, análises) funcionam como antes. /etc/roamswitch/admin-only só conta se pertencer ao root e não puder ser escrito por outros (um utilizador não o pode criar para mudar de modo). Está desativado por predefinição (sem ficheiro).

5. Logs e arquivos de estado de tempo de execução

Chamando IPC diretamente (avançado)

O daemon aceita JSON delimitado por nova linha em /run/roamswitch/roamswitch.sock:

# Forçar mudança de perfil (edição cliente)
printf '{"id":1,"method":"set_security_level","params":{"level":"lockdown"}}\n' \
  | sudo socat - UNIX-CONNECT:/run/roamswitch/roamswitch.sock

# Reconciliar agora o bloqueio ARP do gateway
printf '{"id":1,"method":"reconcile_gateway_lock","params":null}\n' \
  | sudo socat - UNIX-CONNECT:/run/roamswitch/roamswitch.sock

6. Status Programático (MCP)

roamswitch-mcp expõe ferramentas somente leitura sobre JSON-RPC em 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).

Não se liga a anfitriões externos e comunica localmente com o socket do daemon ou chama diretamente o roamswitch-core. get_security_report e verify_security_findings também não enviam nada para a LAN (o gateway só é lido da cache ARP e de outras informações locais). Consulte Guia de configuração do MCP

• Página do produto RoamSwitch para Linux
• Documento técnico sobre segurança do cliente
• Documento técnico sobre segurança do servidor
• Manual de Operações do Servidor
• AI Assistant e Guia de Integração MCP
• Perguntas frequentes