ROAMSWITCH PARA LINUX · REFERÊNCIA DE OPERAÇÕES

Guia de operações CLI/headless

Como operar o RoamSwitch para Linux sem GUI — em instâncias VPS na nuvem, por SSH, a partir de cron, scripts de monitoramento e agentes programáticos de IA (MCP).

Escolhendo a edição

Client Edition (roamswitch): Projetado para laptops, estações de trabalho móveis e dispositivos de desenvolvedor. Alterna automaticamente perfis de firewall nftables com base no nível de confiança da rede conectada. Este guia se concentra principalmente no gerenciamento headless/CLI da Client Edition.
Server Edition (roamswitch-server): Projetado para instâncias VPS em nuvem (AWS, GCP, DigitalOcean, Linode, etc.) e servidores locais expostos diretamente à Internet. Apresenta filtragem de queda padrão de entrada, prevenção de bloqueio SSH, monitoramento de integridade de arquivos de caminho crítico (FIM), integração de tempo de execução eBPF/Falco e notificações instantâneas (Telegram/LINE/Webhooks). Para obter instruções completas de instalação e gerenciamento, consulte o RoamSwitch Server Edition Operations Manual e o Server Security Whitepaper.

1. Componentes

Componente	Funciona como	Função
`roamswitch-daemon` (Cliente)	raiz (sistemad `Type=notify`)	Todas as operações privilegiadas do cliente: controle de nftables, detecção de rede, monitoramento de ransomware/malware, fanotify, fixação de ARP/NDP, aplicação de DNS. Não abre nenhum soquete de escuta TCP/UDP.
`roamswitch-server-daemon` (servidor)	raiz (sistemad `Type=notify`)	Todas as operações privilegiadas do servidor: queda padrão de entrada, SSH e preservação de bastiões de administração, FIM (mais de 150 hashes binários críticos), ouvinte de soquete Falco eBPF UNIX com congelamento `SIGSTOP` autônomo, despacho de alerta.
`roamswitch` (CLI)	usuário de login (algumas ações requerem sudo)	Estado do daemon de leitura do thin client. Usa `/run/roamswitch/roamswitch.sock` IPC no Client Edition ou fornece subcomandos `--server`, `server`, `fim` e `emergency-restore` no Server Edition.
`roamswitch-mcp`	gerado por clientes de IA	Servidor MCP somente leitura (stdio/JSON-RPC) para recuperação de status programática por agentes de IA. Consulte configuração MCP
`roamswitch-app`	usuário de login	GUI GTK (somente edição cliente). Não é necessário em ambientes sem cabeça.

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.

Pacotes mutuamente exclusivos

Client Edition (roamswitch) e Server Edition (roamswitch-server) são pacotes mutuamente exclusivos (Conflicts). Implante roamswitch-server em ambientes de servidor.

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
sudo systemctl reload  roamswitch-server.service      # Recarregar ficheiro de configuração
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).

