Skip to content

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

23 Commits

Folders and files

Repository files navigation

dashboard_inicial

WireSentinel Server

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.


Índice


Dashboard e Interfaces


Responsabilidades

  1. Registrar agentes WireSentinel.
  2. Validar agentes usando UUID e HMAC SHA-256.
  3. Receber pacotes processados via HTTP.
  4. Persistir sistemas e pacotes no PostgreSQL.
  5. Gerenciar usuários com autenticação JWT.
  6. Vincular agentes a usuários.
  7. Expor APIs paginadas para consulta de sistemas e pacotes.
  8. Servir o frontend estático React.
  9. Permitir visualização dos dados capturados pelo dashboard web.

Arquitetura

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/

Visão geral do fluxo

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

Fluxos principais

1. Registro do agente

Na primeira execução, o cliente C registra a máquina monitorada no servidor.

Fluxo:

  1. O cliente gera um timestamp local.
  2. O cliente monta uma string de assinatura.
  3. O cliente gera um HMAC SHA-256 usando a chave compartilhada.
  4. O cliente envia uma requisição para:
GET /api/register
  1. O servidor valida:

    • timestamp;
    • HMAC;
    • User-Agent.
  2. Se a requisição for válida, o servidor cria um novo sistema.

  3. O servidor gera um UUID.

  4. O servidor gera um nome identificável para o sistema.

  5. O servidor salva o sistema no banco.

  6. O servidor retorna o UUID em texto puro.

  7. O cliente salva esse UUID localmente no arquivo .uuid.

Resposta de sucesso:

550e8400-e29b-41d4-a716-446655440000

2. Validação do agente

Quando o cliente já possui um UUID salvo, ele pode validar esse UUID com o servidor.

Endpoint:

GET /api/client_auth

Fluxo:

  1. O cliente lê o UUID local.

  2. O cliente gera timestamp e HMAC.

  3. O cliente envia o UUID no header.

  4. O servidor valida:

    • timestamp;
    • HMAC;
    • formato do UUID;
    • existência do UUID no banco.

Se tudo estiver correto, o servidor responde 200 OK.


3. Ingestão de pacotes

Depois de capturar e processar pacotes, o cliente C envia os dados em lote para o servidor.

Endpoint:

POST /api/ingest

Fluxo:

  1. O cliente captura pacotes via raw socket.
  2. O cliente processa Ethernet, VLAN, IPv4, IPv6, TCP, UDP, ICMP e outros protocolos.
  3. O cliente monta estruturas internas de pacote.
  4. O cliente serializa os pacotes em JSON.
  5. O cliente calcula o Content-Length.
  6. O cliente gera timestamp e HMAC.
  7. O cliente envia o batch para o servidor.
  8. O servidor valida a requisição.
  9. O servidor associa os pacotes ao UUID enviado no header.
  10. 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"
    }
  ]
}

Autenticação

O servidor utiliza dois modelos de autenticação, cada um para um tipo de consumidor.


Autenticação do agente

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_compartilhada

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


Autenticação do usuário

Usuários do dashboard utilizam JWT.

Variável usada no servidor:

JWT_SECRET=chave_jwt

Fluxo:

  1. O usuário cria uma conta ou faz login.
  2. O servidor retorna um JWT em texto puro.
  3. O frontend salva o token.
  4. O frontend envia o token em rotas protegidas:
Authorization: Bearer <token>

Endpoints do agente

Registrar agente

GET /api/register

Usado 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>

Validar agente

GET /api/client_auth

Usado 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 OK

Enviar pacotes

POST /api/ingest

Usado 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 OK

Endpoints do usuário

Cadastro

POST /api/user/register

Body:

{
  "login": "usuario",
  "password": "senha"
}

Resposta de sucesso:

<jwt>

Login

POST /api/user/login

Body:

{
  "login": "usuario",
  "password": "senha"
}

Resposta de sucesso:

<jwt>

Vincular agente ao usuário

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.


Remover vínculo com agente

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.


Endpoints de métricas

Listar sistemas do usuário

GET /api/metrics/systems

Autenticação:

Authorization: Bearer <token>

Suporta paginação:

GET /api/metrics/systems?page=0&size=10

Resposta:

{
  "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
}

Listar pacotes de um sistema

GET /api/metrics/system/{uuid}/packets

Autenticação:

Authorization: Bearer <token>

Suporta paginação e ordenação:

GET /api/metrics/system/{uuid}/packets?page=0&size=50&sort=id,desc

Exemplo:

GET /api/metrics/system/550e8400-e29b-41d4-a716-446655440000/packets?page=0&size=50&sort=id,desc

Resposta:

{
  "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
}

Modelos principais

SystemEntity

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.

PacketEntity

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

UserEntity

Representa um usuário do dashboard.

Responsabilidades:

  • autenticação via login e senha;
  • vínculo com UUIDs de agentes;
  • acesso aos sistemas associados.

Frontend

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:

  1. Criar usuário.
  2. Fazer login.
  3. Vincular UUID de agente.
  4. Listar sistemas vinculados.
  5. Consultar pacotes de cada sistema.
  6. Visualizar métricas e gráficos.
  7. Filtrar pacotes.
  8. Atualizar dados automaticamente.

Fluxo do frontend

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

Servindo o frontend pelo Spring

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.


Rotas SPA

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.


Variáveis de ambiente

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_agente

Variáveis usadas pelo container da aplicação:

JWT_SECRET
WIRESENTINEL_SECRET
SPRING_DATASOURCE_URL
SPRING_DATASOURCE_USERNAME
SPRING_DATASOURCE_PASSWORD
TZ

Build e execução do servidor

Executar com Docker Compose

docker compose up -d --build

Ver logs da aplicação:

docker compose logs -f app

Ver logs do banco:

docker compose logs -f db

Parar os containers:

docker compose down

Buildar e subir o servidor:

docker compose up -d --build

Após isso, o dashboard estará disponível em:

http://localhost:8080

Ou pelo IP da máquina:

http://<ip-do-servidor>:8080

Segurança

O WireSentinel separa autenticação de agente e autenticação de usuário.

Agente

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.

Usuário

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.

Paginação e ordenação

As consultas de sistemas e pacotes usam paginação do Spring.

Exemplos:

GET /api/metrics/systems?page=0&size=10
GET /api/metrics/system/{uuid}/packets?page=0&size=50&sort=id,desc

Ordenações úteis:

id,desc
id,asc
timestamp,desc
timestamp,asc
tamanhoTotalPacote,desc
tamanhoTotalPacote,asc
portaDestino,asc
portaDestino,desc

Checklist operacional

Antes de executar o ambiente:

  1. Criar o arquivo .env.
  2. Definir JWT_SECRET.
  3. Definir WIRESENTINEL_SECRET.
  4. Confirmar que o compose.yaml expõe a porta 8080.
  5. Buildar o frontend.
  6. Copiar o frontend para src/main/resources/static.
  7. Buildar a imagem do servidor.
  8. Subir o ambiente com Docker Compose.
  9. Validar se o Spring iniciou na porta 8080.
  10. Validar se o PostgreSQL está saudável.
  11. Registrar um agente.
  12. Vincular o UUID do agente no dashboard.
  13. Consultar pacotes pelo frontend.

Resumo

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.

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages