ROAMSWITCH SERVER 1.1.0+ · Última atualização: 2026-09-18

Manual de operações do RoamSwitch Server Edition

Instalação oficial, implantação e referência operacional para Cloud VPS (AWS, GCP, Azure, Linode, DigitalOcean), data centers bare-metal e hosts de contêineres.

1. Visão geral e requisitos

RoamSwitch Server Edition é um conjunto autônomo de defesa e monitoramento de integridade headless (zero dependências de GUI) projetado para servidores Linux expostos à Internet pública.

Ao contrário da edição cliente, que alterna perfis dinamicamente com base no estado do Wi-Fi, a edição servidor impõe Inbound Default Drop, monitoramento de integridade de arquivos de caminho crítico (FIM), mitigação preventiva de LPE do kernel (Frag Gap), detecção de ameaças em tempo de execução eBPF, prevenção de bloqueio SSH e alertas de emergência multicanais automatizados (Telegram / LINE / Webhook).

Arquitetura de Telemetria Zero
O RoamSwitch não transmite telemetria de diagnóstico, metadados de IP do host, hashes de arquivos ou logs do sistema para servidores externos. Bibliotecas de rede externas estão ausentes do binário daemon, garantindo total confidencialidade local.

Requisitos do sistema

2. Procedimentos de instalação

O uso dos repositórios assinados oficiais garante a resolução automática de dependências e atualizações contínuas por meio do gerenciador de pacotes do sistema padrão.

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

# 1. Registrar a chave de assinatura do repositório
curl -fsSL https://lafine.net/apt/roamswitch-archive-keyring.asc \
  | sudo gpg --dearmor -o /usr/share/keyrings/roamswitch-archive-keyring.gpg

# 2. Adicionar o repositório
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 a chave GPG
sudo rpm --import https://lafine.net/rpm/RPM-GPG-KEY-roamswitch

# 2. Adicionar o arquivo de configuração do repositório
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 (zypper)

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
Exclusão mútua de pacotes (conflitos)
A Client Edition (roamswitch) e a Server Edition (roamswitch-server) declaram conflitos recíprocos de pacotes. Sempre selecione roamswitch-server em ambientes de servidor headless.

3. Configuração inicial e verificação de serviço

3.1 Status do Serviço

Após a instalação, roamswitch-server.service inicia imediatamente e é ativado na inicialização do sistema.

sudo systemctl status roamswitch-server.service

3.2 Assistente de configuração interativo

Execute o assistente de configuração interativo com o comando abaixo para configurar portas, IPs de origem de manutenção, canais de notificação e a ação de contenção de forma interativa (pressione Enter para aceitar cada valor padrão).

sudo roamswitch server setup
  1. Portas: insira as portas de manutenção SSH (padrão 22) e as portas de serviço públicas (padrão 80,443), separadas por vírgulas.
  2. IPs de origem de manutenção: informe os IPs/CIDRs do bastion SSH ou de monitoramento (ex.: 203.0.113.50/32); deixe em branco para permitir SSH de qualquer IP.
  3. Canais de notificação: ative o bot do Telegram, a API de mensagens do LINE e/ou um webhook genérico (Slack / Discord / Teams).
  4. Resposta a um evento crítico do eBPF: escolha isolate (isolar o host), freeze (congelar o processo) ou alert_only (apenas notificar). Após salvar, você será solicitado a enviar uma notificação de teste e reiniciar o serviço.
  5. Atualizações automáticas de dados de CVE do kernel (padrão n): escolha se o banco de dados de CVE do kernel usado pela auditoria de isolamento de contêineres deve ser obtido anonimamente do lafine.net uma vez por dia (sem query string, cookies ou cabeçalhos identificáveis). A auditoria continua funcionando com a linha de base incorporada mesmo se isso ficar desativado. Esta é a única exceção à política de zero código de rede da Server Edition, e vem desativada por padrão (opt-in).
  6. Configurações do File Scan Guard: escolha se deseja ativar a verificação de vírus para relés de e-mail, pastas compartilhadas e destinos de upload (§13), e defina os diretórios de destino. Opcional, desativado por padrão.
  7. Configurações do Resource Guard: ative a proteção contra esgotamento de recursos que detecta crescimento sustentado de RSS (vazamentos de memória/DoS) ou loops de falha em serviços expostos à rede.
  8. Visão geral das proteções principais sempre ativas: exibe as defesas principais que funcionam o tempo todo, independentemente do assistente — rejeição padrão de entrada, FIM, integração com eBPF etc. (nenhuma entrada necessária).
  9. Configurações de delegação ao agente de investigação (investigation): escolha se deseja delegar automaticamente a investigação inicial — para eventos críticos de eBPF, ou detecções de adulteração de FIM de caminho crítico/arquivos de bloqueio de dependências, quando classificados apenas como notificação — a uma CLI de agente de IA externo (Claude Code / agy / Codex CLI / OpenCode, ou um comando personalizado) (§10.1). Desativado por padrão.
