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 que se coloca na LAN para colmatar estas duas lacunas. O que está hoje implementado e verificado é: auditorias ativas de vulnerabilidades a endpoints com RoamSwitch na mesma LAN; um registo de dispositivos da LAN construído a partir de uma varredura ARP e da monitorização da tabela ARP, com deteção de novos dispositivos e de spoofing; e informação de referência sobre comportamento suspeito (ligações a IPs maliciosos, sinais de participação em botnets, DNS tunnelling e mais) a partir de captura passiva opcional (ver §6). O Sensor apenas deteta e comunica; nunca bloqueia tráfego. Foi concebido como um NDR (Network Detection & Response) leve combinado com um scanner de vulnerabilidades próprio baseado em provas — não como um EDR.

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.
• Colocação na rede: tem de estar ligado, física ou logicamente, ao segmento de LAN que pretende vigiar (o roamswitch-sensor.service corre na rede do anfitrião porque tem de observar diretamente a tabela ARP). Para aceitar pedidos de emparelhamento e de auditoria dos endpoints, tem também de funcionar com um endereço IP fixo (atribuição estática ou reserva DHCP). Escuta na porta TCP 50543 (em todas as interfaces por predefinição; altere-o com control.bind_addr; o TLS 1.3 é aceite na mesma porta — ver §4.4).
• Consumo de recursos: memória residente da ordem de dezenas de MB; a carga de CPU em repouso é extremamente leve.
• Recomendado: nmap (usado para a varredura ARP, as verificações NSE complementares e a verificação do MAC das auditorias agendadas). Sem ele, as restantes funcionalidades continuam a funcionar, mas não é feita nenhuma varredura ARP e o Sensor recorre a um funcionamento passivo que só vê os dispositivos com que ele próprio comunicou.

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; os caracteres facilmente confundíveis 0/O/1/I/L são excluídos). Expira ao fim de 10 minutos e só funciona uma vez, por isso transmita-o rapidamente ao operador do endpoint por qualquer meio fora de banda (voz, chat). É apresentada também a impressão digital (SHA-256) do certificado TLS do Sensor. O endpoint fixa esse valor, pelo que deve transmiti-lo juntamente com o código (pode vê-lo sempre com roamswitch-sensor pairing show ou no ecrã T da TUI).

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

# Lado do endpoint (roamswitch-linux)
sudo roamswitch sensor pair --addr <SENSOR_IP> --code <CODE> --fingerprint <SHA256_FINGERPRINT>

Na edição para Mac pode fazer o mesmo na interface gráfica, a partir do item da barra de menus «🔍 RoamSwitch Sensor Pairing…», introduzindo o endereço IP do Sensor, o código de emparelhamento e a impressão digital do certificado.

Depois de emparelhado, todas as auditorias ativas e obtenções de resultados seguintes são autenticadas com assinaturas Ed25519. Um endpoint Linux comunica por TLS 1.3 apenas com um Sensor cujo certificado corresponda à impressão digital que introduziu, e nunca recorre automaticamente a texto simples (§4.4). Neste ponto, o endpoint que conhecia o código e o Sensor que o emitiu consideram-se mutuamente de confiança.

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

4.4 Segurança da API de controlo (TCP 50543): TLS, impressão digital, bloqueio

O emparelhamento, os pedidos de auditoria e a obtenção de resultados passam pela API de controlo do Sensor (TCP 50543). Estão incorporadas as seguintes proteções.