Comando	Permissões	Descrição
`status [--server]` (alias `report` / `server-status`)	Usuário	Avaliação da integridade da segurança (24 verificações no cliente, 30 verificações com `--server`), pontuação de 0 a 100, nota e recomendações por item
`server [config\|setup\|test-notify\|restart\|ebpf]`	Usuário/raiz	Gerenciamento de configuração do Server Edition, assistente de configuração interativo e notificações de teste. `ebpf` (aliás `incidents`) mostra o estado de isolamento atual da eBPF Runtime Guard e o histórico de incidentes detetados
`fim [verify\|update]`	Usuário/raiz	Verificação do monitoramento de integridade de arquivos de caminho crítico (`verify`) e atualização do banco de dados hash de linha de base (`update`)
`emergency-restore`	raiz	Elimine todos os isolamentos emergenciais de eBPF/firewall e restaure a linha de base da rede
`ports [-a\|--all]`	Usuário	Portas de escuta em 0.0.0.0, bancos de dados não autenticados e servidores de desenvolvimento. `-a` inclui portas somente loopback
`guards`	Usuário	Status das proteções de defesa automáticas (anomalia de porta, ARP, armazenamento USB, download, ameaça de DNS, canário, isolador de servidor de desenvolvimento, Bluetooth)
`wifi`	Usuário	Força de criptografia Wi-Fi (Open/WEP/WPA/com fio) e SSID
`sharing [status\|on\|off]`	Usuário	Parada automática/restauração de SSH/Samba/RDP em redes não confiáveis (`on` desconecta SSH ativo quando não confiável)
`audit-url <URL>`	Usuário	Inspecione phishing de URL e risco de ameaça por meio de feed local + heurística (nunca busca o alvo)
`audit-secrets <text\|path\|directory>`	Usuário	Deteta chaves de API, chaves privadas e tokens em texto, num ficheiro ou diretório (recursivo; ignora .git/node_modules, etc.) — nunca transmite dados
`audit-logs [hours]`	Usuário	Agrega e classifica os registos de diário/autenticação do sistema das últimas N horas (padrão 24). As chaves API e os tokens são mascarados automaticamente. Também mostra os resultados de deteção de anomalias de padrões de registo (padrões novos e picos de frequência estatísticos).
`canary`	Usuário	Status e integridade do arquivo isca canário ransomware, e histórico de incidentes detetados (até os 50 mais recentes)
`port-anomaly` (aliás `port-guard`)	Geral	Estado da linha de base do Port Anomaly Guard, portas atualmente auto-isoladas, e histórico de incidentes detetados (até os 50 mais recentes)
`quarantine [list]`	Usuário	Conteúdo do cofre de quarentena de malware (amostra, caminho original, nome da ameaça, data)
`knowledge [query]` (alias `faq`)	Usuário	Pesquise na base de conhecimento off-line
`airgap [enable\|disable]`	Usuário/raiz	Acionar ou suspender o isolamento de emergência do Air-Gap (`enable` elimina todo o tráfego externo)
`help` (`--help` / `-h`)	Usuário	Mostrar ajuda (`roamswitch <command> --help` para ajuda do subcomando)
`scan-packages [PASTA...]`	Geral	Compara os pacotes do SO instalados (deteta automaticamente dpkg/pacman/dnf/zypper) com o mapeamento de CVE conhecido local. Se forem passadas pastas como argumento, também verifica os ficheiros de bloqueio de dependências desse projeto (npm/PyPI/crates.io e mais 4 ecossistemas). Sem qualquer atividade de rede
`scan-vulns [--confirm]`	Geral	Só é executado se `active_vuln_scan_enabled: true` (desativado por predefinição): verificações de acessibilidade não autenticada limitadas a 127.0.0.1 para Redis/Memcached/MongoDB/dockerd, deteção de configuração incorreta de CORS/path traversal/redirecionamento aberto em servidores de desenvolvimento detetados, diagnóstico de open relay SMTP, e diagnósticos de exposição baseados em prova para Telnet/FTP/SSH. Sem `--confirm` é uma simulação
`notifications` (alias `notification-history`)	Usuário	Histórico das notificações enviadas pelo RoamSwitch (anomalias de auditoria de registos, deteções de ClickFix e outras) — últimos 7 dias, mais recentes primeiro
`frozen [list\|resume <PID>\|resume all]`	Utilizador / root	Lista os processos que as guardas (deteção de rajada de ransomware, adulteração de ficheiro canário, deteção de exploit do kernel) mantêm em `SIGSTOP` e liberta (`SIGCONT`) um falso positivo. Congelar não é terminar: o processo libertado retoma exatamente onde parou. `resume all` liberta todos. Libertar um processo do root requer sudo
`resource-guard` (alias `leak-guard`)	Usuário	Historial de incidentes da guarda de esgotamento de recursos e anomalias de processos (apenas Server Edition): crescimento sustentado do RSS (fuga de memória / DoS) ou ciclos de falha em serviços expostos, com um nível de confiança
`timeline` (alias `incident-timeline`)	Usuário	Reúne as deteções do link guard (falsificação ARP), do canary anti-ransomware, da guarda de execução eBPF e da guarda de recursos numa única linha cronológica, com ascendência de processos e etiquetas MITRE ATT&CK (experimental)
`xdp-gate [status\|enable\|disable]`	Utilizador / root	Mostra ou alterna a porta XDP de arranque (experimental). `status` indica se `roamswitch-xdp-gate.service` está ativado e o estado atual do programa. Desativado por predefinição
`sensor [key\|list\|pair\|unpair\|request-audit\|results]`	Usuário/root	Confiança mútua por código de emparelhamento com o RoamSwitch Sensor, um sensor de rede de um repositório separado que se instala em hardware genérico. `pair --addr <ip> --code <code>` resgata um código emitido pelo Sensor para emparelhar (presume-se que o Sensor seja executado com um IP fixo), `key` mostra a chave pública/endereço próprios deste endpoint, `unpair` remove o emparelhamento, e `request-audit` pede ao Sensor para executar uma auditoria ativa de vulnerabilidades (obtenha o resultado com `results`). Requer `sensor_pairing_enabled: true` (desativado por padrão). Consulte o Manual de Operações do Sensor para mais detalhes
`port-scan` (alias `portscan`)	Usuário	Mostra o histórico de detecção da proteção de detecção de varredura de portas de entrada (IP de origem, se foi bloqueado automaticamente e a duração do bloqueio). Um recurso diferente de `port-anomaly`, que detecta portas desconhecidas recém-“expostas”

