ROAMSWITCH SENSOR ・ Última atualização: 2026-10-27

Manual de Operações do RoamSwitch Sensor

Guia de instalação e operação de um sensor de rede que, apenas por ser colocado na LAN, deteta o aparecimento de novos equipamentos no mesmo segmento e a falsificação. Para os terminais com o RoamSwitch instalado (Mac / Linux Client / Server Edition), realiza também auditorias ativas de vulnerabilidades. Distribuído em 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 RoamSwitch Sensor é um nó dedicado colocado na LAN, que preenche estas duas lacunas. Está implementado o seguinte: auditoria ativa de vulnerabilidades dos terminais com RoamSwitch instalado, inventário de dispositivos por ARP e deteção de falsificação e informação de referência sobre comportamentos suspeitos através de captura passiva opcional (§6). Apenas deteta e comunica; não bloqueia o tráfego.

Política de tráfego de saída (por predefinição, não são enviados dados de dispositivos nem resultados de auditorias)
O Sensor não é «Zero Telemetry». (1) Obtenção de dados de deteção: o mapa de CVE e outros dados são obtidos diariamente (updates.fetch_cve_map, predefinição true; com false, offline). Não incluem dados de dispositivos nem de auditoria. (2) Notificação e agregação para destinos definidos pelo operador: só são enviadas se estiverem configuradas.

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

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
Opt-in: extensão de visibilidade passiva de LAN
Para uso com uma porta espelhada de switch (SPAN) ou uma bridge transparente em linha, especifique o nome da interface de destino na variável de ambiente ROAMSWITCH_SENSOR_PASSIVE_CAPTURE_IFACE (definida via systemctl edit roamswitch-sensor.service) para observar cabeçalhos Ethernet/IPv4/IPv6 nessa interface e detectar novos dispositivos ou contato com IPs maliciosos conhecidos (veja §6.1). Desativado por padrão.

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

É apresentado um código de utilização única de 8 caracteres (0/O/1/I/L são excluídos). Expira 10 minutos após a emissão. Comunique-o de imediato ao operador do lado do terminal, juntamente com a impressão digital do certificado TLS (SHA-256) a fixar no terminal.

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.

Quando um código de emparelhamento expira
Um código de emparelhamento expira automaticamente 10 minutos após a emissão e nunca pode ser utilizado duas vezes. Uma tentativa de emparelhamento após a expiração é recusada. Nesse caso, peça ao operador do Sensor para emitir um novo código com issue-code.

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.

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
Passar control.tls para required
(1) Atualize todos os endpoints para uma versão com suporte TLS e conclua em cada um o emparelhamento TLS (ou uma nova fixação) → (2) confirme que roamswitch-sensor status já não mostra o aviso de ligação em texto simples → (3) execute sudo roamswitch-sensor config set control.tls required → reinicie o daemon. Normalmente não se usa off, porque os endpoints Linux exigem TLS e deixariam de conseguir ligar-se.

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). A uma porta aberta que não mostra qualquer banner envia um único GET / HTTP/1.0 para distinguir o serviço (no máximo 32 portas por auditoria).
  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).

Também são examinados os serviços em portas não padrão. Aplicam-se as mesmas verificações só de leitura, por exemplo, ao Redis na porta 6380 ou ao SSH na porta 2222. A identificação baseia-se no primeiro banner e na resposta a um único GET / HTTP/1.0. A lista autodeclarada de um terminal (até 64 entradas de cada vez) está fora da assinatura, pelo que nunca alarga o âmbito e serve apenas para escolher as verificações.

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

Quando aparece «Portas abertas: nenhuma» e também não há resposta ARP, é apresentado «Pode não estar a chegar ao dispositivo». Isto não significa «sem problemas». «nmap NSE: não executado (o nmap não está instalado)» e «não aplicável» têm significados diferentes.

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

A partir de um terminal emparelhado, também é possível pedir ao Sensor uma auditoria ativa de vulnerabilidades. Na versão Mac, com «Pedir auditoria ao Sensor» na barra de menus; na versão Linux, com o seguinte comando.

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