• TLS 1.3 e fixação de certificado: a definição control.tls (aplicada ao reiniciar o daemon) é off (apenas texto simples), optional (a predefinição: TLS 1.3 e texto simples legado na mesma porta, com um aviso sempre que é aceite texto simples) ou required (apenas TLS 1.3). O certificado é autoassinado (ECDSA P-256) e a confiança é decidida por uma fixação da sua impressão digital SHA-256, não pela validade nem pelo nome. A fixação nunca é obtida através da rede: o operador escreve no endpoint o valor apresentado no ecrã do Sensor.
• Associação da impressão digital ao pedido de emparelhamento: o endpoint assina com a sua própria chave privada a impressão digital que fixou e inclui-a no pedido de emparelhamento. Um pedido que tenha passado por um man-in-the-middle com um certificado diferente falha com fingerprint_mismatch, e o código de emparelhamento não é consumido.
• Assinaturas resistentes a repetição (v2): as assinaturas dos pedidos de auditoria e de obtenção de resultados usam o formato v2, que inclui uma marca temporal (±300 s) e um nonce, pelo que as repetições são recusadas. As assinaturas v1 legadas não têm nenhum dos dois e podem ser repetidas; control.allow_legacy_signatures (predefinição true, pensada para o período de migração; cada utilização regista um aviso de descontinuação) decide se são aceites. Defina-o como false assim que todos os endpoints enviarem v2.
• Bloqueio: adivinhar códigos de emparelhamento bloqueia um IP de origem durante 60 segundos após 5 falhas em 10 minutos (prolongado exponencialmente em caso de repetição, até 1 hora), e 20 falhas somadas de todas as origens desencadeiam um bloqueio global. As falhas de assinatura são tratadas com um pouco mais de tolerância (10 por IP de origem, 100 no total). Um bloqueio gera a notificação control_api_lockout.
• Endereço de escuta: restringir control.bind_addr (predefinição 0.0.0.0, aplicado ao reiniciar) ao endereço LAN do Sensor reduz a exposição. O daemon emite um aviso enquanto for um endereço universal (wildcard).
• Rotação de certificados: roamswitch-sensor tls rotate (no ecrã T da TUI, prima R) regenera o certificado. Todas as fixações da impressão digital antiga deixam de ser válidas, pelo que cada endpoint tem de introduzir o novo valor (sudo roamswitch sensor repin <public key> --fingerprint <value>). O emparelhamento em si é mantido.

sudo roamswitch-sensor pairing show                       # mode, fingerprint, warnings
sudo roamswitch-sensor tls rotate                         # regenerate the certificate
sudo roamswitch sensor repin <PUBLIC_KEY> --fingerprint <NEW_FINGERPRINT>   # on each endpoint

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 conhece os dispositivos da LAN de duas formas. (1) Monitorização da tabela ARP: lê a sua própria tabela ARP (/proc/net/arp) aproximadamente de 10 em 10 segundos e deteta «um IP/MAC novo nunca visto» e «uma alteração de endereço MAC para um IP conhecido» (sinal de spoofing do gateway e afins). (2) Uma varredura ARP ativa: nmap -sn -PR varre a sub-rede diretamente ligada (até uma /22) e guarda no registo de dispositivos o IP, o MAC, o nome de host, o fabricante, o estado online, a primeira/última deteção e o histórico de IP. A varredura corre de hora a hora, a pedido (refresh / tecla r da TUI) e quando a TUI arranca; sem nmap resta apenas o comportamento passivo (1). O fabricante e uma classe de dispositivo (IoT ou não, etc.) são também inferidos a partir do OUI do MAC.

roamswitch-sensor arp-events

Os eventos detetados são mostrados por roamswitch-sensor arp-events e no separador «Eventos ARP» da TUI (Enter para ver detalhes). Cada evento traz a hora, uma gravidade (de crítica a informativa; uma alteração de MAC do IP do gateway é «crítica»), a justificação, a identidade dos dispositivos envolvidos e os passos seguintes concretos.

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

6.2 Registo de dispositivos e notas de dispositivo

Consulte o registo com roamswitch-sensor device-inventory (o separador «Dispositivos» da TUI). Registar uma nota, como um nome, uma finalidade ou uma localização, com device-note (a tecla n na TUI) marca o dispositivo como «identificado», enquanto os dispositivos sem nota ficam destacados como «a verificar» (para cruzar com o seu inventário de ativos).