Observação sobre o ID de chat do Telegram
O ID de chat de um supergrupo é um número negativo que começa com -100 (ex.: -1001234567890). Confirme o valor correto no campo "chat":{"id":...} da resposta de curl -s "https://api.telegram.org/bot<token>/getUpdates".

3.3 Auditoria de segurança de servidor de 30 itens

sudo roamswitch status --server

Executa uma auditoria instantânea de 30 verificações de regras de firewall, mitigação de Frag Gap, restrições Yama LSM, permissões e exposição de porta Docker, produzindo uma pontuação e nota de segurança de 0 a 100 (S a C).

4. Regras de firewall e porta

O arquivo de configuração /etc/roamswitch/server.conf exige permissões 0600 (leitura/gravação somente para root) para proteger informações sensíveis. O formato é chave=valor simples; cabeçalhos de seção como [network] são ignorados.

# --- Firewall ---
ssh_ports=22                     # Porta de gerenciamento SSH (mantida mesmo durante o isolamento de emergência)
allowed_ports=80,443             # Portas de serviço públicas
whitelist_ips=203.0.113.10/32    # IP/CIDR de origem de manutenção (vazio = permitir tudo, antigo nome admin_source_ips)
protect_docker_ports=true        # Proteção DOCKER-USER (impede que contêineres contornem o firewall)
preserve_ssh_on_isolation=true   # Preserva o caminho de gerenciamento SSH mesmo durante o isolamento de emergência (false = corte total)

# --- Guarda de runtime eBPF ---
action_on_critical=isolate       # isolate | freeze (SIGSTOP+corte de rede) | alert_only
ebpf_socket_path=/run/roamswitch/events.sock

# --- Bloqueio de Egress/C2 e sinkhole de DNS ---
egress_ip_blocklist_enabled=true # Padrão true. Inofensivo até que um feed seja populado (não bloqueia nada)
dns_sinkhole_enabled=false       # Padrão false (para não quebrar o DNS interno/configurações split-horizon)
dns_sinkhole_provider=quad9      # quad9 | cloudflare | adguard | cleanbrowsing

# --- Dados de CVE de isolamento de contêineres (opt-in) ---
cve_kernel_map_updates_enabled=false # Padrão false. A única exceção de comunicação externa (uma vez por dia, anônima)

# --- Notificações ---
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      # Antigo nome scan_interval

Depois de editar o arquivo diretamente, reinicie o serviço para aplicar as alterações (roamswitch-server não suporta recarregamento):

sudo roamswitch server restart

4.1 Política por nível de severidade (guard.yaml, opcional)

Se somente action_on_critical não oferecer granularidade suficiente, crie /etc/roamswitch/guard.yaml (um modelo é fornecido em /etc/roamswitch/guard.yaml.example). Se ausente, uma política equivalente é sintetizada automaticamente a partir de action_on_critical em server.conf, sem afetar implantações existentes.

policies:
  on_warning:
    action: log_and_notify
  on_critical:
    server_action: isolate_process
    kill_process: true
    fallback_to_host_isolation_after_retries: 3   # Escala automaticamente para isolamento do host se o mesmo processo recorrer
  on_emergency:
    action: isolate_host_all
    kill_process: true

server_safeguards:
  maintenance_ssh_ports: [22]
  safety_timer_secs: 300   # Restaura automaticamente após esses segundos pós-isolamento se nenhum ack chegar (0 desativa)

Temporizador de segurança: assim que um isolamento de host (Air-Gap) é acionado, o administrador investiga e depois confirma com o comando abaixo. Se nenhuma confirmação chegar dentro de safety_timer_secs, o RoamSwitch restaura automaticamente o acesso à rede para que um falso positivo não deixe o servidor isolado indefinidamente.

sudo roamswitch server ack

4.2 Bloqueio de Egress/C2 e sinkhole de DNS

Com egress_ip_blocklist_enabled=true (padrão), conexões de saída para IPs conhecidos como maliciosos são bloqueadas via nftables. O feed em /var/lib/roamswitch/threatfeed/malicious_ips.txt (gerenciado pelo mecanismo de atualização) é usado primeiro, com fallback para a semente vazia incluída no pacote (/usr/share/roamswitch/threatfeed/) — portanto, enquanto nenhum feed for populado, o padrão true não bloqueia nada.