5.2 Diferenças face à especificação, valores-limite e pistas de uma IA (opcional)

Diferenças face à especificação e valores-limite (design_flaw.enabled; desativado por predefinição, opt-in) Aplica-se apenas aos terminais emparelhados que deram consentimento. Procura documentos OpenAPI / Swagger e comunica as discrepâncias entre o declarado e as respostas reais. Aplica aos parâmetros de consulta valores seguros fixos e comunica anomalias como 5xx. Envia apenas GET, no máximo 20 pedidos por equipamento. A ordem é fixa; a IA não a escolhe (o resumo oculta os segredos, até 240 carateres por item).
Pedir a uma IA que escreva hipóteses (opcional) roamswitch-sensor design-hypotheses passa apenas o resumo dos registos à ferramenta de IA escolhida e pede-lhe que escreva hipóteses não confirmadas. Executa-se com as permissões do utilizador que o lança, e o resumo pode ser enviado ao fornecedor. Nada é enviado aos equipamentos.

6. Monitoramento ARP passivo e visibilidade de LAN

O Sensor identifica os dispositivos da LAN de duas formas. (1) Monitorização da tabela ARP: lê-a cerca de cada 10 segundos e deteta novos pares IP/MAC e alterações de MAC em IP conhecidos (sinal de falsificação). (2) Varrimento ARP ativo: com nmap -sn -PR examina de hora a hora a sub-rede diretamente ligada (até /22) e guarda o resultado no inventário. Sem nmap, aplica-se apenas (1).

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 apenas os cabeçalhos Ethernet/IPv4/IPv6 nela e o que os dispositivos anunciam de si mesmos (o conteúdo dos dados só é lido em DNS, DHCP, mDNS, SSDP, WS-Discovery e LLDP) para fazer o seguinte.

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

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

Depois de acrescentar variáveis de ambiente, reinicie com sudo systemctl restart roamswitch-sensor. Só com systemctl edit, as alterações não chegam ao daemon em execução. Confirme que foram aplicadas em «Captura passiva: a receber em eth0» de roamswitch-sensor status. Se continuar a aparecer «A captura passiva está desativada», não reiniciou.

O buffer de receção altera-se com capture.rcvbuf_mb (MiB; predefinido 4, 0 para o valor predefinido do sistema). Como o único privilégio é CAP_NET_RAW, o que exceder net.core.rmem_max é cortado. Se aparecer kernel_drops, aumente rmem_max (por exemplo: sudo sysctl -w net.core.rmem_max=8388608; para tornar permanente, use /etc/sysctl.d/) e aumente também capture.rcvbuf_mb.

Uma NIC comum vs. uma porta espelhada
Mesmo uma única NIC comum funciona para detectar novos dispositivos dentro do escopo do tráfego ARP/broadcast/multicast (verificado em hardware real em uma LAN física). No entanto, observar o tráfego unicast geral entre outros dois hosts na LAN requer uma porta espelhada de switch (SPAN), ou configurar o Sensor como uma bridge transparente em linha.

6.2 Registo de dispositivos e notas de dispositivo

O inventário pode ser consultado com roamswitch-sensor device-inventory. Os equipamentos com uma nota registada através de device-note ficam «conhecidos»; os não registados ficam «a verificar». Os ID de VLAN observados surgem também na coluna vlans da exportação, entre outros locais.

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.

6.4 O que o Sensor não vê (cobertura)

A monitorização passiva, por si só, não distingue entre não ouvir nada e uma rede calma. O Sensor conta apenas o que conseguiu observar por si e não confunde o que não vê com «sem eventos». Não abre nenhuma ligação nem socket novos. Está ativo por predefinição.

Exemplos de causas que são contadas: não ser possível abrir a captura passiva, uma paragem de 30 segundos ou mais, 5 falhas de receção seguidas, 5 minutos sem tramas com a ligação também em baixo, descartes do kernel (últimos 10 minutos), tramas com mais de 2048 bytes e tramas cujo cabeçalho não pode ser lido. Uma ronda em que a tabela ARP não pode ser lida é contada sem apagar a linha de base.