sudo roamswitch-sensor refresh
roamswitch-sensor device-inventory
sudo roamswitch-sensor device-note aa:bb:cc:dd:ee:ff "3F copier"

6.3 Informação de referência sobre comportamento suspeito (apenas deteção)

Com a captura passiva (§6.1, opcional) ativada, é apresentada a seguinte informação de referência. Tudo isto é apenas deteção e apresentação; o Sensor nunca bloqueia tráfego.

• Comportamento de dispositivos IoT (iot-events): ligações de dispositivos classificados a IPs maliciosos conhecidos ou a portas de gestão (SSH/RDP/SMB e afins). Também é usada a identificação do modelo a partir dos anúncios mDNS/SSDP/DHCP dos próprios dispositivos.
• Tráfego suspeito (network-threats): ligações a muitos destinos numa janela de 30 segundos (sinal de varrimento ou de ponto de salto), uma inundação de ligações a um único destino (sinal de participação num DDoS) e sinais de DNS tunnelling/C2 (apenas se usam as características estruturais dos nomes consultados; os nomes de domínio não são guardados).
• Avisos (iot-advisories): informação de referência sobre CVE públicos de produtos de fabricantes de IoT conhecidos (incluída estaticamente; não há atualização pela rede).

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 e permite operar todos os subcomandos da CLI, todos os métodos IPC do daemon, todas as chaves de configuração e o collector (prima m para o menu de funcionalidades). Alterna-se entre seis separadores principais com a tecla Tab (Shift+Tab recua): Emparelhados (o estado de auditoria mais recente de cada endpoint) / Dispositivos (todos os dispositivos da LAN, com notas) / Eventos ARP / Histórico / Alterações (alterações desde a auditoria anterior; novas deteções a vermelho, resolvidas a verde, possivelmente inacessíveis a amarelo) / Registo de auditoria (quem aprovou ou executou o quê e quando; o resultado da verificação da cadeia de hashes é mostrado no topo). As vistas que não cabem em 80 colunas (monitorização passiva, comportamento de IoT, tráfego suspeito, avisos de IoT) abrem-se a partir do menu m.

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

• Confirmação fora de banda (não TOFU): o operador transmite ao endpoint a impressão digital do certificado apresentada no ecrã do Sensor e o código de emparelhamento, por voz, chat ou meio semelhante. O endpoint nunca obtém a fixação através da rede (não é TOFU, que confia incondicionalmente na primeira ligação) e só comunica e se emparelha com um Sensor cujo certificado corresponda ao valor introduzido. As chaves públicas trocadas no emparelhamento verificam todas as sondagens e pedidos seguintes.
• 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. Além disso, apenas desde o pedido de auditoria deste equipamento a um Sensor até à chegada do relatório (cerca de 25 minutos no máximo se não chegar nenhum), a edição para Mac redige em tom mais calmo as deteções provenientes do endereço do Sensor e o aviso de «inundação de SYN» (que não tem endereço de origem) como provavelmente causados pela auditoria; a edição para Linux faz o mesmo com o aviso de «inundação de SYN». Fora dessa janela o aviso forte mantém-se como antes, e as auditorias que o Sensor inicia por conta própria não estão cobertas.
• O tráfego de saída é limitado e, por predefinição, não são enviados dados de dispositivos: a informação dos dispositivos descobertos, os resultados das auditorias e os eventos ARP são guardados por predefinição apenas no armazenamento local do próprio Sensor e nunca são enviados à Lafine nem a terceiros. O único tráfego de saída é a obtenção de dados de deteção (o mapa de CVE e a base de dados NSE do nmap; pode ser interrompida com updates.fetch_cve_map e não contém dados de dispositivos nem de auditorias) e as notificações (webhook, syslog) e os envios para o collector central da §11, que vão apenas para os seus próprios destinos e só se os configurar.