Definir dns_sinkhole_enabled=true força a resolução por meio de um resolvedor DNS de filtragem (Quad9 / Cloudflare / AdGuard / CleanBrowsing), bloqueando a resolução de domínios conhecidos como maliciosos. O padrão é false, pois isso pode quebrar o DNS interno ou configurações split-horizon.

4.3 Proteção de detecção de varredura de portas de entrada

Detecta IPs de origem que se conectaram a muitas portas distintas em pouco tempo, correlacionando regras de log do nftables com o journald (ativado por padrão). Fontes de varredura de alta confiança podem ser bloqueadas automaticamente por um período definido. Ao usar em conjunto com o RoamSwitch Sensor (um recurso diferente da §10.1 — sondas de auditoria de todas as portas de um Sensor emparelhado são excluídas como mitigação de falsos positivos), o próprio IP do Sensor é excluído automaticamente.

# --- Detecção de varredura de portas de entrada (ativado por padrão) ---
port_scan_detect_enabled=true              # false para desativar
port_scan_detect_min_distinct_ports=15     # Considerado uma varredura quando as conexões atingem esse número de portas distintas
port_scan_detect_window_secs=300           # Janela de agregação para a detecção (segundos)
port_scan_block_enabled=true               # Bloqueia automaticamente o IP de origem da varredura detectada
port_scan_block_duration_secs=600          # Duração do bloqueio automático (segundos)

Você pode consultar o histórico de detecção com o comando roamswitch port-scan.

5. Prevenção contra falhas de bloqueio SSH

O bloqueio acidental por configuração incorreta do firewall é um desastre operacional intolerável. RoamSwitch Server Edition incorpora proteções em vários níveis:

6. Proteção de contêineres (Docker/Podman)

O comportamento padrão do Docker cria regras de iptables personalizadas que ignoram firewalls de host padrão, expondo portas de contêiner (por exemplo, -p 8080:8080) diretamente à Internet.

Quando protect_docker_ports=true (padrão), o RoamSwitch insere regras de inspeção no início da cadeia DOCKER-USER, para que o tráfego destinado a contêineres também obedeça à política de allowed_ports e whitelist_ips. Isso evita de forma confiável a exposição acidental de, por exemplo, contêineres de banco de dados de desenvolvimento.

Além disso, uma proteção em tempo real monitora docker events e notifica você no momento em que um contêiner é iniciado com --privileged ou com um bind-mount de /var/run/docker.sock — um risco de fuga de contêiner. Não requer configuração, está sempre ativa e apenas notifica (sem bloqueio automático).

7. Monitoramento de integridade de arquivos de caminho crítico (FIM)

Monitora mais de 150 binários essenciais (/bin/login, /usr/bin/sudo, /usr/sbin/sshd), configurações de autenticação (/etc/shadow, /etc/pam.d/) e unidades systemd usando hashes SHA-256.

7.1 Verificação manual de hash

sudo roamswitch fim verify

7.2 Detecção orientada a eventos (instantânea)

Os arquivos monitorados são observados individualmente via fanotify (FAN_CLASS_NOTIF, eventos de conclusão de gravação), de modo que uma adulteração é reverificada e detectada no instante em que ocorre, sem esperar a próxima varredura periódica. A varredura periódica (padrão fim_check_interval_secs=300 segundos) permanece como uma proteção de reserva para eventos perdidos.

7.3 Sincronização automática de linha de base em atualizações do sistema operacional

No Debian/Ubuntu, a instalação de pacotes configura automaticamente o gancho DPkg::Post-Invoke em /etc/apt/apt.conf.d/99roamswitch-fim. No Fedora/RHEL/Rocky/AlmaLinux/openSUSE, uma unidade systemd.path (roamswitch-fim-update.path) que monitora /var/lib/rpm desempenha o mesmo papel.

No Debian/Ubuntu, /etc/apt/apt.conf.d/99roamswitch-fim anexa um gancho DPkg::Post-Invoke. Atualizações legítimas de pacotes via sudo apt upgrade atualizam automaticamente a linha de base do FIM, eliminando alertas falsos positivos.

sudo roamswitch fim update

8. eBPF Runtime Guard e Integração Falco

Conecta-se a eventos eBPF do espaço do kernel (Falco/Tetragon) para detectar escalonamento de privilégios do kernel Frag Gap, escapes de contêiner e shells reversos não autorizados.

8.1 Arquitetura Anti-Inchaço