Exemplos

sudo roamswitch status                 # Diagnóstico completo do cliente (24 itens)
sudo roamswitch status --server        # Diagnóstico completo do Server Edition (30 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             # Confirmar o temporizador de segurança (parar a recuperação automática)
roamswitch canary                      # Histórico de incidentes do canário
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 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  # 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

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.

Advertências e Limitações

A ajuda específica do subcomando é suportada por meio de roamswitch <command> --help.
O status legível pela máquina deve ser consultado via MCP (§6) ou /run/roamswitch/state.json (§5).
Na Client Edition, não há comando direto para forçar um perfil de firewall; o daemon gerencia isso de forma autônoma com base na confiança da rede. Para forçar um nível, configure manual_override em config.json ou ligue diretamente para o IPC set_security_level (§5).
status retorna o código de saída 0 independentemente da pontuação. Para monitoramento automatizado, analise a linha de pontuação (consulte §7).

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

Chave	Tipo/Padrão	Descrição
`language`	string / localidade do SO	Linguagem UI e CLI (`ja` / `en` / `ko` / `zh-Hans` / `zh-Hant` / `de` / `fr` / `es` / `it` / `pt-PT`)
`trusted_networks`	`[{name, mac, level}]`	Redes confiáveis; `mac` é gateway MAC, `level` é `open` / `balanced` / `lockdown`
`away_protection_level`	string /`lockdown`	Perfil padrão em redes desconhecidas
`manual_override`	string/nulo	Forçar `open` / `balanced` / `lockdown` (nulo para automático)
`dns_enabled`	bool/`true`	Aplicação de DNS de proteção contra ameaças
`dns_provider`	string /`quad9`	`quad9` / `cloudflare` / `adguard` / `cleanBrowsing`
`dns_scope`	string /`untrusted_only`	`untrusted_only` / `always_on`
`arp_spoof_guard_enabled`	bool/`true`	Monitoramento de falsificação de ARP
`gateway_arp_lock_enabled`	bool/`true`	Bloqueio preventivo de gateway ARP/NDP em redes não confiáveis
`port_anomaly_guard_enabled`	bool/`true`	Bloquear automaticamente novas portas de escuta
`system_wide_fanotify_enabled`	bool/`true`	Fanotify proteção contra malware em todo o sistema
`pre_exec_blocking_enabled`	bool/`true`	Bloqueio de pré-execução (`FAN_DENY`)
`entropy_freeze_enabled`	bool/`true`	Congelamento rápido de ransomware (`SIGSTOP`)
`mount_hardening_enabled`	bool/`true`	`noexec` em `/tmp` e `/dev/shm` (aplicado em perfis não abertos)
`yama_memory_protect_enabled`	bool/`true`	Restrições do Yama ptrace
`usb_storage_guard_enabled` / `usb_keyboard_guard_enabled`	bool/`false`	Armazenamento USB/proteção de teclado BadUSB (desativado por padrão)
`usb_zero_trust_enabled`	bool/`false`	Barramento USB autorizado_default=0
`bluetooth_guard_enabled`	bool/`false`	Desative o rádio Bluetooth em redes não confiáveis
`sharing_service_control_enabled`	bool/`true`	Parar/restaurar automaticamente SSH/Samba/RDP
`scan_exclusions`	`[string]`	Caminhos absolutos excluídos da verificação
`link_guard`	objeto	`{enabled, mode: "off"\|"warn"\|"block", allowlist, blocklist_extra, use_threat_dns}`
`vpn_on_untrusted_enabled`	bool/`false`	Túnel VPN de inicialização automática em redes não confiáveis
`vpn_backend`	string /`wireguard`	`wireguard` / `tailscale`
`active_vuln_scan_enabled`	bool / `false`	Permite a execução de `scan-vulns` (desativado por predefinição). Requer ativação explícita, pois envia sondas de acessibilidade limitadas a 127.0.0.1
`pkgcve_watched_folders`	`[string]`	Pastas de projeto (caminhos absolutos) verificadas pela verificação de dependências da GUI. O comando `scan-packages` da CLI ignora esta definição e usa apenas as pastas passadas como argumentos de linha de comandos
`sensor_pairing_enabled`	bool / `false`	Permite a confiança mútua por código de emparelhamento com o RoamSwitch Sensor (desativado por padrão). Necessário para usar o comando `sensor`
`port_scan_detect_enabled`	bool / `true`	Proteção de detecção de varredura de portas de entrada
`port_scan_detect_min_distinct_ports`	int / `15`	Uma origem que se conecta a pelo menos esse número de portas distintas dentro da janela de detecção é considerada uma varredura
`port_scan_detect_window_secs`	int / `300`	Janela de agregação para a detecção de varredura (segundos)
`port_scan_block_enabled`	bool / `true`	Bloqueia automaticamente o IP de origem da varredura detectada
`port_scan_block_duration_secs`	int / `600`	Duração do bloqueio automático (segundos)