10. Solução de problemas e FAQ

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

Há quatro causas prováveis: (1) o código expirou 10 minutos após a emissão (peça ao operador do Sensor que emita um novo com issue-code), (2) um erro de digitação no código (os caracteres facilmente confundíveis 0/O/1/I/L são excluídos na emissão dos códigos, pelo que um código nunca os contém), (3) o endereço IP indicado em --addr não corresponde ao endereço IP fixo atual do Sensor, (4) --fingerprint não corresponde ao certificado do Sensor (pin_mismatch / fingerprint_mismatch; confirme o valor com roamswitch-sensor pairing show. Erros repetidos bloqueiam-no e devolvem rate_limited).

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 endpoint (desativado por predefinição), (2) o endereço IP fixo do Sensor mudou após o emparelhamento e o endpoint já não consegue alcançar o endereço antigo que guarda (volte a emparelhar), (3) o emparelhamento foi removido no Sensor com unpair, (4) o Sensor regenerou o seu certificado (tls rotate), pelo que a fixação do endpoint está desatualizada (introduza a nova impressão digital com roamswitch sensor repin). Confirme, com roamswitch sensor list (endpoint) e roamswitch-sensor list (Sensor), que cada lado lista 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> --fingerprint <SHA-256>.

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 FILE] [--endpoint KEY-PREFIX] [--since DATE]. A saída html é um único ficheiro: abra-o num browser e escolha «Guardar como PDF» para obter um PDF que pode entregar. O CSV está protegido contra injeção de fórmulas em folhas de cálculo. O registo de dispositivos (inventário) tem uma coluna que indica se cada dispositivo é gerido pelo RoamSwitch (emparelhado). Os ficheiros de saída só são legíveis pelo seu proprietário (0600), e a própria exportação fica registada no registo de auditoria. A tecla e da TUI aceita as mesmas opções num formulário, e os relatórios e exportações são produzidos no idioma de apresentação (10 idiomas; a CLI está em japonês e inglês).

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).
• Com collector.send_unmanaged_devices (predefinição true), o Sensor inclui no resumo os dispositivos que não estão emparelhados (dispositivos não geridos). Cada dispositivo é classificado como «anfitrião RoamSwitch não emparelhado» (quando o RoamSwitch aparece no seu anúncio mDNS/SSDP; ativar collector.probe_control_port faz também uma tentativa de ligação TCP à porta de controlo 50543, desativado por predefinição) ou «dispositivo desconhecido», e são enviados apenas o MAC, o fabricante, a classe do dispositivo e a hora da primeira deteção (nunca o conteúdo do tráfego). Na TUI, O abre o ecrã de gestão do collector.

11.7 Obtenção de dados de deteção (updates.fetch_cve_map)

O Sensor obtém todos os dias, do serviço de atualização, o mapa de CVE assinado (os dados de vulnerabilidades conhecidas usados pelas verificações ativas) e a base de dados NSE do nmap. Este tráfego não contém dados de dispositivos nem de auditorias. Para funcionar totalmente offline, execute sudo roamswitch-sensor config set updates.fetch_cve_map false (a alteração entra em vigor a partir do ciclo seguinte, sem reinício, e a partir daí só são usados os dados incluídos).

11.8 Referência das chaves de configuração

Consulte os valores atuais com roamswitch-sensor config show e altere-os com config set <key> <value> [<key> <value> …] (várias chaves são guardadas atomicamente; o editor de configuração C da TUI também as altera). Apenas as chaves marcadas com «Sim» na coluna Reinício exigem o reinício do daemon (sudo systemctl restart roamswitch-sensor).

12. Deteção de DHCP e IPv6 não autorizados

