Servidor central do WireSentinel, desenvolvido em Java com Spring Boot, responsável por receber, autenticar, persistir e expor os dados capturados pelos agentes locais.
O servidor atua como núcleo do sistema. Ele recebe pacotes processados pelo cliente C, valida a autenticidade das requisições, persiste os dados em PostgreSQL e fornece APIs para o frontend consultar sistemas, pacotes e métricas.
- Dashboard e Interfaces
- Responsabilidades
- Arquitetura
- Visão geral do fluxo
- Fluxos principais
- Autenticação
- Endpoints do agente
- Endpoints do usuário
- Endpoints de métricas
- Modelos principais
- Frontend
- Variáveis de ambiente
- Build e execução do servidor
- Segurança
- Paginação e ordenação
- Checklist operacional
- Resumo
- Registrar agentes WireSentinel.
- Validar agentes usando UUID e HMAC SHA-256.
- Receber pacotes processados via HTTP.
- Persistir sistemas e pacotes no PostgreSQL.
- Gerenciar usuários com autenticação JWT.
- Vincular agentes a usuários.
- Expor APIs paginadas para consulta de sistemas e pacotes.
- Servir o frontend estático React.
- Permitir visualização dos dados capturados pelo dashboard web.
O servidor é organizado em três grandes responsabilidades:
- API do agente: endpoints usados pelo cliente C para registro, autenticação e ingestão.
- API do usuário: endpoints usados pelo frontend para login, cadastro e vínculo de agentes.
- API de métricas: endpoints usados pelo frontend para consultar sistemas e pacotes.
O frontend é buildado como aplicação estática e servido pelo próprio Spring Boot a partir de:
src/main/resources/static/
WireSentinel Client
│
▼
HTTP + HMAC SHA-256
│
▼
WireSentinel Server
│
├── Validação de timestamp
├── Validação de HMAC
├── Validação de UUID
│
▼
PostgreSQL
│
▼
API protegida por JWT
│
▼
Frontend React / Dashboard
Na primeira execução, o cliente C registra a máquina monitorada no servidor.
Fluxo:
- O cliente gera um timestamp local.
- O cliente monta uma string de assinatura.
- O cliente gera um HMAC SHA-256 usando a chave compartilhada.
- O cliente envia uma requisição para:
GET /api/register-
O servidor valida:
- timestamp;
- HMAC;
- User-Agent.
-
Se a requisição for válida, o servidor cria um novo sistema.
-
O servidor gera um UUID.
-
O servidor gera um nome identificável para o sistema.
-
O servidor salva o sistema no banco.
-
O servidor retorna o UUID em texto puro.
-
O cliente salva esse UUID localmente no arquivo
.uuid.
Resposta de sucesso:
550e8400-e29b-41d4-a716-446655440000
Quando o cliente já possui um UUID salvo, ele pode validar esse UUID com o servidor.
Endpoint:
GET /api/client_authFluxo:
-
O cliente lê o UUID local.
-
O cliente gera timestamp e HMAC.
-
O cliente envia o UUID no header.
-
O servidor valida:
- timestamp;
- HMAC;
- formato do UUID;
- existência do UUID no banco.
Se tudo estiver correto, o servidor responde 200 OK.
Depois de capturar e processar pacotes, o cliente C envia os dados em lote para o servidor.
Endpoint:
POST /api/ingestFluxo:
- O cliente captura pacotes via raw socket.
- O cliente processa Ethernet, VLAN, IPv4, IPv6, TCP, UDP, ICMP e outros protocolos.
- O cliente monta estruturas internas de pacote.
- O cliente serializa os pacotes em JSON.
- O cliente calcula o
Content-Length. - O cliente gera timestamp e HMAC.
- O cliente envia o batch para o servidor.
- O servidor valida a requisição.
- O servidor associa os pacotes ao UUID enviado no header.
- O servidor persiste os pacotes no PostgreSQL.
Formato do body:
{
"packets": [
{
"timestamp": "2026-05-07T12:09:06",
"macAdressOrigem": "aa:bb:cc:dd:ee:ff",
"macAdressDestino": "11:22:33:44:55:66",
"protocoloIp": "IPv4",
"ipOrigem": "192.168.0.10",
"ipDestino": "8.8.8.8",
"tempoDeVida": 64,
"tamanhoTotalHeader": 54,
"tamanhoTotalPacote": 1500,
"portaOrigem": 51544,
"portaDestino": 443,
"tcpSeq": 123456789,
"tcpAckSeq": 987654321,
"tcpAck": true,
"tcpFin": false,
"tcpSyn": true,
"tcpRst": false,
"tcpPsh": false,
"tcpUrg": false,
"tcpCwr": false,
"tcpEce": false,
"isVlan": false,
"protocolo_transporte": "TCP",
"protocolo_aplicacao": "https"
}
]
}O servidor utiliza dois modelos de autenticação, cada um para um tipo de consumidor.
O agente C não usa JWT.
A comunicação entre agente e servidor usa HMAC SHA-256 com uma chave compartilhada.
Variável usada no servidor:
WIRESENTINEL_SECRET=chave_compartilhadaO cliente deve usar a mesma chave no arquivo .security:
SHRD_SCRT=chave_compartilhada
URL=192.168.0.10
PORT=8080
Headers usados pelo agente:
User-Agent: WireSentinel-Agent/1.0
X-WireSentinel-Timestamp: <timestamp>
X-WireSentinel-Credential: <hmac_sha256>
X-WireSentinel-UUID: <uuid_do_agente>O header X-WireSentinel-UUID é usado em /api/client_auth e /api/ingest.
Usuários do dashboard utilizam JWT.
Variável usada no servidor:
JWT_SECRET=chave_jwtFluxo:
- O usuário cria uma conta ou faz login.
- O servidor retorna um JWT em texto puro.
- O frontend salva o token.
- O frontend envia o token em rotas protegidas:
Authorization: Bearer <token>GET /api/registerUsado pelo cliente C para criar um novo sistema no servidor.
Headers:
User-Agent: WireSentinel-Agent/1.0
X-WireSentinel-Timestamp: <timestamp>
X-WireSentinel-Credential: <hmac_sha256>Resposta:
<uuid_gerado>
GET /api/client_authUsado pelo cliente C para validar se o UUID salvo localmente ainda existe no servidor.
Headers:
User-Agent: WireSentinel-Agent/1.0
X-WireSentinel-Timestamp: <timestamp>
X-WireSentinel-Credential: <hmac_sha256>
X-WireSentinel-UUID: <uuid_do_agente>Resposta de sucesso:
200 OKPOST /api/ingestUsado pelo cliente C para enviar pacotes processados em lote.
Headers:
Content-Type: application/json
Content-Length: <tamanho_do_body>
User-Agent: WireSentinel-Agent/1.0
X-WireSentinel-Timestamp: <timestamp>
X-WireSentinel-Credential: <hmac_sha256>
X-WireSentinel-UUID: <uuid_do_agente>Body:
{
"packets": []
}Resposta de sucesso:
200 OKPOST /api/user/registerBody:
{
"login": "usuario",
"password": "senha"
}Resposta de sucesso:
<jwt>
POST /api/user/loginBody:
{
"login": "usuario",
"password": "senha"
}Resposta de sucesso:
<jwt>
POST /api/user/register_uuid/{uuid}Autenticação:
Authorization: Bearer <token>Uso:
POST /api/user/register_uuid/550e8400-e29b-41d4-a716-446655440000
Esse endpoint vincula um agente já registrado no servidor à conta do usuário autenticado.
POST /api/user/remove_uuid/{uuid}Autenticação:
Authorization: Bearer <token>Esse endpoint remove o vínculo entre o usuário autenticado e o agente informado.
GET /api/metrics/systemsAutenticação:
Authorization: Bearer <token>Suporta paginação:
GET /api/metrics/systems?page=0&size=10Resposta:
{
"content": [
{
"id": 1,
"uuid": "550e8400-e29b-41d4-a716-446655440000",
"mockName": "purple-wolf-123"
}
],
"totalElements": 1,
"totalPages": 1,
"size": 10,
"number": 0,
"first": true,
"last": true,
"empty": false
}GET /api/metrics/system/{uuid}/packetsAutenticação:
Authorization: Bearer <token>Suporta paginação e ordenação:
GET /api/metrics/system/{uuid}/packets?page=0&size=50&sort=id,descExemplo:
GET /api/metrics/system/550e8400-e29b-41d4-a716-446655440000/packets?page=0&size=50&sort=id,descResposta:
{
"content": [
{
"id": 123,
"timestamp": "2026-05-07T12:09:06",
"macAdressOrigem": "aa:bb:cc:dd:ee:ff",
"macAdressDestino": "11:22:33:44:55:66",
"protocoloIp": "IPv4",
"ipOrigem": "192.168.0.10",
"ipDestino": "8.8.8.8",
"tempoDeVida": 64,
"tamanhoTotalHeader": 54,
"tamanhoTotalPacote": 1500,
"portaOrigem": 51544,
"portaDestino": 443,
"tcpSeq": 123456789,
"tcpAckSeq": 987654321,
"tcpAck": true,
"tcpFin": false,
"tcpSyn": true,
"tcpRst": false,
"tcpPsh": false,
"tcpUrg": false,
"tcpCwr": false,
"tcpEce": false,
"isVlan": false,
"protocolo_transporte": "TCP",
"protocolo_aplicacao": "https",
"uuid": "550e8400-e29b-41d4-a716-446655440000"
}
],
"totalElements": 1,
"totalPages": 1,
"size": 50,
"number": 0,
"first": true,
"last": true,
"empty": false
}Representa um agente/sistema registrado.
Campos principais:
id
uuid
mockName
Uso:
- identificar máquinas monitoradas;
- vincular agentes a usuários;
- consultar pacotes de um sistema específico.
Representa um pacote processado pelo agente.
Campos principais:
id
timestamp
macAdressOrigem
macAdressDestino
protocoloIp
ipOrigem
ipDestino
tempoDeVida
tamanhoTotalHeader
tamanhoTotalPacote
portaOrigem
portaDestino
tcpSeq
tcpAckSeq
tcpAck
tcpFin
tcpSyn
tcpRst
tcpPsh
tcpUrg
tcpCwr
tcpEce
isVlan
protocolo_transporte
protocolo_aplicacao
uuid
Representa um usuário do dashboard.
Responsabilidades:
- autenticação via login e senha;
- vínculo com UUIDs de agentes;
- acesso aos sistemas associados.
O frontend do WireSentinel é uma aplicação React estática servida pelo próprio Spring Boot.
Ele consome apenas os endpoints HTTP do servidor.
O frontend permite:
- Criar usuário.
- Fazer login.
- Vincular UUID de agente.
- Listar sistemas vinculados.
- Consultar pacotes de cada sistema.
- Visualizar métricas e gráficos.
- Filtrar pacotes.
- Atualizar dados automaticamente.
Usuário acessa o dashboard
│
▼
Login ou cadastro
│
▼
JWT salvo no navegador
│
▼
Usuário vincula UUID do agente
│
▼
Frontend consulta /api/metrics/systems
│
▼
Usuário abre um sistema
│
▼
Frontend consulta /api/metrics/system/{uuid}/packets
│
▼
Dashboard exibe tabela, filtros e gráficos
Após o build do frontend, os arquivos devem ser copiados para:
src/main/resources/static/
Estrutura esperada:
src/main/resources/static/index.html
src/main/resources/static/assets/
O Spring Boot detecta automaticamente o index.html e serve a aplicação.
Como o frontend usa rotas client-side, o servidor precisa encaminhar algumas rotas para o index.html.
Exemplo de controller:
package com.bolota.wiresentinelserver.Controller;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.GetMapping;
@Controller
public class SpaController {
@GetMapping(value = {
"/login",
"/register",
"/dashboard",
"/systems",
"/systems/{path:[^\\.]*}",
"/link",
"/docs"
})
public String forward() {
return "forward:/index.html";
}
}As rotas /api/** não devem ser encaminhadas para o frontend.
O servidor utiliza variáveis de ambiente para configurar autenticação e banco de dados.
Exemplo .env:
JWT_SECRET=chave_jwt_grande_e_segura
WIRESENTINEL_SECRET=chave_compartilhada_do_agenteVariáveis usadas pelo container da aplicação:
JWT_SECRET
WIRESENTINEL_SECRET
SPRING_DATASOURCE_URL
SPRING_DATASOURCE_USERNAME
SPRING_DATASOURCE_PASSWORD
TZdocker compose up -d --buildVer logs da aplicação:
docker compose logs -f appVer logs do banco:
docker compose logs -f dbParar os containers:
docker compose downBuildar e subir o servidor:
docker compose up -d --buildApós isso, o dashboard estará disponível em:
http://localhost:8080
Ou pelo IP da máquina:
http://<ip-do-servidor>:8080
O WireSentinel separa autenticação de agente e autenticação de usuário.
Usa:
HMAC SHA-256
Timestamp
UUID
Chave compartilhada
Objetivo:
- validar que o agente possui a chave correta;
- evitar ingestão de dados por clientes não autorizados;
- associar pacotes ao sistema correto.
Usa:
JWT
Authorization Bearer
Objetivo:
- proteger as rotas do dashboard;
- permitir que cada usuário acesse apenas seus sistemas vinculados;
- separar autenticação humana da autenticação de máquina.
As consultas de sistemas e pacotes usam paginação do Spring.
Exemplos:
GET /api/metrics/systems?page=0&size=10GET /api/metrics/system/{uuid}/packets?page=0&size=50&sort=id,descOrdenações úteis:
id,desc
id,asc
timestamp,desc
timestamp,asc
tamanhoTotalPacote,desc
tamanhoTotalPacote,asc
portaDestino,asc
portaDestino,desc
Antes de executar o ambiente:
- Criar o arquivo
.env. - Definir
JWT_SECRET. - Definir
WIRESENTINEL_SECRET. - Confirmar que o
compose.yamlexpõe a porta8080. - Buildar o frontend.
- Copiar o frontend para
src/main/resources/static. - Buildar a imagem do servidor.
- Subir o ambiente com Docker Compose.
- Validar se o Spring iniciou na porta
8080. - Validar se o PostgreSQL está saudável.
- Registrar um agente.
- Vincular o UUID do agente no dashboard.
- Consultar pacotes pelo frontend.
O WireSentinel Server centraliza todo o fluxo da aplicação:
Agente C
↓
Registro por UUID
↓
Autenticação HMAC
↓
Ingestão de pacotes
↓
Persistência PostgreSQL
↓
API protegida por JWT
↓
Frontend React
↓
Dashboard de observabilidade
O servidor fornece a base de autenticação, persistência, consulta e visualização dos dados capturados pelos agentes WireSentinel.