O que não consegue fazer Conta apenas o que o próprio Sensor consegue observar. Não distingue um caso em que a receção está boa mas as tramas que chegam são enviesadas, como uma porta espelho mal configurada. Quando não há tramas há 5 minutos mas a ligação está ativa (capture_silent, info), diz claramente que não consegue distinguir «calmo» de «não ouve».

7. Referência rápida de comandos CLI

Comando Descrição
roamswitch-sensor status Mostrar a chave pública, o IP e o endereço MAC do próprio Sensor, o número de endpoints emparelhados, de eventos ARP e de pedidos de auditoria pendentes, e o estado do TLS da API de controlo
roamswitch-sensor issue-code Emitir um código de emparelhamento de uso único (válido durante 10 minutos); mostra também a impressão digital do certificado do Sensor
roamswitch-sensor list Lista todos os endpoints emparelhados
roamswitch-sensor pair <public-key> [--addr <IP>] [--name <name>] --confirm Emparelha manualmente um endpoint indicando diretamente a sua chave pública e endereço (normalmente é mais simples usar issue-code e deixar o endpoint emparelhar-se sozinho)
roamswitch-sensor unpair <public-key> Remove um emparelhamento
roamswitch-sensor scan <public-key> Executa uma auditoria ativa de vulnerabilidades em um endpoint emparelhado
roamswitch-sensor history [public-key] Mostra o histórico de auditoria (omita a chave pública para ver todos os endpoints)
roamswitch-sensor report <public-key> [--out <file>] Exporta o resultado de auditoria mais recente como relatório Markdown
roamswitch-sensor arp-events Mostra os eventos ARP detectados (novos dispositivos, suspeita de spoofing)
roamswitch-sensor pairing show / tls show Mostrar o estado do TLS da API de controlo (modo, impressão digital, aviso de ligação em texto simples, IP de escuta, se as assinaturas v1 legadas são aceites); pairing show e tls show são equivalentes
roamswitch-sensor tls rotate Regenerar o certificado TLS (todas as fixações da impressão digital antiga deixam de ser válidas; os endpoints têm de voltar a fixar)
roamswitch-sensor refresh Voltar a analisar a LAN agora (varredura ARP) e atualizar o registo de dispositivos
roamswitch-sensor device-inventory Mostrar o registo de dispositivos (todos os dispositivos observados na LAN, o seu estado online e nota)
roamswitch-sensor device-note <MAC> [note] Registar uma nota para um dispositivo (omita a nota para a eliminar)
roamswitch-sensor passive-events / iot-events / network-threats / iot-advisories Mostrar os eventos da captura passiva (novos dispositivos e ligações a IPs maliciosos / comportamento de IoT / tráfego suspeito / avisos de IoT)
roamswitch-sensor lan-overview [--json]
roamswitch-sensor network-threats --json [--limit N] [--min-severity …]
Mostra o estado geral da LAN (número de dispositivos, VLAN, número de ameaças, etc.) e a lista de ameaças. --json produz JSON (--limit é no máximo 500). Ambos são só de leitura e podem ser executados sem ser root. O PersonalSOC e a versão Linux do MCP leem-nos.
roamswitch-sensor config [show | set <chave> <valor>] Mostrar ou alterar definições (auditorias agendadas, notificações, retenção, collector, API de controlo, obtenção de dados de deteção, idioma). control.bind_addr e control.tls entram em vigor ao reiniciar o daemon; as restantes não precisam de reinício (§11.8)
roamswitch-sensor diff [chave pública] Mostrar o que mudou desde a auditoria anterior (novas deteções, resolvidas, portas recém-abertas, possivelmente inacessível)
roamswitch-sensor export <scans|inventory|audit-log|unmanaged|all> … Escrever as evidências de auditoria em CSV / JSON / HTML imprimível
roamswitch-sensor audit-log [verify] Mostrar o registo de operações e aprovações; verify deteta a adulteração da cadeia de hashes
roamswitch-sensor notify-test Enviar uma notificação de teste para os destinos configurados (webhook / syslog) para verificar a ligação
roamswitch-sensor audit-unmanaged <IP|MAC> --confirm
roamswitch-sensor unmanaged-audits
Auditoria ligeira de dispositivos sem RoamSwitch (apenas verificações de ligação). audit-unmanaged <IP ou MAC> --confirm lança uma à mão, unmanaged-audits [--detail] lista os resultados (§13)
roamswitch-sensor design-hypotheses [鍵] --llm 名前 Pede à ferramenta de IA escolhida pistas por verificar a partir do último resultado de design_flaw (§5.2). --llm, --model, --timeout, --show-prompt
roamswitch-sensor lockdown [status | on | off] Mostra se o Sensor está bloqueado (status), bloqueia-o (on --reason TEXTO) ou liberta-o (off). Bloqueado, pára emparelhamentos, auditorias, envios e notificações (§14)
roamswitch-sensor decommission --confirm Apaga as chaves e os dados deste Sensor e bloqueia-o (irreversível). O registo de auditoria é mantido e os endpoints que estavam emparelhados são listados com a forma de remover o emparelhamento (§14)

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) existe em 10 idiomas e permite operar tudo o que a CLI e as definições permitem (m mostra a lista de funções). Os 6 separadores principais (emparelhados, configuração de rede, eventos ARP, histórico de auditorias, diferenças, registo de operações) alternam-se com Tab. As diferenças mostram os novos a vermelho, os resolvidos a verde e os suspeitos de inacessibilidade a amarelo.

