Skip to content
BranchesTags

Latest commit

 

History

112 Commits

Folders and files

NameName
Last commit message
Last commit date
.github/workflows
.github/workflows
 
 
backend-python
backend-python
 
 
frontend
frontend
 
 
.gitignore
.gitignore
 
 
CONTRIBUTING.md
CONTRIBUTING.md
 
 
README.md
README.md
 
 
docker-compose.yml
docker-compose.yml
 
 

Repository files navigation

🛰️ OrbNOC

OrbNOC Banner

Enterprise Network Operations Center Platform

Monitoramento de infraestrutura, disponibilidade e desempenho em tempo real

Version Status Next.js Python FastAPI PostgreSQL License

🖥️ Projeto configurado para rodar 100% localmente

📋 Índice

  • Sobre
  • Principais Recursos
  • Screenshots
  • Arquitetura
  • Stack Tecnológica
  • Estrutura do Projeto
  • Rodando Localmente
  • Variáveis de Ambiente
  • Roadmap
  • Contribuição
  • Licença

📖 Sobre o Projeto

O OrbNOC é uma plataforma moderna de Network Operations Center (NOC) desenvolvida para monitoramento contínuo de infraestrutura de rede, servidores e serviços críticos.

Projetado para provedores de internet, equipes de operações, MSPs e administradores de sistemas, o OrbNOC fornece uma visão centralizada da saúde operacional do ambiente através de dashboards em tempo real, alertas inteligentes e ferramentas avançadas de diagnóstico.

O backend é escrito em Python (FastAPI). O contrato da API REST e o protocolo WebSocket (Socket.IO) são compatíveis com o socket.io-client usado pelo frontend em Next.js.

Principais Benefícios

✅ Monitoramento em tempo real ✅ Alertas automatizados ✅ Diagnóstico integrado ✅ Dashboard operacional moderno ✅ Wallboard para NOC ✅ Arquitetura escalável

✨ Principais Recursos

📡 Monitoramento

  • Disponibilidade de Hosts (ICMP + fallback TCP)
  • Monitoramento de Portas
  • Latência
  • Jitter
  • Packet Loss
  • SLA
  • Uptime

🔔 Sistema de Alertas

  • Alertas em tempo real
  • Integração Telegram
  • Histórico de incidentes
  • Reconhecimento de alertas
  • Escalonamento de criticidade

📊 Dashboard Operacional

  • KPIs em tempo real
  • Gráficos interativos
  • Filtros avançados
  • Busca instantânea
  • Ordenação dinâmica
  • Atualização via WebSocket

🗺️ Topologia de Rede

  • React Flow
  • Layout Hierárquico
  • Layout Radial
  • Layout Grid
  • Status visual dos dispositivos
  • Links animados

🔧 Ferramentas de Diagnóstico

  • Ping Avançado
  • Traceroute
  • DNS Lookup (com reverse lookup via registro PTR)
  • TCP Port Scanner
  • Diagnóstico Inteligente

📺 Wallboard

  • Modo TV
  • Atualização automática
  • Visualização otimizada para NOC
  • Exibição de incidentes críticos

📸 Screenshots

Dashboard Principal

Dashboard

Centro de Alertas

Alerts

Mapa de Rede

Topology

🏗️ Arquitetura

graph TD

A[Browser] --> B[Next.js Frontend]

B --> C[Socket.IO]
B --> D[REST API]

C --> E[Python Backend / FastAPI]
D --> E

E --> F[(PostgreSQL)]

E --> G[Monitor Engine]
E --> H[Alert Engine]

G --> I[TCP / ICMP Checks]
G --> J[Latency Monitoring]

H --> K[Telegram]
Loading

⚙️ Stack Tecnológica

Frontend

  • Next.js 14
  • React 18
  • TypeScript
  • Tailwind CSS
  • Recharts
  • React Flow
  • Socket.IO Client

Backend

  • Python 3.12
  • FastAPI
  • asyncpg (driver PostgreSQL assíncrono)
  • python-socketio
  • PyJWT + bcrypt
  • httpx (alertas Telegram)
  • dnspython (diagnóstico DNS)

Banco de Dados

  • PostgreSQL

Infraestrutura

  • Docker / Docker Compose (local)

📂 Estrutura do Projeto