Cuidado com SSH remoto

Com sharing_service_control_enabled: true, conectar-se a uma rede não confiável desconecta sessões SSH ativas. Deixe-o desativado em servidores headless.

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

Server Edition usa um arquivo de configuração no formato INI com permissões estritas (0600, somente root). Consulte o Manual de Operações do Server Edition

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

Caminho	Alvo	Descrição
`journalctl -u roamswitch.service`	Cliente	Logs do daemon do cliente (alterações de perfil, detecções, erros)
`journalctl -u roamswitch-server.service`	Servidor	Logs do daemon do servidor (eventos FIM, detecções Falco, isolamentos)
`/run/roamswitch/roamswitch.sock`	Cliente	Soquete de domínio Unix do daemon do cliente IPC
`/run/roamswitch/events.sock`	Servidor	Soquete de integração Falco / Tetragon eBPF (root:root, modo 0660; Falco é executado como root por padrão, permitindo gravações diretas de soquete com configuração zero)
`/run/roamswitch/state.json`	Cliente	Estado do ciclo: `{active_level, network_trusted, fanotify_ready}`
`/run/roamswitch/alerts.json`	Cliente	Fila de alertas recentes
`/run/roamswitch/approvals.json`	Cliente	Fila de aprovação pendente
`/run/roamswitch/fanotify.ready`	Cliente	Arquivo de sinalização indicando que o fanotify guard está em execução
`/var/lib/roamswitch/fim_baseline.db`	Servidor	Banco de dados hash de linha de base FIM SHA-256
`~/.local/share/roamswitch/quarantine/`	Ambos	Cofre de quarentena (`0700`, amostras `0400`) + `.metadata.json`

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 / get_exposed_ports / get_guard_status / audit_url_safety / audit_secrets / audit_security_logs / 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_canary_status / get_notification_history / get_incident_timeline / run_active_vuln_scan / run_package_cve_scan / run_package_cve_scan_languages).

Ele não usa comunicação de rede externa, conectando-se localmente ao soquete daemon ou chamando roamswitch-core. Consulte Guia de configuração do MCP

7. Receitas de automação

Verificação diária de integridade do cron → Enviar e-mail se a pontuação cair abaixo do limite

#!/usr/bin/env bash
# /etc/cron.daily/roamswitch-health
out=$(runuser -u "$SUDO_USER" -- roamswitch status 2>&1)
score=$(printf '%s\n' "$out" | grep -oE '[0-9]+/100' | head -1 | cut -d/ -f1)
if [ -n "$score" ] && [ "$score" -lt 80 ]; then
  printf '%s\n' "$out" | mail -s "RoamSwitch health: ${score}/100" root
fi

Fila de alertas do monitor (poll alerts.json)

#!/usr/bin/env bash
last=0
while :; do
  ts=$(jq -r 'max_by(.timestamp).timestamp // 0' /run/roamswitch/alerts.json 2>/dev/null || echo 0)
  if [ "$ts" -gt "$last" ]; then
    jq -c ".[] | select(.timestamp > $last)" /run/roamswitch/alerts.json | logger -t roamswitch-alert
    last=$ts
  fi
  sleep 10
done

Verifique a integridade do guarda fanotify (state.json)

jq -e '.fanotify_ready == true' /run/roamswitch/state.json >/dev/null \
  || echo "WARNING: fanotify guard is not running" >&2

8. Solução de problemas

Sintoma	Resolução
`roamswitch` sai com "verifique se roamswitch-mcp está instalado"	O Daemon não está rodando → `sudo systemctl start roamswitch.service` (ou `roamswitch-server.service`). Verifique se o soquete existe
`roamswitch status` mostra fanotify 🔴 "guarda parado"	Exaustão transitória `fs.fanotify.max_user_groups`. Reinicie com `sudo systemctl restart roamswitch.service` e verifique no diário
O perfil permanece em `balanced`, nunca chega a `open`	Verifique se o gateway MAC está registrado em `trusted_networks` com `level: open`
SSH desconecta inesperadamente	A edição do cliente possui `sharing_service_control_enabled: true` em uma rede não confiável. Desativar via `roamswitch sharing off`
As alterações de configuração não entram em vigor	The client daemon reads the first of `/home/*/.config/…`; apply with `systemctl restart roamswitch.service`. For the server edition, edit `/etc/roamswitch/server.conf` then run `sudo roamswitch server restart` (no reload).
Comunicações do servidor bloqueadas acidentalmente	Acesse o console da nuvem (VNC/Serial) e execute `sudo roamswitch emergency-restore`