Manual de Operações do RoamSwitch Sensor

O guia de instalação e operação do RoamSwitch Sensor — um sensor de rede que, uma vez colocado na sua LAN, detecta novos dispositivos e spoofing no mesmo segmento, e executa auditorias ativas de vulnerabilidades em qualquer endpoint que já execute o RoamSwitch (Mac / Linux Client / Server Edition). Distribuído via pacotes apt/dnf.

1. Visão geral e posicionamento

O RoamSwitch (Mac / Linux Client / Server Edition) é, em todos os casos, um agente residente no host. Essa forma tem duas lacunas estruturais.

• O autodiagnóstico de um único host tem uma lacuna fundamental: o risco de movimento lateral — "fechado para o exterior, mas totalmente exposto a partir de outro dispositivo na mesma LAN" — nunca pode ser detectado por um host que só observa a si mesmo.
• Alguns dispositivos nunca poderão executar o RoamSwitch: dispositivos IoT (câmeras de rede, tomadas inteligentes, impressoras multifuncionais), dispositivos de convidados/BYOD, o próprio equipamento de rede, dispositivos embarcados e mais.

O RoamSwitch Sensor é um nó dedicado colocado na LAN, com o objetivo de fechar ambas as lacunas. O que está de fato implementado e verificado hoje se limita a duas coisas: auditorias ativas de vulnerabilidades em endpoints equipados com RoamSwitch na mesma LAN, e detecção passiva do surgimento de novos dispositivos e de spoofing, impulsionada pela própria tabela ARP do Sensor (conforme indicado na §6, não é um recurso que varre ativamente e visualiza cada dispositivo da LAN). Ele não é projetado como um EDR, mas como um NDR leve (Network Detection & Response) combinado com um scanner de vulnerabilidades baseado em prova, desenvolvido internamente.

A autodefesa não é implementada intencionalmente (uma decisão de design deliberada). Se você precisar proteger o próprio host do Sensor contra ataques, recomendamos instalar separadamente o RoamSwitch for Linux Server Edition na mesma máquina. Os dois são executados como processos totalmente independentes e coexistem sem conflitos.

2. Ambiente de verificação atual

• SO compatível: Debian 12 (bookworm) ou posterior / Ubuntu 22.04 ou posterior (apt), família Fedora/RHEL (dnf). Apenas x86_64 (amd64) — arm64 ainda não é compatível.
• Hardware-alvo (plano futuro): para operação real, prevemos um dispositivo de baixo consumo adequado para operação contínua, como um mini PC sem ventoinha da série N100/N150, mas hoje não é fornecida nenhuma compilação ou entrega dedicada voltada para isso.
• Posicionamento na rede: deve estar conectado física ou logicamente ao segmento de LAN monitorizado (roamswitch-sensor.service é executado na rede do host — necessário para observar diretamente a tabela ARP). Deve também funcionar com um endereço IP fixo (atribuição estática, ou reserva no lado do servidor DHCP) para que os endpoints o consigam alcançar para emparelhar e solicitar auditorias. Escuta na porta TCP 50543.
• Consumo de recursos: memória residente da ordem de dezenas de MB; a carga de CPU em repouso é extremamente leve.
• Opcional: nmap (usado para diagnósticos complementares via NSE; todos os demais recursos funcionam normalmente sem ele).

3. Instalação e inicialização

Instale o pacote roamswitch-sensor a partir do repositório oficial assinado. Após a instalação, o roamswitch-sensor.service (systemd) é automaticamente habilitado e iniciado.

3.1 APT (Ubuntu / Debian)

# 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 [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-sensor

3.2 DNF / RPM (Fedora / RHEL)

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

3.3 Verificação da inicialização

systemctl status roamswitch-sensor.service
sudo roamswitch-sensor status

3.4 Execução do CLI / TUI

A CLI (roamswitch-sensor) e a TUI interativa (roamswitch-sensor-tui) podem ser executadas diretamente após a instalação.

sudo roamswitch-sensor status
sudo roamswitch-sensor-tui

4. Emparelhamento (método por código)

De fábrica, o Sensor não confia em nada. O emparelhamento é feito com um código de emparelhamento de uso único emitido pelo operador do Sensor. A relação de confiança — «o Sensor pode executar auditorias ativas de vulnerabilidades contra este endpoint» — é estabelecida simultaneamente em ambas as direções num único passo de emparelhamento (não existe um estado de confiança apenas numa direção).