Os agentes de segurança tradicionais sofrem graves explosões de syslog e desgaste de disco. RoamSwitch se conecta diretamente ao Falco através de um soquete de domínio UNIX dedicado (/run/roamswitch/events.sock):

8.2 Contenção Autônoma

Ao detectar um ataque crítico, o RoamSwitch emite imediatamente SIGSTOP para congelar o PID do processo agressor e aplica o isolamento Air-Gap nftables.

9. Alertas de Emergência (Telegram/LINE/Webhook)

Envia alertas imediatos para canais de notificação externos quando ocorrem anomalias nas portas, adulteração de FIM ou eventos de contenção de eBPF:

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

# LINE: token de acesso ao canal Messaging API e ID do usuário
line_channel_access_token = "YOUR_LINE_ACCESS_TOKEN"
line_user_id = "U1234567890abcdef1234567890abcdef"

# Webhook genérico (Slack, Discord, Teams, sua própria plataforma de monitoramento)
webhook_url = "https://hooks.slack.com/services/T00/B00/XXXXX"

Mesmo sem configurar estes canais externos, cada alerta enviado também é guardado localmente durante os últimos 7 dias. Consulte-o com roamswitch notifications.

10. Integração Agente AI/MCP (Protocolo de Contexto do Modelo)

O RoamSwitch Server Edition inclui roamswitch-mcp, permitindo que agentes de IA (Claude, Gemini, Cursor) monitorem a integridade e a postura da infraestrutura.

Garantia de segurança somente leitura
Para evitar que ataques de injeção imediata comprometam a infraestrutura, a interface MCP é estritamente somente leitura. Os agentes de IA não podem abrir portas, remover isolamento ou alterar configurações de segurança via MCP. A correção requer acesso ao shell TTY local autenticado.

Exemplo de configuração (`claude_desktop_config.json`)

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

10.1 Delegação ao agente de investigação (investigation — delegação da investigação automatizada inicial a um agente de IA)

Enquanto o roamswitch-mcp da §10 atende consultas do cliente de IA de um humano, a delegação investigation é um mecanismo separado em que o próprio daemon inicia de forma autônoma uma CLI de agente de IA externo, acionada por um evento de detecção. Ela visa eventos críticos de eBPF classificados como apenas notificação (que não desencadearam isolamento automático ou congelamento de processo), além de detecções de adulteração de FIM de caminho crítico e arquivos de bloqueio de dependências. Quando ativado, o daemon primeiro gera um relatório de triagem inicial heurístico local (probabilidade de falso positivo, raciocínio, próximos passos sugeridos) e, em seguida, inicia a CLI de agente de IA configurada como subprocesso com esse relatório anexado, delegando investigação e resumo adicionais. Desativado por padrão.

# Adicionar a /etc/roamswitch/guard.yaml (um arquivo separado de server.conf)
investigation:
  enabled: true
  command: "claude"                 # "claude" | "agy" | "codex" | "opencode" | qualquer comando personalizado
  args: ["-p"]                      # O prompt é adicionado automaticamente como o último argumento
  timeout_secs: 180

As mesmas configurações também podem ser definidas no assistente interativo de sudo roamswitch server setup (§3.2, etapa final). Escolha entre predefinições para Claude Code (claude -p), agy (agy -p --dangerously-skip-permissions), Codex CLI (codex exec), OpenCode (opencode run), ou um comando personalizado. Ao executar novamente, a predefinição correspondente é selecionada automaticamente com base na configuração salva.

Observação sobre injeção de prompt
A delegação investigation transmite detalhes do evento de detecção — nomes de processo, caminhos de arquivo e outras strings que um invasor pode controlar parcialmente — como parte do prompt enviado ao agente de IA. Configurar a ferramenta para executar em um modo que ignora verificações de permissão, como --dangerously-skip-permissions, aumenta o risco de uma entrada maliciosa fazer o agente executar ações não intencionais. O assistente exibe este aviso ao selecionar agy. Em ambientes com um caminho de entrada de logs não confiável, recomendamos uma configuração de ferramenta que não ignore as verificações de permissão.

A delegação investigation nunca é chamada enquanto a rede está isolada (por exemplo, durante um Air-Gap ativo, ou qualquer estado equivalente a isolate_host_all).

11. Folha de referências do comando CLI