Tecla Ação
TabAlterna entre abas
↑↓ / j kSeleciona um item
cEmitir um código de emparelhamento (válido durante 10 minutos). O ecrã mostra o comando a executar no endpoint, sudo roamswitch sensor pair --addr <this Sensor’s IP> --code <code> --fingerprint <fingerprint>, já com os valores reais preenchidos
uRemove um emparelhamento
sExecuta uma auditoria ativa de vulnerabilidades no endpoint selecionado
a(Separador Dispositivos de rede) Auditoria ligeira do dispositivo selecionado, após um ecrã de confirmação (§13). Os resultados estão no separador «Não geridos» do menu
KBloqueia ou liberta este Sensor após um ecrã de confirmação; um aviso vermelho fica no fundo de cada ecrã enquanto estiver bloqueado. A desativação está no menu (§14)
n(Separador Dispositivos) Adicionar uma nota — nome, utilização, localização — ao dispositivo selecionado; um dispositivo com nota conta como identificado
rVoltar a analisar a LAN agora (varrimento ARP; por predefinição corre automaticamente a cada hora)
eExportar evidências de auditoria (CSV dos resultados de análise, do registo de dispositivos e do registo de auditoria; um relatório HTML; JSON). Um formulário permite escolher o conteúdo, o formato, o endpoint, a data de início e o destino; os ficheiros são produzidos no idioma de apresentação (10 idiomas). O destino predefinido é ~/.local/state/roamswitch-sensor/; os ficheiros são criados de novo e legíveis apenas pelo proprietário (um ficheiro existente nunca é substituído), e a própria exportação fica registada no registo de auditoria
pEmparelhamento manual (introduzir a chave pública e o endereço, depois um ecrã de confirmação, depois executar). O formulário mostra a impressão digital TLS do Sensor que o endpoint fixa
TEstado do TLS e do emparelhamento (modo, impressão digital, aviso de ligação em texto simples, IP de escuta, se as assinaturas v1 legadas são aceites). R regenera o certificado (com um ecrã de confirmação que explica o impacto)
CEditor de configuração (mostra e altera todas as chaves de configuração; os URLs de webhook estão sempre mascarados; as chaves que exigem reinício estão assinaladas)
NTeste de notificação (mostra o sucesso ou a falha por destino; os URLs estão mascarados)
mMenu de funcionalidades (monitorização passiva, comportamento de IoT, tráfego suspeito, avisos de IoT, estado i, gestão do collector e mais)
OGestão do collector (apenas num anfitrião que tenha o diretório de dados do collector): registar, revogar e listar Sensors, o token de leitura e a limpeza de uma anomalia do registo de auditoria. n define o destino dos alertas do próprio collector
f / l / v(Separador Histórico) filtrar por endpoint. (Separador Registo de auditoria) l altera o número de linhas apresentadas e v volta a verificar a cadeia de hashes
EnterMostrar os detalhes da linha selecionada (histórico, alterações, eventos ARP, dispositivos, registo)
w(Numa vista de detalhe) gravar o relatório num ficheiro, no destino que escolher (produzido no idioma de apresentação)
LEscolher o idioma de apresentação (guardado na definição language, pelo que também se aplica às notificações e aos registos produzidos pelo daemon)
qSai

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

