Documentação SynexGuard

Referência técnica completa — configuração, API, guias de uso e arquitetura do sistema.

📋 Visão Geral

SynexGuard é uma plataforma completa de segurança e monitoramento para servidores Linux. O sistema é composto por três componentes:

• Agente Go — binário leve instalado em cada servidor, envia heartbeats (CPU, RAM, disco, logins SSH, eventos) a cada 30 segundos.
• Backend FastAPI — API REST em Python que recebe, processa, armazena dados e executa automações (auto-ban, alertas).
• Frontend React — SPA dashboard em React + TypeScript + Tailwind CSS com tema dark red/black.

🏗 Arquitetura

O fluxo de dados segue uma direção clara:

┌─────────────────────────────────────────────────────────────┐
│  Servidor Linux (N instâncias)                             │
│  ┌──────────────────────┐                                   │
│  │ 🛡 SynexGuard Agent   │  ← Go binary + systemd            │
│  │  • auth.log parser   │                                   │
│  │  • system metrics    │                                   │
│  │  • network stats     │                                   │
│  └─────────┬────────────┘                                   │
└────────────┼────────────────────────────────────────────────┘
             │ POST /api/v1/agents/heartbeat
             │ Header: X-Agent-Token: ng_xxxxx
             ▼
┌─────────────────────────────────────────────────────────────┐
│  Backend (FastAPI + Python)                                 │
│  ┌──────────────┐  ┌───────────────┐  ┌──────────────────┐ │
│  │  Routers     │  │ Automation    │  │   Data Store     │ │
│  │  (11 módulos)│→ │ Engine        │→ │   (in-memory)    │ │
│  └──────────────┘  └───────────────┘  └──────────────────┘ │
│  JWT Auth · Rate Limiting · Prometheus                      │
└─────────────────────────────┬───────────────────────────────┘
                              │ REST API + JWT Bearer
                              ▼
┌─────────────────────────────────────────────────────────────┐
│  Frontend (React + Vite + TypeScript)                       │
│  Dashboard · Servidores · Segurança · Métricas · Logs       │
│  Alertas · Automações · Forense · Tráfego · Admin           │
└─────────────────────────────────────────────────────────────┘

🔧 Stack Tecnológica

📦 Requisitos

Backend

• Python 3.12 ou superior
• pip (gerenciador de pacotes Python)

Frontend

• Node.js 18+ e npm 9+

Agente

• Servidor Linux (Ubuntu 20.04+, Debian 11+, CentOS 8+, etc.)
• systemd para gerenciamento do serviço
• Acesso a /var/log/auth.log (ou /var/log/secure)

⚙ Instalação do Backend

1. Clone e entre no diretório

# Clone o repositório
git clone https://github.com/seu-usuario/synexguard.git
cd nodeguard/backend

2. Crie um ambiente virtual (recomendado)

python -m venv venv
source venv/bin/activate  # Linux/Mac
venv\Scripts\activate     # Windows

3. Instale dependências

pip install -r requirements.txt

4. Configure variáveis de ambiente

# Crie o arquivo .env na pasta backend/
cp .env.example .env
# Edite com suas configurações (ver seção Variáveis de Ambiente)

5. Inicie o servidor

# Desenvolvimento (com auto-reload)
python -m uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

# Produção (com workers)
python -m uvicorn app.main:app --host 0.0.0.0 --port 8000 --workers 4

🖥 Instalação do Frontend

cd frontend
npm install
npm run dev       # Desenvolvimento — http://localhost:5173

Build para Produção

npm run build     # Gera pasta dist/