Comando Privilégios Descrição
sudo roamswitch status --server root Exibir pontuação de postura do servidor de 30 itens e verificar detalhamento
sudo roamswitch ports root Auditar portas de escuta abertas e processos vinculados
sudo roamswitch fim verify root Verifique a integridade SHA-256 dos arquivos do sistema de caminho crítico
roamswitch notifications Usuário Mostra o histórico de notificações (todos os alertas enviados) dos últimos 7 dias
sudo roamswitch server setup root Iniciar assistente de configuração inicial interativo
sudo roamswitch fim update root Atualizar banco de dados de linha de base FIM SHA-256
sudo roamswitch server config set <key> <value> root Altera e salva uma única chave de configuração (lista no §4)
sudo roamswitch airgap enable / disable root Aciona/libera manualmente o corte de emergência Air-Gap
sudo roamswitch emergency-restore Raiz Desarma todo o isolamento de eBPF/firewall e restaura a linha de base inicial
roamswitch port-scan Usuário Mostra o histórico de detecção da proteção de detecção de varredura de portas de entrada (§4.3) (IP de origem, se foi bloqueado automaticamente e a duração do bloqueio)
roamswitch sensor [key|list|pair|unpair|request-audit|results] Usuário/root Confiança mútua por código de emparelhamento com o RoamSwitch Sensor. pair --addr <ip> --code <code> para emparelhar, request-audit para solicitar 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

12. Solução de problemas e perguntas frequentes

Q1. O RoamSwitch desconectará inesperadamente minha sessão SSH?

Não. O RoamSwitch permite incondicionalmente os estados de conexão ESTABLISHED/RELATED e as ssh_ports (padrão 22). Mesmo durante um isolamento de emergência Air-Gap acionado por um ataque grave, preserve_ssh_on_isolation=true (padrão) mantém sua sessão administrativa ativa.

Q2. Como posso recuperar o acesso se for bloqueado acidentalmente?

Faça login pelo console web do seu provedor de nuvem (VNC / console serial) e execute sudo roamswitch emergency-restore para desarmar o isolamento, ou sudo systemctl stop roamswitch-server para parar o serviço.

Q3. Como exponho portas para serviços da Web recém-adicionados (por exemplo, Nginx)?

Execute sudo roamswitch server config set allowed_ports 80,443,3000 (ou edite diretamente /etc/roamswitch/server.conf) e depois execute sudo roamswitch server restart.

13. File Scan Guard (protegendo relés de e-mail, pastas compartilhadas e pontos de upload)

Um recurso opcional relevante apenas se este host tiver um diretório que armazena arquivos para terceiros — um relé de e-mail, um compartilhamento Samba/NFS, um ponto de upload de arquivos. O mecanismo YARA integrado sempre varre clamav_scan_dirs sem dependência externa; definir clamav_enabled=true adiciona o ClamAV como uma segunda opinião. Ameaças confirmadas são automaticamente colocadas em quarentena em /var/lib/roamswitch/quarantine e o operador é notificado.

# --- File Scan Guard (ClamAV, opt-in) ---
# O mecanismo YARA integrado sempre varre clamav_scan_dirs incondicionalmente.
clamav_enabled=false             # true habilita a inspeção adicional via clamdscan
clamav_scan_dirs=                # Caminhos absolutos para verificar (separados por vírgula)
clamav_scan_interval_secs=86400  # Intervalo de verificação (segundos, mínimo 3600)
clamav_freshclam_interval_secs=7200  # Intervalo de atualização automática do banco de assinaturas (segundos, mínimo 1800)

Também configurável pelo assistente interativo sudo roamswitch server setup; verifique a configuração e o status da quarentena pela ferramenta MCP get_file_scan_guard_status.

14. Log Audit (deteção e notificação de anomalias de padrões de registo)

Uma verificação periódica do journalctl transforma as mensagens de registo em modelos para detetar padrões novos (formas de registo nunca vistas) e anomalias de frequência (um pico estatístico, Z-score > 3.0). É um mecanismo leve que não requer nenhum daemon adicional nem dependência externa, pelo que está ativado por predefinição. As deteções são enviadas através dos mesmos canais de notificação que o File Scan Guard e o FIM (Telegram / LINE / Webhook). Quaisquer chaves API ou tokens que possam aparecer numa linha de registo são automaticamente mascarados antes de serem incluídos na notificação.

# --- Log Audit (ativado por predefinição) ---
log_audit_enabled=true           # false para desativar
log_audit_interval_secs=1800     # Intervalo de verificação em segundos (mínimo 300)

Também pode ser configurado a partir do assistente interativo sudo roamswitch server setup, e os resultados de deteção mais recentes podem ser consultados através do comando CLI roamswitch audit-logs ou da ferramenta MCP audit_security_logs.

← Whitepaper da Server Edition Para a página de instalação do Linux →