Deteta outro router, ou o equipamento de um atacante, levado para a rede que se faz passar pelo legítimo para controlar por onde vai o tráfego dos clientes. Apenas deteta e notifica; o Sensor nunca bloqueia tráfego. Está ativo por predefinição e não requer captura passiva. Os resultados aparecem em roamswitch-sensor network-threats, no separador Ameaças do TUI (a partir de m), nas notificações (dhcp_rogue_server, ipv6_rogue_router, ndp_spoof, ipv6_unknown_device), no registo de operações e nas exportações.

12.1 Servidores DHCP não autorizados (IPv4 e DHCPv6)

De hora a hora (e em cada roamswitch-sensor refresh) o Sensor envia um único pacote DHCP discover (um SOLICIT em DHCPv6) a partir de um endereço MAC aleatório e conta todos os servidores que respondem. Não envia nenhum REQUEST, pelo que não é tomada nenhuma concessão. As respostas DHCP vistas pela captura passiva passam pelo mesmo julgamento. O primeiro servidor ouvido é aprendido como legítimo e qualquer servidor que apareça depois é comunicado. Um servidor que distribui um gateway ou um DNS que o legítimo não distribui decide para onde os clientes que aceitam a sua concessão enviam o tráfego, e é o nível mais grave, critical. Se vários servidores responderem em simultâneo à primeiríssima sonda, o Sensor não consegue saber qual é o autêntico: não aprende nenhum e comunica todos.

12.2 IPv6 (anúncios de router não autorizados, falsificação NDP, dispositivos só IPv6)

Anúncios de router não autorizados: qualquer um na LAN pode dizer-se router IPv6. O Sensor combina a tabela de vizinhos e as rotas predefinidas do kernel, os anúncios de router vistos pela captura passiva e as respostas ao seu próprio pedido de router, e avisa se algo que não seja o gateway IPv4 predefinido se comportar como router (adicione o autêntico a ipv6.allowed_routers para o tratar como legítimo; uma rede cujo router IPv6 é um dispositivo diferente do gateway IPv4 é um caso normal, adicione-o então). Os anúncios cujo limite de saltos não é 255 são forjados ou encaminhados e são ignorados. Falsificação NDP: avisa quando o titular de um endereço IPv6 muda para outro MAC (high se for o endereço de um router). Dispositivos só IPv6: um dispositivo que nunca aparece no ARP mas aparece na tabela de vizinhos só é comunicado depois de uma varredura ARP ter tido oportunidade de o encontrar. O inventário de dispositivos (coluna CSV ipv6, ipv6_addrs em JSON) também guarda endereços IPv6.

12.3 Quem conta como legítimo e as definições

Com dhcp.allowed_servers e ipv6.allowed_routers (MAC ou IP), tudo o resto que responder é comunicado; se ficarem vazios, aprende-se o primeiro encontrado. dhcp.active_probe e ipv6.active_probe (predefinição true) desligam as sondas ativas, e ipv6.enabled desliga toda a vigilância IPv6. A escuta da API de controlo (50543) em IPv6 acrescenta-se com control.listen_ipv6 (predefinição false, aplicado após reiniciar); um endereço IPv6 global pode ser acessível a partir da Internet se o router não tiver firewall IPv6, por isso não está ativo por predefinição. Os limites de ligação e os bloqueios contam o IPv6 por /64. Um endpoint que se ligou a partir de um endereço de ligação local não é memorizado como alvo de auditoria, porque não pode ser chamado de volta sem um identificador de âmbito.

13. Auditoria ligeira de dispositivos sem RoamSwitch (opcional)

A auditoria ativa de vulnerabilidades do §5 abrange apenas os endpoints emparelhados que aceitaram. Para impressoras, câmaras, NAS e outros dispositivos que nunca foram emparelhados mas cujos serviços expostos se quer conhecer, existe uma verificação à parte e muito mais limitada. Os diagnósticos profundos ao estilo do OpenVAS, as tentativas de início de sessão, a exploração de vulnerabilidades, o nmap NSE e as varreduras de todo o intervalo de portas só são feitos aos endpoints que aceitaram.

