DockProbe
Painel leve de monitoramento Docker com detecção de anomalias e alertas Telegram
Um contêiner. Um comando. Visibilidade total.
English | 한국어 | 日本語 | Deutsch | Français | Español | Português | Italiano
---
## O que é o DockProbe?
DockProbe é um painel de monitoramento Docker auto-hospedado que roda como um único contêiner. Ele coleta em tempo real métricas de CPU, memória, rede e disco de todos os seus contêineres e da máquina host — e exibe tudo em uma interface web limpa com tema escuro.
**O monitoramento de host com suporte a GPU** rastreia a temperatura e utilização de GPUs NVIDIA junto com o uso de CPU, memória do host, pressão de disco e média de carga — tudo em gráficos em tempo real. Se você executa cargas de trabalho de ML ou contêineres intensivos em GPU, o DockProbe oferece visibilidade completa sem instalar ferramentas de monitoramento GPU separadas.
Quando algo dá errado, o DockProbe detecta automaticamente. Seis regras integradas de detecção de anomalias monitoram picos de CPU, estouro de memória, alertas de temperatura, pressão de disco, reinicializações inesperadas e surtos de rede. Cada alerta inclui **ações recomendadas com comandos prontos para execução** — para que você saiba exatamente o que fazer, não apenas o que deu errado. Os alertas são enviados instantaneamente via Telegram para que você possa reagir antes que os usuários percebam.
Um scanner de segurança integrado executa 16 verificações automatizadas a cada 5 minutos — cobrindo erros de configuração de contêineres, exposição de rede e hardening do host — para detectar vulnerabilidades antes que se tornem incidentes.
Não há agente para instalar em cada contêiner, nem banco de dados externo, nem configuração complexa. Basta montar o socket do Docker, executar um comando, e você terá visibilidade completa do seu ambiente Docker em `https://localhost:9090`. Precisa acessar de fora da sua rede? O suporte integrado ao Cloudflare Tunnel oferece HTTPS público seguro sem redirecionamento de portas.
---
## Início rápido
```bash
git clone https://github.com/deep-on/dockprobe.git && cd dockprobe && bash install.sh
```
É só isso. O instalador interativo configura a autenticação, alertas Telegram e HTTPS — depois abre `https://localhost:9090`.
> **Requisitos:** Docker (com Compose v2), Git, OpenSSL
---
## Executar a partir do Docker Hub
Sem git clone, sem build — basta fazer pull e executar:
```bash
# 1. Baixar o arquivo Compose e o modelo de variáveis de ambiente
curl -fsSL https://raw.githubusercontent.com/deep-on/dockprobe/main/docker-compose.hub.yaml -o docker-compose.yaml
curl -fsSL https://raw.githubusercontent.com/deep-on/dockprobe/main/.env.example -o .env
# 2. Editar .env com suas credenciais
vi .env
# 3. (Opcional) Gerar certificado SSL autoassinado
mkdir -p certs && openssl req -x509 -newkey rsa:4096 -nodes \
-keyout certs/key.pem -out certs/cert.pem \
-days 825 -subj "/CN=dockprobe"
# 4. Iniciar
docker compose up -d
```
> **Disponível no Docker Hub:** [`deeponinc/dockprobe`](https://hub.docker.com/r/deeponinc/dockprobe) — Multi-arch (amd64 + arm64)
---
## Pré-visualização do painel
---
## Funcionalidades
| Categoria | O que você obtém |
|-----------|-----------------|
| **Painel em tempo real** | Interface web escura, atualização automática a cada 10s, tabelas ordenáveis, gráficos Chart.js |
| **Monitoramento de contêineres** | CPU %, memória %, E/S de rede, E/S de bloco, contador de reinícios |
| **Monitoramento do host** | Temperatura e utilização CPU/GPU, memória, uso de disco, média de carga |
| **Detecção de anomalias** | 6 regras com ações recomendadas — pico de CPU, estouro de memória, alta temperatura, disco cheio, reinício, pico de rede |
| **Alertas Telegram** | Notificação instantânea com cooldown de 30 min por tipo de alerta |
| **Segurança** | Basic Auth, limitação de taxa (5 falhas = 60s de bloqueio), HTTPS |
| **Scanner de segurança** | 16 verificações automatizadas (contêiner/host/rede), ciclo de varredura de 5 min, badges de severidade |
| **Gestão de sessões** | Rastreamento de conexões ativas, máx. conexões configurável, exibição de IP ao vivo |
| **Gestão de senhas** | Alterar usuário/senha pela interface do painel |
| **Interface de configurações** | Ajustar máx. conexões em tempo de execução pelo painel |
| **Modos de acesso** | SSL autoassinado (padrão) ou Cloudflare Tunnel (sem redirecionamento de portas) |
| **Leve** | 4 pacotes Python, arquivo HTML único, SQLite com retenção de 7 dias |
---
## Composição do painel
| Seção | Detalhes |
|-------|---------|
| Barra de sessão | Usuário conectado, IP, conexões ativas / limite máximo |
| Cartões do host | Temp CPU, temp GPU, CPU/GPU %, memória do host, disco %, média de carga |
| Tabela de contêineres | Ordenável por CPU/memória/rede, anomalias com código de cores |
| Gráficos (5) | Tendências de CPU e memória dos contêineres, CPU/GPU % do host, temperatura e carga do host |
| Disco Docker | Imagens, cache de build, volumes, camadas RW dos contêineres |
| Histórico de alertas | Últimas 24h com timestamps |
---
## Regras de detecção de anomalias
| Regra | Condição | Ação |
|-------|----------|------|
| CPU do contêiner | >80% por 3 verificações consecutivas (30s) | Telegram + destaque vermelho |
| Memória do contêiner | >90% do limite | Alerta imediato |
| Temperatura CPU do host | >85°C | Alerta imediato |
| Disco do host | >90% de uso | Alerta imediato |
| Reinício do contêiner | restart_count incrementado | Alerta imediato |
| Pico de rede | RX aumento de 10x + >100MB | Alerta imediato |
Todos os limites são configuráveis via variáveis de ambiente.
Cada anomalia inclui **recomendações acionáveis** com comandos específicos:
| Anomalia | Exemplo de recomendação |
|----------|------------------------|
| Pico de CPU | `docker stats ` · `docker restart ` · `docker update --cpus=2 ` |
| Estouro de memória | `docker stats ` · `docker update --memory=2g ` |
| Loop de reinício | `docker logs --tail 50 ` · `docker inspect ` |
| Pico de rede | `docker logs --tail 50 ` · Verificar DDoS ou tráfego inesperado |
| Alta temperatura | Verificar ventilador/sistema de refrigeração · `sensors -u` para detalhes |
| Disco cheio | `docker system prune -f` · `docker builder prune -f` · `docker volume prune` |
---
## Scanner de segurança
O DockProbe executa 16 verificações de segurança automatizadas a cada 5 minutos e exibe os resultados em uma seção dedicada do painel com badges de severidade.
| Categoria | Verificações |
|-----------|-------------|
| **Contêiner** (9) | Modo privilegiado, execução como root, capabilities perigosas, montagem do socket Docker, montagem de caminhos sensíveis, rootfs somente leitura, AppArmor/Seccomp desabilitados, segredos em variáveis de ambiente, sem limites de memória/CPU |
| **Rede** (3) | Modo de rede do host, exposição excessiva de portas, exposição da porta SSH (22) |
| **Host** (4) | Opções de segurança do daemon Docker, ASLR do kernel, encaminhamento de IP, estado do Linux Security Module |
**Níveis de severidade:**
- 🔴 **Crítico** — Ação imediata necessária (ex.: modo privilegiado, socket Docker com escrita)
- 🟡 **Aviso** — Melhoria de segurança recomendada
- 🔵 **Info** — Descobertas informativas
- 🟣 **Indisponível** — A verificação não pode ser executada devido a restrições do ambiente; mostra como habilitá-la
> As verificações a nível de host requerem montagens de volume (`/proc:/host_proc:ro`, `/sys:/host_sys:ro`). Se não montados, essas verificações são exibidas como **Indisponível** com instruções de configuração.
---
## Arquitetura
```
┌──────────────────────────────────────────────┐
│ DockProbe Container │
│ │
│ FastAPI + uvicorn (porta 9090) │
│ ├── collectors/ │
│ │ ├── containers.py (aiodocker) │
│ │ ├── host.py (/proc, /sys, GPU) │
│ │ └── images.py (system df) │
│ ├── alerting/ │
│ │ ├── detector.py (6 regras + ações) │
│ │ └── telegram.py (httpx) │
│ ├── security/ │
│ │ └── scanner.py (16 checks) │
│ ├── storage/ │
│ │ └── db.py (SQLite WAL) │
│ └── static/ │
│ └── index.html (Chart.js) │
│ │
│ Volumes: │
│ docker.sock (ro), /sys (ro), /proc (ro), │
│ nvidia-smi (ro), SQLite named volume │
└──────────────────────────────────────────────┘
```
**Dependências (apenas 4 pacotes):**
- `fastapi` — Framework web
- `uvicorn` — Servidor ASGI
- `aiodocker` — Cliente Docker API assíncrono
- `httpx` — Cliente HTTP assíncrono (API Telegram)
---
## Configuração
Todas as configurações via arquivo `.env`:
```env
# Autenticação (obrigatório)
AUTH_USER=admin
AUTH_PASS=your-password
# Alertas Telegram (opcional)
TELEGRAM_BOT_TOKEN=your-bot-token
TELEGRAM_CHAT_ID=your-chat-id
# Limites (opcional, valores padrão exibidos)
# CPU_THRESHOLD: sem definir, escala com a máquina (80 × núcleos; 100% = um núcleo)
MEM_THRESHOLD=90
# Limite de conexões (opcional, 0 = ilimitado)
MAX_CONNECTIONS=3
# Cloudflare Tunnel (opcional)
CF_TUNNEL_TOKEN=your-tunnel-token
```
---
## Modos de acesso
### Opção 1: Rede local (SSL autoassinado) — padrão
```bash
bash install.sh # escolher opção 1
```
Acesso via `https://localhost:9090` ou `https://:9090`
Para acessar de outros dispositivos na mesma rede, use o IP LAN do servidor (ex: `https://192.168.1.100:9090`). Se necessário:
- Liberar a porta no firewall: `sudo ufw allow 9090/tcp`
- Aceitar o aviso de certificado autoassinado no navegador
> **Por que o aviso do navegador?** O DockProbe usa um certificado SSL autoassinado gerado durante a instalação. Como não foi emitido por uma Autoridade Certificadora (CA) confiável, o navegador exibe um aviso "Sua conexão não é particular". Isso é normal — clique em "Avançado" → "Prosseguir para o site". Para eliminar este aviso, use o Cloudflare Tunnel (Opção 3) que fornece automaticamente um certificado TLS confiável.
### Opção 2: Acesso remoto por redirecionamento de portas
Para acesso externo sem Cloudflare:
1. Redirecionar a porta 9090 no roteador para o IP LAN do servidor
2. Acessar via `https://:9090`
3. Usar um serviço DDNS (No-IP, DuckDNS, etc.) se seu IP público mudar
> **Nota:** A porta fica diretamente exposta. Basic Auth + HTTPS estão ativados por padrão, mas recomenda-se o Cloudflare Tunnel (Opção 3) para maior segurança.
### Opção 3: Cloudflare Tunnel (recomendado para acesso remoto)
Sem redirecionamento de portas, sem alterações no firewall, certificado TLS válido — a forma mais fácil e segura de acessar de qualquer lugar.
```bash
bash install.sh # escolher opção 2, colar token do túnel
```
**Passos de configuração:**
1. Criar uma conta gratuita no [Cloudflare Zero Trust](https://one.dash.cloudflare.com)
2. Ir em **Networks** > **Tunnels** > **Create a tunnel**
3. Nomear o túnel (ex: `dockprobe`) e copiar o token
4. Executar `bash install.sh` e escolher a opção Cloudflare Tunnel
5. Colar o token
6. No painel do Cloudflare, adicionar um **Public Hostname** apontando para `http://localhost:9090`
7. Acessar via `https://your-domain.com` com certificado TLS válido
---
## Endpoints da API
| Endpoint | Método | Descrição |
|----------|--------|-----------|
| `/` | GET | HTML do painel |
| `/api/current` | GET | Último snapshot (contêineres + host + imagens + anomalias) |
| `/api/history/{name}?hours=1` | GET | Séries temporais dos contêineres |
| `/api/history/host?hours=1` | GET | Séries temporais do host |
| `/api/alerts?hours=24` | GET | Histórico de alertas |
| `/api/session` | GET | Usuário atual, IP, conexões ativas |
| `/api/settings` | GET/POST | Configurações em tempo de execução (max_connections) |
| `/api/change-password` | POST | Alterar usuário/senha |
| `/api/health` | GET | Verificação de saúde (sem autenticação) |
---
## Segurança
DockProbe é projetado para auto-hospedagem segura com múltiplas camadas de proteção:
**Autenticação e acesso**
- **Basic Auth** em todos os endpoints (exceto `/api/health`)
- **PBKDF2-SHA256** hash de senha com sal aleatório (600k iterações)
- **Limitação de taxa** — 5 tentativas de login falhas → 60s de bloqueio por IP
- **Mínimo de 8 caracteres** exigidos para a senha
- **Limite de conexões** — Máximo de usuários simultâneos configurável
**Rede e transporte**
- **HTTPS** — RSA-4096 autoassinado (padrão) ou Cloudflare Tunnel
- **CORS** — Requisições de origem cruzada bloqueadas explicitamente
- **Proteção CSRF** — Endpoints POST exigem o cabeçalho `X-Requested-With`
- **Aviso de fallback HTTP** — Modo texto claro avisa na inicialização (apenas túnel)
**Fortalecimento do contêiner**
- **Não root** — O contêiner executa como `appuser`, não como root
- **Montagens somente leitura** — Docker socket, /sys, /proc todos montados em read-only
- **Proteção contra travessia de caminho** — O serviço de arquivos estáticos valida os caminhos resolvidos
- **Sem acesso de escrita** — Apenas monitoramento, sem controle de contêineres
- **Sem OpenAPI/Swagger** — Endpoints de documentação da API desativados em produção
**Limitação de taxa com reconhecimento de proxy**
- `X-Forwarded-For` só é confiável a partir de IPs listados na variável de ambiente `TRUSTED_PROXIES`
- Conexões diretas sempre usam o IP real do cliente
---
## Configuração manual
Se preferir a configuração manual:
```bash
git clone https://github.com/deep-on/dockprobe.git
cd dockprobe
# Criar .env
cp .env.example .env
vi .env
# Gerar certificado SSL (opcional)
mkdir -p certs
openssl req -x509 -newkey rsa:2048 -nodes \
-keyout certs/key.pem -out certs/cert.pem \
-days 365 -subj "/CN=dockprobe"
# Iniciar
docker compose up -d --build
```
---
## Licença
Apache License 2.0 — ver [LICENSE](LICENSE)
**Atribuição:** Versões modificadas ou redistribuídas devem manter o logo DeepOn e o aviso "Powered by DeepOn Inc." na interface.
---
Desenvolvido por DeepOn Inc.