OrbNOC/
├── backend-python/       # Backend em Python (FastAPI + Socket.IO)
│   ├── app/
│   │   ├── app.py             # Criação da app FastAPI (CORS, rotas, logger)
│   │   ├── config.py          # Variáveis de ambiente
│   │   ├── database.py        # Pool asyncpg, criação de tabelas, seed do admin
│   │   ├── security.py        # Hash de senha + JWT
│   │   ├── auth_dependency.py # Dependência de autenticação das rotas
│   │   ├── sockets.py          # Servidor Socket.IO
│   │   ├── routes/             # auth, devices, alerts, diagnostic, public
│   │   └── services/           # ping, dns, telegram, monitor
│   ├── server.py               # Entrypoint (uvicorn + loop de monitoramento)
│   ├── requirements.txt
│   ├── .env.example
│   └── Dockerfile
├── frontend/               # Next.js
│   └── .env.example
├── docker-compose.yml
└── README.md

🚀 Rodando Localmente

Pré-requisitos

  • Docker Desktop instalado e rodando (para a Opção 1)
  • Ou, para rodar sem Docker: Python 3.11+, Node.js 20+ e PostgreSQL instalados localmente

Opção 1 — Docker Compose (recomendado, sobe tudo com 1 comando)

Sobe o PostgreSQL, o backend e o frontend juntos, já configurados para se falarem via localhost. As tabelas do banco e um usuário de demonstração são criados automaticamente na primeira inicialização.

docker compose up --build

Acesse:

Login de demonstração (criado automaticamente):

usuário: admin
senha:   admin123

Para parar:

docker compose down

Para parar e apagar os dados do banco (útil se algo ficou inconsistente e você quer recomeçar do zero):

docker compose down -v

Problemas comuns

Sintoma Causa provável Solução
Conflict. The container name "/orbnoc-db" is already in use Sobrou container de uma execução anterior docker compose down e rode up --build de novo
Erro 500 ao logar / relation "..." does not exist nos logs Backend subiu antes do Postgres estar pronto Já tratado via healthcheck + retry automático; se persistir, rode docker compose down -v para recriar o banco do zero
Falha ao baixar imagens (no such host, registry-1.docker.io) Problema de DNS/rede do Docker Desktop Reinicie o Docker Desktop, ou configure DNS manual (8.8.8.8 / 1.1.1.1) em Settings → Docker Engine

Opção 2 — Rodando manualmente (sem Docker)

Backend

cd backend-python
python3 -m venv .venv
source .venv/bin/activate      # Windows: .venv\Scripts\activate
pip install -r requirements.txt
cp .env.example .env
# edite .env e ajuste DATABASE_URL para o seu PostgreSQL local
python server.py

Requer Python 3.11+ e o comando ping disponível no sistema (no Linux, pacote iputils-ping; no Windows/macOS já vem instalado por padrão).

Frontend

cd frontend
npm install
npm run dev

Por padrão o frontend já aponta para http://localhost:3001 (backend local), sem precisar configurar nada — mas se quiser ser explícito:

cd frontend
cp .env.example .env.local

🔧 Variáveis de Ambiente (backend-python)