13.1 O que faz

Só faz uma ligação TCP a 54 portas fixas (Telnet, FTP, RDP, VNC, SMB, Redis, MongoDB, API do Docker, MQTT, RTSP, etc.), lê o banner que um serviço envia por si nas portas abertas (mais um HEAD / às portas web) e acrescenta uma nota quando o fabricante publicou vulnerabilidades (tabela de avisos IoT). Um resultado diz «a este serviço chega-se a partir da LAN», nunca «isto é vulnerável»; cada deteção indica que não foi testado se a autenticação está ativa.

13.2 Ativá-la

Para ativar unmanaged_audit.enabled, defina primeiro unmanaged_audit.authorization (quem aprovou: um nome, número de ticket ou referência de política) e unmanaged_audit.allowed_cidrs (os intervalos que podem ser auditados; os intervalos IPv4 mais amplos que /16 e IPv6 mais amplos que /48 são recusados). As execuções agendadas ocorrem a cada interval_hours (168 por predefinição) dentro da janela de schedule. Uma execução manual precisa de --confirm como segundo consentimento.

sudo roamswitch-sensor config set unmanaged_audit.authorization "IT policy 2026-07, approved by A. Suzuki"
sudo roamswitch-sensor config set unmanaged_audit.allowed_cidrs 192.168.10.0/24
sudo roamswitch-sensor config set unmanaged_audit.exclude 192.168.10.1
sudo roamswitch-sensor config set unmanaged_audit.enabled true
sudo roamswitch-sensor audit-unmanaged 192.168.10.40 --confirm
roamswitch-sensor unmanaged-audits --detail

13.3 Salvaguardas

Nada fora de allowed_cidrs, nenhum dispositivo em unmanaged_audit.exclude (IP, intervalo ou MAC), nenhum endpoint emparelhado e nem o próprio Sensor é alguma vez examinado. Antes e depois de uma execução, o MAC do dispositivo nesse endereço é confirmado com uma consulta em direto (ARP em IPv4, que requer o nmap; solicitação de vizinho em IPv6); se tiver mudado, a execução é interrompida ou o resultado descartado e é enviada uma notificação. O texto de authorization é escrito no registo de operações a cada execução e aparece nas exportações (export unmanaged, JSON, relatório HTML), podendo assim mostrar-se quem aprovou a auditoria.

13.4 Verificação do produto (tem vulnerabilidades do KEV da CISA? Opt-in)

Ao ativar unmanaged_audit.product_check (desativado por predefinição), a auditoria leve lê o nome do produto na página web que um dispositivo devolve normalmente e indica se esse produto tem vulnerabilidades do catálogo KEV da CISA. Só se envia um GET / para as portas web que aceitaram a ligação (80, 8080, 8181, 443, 8443, 10443), os redirecionamentos que o próprio dispositivo indica para o mesmo endereço (no máximo dois) e a leitura do emissor e do assunto do certificado HTTPS. Não se enviam inícios de sessão, tentativas de palavra-passe, caminhos adivinhados nem nada que explore uma vulnerabilidade. O limite é de 12 pedidos por dispositivo, com 150 ms de intervalo. As condições de consentimento (enabled, authorization, allowed_cidrs, exclude, exclusão de dispositivos emparelhados e nova verificação do MAC) são exatamente as dos §13.2–13.3; se a auditoria leve estiver desativada, não se envia nada, mesmo com product_check ativado.