10. Solução de problemas e FAQ

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

Há quatro causas possíveis. (1) Passaram mais de 10 minutos desde a emissão (volte a emitir com issue-code). (2) Erro de escrita. (3) O IP de --addr é diferente do IP fixo do Sensor. (4) --fingerprint é diferente do certificado (confirme com roamswitch-sensor pairing show). Se os erros continuarem, ocorre o bloqueio com rate_limited.

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

A causa é uma das duas seguintes. (1) O nmap não está instalado no contentor. (2) Foi executado, mas na realidade não houve saída de nenhum script seguro correspondente às portas de destino. O diagnóstico complementar nmap NSE é executado automaticamente se o nmap estiver instalado no anfitrião.

P3. Quanto tempo leva para concluir uma auditoria?

A análise de todas as portas, por si só, demora algumas dezenas de segundos. Se o nmap estiver instalado no anfitrião, o diagnóstico complementar NSE é acrescentado automaticamente e pode demorar até cerca de 2 minutos, consoante o número de portas abertas do alvo. A TUI continua a mostrar os segundos decorridos durante a execução, pelo que se pode acompanhar o progresso.

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

Há quatro causas possíveis. (1) sensor_pairing_enabled: true não está definido no terminal (desativado por predefinição). (2) O IP fixo do Sensor mudou (é preciso emparelhar de novo). (3) Foi executado unpair no lado do Sensor. (4) O certificado foi regenerado e o pin do terminal ficou desatualizado (roamswitch sensor repin). Verifique, nas listas de ambos os lados, o registo do 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

Com schedule.enabled em true, todos os terminais emparelhados são auditados periodicamente (de 24 em 24 horas por predefinição). A diferença em relação à auditoria anterior pode ser verificada com roamswitch-sensor diff. Quando todas as portas que estavam abertas deixam de ser visíveis, não é possível distingui-lo de um terminal parado, pelo que é tratado como suspeita de inacessibilidade.

Nem as auditorias sem supervisão quebram a garantia de auditar apenas os terminais que deram o seu consentimento. É guardado o MAC do momento da última autenticação do terminal e, antes e depois da auditoria, verifica-se com o ARP do nmap se o mesmo MAC responde nesse IP. Se diferir, a auditoria não é feita (ou o resultado é descartado) e é enviada uma notificação.

Os terminais de outra VLAN ficam excluídos por predefinição. Com schedule.allow_routed_endpoints (desativado por predefinição), verifica-se, entre outras coisas, que um pedido assinado chegou do mesmo endereço dentro de schedule.routed_proof_minutes (predefinição 30 minutos, de 5 a 1440).

Os motivos pelos quais não funciona (sem nmap, dispositivo sem endereço, dispositivo sem vínculo de identidade) aparecem como aviso em «Âmbito visível» no status. Se houver um destino de notificação, é entregue um coverage_gap uma vez e, depois de resolvido, um coverage_restored. Durante o lockdown e fora do horário, não é emitido aviso e é apresentada uma linha no status.

11.2 Notificações (webhook e syslog)

Envia regressões, novos dispositivos, falsificação ARP, etc. para notify.webhook_urls e notify.syslog.host (RFC 5424, UDP ou TCP). Podem ser filtrados com notify.min_severity e o intervalo de reenvio, e a conectividade verifica-se com roamswitch-sensor notify-test.