Pré-requisito: execute o Sensor com um endereço IP fixo (atribuição estática, ou reserva no lado do servidor DHCP). Após o emparelhamento, o endpoint liga-se sempre diretamente ao endereço IP do Sensor confirmado no momento do emparelhamento (já não existe descoberta automática, seja por mDNS ou outro meio); se o IP do Sensor mudar depois, será necessário emparelhar novamente. O lado do endpoint pode manter um IP dinâmico.

4.1 Emitir um código de emparelhamento (lado do Sensor)

# Executar no lado do Sensor (ou premir c na TUI)
sudo roamswitch-sensor issue-code

É emitido um código de uso único de 8 caracteres (letras maiúsculas e dígitos, excluindo os caracteres facilmente confundíveis 0/O/1/I/L). Expira 10 minutos após a emissão e só pode ser usado uma vez, por isso transmita-o rapidamente ao operador do endpoint por qualquer canal fora de banda (verbalmente, por chat, etc.).

4.2 Emparelhamento com o código (lado do endpoint)

# Lado do endpoint (roamswitch-linux)
sudo roamswitch sensor pair --addr <IP fixo do Sensor> --code <código de pareamento>

Na edição Mac, a mesma operação está disponível pela GUI em “🔍 Emparelhamento do RoamSwitch Sensor…” na barra de menus, onde introduz o endereço IP e o código de emparelhamento do Sensor.

Assim que o emparelhamento for concluído, toda auditoria ativa de vulnerabilidades e toda obtenção de resultados de auditoria subsequentes são autenticadas com uma assinatura Ed25519. Tanto o endpoint que conhecia o código como o Sensor que o emitiu passam a confiar um no outro a partir desse momento.

4.3 Emparelhamento manual (registo direto de uma chave pública já conhecida)

Se o operador do Sensor já conhecer, por outro meio, a chave pública e o endereço de um endpoint, também pode registá-lo diretamente no lado do Sensor sem trocar um código de emparelhamento (normalmente é preferível usar o método por código da §4.2 e deixar o endpoint emparelhar-se sozinho). Pode consultar a sua própria chave pública e endereço com os comandos seguintes.

# Verificar a própria chave pública/endereço no lado do endpoint
sudo roamswitch sensor key

# Verificar a própria chave pública/endereço/endereço MAC no lado do Sensor
sudo roamswitch-sensor status

# Lado do Sensor
sudo roamswitch-sensor pair <chave pública completa> --addr <endereço IP> --confirm

5. Auditoria ativa de vulnerabilidades

O Sensor executa diagnósticos de vulnerabilidade não destrutivos e baseados em prova contra os endpoints emparelhados. Ele nunca realiza operações destrutivas (gravação ou exclusão de dados, interrupção de serviços).

sudo roamswitch-sensor scan <chave pública ou seu início>

A auditoria consiste em quatro fases.

1. Varredura completa de portas: detecta de forma exaustiva todas as portas TCP abertas no host de destino.
2. Diagnóstico de assinaturas conhecidas: verificações não destrutivas e baseadas em prova contra padrões de vulnerabilidade conhecidos — exposição sem autenticação de Redis / dockerd / Memcached / MongoDB / Elasticsearch / CouchDB / Jenkins / VNC, diagnóstico de open relay SMTP (um método seguro que envia apenas MAIL FROM/RCPT TO, nunca DATA), e diagnósticos de configuração incorreta de CORS, path traversal e open redirect em servidores de desenvolvimento, entre outros.
3. Captura genérica de banner: para portas abertas não cobertas pelas assinaturas acima, obtém a string de banner apenas conectando-se (nenhum dado é enviado).
4. Diagnóstico complementar via nmap NSE: diagnóstico complementar de ampla cobertura de protocolos via nmap --script safe. É executado automaticamente sempre que o nmap está instalado no host (caso contrário, não faz nada).

Cada execução de auditoria é registrada em /var/lib/roamswitch-sensor/scan_history.json — independentemente de algo ter sido encontrado, já que um resultado limpo naquele momento também tem valor de registro — e pode ser visualizada pela CLI ou pela TUI.

roamswitch-sensor history
sudo roamswitch-sensor report <chave pública ou seu início> --out /tmp/report.md

5.1 Pedido de auditoria a partir do cliente (modelo pull)

Um endpoint emparelhado também pode solicitar ativamente uma auditoria ao Sensor. Na edição Mac, use “Solicitar auditoria ao Sensor” na barra de menus; no Linux, use o comando seguinte.

sudo roamswitch sensor request-audit

Depois de o Sensor executar a auditoria, o endpoint consulta o resultado a partir de 5 minutos após o pedido, e depois a cada 5 minutos, até um máximo de 5 tentativas (ou seja, até 25 minutos no total). O resultado obtido também é guardado localmente no endpoint.

