Guia técnico do Net Wise: instalação, funcionamento do agente, métricas, detecção de incidentes, API e segurança. Os limiares mostrados abaixo são os configurados agora nesta instalação.
Versão 1.0.0 · 75 páginas · 0,3 MB · gerado em 26/09/2026 16:13
1. Primeiros passos
- Crie a conta em Criar conta e ative a assinatura.
- Em Dispositivos → Instalar agente, gere o código de pareamento (8 caracteres, válido por 30 min, uso único).
- Instale o agente no dispositivo e digite o código.
- A rede atual do dispositivo aparece em Redes. Confirme a autorização (ou ative a autorização automática).
- Acompanhe em Visão geral, Ao vivo e na página de cada rede.
2. Instalação do agente (versão 1.3.0)
Gere o código em Dispositivos → Instalar agente e escolha uma das formas abaixo. Cada download já vem com o endereço deste servidor embutido — não é preciso digitá-lo.
Windows 10 / 11 — aplicativo único (recomendado)
- Baixe
netwise-agent.exeno painel. Não precisa instalar o Python nem nenhum outro programa: tudo já vem dentro do arquivo. - Dê dois cliques. Na janela, digite o código de pareamento e clique em Parear e instalar (o Windows pede permissão de administrador).
- Pronto. O agente passa a rodar sempre em segundo plano, mesmo com a janela fechada e após reiniciar o computador.
O aplicativo analisa o que já existe e pula etapas prontas; se algum componente do sistema faltar, ele apenas ignora a medição correspondente, sem travar. Também se autorrepara: se a tarefa em segundo plano for apagada, o próprio serviço a recria.
Como funciona por dentro / instalação silenciosa
O executável é copiado para %ProgramData%\NetWise (acesso só de SYSTEM e Administradores, onde fica o token) e registrado como a Tarefa Agendada Net Wise Agent, na conta SYSTEM, disparada ao iniciar o Windows e revivida sozinha (gatilho de repetição + reinício automático). Sem console, sem janela.
netwise-agent.exe repair (reinstala o serviço se necessário)
netwise-agent.exe uninstall
Logs em %ProgramData%\NetWise\agent.log. Para atualizar, basta abrir uma versão nova do .exe: ele se atualiza sozinho e mantém o pareamento.
Windows — outras formas (agente em Python)
Para quem prefere não usar o executável pronto. Estas exigem Python 3.9+ instalado (python.org, marque “Add to PATH”):
- ZIP + assistente: baixe o pacote, extraia e rode
instalar.bat(como administrador). - PowerShell (TI): rode
install.ps1como administrador; ele pergunta o código de pareamento e registra o serviço.
Linux — um comando (Debian, Ubuntu, Mint, Fedora, RHEL, Rocky, Alma, CentOS, openSUSE, Arch, Manjaro, Raspberry Pi OS, Alpine)
O instalador confere as dependências (python3, ping, ip, traceroute, curl) e só instala o que faltar, pelo gerenciador de pacotes da distro (apt/dnf/yum/zypper/pacman/apk). Se tudo já existe, pula essa etapa. Registra o serviço com systemd ou, no Alpine, OpenRC.
tail -f /var/lib/netwise/agent.log
Roda como usuário de sistema netwise, com ProtectSystem=strict, NoNewPrivileges e CAP_NET_RAW (para ICMP). Opcional: NetworkManager (dados de Wi-Fi) e traceroute (rota até a internet).
Comandos do agente
| Comando | Uso |
|---|---|
enroll --server URL --code XXXX-XXXX | Pareia com a conta |
run | Loop contínuo (usado pelo serviço) |
once | Uma medição local, imprime JSON (não envia) |
diagnose [--speed] | Diagnóstico completo local (rota, latência por destino, IP público) |
wifi-list / wifi-connect SSID | Lista e conecta a redes Wi-Fi como o menu do sistema |
status | Mostra servidor, dispositivo e rede atual |
3. Redes automáticas
O agente identifica a rede atual por uma impressão digital: SHA-256(SSID | MAC do gateway) — em rede cabeada, apenas o MAC do gateway. O MAC é obtido da tabela ARP do próprio sistema e só o hash é enviado.
- Impressão digital nova → a rede é criada na conta como pendente (ou ativa, se a autorização automática estiver ligada; a declaração fica registrada).
- Medições de redes pendentes ou ignoradas não são armazenadas.
- Cada amostra carrega a impressão digital da rede em que foi medida, então a fila offline do agente nunca mistura redes.
- Trocou o roteador? A rede nova aparece como pendente; use “É a mesma rede de…” para associá-la ao histórico existente.
- Ao mudar de rede, incidentes abertos da rede anterior são encerrados com a nota “Dispositivo saiu desta rede”.
4. Monitoramento ao vivo
No ciclo normal o agente faz uma medição completa a cada 60 s e envia um heartbeat a cada 15 s. Ao abrir Ao vivo, o painel marca os agentes daquela rede; no próximo heartbeat (até 15 s) eles passam a:
- medir a cada 1 s um ICMP até a internet e outro até o roteador, em paralelo;
- ler o RSSI do Wi-Fi a cada 5 s;
- enviar os pontos em lotes a cada ~2 s (
POST /api/agent/live).
O painel calcula no servidor, sobre a janela dos últimos 60 s: RTT médio, p95, jitter, perda, média do gateway e MOS estimado. A sessão ao vivo dura até 30 min por vez e termina sozinha em 90 s quando a página é fechada. Pontos ao vivo ficam guardados por 2 horas; o histórico permanente usa as medições completas.
5. Métricas e glossário
| Termo | Definição |
|---|---|
| RTT / latência | Tempo de ida e volta de um pacote ICMP echo até 1.1.1.1 e 8.8.8.8 (5 pacotes cada por medição). Sem ICMP, usa o tempo de conexão TCP na porta 443. |
| Jitter | Média do valor absoluto da diferença entre RTTs consecutivos (em ms). |
| Perda | (pacotes enviados − respostas) ÷ enviados × 100. |
| Gateway | RTT e perda de 5 pings até o roteador padrão. Em Wi-Fi saudável, costuma ficar abaixo de 10 ms e sem perda. |
| DNS | Tempo para resolver nwNNNNNNN.exemplo aleatório — o nome não existe em cache, então mede o resolvedor de verdade (NXDOMAIN conta como resposta). |
| TCP / HTTPS | Handshake TCP com 1.1.1.1:443 e requisição HTTPS a generate_204. |
| Disponibilidade | Amostras com internet ÷ amostras totais. Uma queda só é registrada após nova tentativa 5 s depois. |
| p50 / p95 / p99 | Percentis do RTT no período (amostras brutas, até 7 dias). |
| MOS estimado | Modelo E simplificado (ITU-T G.107): latência efetiva = RTT + 2×jitter + 10; R = 93,2 − penalidade de atraso − 2,5×perda; MOS = 1 + 0,035R + 7×10⁻⁶·R(R−60)(100−R). Estimativa, não teste de VoIP. |
| RSSI | Intensidade do sinal Wi-Fi em dBm. No Windows é derivada do percentual do netsh (dBm ≈ % ÷ 2 − 100). |
| Rota até a internet | No diagnóstico completo, o traceroute é estruturado em saltos (número, IP e ms). O painel destaca o salto em que a latência dispara, separando problema na sua rede do problema no caminho do provedor. |
| Latência por destino | Tabela comparando, na mesma medição, o tempo até o roteador, a borda do provedor (1º salto além do roteador), o servidor DNS e a nuvem (Cloudflare/Google). Diz onde a lentidão começa. |
| IP público | Endereço público da sua conexão (metadado da linha, não é histórico de navegação). Serve para detectar reconexão do provedor ou troca de link; a mudança vira um evento na linha do tempo da rede. |
| Detecção de gargalo | Classifica cada trecho do caminho (Wi-Fi, roteador, provedor, DNS) comparando a latência/perda de cada um e aponta, em linguagem cautelosa, onde há indícios de problema. |
| Mapa de Wi-Fi | A cada ~30 min o agente varre a vizinhança e envia apenas canais e intensidade (não os nomes das redes). O painel mostra a ocupação por canal, quantas redes disputam o seu e sugere um canal melhor (2,4 GHz). |
| Serviços monitorados | Testes de aplicação definidos pelo cliente (HTTPS, ping ou porta TCP) para serviços públicos. Mede tempo de resposta e disponibilidade — nunca o conteúdo. Só endereços públicos são aceitos. |
| SLA / uptime | Compara a disponibilidade de 30 dias com a meta definida na rede e acompanha a velocidade média contra a contratada, com alerta configurável quando cai abaixo de um limite. |
| Índice de qualidade | Nota 0–100 ponderada. Documentação do índice. |
6. Incidentes e limiares
Um incidente abre após 2 amostras ruins seguidas (queda, velocidade e IPv6: 1) e fecha após 2 amostras boas. Eventos: INCIDENT_START, INCIDENT_UPDATE (piora ou a cada 30 min) e INCIDENT_RESOLVED.
| Tipo | Condição (configuração atual) |
|---|---|
| Conexão perdida | Sem resposta da internet (ICMP, TCP e HTTPS), confirmada após 5 s |
| Latência elevada | RTT > 150 ms (crítico > 300 ms) |
| Jitter elevado | > 30 ms |
| Perda de pacotes | ≥ 5,0% (crítico ≥ 20%) |
| DNS lento | > 300 ms |
| Sinal Wi-Fi fraco | RSSI < -75 dBm |
| IPv6 indisponível | IPv6 falha num dispositivo em que funcionou nas últimas 24 h |
| Velocidade reduzida | Download < 50% da mediana dos últimos 7 dias |
| Agente offline | Sem contato por 15 min |
7. Relatórios e análise profissional
- Relatórios automáticos (semanal/mensal) e relatórios feitos por especialista, com as métricas congeladas no momento da geração.
- Incidentes simultâneos são agrupados em períodos de instabilidade.
- PDF, link temporário (
/report/share/…) com expiração, senha opcional e revogação, e exportação CSV do período. - Na análise profissional, o especialista só acessa a rede com sua autorização, por 30 dias, e cada acesso é auditado e visível para você em Minha conta.
8. API do agente
REST/JSON sobre HTTPS. Autenticação: Authorization: Bearer nw_dev_… (o servidor guarda apenas o SHA-256 do token).
| Endpoint | Função |
|---|---|
POST /api/agent/enroll | Troca o código de pareamento por um token; aceita o bloco network (fp, ssid, iface, dns) |
POST /api/agent/heartbeat | Sinal de vida + rede atual; retorna configuração (intervalos, alvos, ao vivo) e comandos pendentes |
POST /api/agent/measurements | Até 500 amostras por lote, até 7 dias no passado; idempotente por dispositivo + horário |
POST /api/agent/live | Pontos do modo ao vivo (até 30 por chamada) |
POST /api/agent/diagnostic | Resultado de um diagnóstico sob demanda |
POST /api/agent/rotate | Rotação do token (automática a cada 30 dias) |
{"samples":[{"measured_at":"2026-09-26T14:55:45-03:00","online":true,"ping_ms":32.5,"jitter_ms":0.3,"loss_pct":0,
"gw_ms":2.1,"gw_loss_pct":0,"dns_ms":36.7,"tcp_ms":33.6,"https_ms":222,"ipv4_ok":true,"ipv6_ok":true,
"wifi_rssi":-50,"wifi_channel":44,"wifi_freq_mhz":5220,"wifi_radio":"802.11ac","wifi_link_mbps":780,
"iface_type":"wifi","net_fp":"80e4…(64 hex)","ssid":"Minha Rede"}]}
Respostas de erro: 401 (token inválido/revogado), 402 (assinatura inativa), 422 (lote inválido), 429 (limite de requisições).
9. Segurança
- Senhas com Argon2id; recuperação por token aleatório de uso único (1 h), guardado como hash.
- Verificação em duas etapas (TOTP, RFC 6238) com 8 códigos de recuperação.
- Sessões com cookie HttpOnly/SameSite, expiração por inatividade e revogação global ao trocar a senha.
- CSRF em todos os formulários, CSP sem JavaScript inline, limites de tentativas em login, cadastro, pareamento, 2FA e API.
- Isolamento por cliente em todas as consultas; o ID enviado pelo navegador nunca é confiado sozinho.
- Trilha de auditoria de acessos administrativos (quem, quando, cliente, rede, dispositivo, ação).
- Pagamentos pelo checkout do Asaas; nenhum dado de cartão passa pelo Net Wise. Webhooks autenticados e idempotentes.
10. Solução de problemas
“Código inválido ou expirado”
O código vale 30 min e uma vez. Gere outro em Dispositivos → Instalar agente.
A rede não aparece
Veja o log do agente. Sem gateway padrão (sem conexão de rede) não há impressão digital. Confira também se a rede não foi ignorada (Redes → arquivadas).
“Aguardando as primeiras leituras” no ao vivo
O agente só percebe o pedido no próximo heartbeat (até 15 s). Se continuar, confira se o dispositivo está online e conectado à rede selecionada.
Wi-Fi aparece como “—”
No Linux instale o NetworkManager (nmcli). Em cabo, não há dados de Wi-Fi.
Gateway aparece como “—”
Alguns roteadores bloqueiam ping. Nesse caso não é possível separar rede local de provedor.
O agente parou de enviar
Se o dispositivo foi removido no painel, o token é revogado e o agente encerra (log: “Token recusado”). Pareie novamente.