# Servir com Nginx:
server {
    listen 80;
    root /path/to/frontend/dist;
    location / { try_files $uri /index.html; }
    location /api/ { proxy_pass http://127.0.0.1:8000; }
}

🐳 Deploy com Docker

# Na raiz do projeto
docker compose up --build -d

# Ver logs
docker compose logs -f

# Parar
docker compose down

🛡 Instalação do Agente

O agente é instalado nos servidores Linux que você deseja monitorar. Primeiro, gere um token no painel.

One-liner (recomendado)

curl -fsSL https://synex-guard.io/install-agent.sh | bash -s -- \
  --token SEU_TOKEN_AQUI \
  --api-url http://seu-backend:8000

Verificar status

sudo systemctl status synexguard-agent
sudo journalctl -u synexguard-agent -f  # logs em tempo real

Reiniciar / Parar

sudo systemctl restart synexguard-agent
sudo systemctl stop synexguard-agent

Arquivo de configuração

# /etc/synexguard/agent.yaml
api_url: "http://seu-backend:8000"
token: "ng_xxxxxxxxxxxxxxxxxxxxxxxxxx"
heartbeat_interval: 30   # segundos
log_file: "/var/log/auth.log"

📝 Variáveis de Ambiente

Crie um arquivo .env na pasta backend/. Todas as variáveis são opcionais (possuem defaults).

Notificações (opcionais)

🔒 Autenticação

JWT (Usuários)

O sistema usa OAuth2 Bearer Token com JWT assinado via HS256. O payload do token contém:

{
  "sub": "user@email.com",
  "uid": 1,
  "role": "user",
  "nome": "João Silva",
  "exp": 1739540400
}

Hashing de Senhas

Algoritmo: PBKDF2-HMAC-SHA256 com 260.000 iterações e salt aleatório de 16 bytes (hex). Formato armazenado: salt$hex_digest.

Tokens de Agente

Formato: ng_ + 28 caracteres hex aleatórios. Enviados via header X-Agent-Token. Cada token é vinculado a um usuário específico.

Conta Superadmin

Email: admin@synex-guard.io
Senha: admin123

📢 Notificações

O sistema suporta notificações via múltiplos canais. Configure as variáveis de ambiente correspondentes:

• Discord — Preencha DISCORD_WEBHOOK_URL
• Slack — Preencha SLACK_WEBHOOK_URL
• Telegram — Preencha TELEGRAM_BOT_TOKEN e TELEGRAM_CHAT_ID
• Email (SMTP) — Preencha SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASS, SMTP_FROM

⚡ Automações

O motor de automações executa regras em tempo real a cada evento recebido. O sistema vem com 5 regras globais pré-configuradas:

Regras podem ser ativadas/desativadas pelo painel. Clientes também podem criar regras personalizadas via API.

Como funciona o brute-force detection

1. O agente parseia /var/log/auth.log e envia tentativas de login via heartbeat.
2. O backend registra cada tentativa e gera um evento ssh_login_failed.
3. O motor de automações verifica: se o IP teve ≥ 5 falhas em janela de 5 minutos → executa ban automático + alerta crítico.

🔑 API — Auth

Prefixo: /api/v1/auth

{
  "nome": "João Silva",
  "email": "joao@empresa.com",
  "password": "minhasenhaforte"
}

{
  "id": 2,
  "nome": "João Silva",
  "email": "joao@empresa.com",
  "role": "user",
  "avatar_url": null,
  "criado_em": "2026-02-13T14:00:00Z"
}

{
  "email": "joao@empresa.com",
  "password": "minhasenhaforte"
}

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "bearer"
}

{
  "id": 2,  "nome": "João Silva",  "email": "joao@empresa.com",
  "role": "user",  "avatar_url": null
}

{
  "nome": "João M. Silva",
  "email": "joao.novo@empresa.com",
  "avatar_url": "https://..."
}

{
  "current_password": "senhaatual",
  "new_password": "novaSenhaForte123"
}

📡 API — Agents

Prefixo: /api/v1/agents

X-Agent-Token: ng_a1b2c3d4e5f6...

{
  "hostname": "srv-prod-01",
  "ip_publico": "203.0.113.10",
  "os_info": "Ubuntu 22.04.3 LTS",
  "cpu": 32.5,
  "ram": 61.2,
  "disk": 49.8,
  "uptime": "45d 12h 30m",
  "conns": 120,
  "open_ports": [22, 80, 443, 3306],
  "interfaces": [
    { "name": "eth0", "bytes_in": 134217728, "bytes_out": 89128960,
      "packets_in": 142000, "packets_out": 98000, "status": "up" }
  ],
  "login_attempts": [
    { "user": "root", "ip": "203.0.113.14", "method": "SSH", "success": false }
  ],
  "events": [
    { "tipo": "port_scan", "severidade": "critical",
      "mensagem": "Port scan from 192.0.2.50", "origem_ip": "192.0.2.50" }
  ]
}