roamswitch sensor results

Na edição Mac, os resultados também aparecem na lista “Resultados de auditoria” da janela de definições, ou podem ser lidos através da ferramenta MCP get_sensor_audit_results, como entrada para um agente de IA planear uma correção. A obtenção de um resultado também pode ser explicitamente recusada, por exemplo se o emparelhamento tiver sido revogado no lado do Sensor (ver §10 P6).

6. Monitoramento ARP passivo e visibilidade de LAN

O Sensor tira periodicamente um snapshot de sua própria tabela ARP (equivalente a /proc/net/arp) e, ao compará-lo com o snapshot anterior, detecta dois tipos de eventos: um novo IP/MAC nunca visto antes, e uma mudança de endereço MAC para um IP já conhecido (um sinal, por exemplo, de spoofing de gateway). Ele nunca envia pacotes de forma ativa e cobre apenas dispositivos com os quais o Sensor já se comunicou de alguma forma (não é um recurso que descobre e enumera ativamente cada dispositivo da LAN). Ele não tem capacidade de classificar o tipo de dispositivo (por exemplo, se é um dispositivo IoT) — detecta apenas uma mudança de IP/MAC.

roamswitch-sensor arp-events

Os eventos detectados também podem ser listados na aba “ARP Events” da TUI, que distingue dois tipos: “novo dispositivo apareceu” e “endereço MAC de um IP conhecido mudou (suspeita de spoofing)”.

6.1 Extensão de visibilidade passiva de LAN (opt-in)

Enquanto o monitoramento de ARP acima cobre apenas dispositivos com os quais o Sensor já se comunicou, definir a variável de ambiente ROAMSWITCH_SENSOR_PASSIVE_CAPTURE_IFACE para uma interface de destino observa cabeçalhos Ethernet/IPv4 nela (sem inspeção de payload) para detectar o seguinte.

• Observação passiva de novos dispositivos: dispositivos com os quais o Sensor nunca se comunicou diretamente, não cobertos apenas pelo monitoramento de ARP. Aprendido a partir do tráfego de broadcast/multicast.
• Detecção de contato com IPs maliciosos conhecidos: sinaliza o tráfego cujo IP de destino corresponde ao feed de ameaças local (mesmo formato do Egress Guard do próprio RoamSwitch) — apenas detecção, nunca bloqueado.

sudo systemctl edit roamswitch-sensor.service
# [Service]
# Environment=ROAMSWITCH_SENSOR_PASSIVE_CAPTURE_IFACE=eth0

sudo systemctl restart roamswitch-sensor.service
roamswitch-sensor passive-events

7. Referência rápida de comandos CLI

A CLI oferece suporte apenas a japonês e inglês (segue a variável de ambiente LANG).

8. Guia de operação da TUI

A TUI interativa (roamswitch-sensor-tui) suporta 10 idiomas. Com a tecla Tab (Shift+Tab para recuar) alterna entre seis separadores: Confiável (último estado de auditoria de cada endpoint) / Dispositivos (todos os dispositivos da LAN, com notas) / Eventos ARP / Histórico / Alterações (o que mudou desde a auditoria anterior: novas deteções a vermelho, resolvidas a verde, possivelmente inacessível a amarelo) / Registo (quem aprovou ou executou o quê e quando; no topo é mostrado o resultado da verificação da cadeia de hashes).

9. Modelo de confiança e design de segurança

• TOFU (Trust On First Use): o próprio código de emparelhamento não é uma prova criptográfica de propriedade — é confirmado pelo julgamento do próprio operador, que recebeu o código emitido pelo operador do Sensor por um canal fora de banda (verbalmente, por chat, etc.), de forma semelhante à confirmação mútua explícita do emparelhamento Bluetooth. A partir do momento em que o emparelhamento é bem-sucedido, a legitimidade de cada sonda ou pedido subsequente é verificada em relação à chave pública trocada nesse momento.
• Projetado para encontrar brechas que permitiriam uma ação destrutiva, sem nunca executar uma ação destrutiva ele mesmo: toda auditoria ativa de vulnerabilidades é não destrutiva (nunca grava ou exclui dados, nem interrompe um serviço). O que ele detecta são as próprias configurações incorretas — como “gravável sem autenticação” ou “funciona como open relay” — que, se exploradas, permitiriam uma ação destrutiva.
• Mitigação de falsos positivos (exclusão de autoauditoria): uma exclusão por correspondência de IP de origem está integrada para que a auditoria completa de portas realizada pelo próprio Sensor emparelhado não seja confundida com reconhecimento pela proteção de detecção de varredura de portas de entrada (um recurso do lado do RoamSwitch). O IP é usado apenas para essa correspondência, unicamente para evitar um bloqueio automático — nunca para a própria determinação de confiança.
• Nada é enviado sem a sua configuração: as informações dos dispositivos descobertos, os resultados das auditorias e os eventos ARP ficam, por predefinição, apenas no armazenamento local do próprio Sensor e nunca são enviados à Lafine nem a servidores de terceiros. As notificações (webhook / syslog) e o envio ao coletor central descritos no §11 só vão para destinos que a sua organização tenha configurado.