Em status aparecem o canal de notificação e o resultado da última entrega. Enquanto a entrega estiver a falhar, é mostrado um aviso; confirme com roamswitch-sensor notify-test. Quando tiver êxito, o aviso desaparece.

11.3 Exportação de evidências de auditoria

roamswitch-sensor export <scans|inventory|audit-log|all> --format csv|json|html [--out ficheiro] [--endpoint início da chave pública] [--since data]. O html pode ser guardado como PDF num navegador. O CSV está protegido contra injeção de fórmulas. A saída tem permissões 0600 e a própria exportação fica também registada no registo de operações. Na TUI, a tecla e permite as mesmas indicações.

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

O emparelhamento, as auditorias, as alterações de configuração e os acessos recusados são registados juntamente com quem os executou. Cada linha forma uma cadeia de hashes que inclui o SHA-256 da linha anterior, e a adulteração deteta-se com roamswitch-sensor audit-log verify (código de saída 2 em caso de anomalia). Os valores dos URL de webhook não são guardados. Como proteção contra a eliminação do fim, o início é também enviado 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
# On the collector host: where the collector's own alerts go
echo 'https://hooks.example.org/…' | sudo roamswitch-sensor-collector notify set --add-webhook - --min-severity high
sudo roamswitch-sensor-collector notify set --syslog-host 192.0.2.10 --syslog-protocol tcp
sudo roamswitch-sensor-collector notify show   # a Webhook URL is shown up to its host only
sudo roamswitch-sensor-collector notify test

Quando o coletor não consegue ler o seu histórico (scans.jsonl, events.jsonl), conta o que não foi possível ler para que não seja confundido com «sem dados». Uma linha danificada é ignorada isoladamente, e as linhas cuja data não é legível não são apagadas pela limpeza. O resultado aparece em storage_health de /api/overview, no painel e no registo de arranque. Não é feita nenhuma comunicação nova.

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

Chave Tipo / valores Predefinição Reinício
sitestring(empty)Não
languageja | en | ko | zh-Hans | zh-Hant | de | fr | es | it | pt-PT(empty = system locale)Não
schedule.enabledboolfalseNão
schedule.interval_hoursint24Não
schedule.window_start_hourint 0–23(unset = always)Não
schedule.window_end_hourint 0–23(unset = always)Não
schedule.max_parallelint 1–81Não
schedule.allow_routed_endpointsboolfalseNão
schedule.routed_proof_minutesint 5–144030Não
notify.webhook_urlsURL list(empty)Não
notify.min_severityinfo | medium | high | criticalmediumNão
notify.cooldown_minutesint30Não
notify.syslog.hoststring(empty = off)Não
notify.syslog.portint514Não
notify.syslog.protocoludp | tcpudpNão
retention.scan_history_daysint (0 = never prune)0Não
retention.audit_log_daysint (0 = never prune)0Não
retention.inventory_stale_daysint (0 = never prune)0Não
collector.enabledboolfalseNão
collector.urlURL(empty)Não
collector.push_interval_minutesint15Não
collector.send_unmanaged_devicesbooltrueNão
collector.send_unmanaged_auditsboolfalseNão
collector.probe_control_portboolfalseNão
control.bind_addrIP address0.0.0.0Sim
control.tlsoff | optional | requiredoptionalSim
control.allow_legacy_signaturesbooltrueNão
updates.fetch_cve_mapbooltrueNão
control.listen_ipv6boolfalseSim
capture.rcvbuf_mbint 0–256 (MiB, 0 = system default)4Sim
dhcp.active_probebooltrueNão
dhcp.allowed_serversMAC / IP list(empty = learn the first)Não
ipv6.enabledbooltrueNão
ipv6.active_probebooltrueNão
ipv6.allowed_routersMAC / IP list(empty = trust the IPv4 gateway)Não
unmanaged_audit.enabledbool (needs authorization + allowed_cidrs first)falseNão
unmanaged_audit.authorizationstring(empty)Não
unmanaged_audit.allowed_cidrsCIDR list (IPv4 ≤ /16 and IPv6 ≤ /48 refused)(empty)Não
unmanaged_audit.excludeIP / CIDR / MAC list(empty)Não
unmanaged_audit.interval_hoursint168Não
unmanaged_audit.max_parallelint 1–42Não
unmanaged_audit.product_checkbool (needs unmanaged_audit.enabled)falseNão
unmanaged_audit.noauth_checkbool (needs unmanaged_audit.enabled)falseNão
design_flaw.enabledboolfalseNão
design_flaw.llm.toolclaude | opencode | codex | agy | (empty)(empty)Não
design_flaw.llm.modelstring(empty)Não
design_flaw.llm.timeout_secsint (0 or 5–600)0Não
security.on_revokedlockdown | wipe | nonelockdownNão
security.lockdown_after_offline_daysint (0 = off)0Não

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