Variável Padrão Descrição
PORT 3001 Porta HTTP do backend
ENVIRONMENT development Use production para ativar as travas de segurança de produção (ver abaixo)
JWT_SECRET (valor de dev, trocar em produção) Segredo usado para assinar os tokens JWT. Obrigatório e sem valor padrão aceito quando ENVIRONMENT=production — o backend recusa subir se detectar o segredo de desenvolvimento em produção.
DATABASE_URL — String de conexão PostgreSQL (postgresql://user:pass@host:5432/db)
DATABASE_SSL false true para exigir SSL (bancos remotos)
FRONTEND_URL http://localhost:3000 Origem liberada no CORS (HTTP e WebSocket)
EXTRA_CORS_ORIGINS — Origens extras liberadas no CORS, separadas por vírgula
MONITOR_INTERVAL_MS 10000 Intervalo entre varreduras de monitoramento
LOGIN_RATE_LIMIT 5/minute Limite de tentativas de login por IP
REGISTER_RATE_LIMIT 3/minute Limite de registros por IP

🔒 Segurança

  • CORS é restrito à(s) origem(ns) definidas em FRONTEND_URL/EXTRA_CORS_ORIGINS — nunca reflete qualquer origem.
  • JWT_SECRET: o backend recusa iniciar em produção (ENVIRONMENT=production) se detectar o segredo de desenvolvimento. Gere um valor próprio, por exemplo com python3 -c "import secrets; print(secrets.token_urlsafe(48))".
  • Rate limiting em /api/auth/login e /api/auth/register (configurável via env vars acima).
  • RBAC: usuários com role = 'admin' têm acesso a /api/admin/* (listar usuários, ver logs de acesso, remover usuários). O usuário demo admin/admin123 já nasce com essa role — troque a senha em produção.
  • Vulnerabilidades conhecidas do frontend (npm audit): a biblioteca xlsx (SheetJS) tem CVEs sem correção publicada no momento (prototype pollution / ReDoS). Se a exportação para Excel não for essencial, considere substituí-la por uma alternativa mantida (ex: exceljs) ou mover a geração para o backend.

🧪 Testes e Lint

cd backend-python
pip install -r requirements-dev.txt
pytest -v          # 39 testes: security, ping/traceroute services, rotas (RBAC etc.)
ruff check .        # lint
cd frontend
npm run lint
npm run build

O workflow .github/workflows/ci.yml roda automaticamente ambos em cada push/PR para main, além de validar que as imagens Docker buildam.

☁️ Deploy em Produção

Checklist mínimo antes de subir o OrbNOC fora do ambiente local:

  1. Defina ENVIRONMENT=production e um JWT_SECRET forte e único (o backend recusa subir sem isso).
  2. Configure FRONTEND_URL com o domínio real do frontend (HTTPS) — não use * nem deixe o padrão de localhost.
  3. Coloque um reverse proxy com TLS na frente (Nginx, Caddy ou o load balancer do seu provedor) — nem o backend Python nem o Next.js standalone servem HTTPS diretamente.
  4. PostgreSQL gerenciado ou com backup automatizado: ative DATABASE_SSL=true se o provedor exigir, e configure backups/retenção — o schema é criado automaticamente no primeiro boot (create_tables), mas isso não substitui backup dos dados.
  5. Troque a senha do usuário demo (admin/admin123) criado no seed inicial, ou remova o seed em produção.
  6. Rotação de logs: o backend loga em stdout; em produção, capture isso com o driver de log do seu orquestrador (Docker/K8s) ou um agregador (ex: Loki, CloudWatch).
  7. Monitore o próprio monitor: como o loop de monitoramento roda dentro do processo do backend, rodar múltiplas réplicas duplica as leituras e os alertas — mantenha uma única instância do backend responsável pelo loop, ou externalize-o para um worker dedicado antes de escalar horizontalmente.

🛣️ Roadmap

  • Dashboard Operacional
  • Alertas Telegram
  • Topologia de Rede
  • Diagnóstico Integrado (traceroute real via SO)
  • Wallboard
  • Backend em Python (FastAPI)
  • Testes automatizados + CI (GitHub Actions)
  • Rate limiting, RBAC e CORS restrito
  • Histórico de métricas (série temporal por dispositivo)

Próximas Funcionalidades

  • Multi-Tenant
  • SNMP Monitoring
  • NetFlow
  • Syslog Server
  • Mobile App
  • Dark/Light Themes
  • Notificações por e-mail e webhook genérico (hoje só Telegram está implementado, embora o schema já tenha email_alerts_enabled)
  • Gráfico de uptime/latência histórico no frontend consumindo GET /api/devices/{id}/history

🤝 Contribuição

Contribuições são bem-vindas. Veja o CONTRIBUTING.md para o passo a passo (setup, testes, padrão de commits e PRs).

📄 Licença

Distribuído sob a licença MIT.

Desenvolvido por Adan William

Network Monitoring • NOC • Observability • Infrastructure

About

O OrbNOC é uma plataforma moderna de Network Operations Center (NOC) desenvolvida para monitoramento contínuo de infraestrutura de rede, servidores e serviços críticos.

Resources

Readme

Contributing

Contributing
Activity

Stars

2 stars

Watchers

0 watching

Forks

1 fork
Report repository

Releases

Packages

Contributors

Languages