10. Solução de problemas e FAQ

P1. Introduzir um código de emparelhamento é recusado.

Três causas prováveis: (1) já passaram mais de 10 minutos desde a emissão e o código expirou (peça ao operador do Sensor para emitir um novo com issue-code); (2) um erro ao introduzir o código (os caracteres facilmente confundíveis 0/O/1/I/L já são excluídos no momento da emissão, pelo que um código nunca os contém); (3) o endereço IP indicado com --addr não corresponde ao endereço IP fixo atual do Sensor.

P2. O resultado do diagnóstico complementar via NSE está vazio.

Uma das duas causas a seguir: (1) o nmap não está instalado no contêiner; (2) foi executado, mas os scripts seguros aplicáveis às portas de destino realmente não produziram nenhuma saída. O diagnóstico complementar via nmap NSE é executado automaticamente sempre que o nmap está instalado no host.

P3. Quanto tempo leva para concluir uma auditoria?

Uma varredura completa de portas isolada leva cerca de dezenas de segundos, mas assim que o nmap está instalado no host, o diagnóstico complementar NSE é adicionado automaticamente, podendo levar até cerca de 2 minutos, dependendo do número de portas abertas do alvo. A TUI continua mostrando os segundos decorridos durante a execução, para que você possa acompanhar o progresso enquanto aguarda.

P4. Emparelhei, mas continuo sem conseguir executar uma auditoria.

Causas prováveis: (1) sensor_pairing_enabled: true não está definido no lado do endpoint (desativado por predefinição); (2) o endereço IP fixo do Sensor mudou após o emparelhamento, pelo que o endpoint está a tentar alcançar um endereço desatualizado (um novo emparelhamento resolve isto); (3) o emparelhamento foi removido no lado do Sensor com unpair. Verifique com roamswitch sensor list (lado do endpoint) e roamswitch-sensor list (lado do Sensor) que cada um reconhece o outro.

P5. O Sensor pode ser usado junto com o próprio RoamSwitch (Client/Server Edition)?

Sim. Como o Sensor é projetado sem recursos de autodefesa, recomendamos executar também o RoamSwitch for Linux Server Edition na mesma máquina. Os dois operam com processos e armazenamentos de dados totalmente independentes, sem conflitos.

P6. roamswitch sensor results indica que o emparelhamento foi revogado.

O emparelhamento deste endpoint foi removido no lado do Sensor com unpair. Peça ao operador do Sensor para emitir um novo código de emparelhamento e volte a emparelhar com roamswitch sensor pair --addr <ip> --code <code>.

11. Funcionalidades de auditoria para organizações (opcionais)

Um conjunto de funcionalidades para as equipas de segurança de grandes organizações que precisam de evidências de auditoria e de uma visão clara do que mudou. Todas vêm desativadas por predefinição e nunca é enviado nada à Lafine nem a terceiros: cada destino de notificação ou agregação é escolhido pela sua organização. As definições alteram-se com sudo roamswitch-sensor config set <chave> <valor> (sem reiniciar o daemon; cada alteração fica registada no registo de operações); config show mostra os valores atuais.

11.1 Auditorias agendadas e deteção de alterações

Ao definir schedule.enabled como true, todos os endpoints emparelhados são auditados automaticamente (a cada 24 horas por predefinição: schedule.interval_hours; janela horária local em que as auditorias podem começar: schedule.window_start_hour / window_end_hour, podendo atravessar a meia-noite; concorrência: schedule.max_parallel). Cada auditoria é comparada com a anterior, e roamswitch-sensor diff mostra as novas deteções (regressões), as resolvidas e as portas recém-abertas. Se todas as portas que estavam abertas deixarem de ser visíveis, isso é comunicado como possivelmente inacessível, e não como «resolvido»: um equipamento desligado não se distingue, do exterior, de um que fechou todas as portas.