Deteta ataques em que um router ou dispositivo semelhante introduzido se faz passar por legítimo e sequestra o caminho de comunicação dos terminais. Apenas deteta e notifica; não bloqueia o tráfego. Ativado por predefinição, sem necessidade de captura passiva. Os resultados aparecem em roamswitch-sensor network-threats, na TUI, nas notificações, nos registos e nas exportações.

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

De hora a hora, envia apenas um DHCP discover a partir de um MAC aleatório e conta todos os servidores que respondem. Não envia REQUEST e não aluga nenhum endereço. Aprende o primeiro servidor como legítimo e assinala os que surgem depois. Quem distribuir outro gateway ou outro DNS é critical.

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

Anúncios de router não autorizados: se um dispositivo que não seja o gateway IPv4 se comportar como router IPv6, é enviada uma notificação (numa configuração normal, registe-o em ipv6.allowed_routers). Os anúncios cujo limite de saltos não é 255 são ignorados. Falsificação NDP: é assinalada quando o MAC de um endereço IPv6 é trocado (high se for um router). Dispositivos visíveis apenas por IPv6: são comunicados os dispositivos que surgem apenas na tabela de vizinhos.

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

Ao definir dhcp.allowed_servers e ipv6.allowed_routers, qualquer resposta de outros é comunicada (se estiverem vazios, aprende-se o primeiro). ipv6.enabled permite desativar a monitorização IPv6. A escuta IPv6 da API de controlo (50543) acrescenta-se com control.listen_ipv6 (predefinição false). O IPv6 global pode ser alcançável a partir da internet, pelo que está desativado por predefinição.

13. Auditoria ligeira de dispositivos sem RoamSwitch (opcional)

A auditoria ativa de vulnerabilidades do §5 destina-se apenas aos terminais emparelhados e que deram o seu consentimento. Se quiser verificar «o que está aberto para o exterior» em impressoras, câmaras, NAS e afins sem emparelhamento, pode usar uma verificação separada, muito mais limitada. Os diagnósticos profundos como o OpenVAS, as tentativas de início de sessão, a exploração de vulnerabilidades, o nmap NSE e as análises de todas as portas só são feitos nos terminais que deram o seu consentimento.

13.1 O que faz

Consiste apenas em verificações de ligação TCP a 55 portas fixas, na leitura do banner que uma porta aberta envia por si própria (um único HEAD / nos serviços web) e em notas sobre vulnerabilidades já publicadas. O resultado é «alcançável a partir da LAN», não «vulnerável». A verificação do produto e a da autenticação são opt-ins separados (desativados por predefinição).

13.2 Ativá-la

Antes de ativar, defina unmanaged_audit.authorization (o aprovador) e unmanaged_audit.allowed_cidrs (o intervalo; é recusado se for mais amplo do que /16 em IPv4 ou /48 em IPv6). A execução agendada é, por predefinição, de 168 em 168 horas; a manual exige --confirm.

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