{
  "status": "ok",
  "server_id": 1,
  "events_processed": 1,
  "login_attempts_processed": 1
}

{ "items": [ { "id": 1, "hostname": "srv-prod-01", ... } ] }

🖥 API — Servers

Prefixo: /api/v1/servers

{
  "items": [{
    "id": 1, "hostname": "srv-prod-01", "ip_publico": "203.0.113.10",
    "os_info": "Ubuntu 22.04", "cpu": 32.5, "ram": 61.2, "disk": 49.8,
    "uptime": "45d 12h", "conns": 120, "open_ports": [22,80,443],
    "status": "online", "ultimo_heartbeat": "2026-02-13T14:23:00Z"
  }]
}

{
  "ataques_detectados": 12,
  "ips_banidos": 3,
  "servidores_online": 4,
  "servidores_total": 5,
  "alertas_ativos": 2,
  "cpu_medio": 29.3,
  "ram_medio": 57.1,
  "disco_medio": 45.8
}

📋 API — Events

Prefixo: /api/v1/events

{
  "items": [{
    "id": 42, "hostname": "srv-prod-01",
    "tipo": "ssh_login_failed", "severidade": "warning",
    "mensagem": "Failed login as 'root' from 203.0.113.14",
    "origem_ip": "203.0.113.14",
    "criado_em": "2026-02-13T14:23:01Z"
  }],
  "total": 42
}

🛡 API — Security

Prefixo: /api/v1/security

{
  "items": [{
    "id": 1, "hostname": "srv-prod-01",
    "user": "root", "origem_ip": "203.0.113.14",
    "method": "SSH", "success": false,
    "criado_em": "2026-02-13T14:23:01Z"
  }],
  "stats": {
    "total": 342,
    "blocked": 338,   // falhas
    "suspicious": 4  // sucesso como root/admin
  }
}

{
  "items": [{
    "id": 1, "ip": "203.0.113.14", "hostname": "srv-prod-01",
    "motivo": "SSH brute-force (5 tentativas)",
    "origem": "Automático", "expira": "24h", "ativo": true
  }]
}

{
  "servidor_id": 1,
  "ip": "192.0.2.100",
  "motivo": "Atividade suspeita",
  "origem": "Manual"
}

{ "unbanned": "192.0.2.100" }

📊 API — Metrics

Prefixo: /api/v1/metrics

{
  "items": [{
    "servidor_id": 1, "hostname": "srv-prod-01",
    "cpu": 32.5, "ram": 61.2, "disk": 49.8,
    "conns": 120, "open_ports": 4
  }]
}

🌐 API — Traffic

Prefixo: /api/v1/traffic

{
  "items": [{
    "hostname": "srv-prod-01", "interface": "eth0",
    "bytes_in": 134217728, "bytes_out": 89128960,
    "packets_in": 142000, "packets_out": 98000,
    "status": "up"
  }],
  "total_in": 134217728,
  "total_out": 89128960
}

🔔 API — Alerts

Prefixo: /api/v1/alerts

{
  "items": [{
    "id": 1, "hostname": "srv-prod-01",
    "titulo": "SSH Brute-Force detectado de 203.0.113.14",
    "severidade": "critical",
    "mensagem": "IP fez 5 tentativas em 5 min",
    "status": "ativo",
    "criado_em": "2026-02-13T14:22:49Z"
  }],
  "total": 1
}

{ "resolved": true }

⚡ API — Automations

Prefixo: /api/v1/automations

{
  "items": [{
    "id": 1, "nome": "SSH Brute-Force Auto Ban",
    "condicao": "ssh_login_failed >= 5 in 5min",
    "acao": "Banir IP por 24h",
    "ativo": true
  }]
}

{
  "nome": "My Custom Rule",
  "condicao": "ssh_login_failed >= 3 in 2min",
  "condicao_tipo": "ssh_login_failed",
  "condicao_threshold": 3,
  "acao": "Banir IP por 48h",
  "acao_type": "ban_ip",
  "acao_duration": "48h"
}