Um produto só é nomeado quando todas as suas marcas no ecrã aparecem na mesma resposta. É indicado como afetado (high) apenas se for possível ler a versão que o próprio dispositivo mostra e um CVE tiver um intervalo NVD que a inclua. Se a versão não puder ser lida, fica como aviso (medium): este produto tem vulnerabilidades listadas no KEV, a versão não foi lida, por isso não está confirmado se está afetado. Nunca se afirma que o dispositivo é vulnerável. Hoje só o MikroTik RouterOS mostra a sua versão, pelo que os outros produtos recebem normalmente o aviso «não confirmado». Estão cobertos Fortinet FortiGate, Ivanti Connect Secure, Citrix NetScaler, Cisco (a VPN SSL do ASA e a interface web do IOS XE), UniFi OS, GeoVision, TerraMaster, Check Point Security Gateway e MikroTik RouterOS; os dispositivos Aruba não têm entrada no KEV e não estão cobertos. As marcas baseiam-se em assinaturas de deteção públicas e não foram verificadas em dispositivos reais; uma marca que não coincide tende a não detetar nada. Uma cópia do KEV é incluída no produto e só é atualizada, quando product_check e updates.fetch_cve_map estão ambos ativados, descarregando de 24 em 24 horas um ficheiro do feed público da CISA (nada da sua LAN é enviado).

14. Em caso de perda, roubo ou desativação

Um Sensor guarda a lista de vulnerabilidades encontradas em cada endpoint, os endereços dos endpoints emparelhados e a sua chave de assinatura. Os endpoints emparelhados também o tratam como um scanner autorizado, pelo que um Sensor roubado ligado à mesma LAN poderia fazer-se passar por um. O que se segue impede-o.

14.1 Revogação no coletor e bloqueio

Depois de roamswitch-sensor-collector revoke <chave pública> --reason TEXTO, os envios desse Sensor são recusados com 403 sensor_revoked (dado só a pedidos com assinatura válida, pelo que apenas quem tem a chave o fica a saber). Um Sensor revogado descobre-o no envio seguinte e pára por si (bloqueio). Bloqueada, a API de controlo só responde sensor_locked_down, e param os emparelhamentos, as auditorias (agendadas e manuais), os envios para o coletor, as notificações e a sondagem da rede. O bloqueio fica guardado num ficheiro, pelo que sobrevive a um reinício, e se esse ficheiro não puder ser lido o Sensor continua bloqueado. Os dados mantêm-se; com roamswitch-sensor lockdown off (K no TUI) liberta-se quando houver a certeza de que voltou a mãos seguras. Se continuar revogado no coletor, volta a bloquear-se no envio seguinte. revoke mostra também os endpoints que estavam emparelhados com esse Sensor e como remover o emparelhamento de cada um.

14.2 Apagamento, desativação e deteção offline

Com security.on_revoked em wipe, um Sensor revogado sobrescreve com zeros e apaga as suas chaves, a chave TLS, as definições (incluindo os URL de webhook), a lista de endpoints emparelhados, os resultados de auditoria e o inventário de dispositivos. Apenas o registo de operações é mantido, como prova. lockdown (predefinição) pára-o e mantém os dados, e none apenas notifica. Para desativar manualmente um Sensor que se tem à mão, use roamswitch-sensor decommission --confirm (bloquear e apagar; irreversível). Definir security.lockdown_after_offline_days com um número de dias faz com que um Sensor que não conseguiu contactar o coletor durante esse tempo pare por si, como salvaguarda de um Sensor roubado e usado noutra rede; só se aplica se o envio para o coletor estiver ativo e tiver tido êxito pelo menos uma vez, e a predefinição é 0 (desligado).

14.3 O que isto não consegue fazer

Os endpoints que estavam emparelhados com o Sensor continuam a confiar nele até cada um remover o emparelhamento. Um Sensor não tem forma de avisar os seus endpoints, por isso em cada endpoint da lista que revoke e decommission mostram execute roamswitch sensor unpair <chave pública deste Sensor> no Linux, ou Definições > Sensor > Desemparelhar no Mac. Um Sensor levado desligado ou mantido fora da rede nunca recebe a ordem para parar; aí a proteção real é a cifragem do disco (LUKS e semelhantes). Sobrescrever não garante um apagamento completo em armazenamento flash nem em sistemas de ficheiros copy-on-write.