As auditorias não vigiadas não quebram a garantia de que só são auditados endpoints que deram o seu consentimento. O IP de um endpoint pode ser atribuído a outro dispositivo pelo DHCP; por isso o Sensor guarda o MAC que o endpoint tinha na sua última autenticação (emparelhamento ou pedido de auditoria assinado) e confirma, antes e depois de cada auditoria agendada, com um pedido ARP real do nmap, que continua a responder o mesmo MAC nesse IP. Se não responder, a auditoria é ignorada (ou o seu resultado descartado) e é emitida uma notificação. Um scan manual também é recusado quando há indícios de que o endereço passou a pertencer a outro dispositivo. Esta verificação requer o nmap; os endpoints emparelhados antes desta funcionalidade só são agendados depois de voltarem a emparelhar ou de enviarem um pedido de auditoria assinado; só são cobertos endpoints do mesmo segmento L2.

11.2 Notificações (webhook e syslog)

Regressões, novos dispositivos, ARP spoofing, tráfego suspeito e mais são enviados para notify.webhook_urls (webhooks de entrada do Slack, Discord ou Teams, ou qualquer ponto JSON genérico) e para notify.syslog.host / port / protocol (RFC 5424 sobre UDP ou TCP). Pode restringir com notify.min_severity (info / medium / high / critical) e notify.cooldown_minutes (intervalo mínimo antes de reenviar o mesmo evento). roamswitch-sensor notify-test verifica cada destino.

11.3 Exportação de evidências de auditoria

roamswitch-sensor export <scans|inventory|audit-log|all> --format csv|json|html [--out ficheiro] [--endpoint prefixo-da-chave] [--since data]. A saída html é um único ficheiro autónomo: abra-o num navegador e escolha «Guardar como PDF» para obter um PDF a entregar aos auditores. O CSV está protegido contra a injeção de fórmulas em folhas de cálculo. A exportação do inventário de dispositivos inclui uma coluna que indica se cada dispositivo está sob gestão do RoamSwitch (emparelhado). Os ficheiros de saída só podem ser lidos pelo proprietário (0600), e a própria exportação fica registada no registo de operações.

11.4 Registo de operações e aprovações (à prova de adulteração)

O emparelhamento, a sua remoção, o início e a conclusão das auditorias, as alterações de configuração e os acessos recusados são registados juntamente com quem os realizou (UID / chave pública do endpoint / IP de origem). Cada linha contém o SHA-256 da anterior, pelo que qualquer edição ou eliminação é detetada por roamswitch-sensor audit-log verify (código de saída 2 em caso de problema). A lista obtém-se com roamswitch-sensor audit-log [--limit N]. Os URL de webhook costumam incluir um token, por isso o registo de alterações de configuração nunca guarda os seus valores. Uma cadeia de hashes, por si só, não revela que as entradas mais recentes foram cortadas; por isso a cabeça da cadeia (número de sequência e hash) também é enviada ao coletor (§11.6).

11.5 Retenção

Defina retention.scan_history_days, retention.audit_log_days e retention.inventory_stale_days para eliminar automaticamente o histórico de auditorias, as entradas do registo e os dispositivos que não são vistos há muito tempo (0 = não eliminar por antiguidade, valor predefinido). Os dispositivos com uma nota nunca são removidos do inventário.

11.6 Agregar vários Sensors (coletor central, opcional)

Quando há vários Sensors em vários locais, execute roamswitch-sensor-collector (incluído no pacote, desativado por predefinição) num anfitrião separado para recolher os resumos assinados de cada um.

# On the collector host (a separate host from the Sensor is recommended)
sudo systemctl enable --now roamswitch-sensor-collector   # listens on 127.0.0.1:8443 by default
sudo roamswitch-sensor-collector token                     # read token for the dashboard
sudo roamswitch-sensor-collector enroll <Sensor public key> --name Tokyo --site Tokyo

# On each Sensor
sudo roamswitch-sensor config set collector.url https://collector.example.org:8443
sudo roamswitch-sensor config set collector.enabled true

• Só são aceites pedidos assinados (Ed25519) de Sensors registados (enroll); a marca temporal também rejeita repetições.
• O TLS é obrigatório sempre que o serviço seja acessível a partir de fora da LAN. Indique --bind 0.0.0.0:8443 --tls-cert … --tls-key … em COLLECTOR_ARGS de /etc/default/roamswitch-sensor-collector, ou use --allow-plain-http atrás de um proxy inverso que termine o TLS. Escutar noutro endereço que não 127.0.0.1 sem TLS é recusado no arranque.
• O painel é protegido por um token e oferece filtragem por local, eventos por gravidade e exportação CSV. Destaca os Sensors que deixaram de responder e aqueles cujo registo de auditoria parece truncado, recuado ou bifurcado (a remover com clear-anomaly <chave-pública> após investigação).