{ "toggled": true }

🔑 API — Tokens

Prefixo: /api/v1/tokens

[{
  "id": 1,
  "nome": "Servidor Produção",
  "descricao": "Token para srv-prod-01",
  "token": "ng_a1b2...d4e5",
  "ativo": true,
  "ultimo_uso": "2026-02-13T14:23:00Z",
  "criado_em": "2026-02-12T10:00:00Z",
  "install_command": "curl -sSL ... | sudo bash -s -- --token ng_..."
}]

{
  "nome": "Servidor Produção",
  "descricao": "Token para srv-prod-01"
}

👑 API — Admin

Prefixo: /api/v1/admin — Todos os endpoints requerem role superadmin.

{
  "total_users": 15,
  "active_users": 12,
  "inactive_users": 3,
  "total_tokens": 28,
  "active_tokens": 22
}

{ "ativo": false }

Tabela de Autenticação

👤 Guia do Cliente

1. Criar Conta

Acesse o painel (ex: http://localhost:5173/login) e clique em "Criar conta". Preencha nome, email e senha.

2. Fazer Login

Use email e senha. O sistema retorna um token JWT válido por 60 minutos (configurável).

3. Gerar Token de Agente

No menu lateral → 🔑 Tokens → "Novo Token". Dê um nome descritivo e copie o token/comando de instalação.

4. Instalar o Agente

Execute o one-liner no servidor Linux:

curl -fsSL https://synex-guard.io/install-agent.sh | bash -s -- --token SEU_TOKEN --api-url http://backend:8000

5. Verificar Conexão

Na seção 🖥 Servidores, seu servidor aparecerá como Online em ~30 segundos.

6. Navegar pelos Módulos

7. Configurações

Em ⚙ Configurações altere nome, email, avatar e senha da sua conta.

🔧 Guia do Administrador

1. Primeiro Acesso

Login com admin@synex-guard.io / admin123. Altere a senha em Configurações.

2. Painel Admin

O menu 👑 Admin (visível só para superadmins) permite:

• Ver estatísticas globais (usuários, tokens, servidores)
• Listar, ativar/desativar e excluir usuários
• Ver todos os tokens de agente do sistema
• Ver todos os servidores de todos os clientes

3. Deploy em Produção

1. Configure JWT_SECRET com valor forte e único.
2. Use --workers 4 no uvicorn para múltiplos workers.
3. Coloque um reverse proxy (Nginx/Caddy) na frente.
4. Use HTTPS (Let's Encrypt) para o domínio público.
5. Faça build do frontend (npm run build) e sirva via Nginx.

4. Checklist de Segurança

5. Monitoramento do Agente

# Status do serviço
sudo systemctl status node-guardian-agent

# Logs em tempo real
sudo journalctl -u node-guardian-agent -f

# Reiniciar
sudo systemctl restart synexguard-agent

🐛 Troubleshooting

O servidor não aparece como Online

• Verifique se o agente está rodando: systemctl status synexguard-agent
• Verifique se o token é válido e ativo no painel
• Verifique conectividade: curl -v http://backend:8000/health
• Verifique logs do agente: journalctl -u synexguard-agent -f

Erro 401 no heartbeat

• Token inválido ou revogado — gere um novo no painel
• Header X-Agent-Token não está sendo enviado

Erro 403 ao fazer login

• Conta desativada pelo administrador — contacte o admin

Frontend não carrega dados

• Verifique se o backend está rodando: curl http://localhost:8000/health
• Verifique o proxy do Vite em vite.config.ts
• Abra o DevTools (F12) → Network para ver erros de API

Automações não disparam

• Verifique se a regra está ativa no painel de Automações
• Para brute-force: são necessários ≥ 5 falhas em 5 minutos do mesmo IP
• Verifique se o agente está enviando login_attempts no heartbeat

Métricas aparecem zeradas

• O agente precisa enviar pelo menos 1 heartbeat com dados de CPU/RAM/disco
• Dados aparecem somente para servidores com status online