Os equipamentos fora de allowed_cidrs, os que estão em unmanaged_audit.exclude, os terminais emparelhados e o próprio Sensor nunca são examinados, em circunstância alguma. O MAC é verificado antes e depois; se pertencer a outro equipamento, a verificação é interrompida ou o resultado é descartado. O texto de authorization fica no registo em cada execução.

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

unmanaged_audit.product_check (desativado por predefinição) lê o nome do produto na interface web de um equipamento e indica se tem uma vulnerabilidade do CISA KEV. Envia apenas GET / e redirecionamentos (no máximo 2) para as portas web (80, 8080, 8181, 443, 8443, 10443). Por conceção, não envia inícios de sessão, tentativas de palavra-passe, caminhos adivinhados nem dados que explorem vulnerabilidades. No máximo 12 pedidos por equipamento, com 150 ms de intervalo.

Um produto só é nomeado quando todos os seus indicadores surgem na mesma resposta. Se a versão indicada pelo equipamento tiver um CVE num intervalo afetado do NVD, é comunicada como «afetado» (high); se a versão não puder ser lida, como aviso «não confirmado» (medium), sem dizer que o equipamento é vulnerável. Só o MikroTik RouterOS expõe uma versão legível. Os produtos suportados incluem Fortinet FortiGate, Ivanti Connect Secure e Citrix NetScaler. Os indicadores baseiam-se em assinaturas de deteção públicas e não foram verificados em equipamentos reais.

A cópia do KEV vem incluída. Só quando product_check e updates.fetch_cve_map estão ambos ativados é que é obtido, de 24 em 24 horas, um ficheiro do feed público da CISA (não é enviada qualquer informação da LAN).

Verificação de resposta sem autenticação (unmanaged_audit.noauth_check; desativada por predefinição, opt-in) Envia um único pedido só de leitura a cada uma das seguintes portas, e apenas se estavam abertas: Redis (6379, PING), Memcached (11211), Docker API (2375), Elasticsearch (9200), etcd (2379), CouchDB (5984), kubelet (10250), ZooKeeper (2181), Ollama (11434). Não escreve, não altera a configuração, não envia AUTH, não envia nem tenta adivinhar palavras-passe e não inicia sessão.

MongoDB, MySQL e semelhantes não são examinados, porque uma tentativa poderia equivaler a um início de sessão. O resultado é um destes: «respondeu sem autenticação», «autenticação necessária», «recusado» ou «não foi possível determinar». Só funciona com o mesmo consentimento da auditoria ligeira. Utilize-a apenas em equipamentos que administre.

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

Quando um Sensor é revogado com roamswitch-sensor-collector revoke <chave pública> --reason motivo, os seus envios são recusados com 403 sensor_revoked. Um Sensor que tome conhecimento da revogação para por si próprio (lockdown) e interrompe a auditoria, o envio, as notificações e a sondagem. A paragem mantém-se após reiniciar e os dados permanecem. Só quando houver a certeza de que o Sensor está nas mãos do proprietário é que se pode levantar com roamswitch-sensor lockdown off.

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

Com security.on_revoked definido como wipe, a revogação substitui por zeros e elimina as chaves, a chave TLS, a configuração (incluindo o URL do Webhook), a lista de terminais, os resultados de auditoria e o inventário de equipamentos. Apenas os registos de operações e de aprovações são mantidos, como prova. O valor predefinido, lockdown, apenas para o Sensor. Com security.lockdown_after_offline_days (predefinição 0 = desativado), um Sensor que não consiga enviar durante muito tempo também para por si próprio.

14.3 O que isto não consegue fazer

Os terminais continuam a confiar neste Sensor até cada um o desemparelhar, e o Sensor não os pode notificar. Em cada terminal apresentado, execute roamswitch sensor unpair <chave pública deste Sensor> no Linux, ou Definições > Sensor > Desemparelhar no Mac. Um Sensor levado desligado nunca recebe a instrução de paragem, pelo que a cifragem do disco (LUKS, etc.) é a defesa real. O apagamento por substituição não garante um apagamento completo em flash ou CoW.

← Manual de Operações do Server Edition Para a página de instalação da edição Linux →