From 058d1a22ddd3a10b907a8f494d7ce3f5c127b3e5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jo=C3=A3o=20Pedro?= Date: Thu, 22 Jan 2026 13:22:58 -0300 Subject: [PATCH] docs: Update README.md (pt-BR) and Tech Specs --- .gemini/GEMINI.md | 237 ++++++++++++++++++---------------------------- README.md | 148 +++++++++++++++++++++++------ 2 files changed, 208 insertions(+), 177 deletions(-) diff --git a/.gemini/GEMINI.md b/.gemini/GEMINI.md index 8f1bbf0..18d6b97 100644 --- a/.gemini/GEMINI.md +++ b/.gemini/GEMINI.md @@ -1,177 +1,122 @@ -# NGINX Pathfinder Proxy - Documentação da Estrutura +# NGINX Pathfinder Proxy - Documentação Técnica ## Visão Geral -Este projeto é um proxy reverso NGINX containerizado com suporte a: -- **HTTP/3 (QUIC)** - Protocolo moderno para melhor performance -- **Brotli** - Compressão avançada para menor uso de banda -- **High Availability** - Restart automático e cache stale -- **Validação Automática** - Verificação de DNS e SSL no startup +Projeto de infraestrutura para Proxy Reverso de Alta Disponibilidade, utilizando Containers Docker para modularidade e fácil manutenção. + +## Arquitetura de Containers + +O projeto roda sobre 3 serviços orquestrados via `docker-compose.yml`: + +| Serviço | Imagem | Porta Exposta | Função | +|---------|--------|---------------|--------| +| **modsecurity** | `owasp/modsecurity-crs:nginx-alpine` | `80`, `443` | **Frontend (WAF)**. Recebe todo o tráfego da internet, filtra ataques (SQLi, XSS) e encaminha requisições limpas para o Proxy. | +| **nginx-proxy** | `alpine` (Custom Build) | `8080` (Interna) | **Backend Proxy**. Gerencia vhosts, terminação SSL, cache, compressão Brotli e roteamento para as aplicações finais. | +| **fail2ban** | `crazymax/fail2ban` | - | **Watchdog**. Lê logs compartilhados dos dois containers acima e bane IPs maliciosos diretamente no host (via iptables). | --- -## Estrutura de Pastas +## Automação SSL + +O sistema possui um mecanismo de **auto-cura** para certificados SSL. + +### Componentes +1. **Certbot**: Instalado dentro do container `nginx-proxy`. +2. **Volumes**: + - `ssl/`: Onde ficam os arquivos `.crt` e `.key` usados pelo NGINX. + - `certbot/`: Onde o Certbot guarda os arquivos originais do Let's Encrypt. +3. **Scripts**: + - `scripts/inject_acme.sh`: Varre todos os arquivos em `conf.d/` e injeta o snippet de validação ACME (`.well-known`) se não existir. + - `scripts/renew_ssl.sh`: + 1. Verifica a data de expiração de cada certificado ativo. + 2. Se faltar **3 dias ou menos**, dispara `certbot renew`. + 3. Copia os novos arquivos gerados para a pasta `ssl/`. + 4. Recarrega o NGINX. + +### Agendamento +- **Cron**: Configurado no `pre-flight.sh` para rodar todos os dias às **01:00 AM**. +- **Startup**: A verificação também roda a cada reinício do container. + +--- + +## Estrutura de Arquivos ``` . -├── conf.d/ # Configurações de sites (carregadas automaticamente) -├── snippets/ # Trechos reutilizáveis de configuração -├── scripts/ # Scripts auxiliares (pre-flight.sh) -├── ssl/ # Certificados SSL/TLS -├── legacy/ # Arquivos antigos do servidor original +├── conf.d/ # Configurações de sites (VHosts) +├── snippets/ # Trechos reutilizáveis +│ ├── acme_challenge.conf # Snippet para validação Let's Encrypt +│ ├── internal_networks.conf # IPs permitidos (VPN/Local) +│ └── ... +├── scripts/ # Scripts de automação +│ ├── pre-flight.sh # Entrypoint (DNS Check + Cron Setup) +│ ├── inject_acme.sh # Injetor de config ACME +│ └── renew_ssl.sh # Lógica de renovação +├── ssl/ # Certificados em uso +├── fail2ban/ # Configs do Fail2ban +│ ├── jail.d/ # Definição das prisões +│ └── filter.d/ # Regex de detecção ├── .gemini/ # Documentação do projeto -├── Dockerfile # Build customizado do NGINX -├── docker-compose.yml # Orquestração do container -├── nginx.conf # Configuração principal do NGINX -└── deploy.sh # Script de deploy automatizado +└── docker-compose.yml # Orquestração ``` --- -## Arquivos Principais +## Módulos Especiais -### `Dockerfile` -Constrói uma imagem NGINX customizada baseada em Alpine Linux com: -- Módulo Brotli (compressão) -- Módulo headers_more (manipulação de headers) -- Ferramentas de diagnóstico (dig, openssl, curl) +### 1. Brotli & Headers More +O container `nginx-proxy` é construído manualmente (`Dockerfile`) para incluir módulos que não vêm por padrão no Alpine: +- `nginx-mod-http-brotli` +- `nginx-mod-http-headers-more` -### `docker-compose.yml` -Orquestra o container com: -- **Portas**: 80 (HTTP), 443 (HTTPS), 443/udp (HTTP/3) -- **Volumes**: conf.d, ssl, snippets, cache, logs -- **Restart**: always (alta disponibilidade) -- **Variável**: HOST_PUBLIC_IP (injetada pelo deploy.sh) - -### `nginx.conf` -Configuração principal que: -- Carrega os módulos (Brotli, headers_more) -- Inclui snippets do `/etc/nginx/snippets/` -- Inclui sites do `/etc/nginx/conf.d/` - -### `deploy.sh` -Script de deploy que: -1. Detecta o IP público do servidor -2. Grava no `.env` -3. Build da imagem Docker -4. Testa configuração com `nginx -t` -5. Inicia o container +### 2. ModSecurity (WAF) +Rodar o WAF em container separado (`modsecurity`) evita a necessidade de compilar o ModSecurity no NGINX principal, facilitando atualizações e isolando falhas. Se o WAF falhar, o Proxy pode ser exposto diretamente mudando as portas no `docker-compose.yml` (Bypass de emergência). --- -## Pasta `snippets/` - -Contém configurações reutilizáveis incluídas no `nginx.conf`: - -| Arquivo | Função | -|---------|--------| -| `rate_limit.conf` | Define zonas de rate limiting | -| `security_maps.conf` | Maps para detecção de bots e IPs internos | -| `log_formats.conf` | Formato JSON detalhado para logs | -| `cache_zones.conf` | Define todas as zonas de cache | -| `custom_errors.conf` | Páginas de erro customizadas | - ---- - -## Pasta `conf.d/` - -Contém configurações individuais de cada site/sistema. Cada arquivo `.conf` representa um virtual host. - -**Padrão de nomenclatura**: `dominio.conf` (ex: `itguys.com.br.conf`) - -**Estrutura típica de um site**: -```nginx -upstream nome_backend { - server IP:PORTA; -} - -server { - listen 80; - server_name dominio.com; - return 301 https://$host$request_uri; -} - -server { - listen 443 ssl; - http2 on; - server_name dominio.com; - - ssl_certificate /etc/letsencrypt/live/dominio.com/fullchain.pem; - ssl_certificate_key /etc/letsencrypt/live/dominio.com/privkey.pem; - - proxy_cache STATIC; - proxy_cache_use_stale error timeout; - - location / { - proxy_pass http://nome_backend; - } -} -``` - ---- - -## Pasta `scripts/` - -### `pre-flight.sh` -Script executado ANTES do NGINX iniciar. Valida: -- Se `HOST_PUBLIC_IP` está definida -- Se os domínios configurados apontam para o IP correto -- Logs de warning se houver inconsistências - ---- - -## Pasta `legacy/` - -Contém arquivos do servidor original (synced via proxy-sinc). **Não são usados diretamente** - servem como referência. - ---- - -## Fluxo de Deploy +## Fluxo de Deploy Atualizado ```mermaid -graph LR - A[deploy.sh] --> B[Detecta IP] - B --> C[Gera .env] - C --> D[Docker Build] - D --> E[nginx -t] - E --> F[Docker Up] - F --> G[pre-flight.sh] - G --> H[NGINX Start] +graph TD + Start[Deploy] --> DetectIP[Detectar IP Público] + DetectIP --> Build[Docker Build (NGINX + Certbot)] + Build --> Up[Docker Compose Up] + Up --> PreFlight[Pre-Flight Script] + + PreFlight --> DNSCheck[Validar DNS dos Domínios] + DNSCheck --> CronSetup[Configurar Cron Job] + CronSetup --> SSLCheck[Verificar Validade SSL] + + SSLCheck -- Vence > 3 dias --> StartNginx[Iniciar NGINX] + SSLCheck -- Vence <= 3 dias --> Renew[Rodar renew_ssl.sh] + Renew --> StartNginx ``` --- -## Variáveis de Ambiente - -| Variável | Descrição | -|----------|-----------| -| `HOST_PUBLIC_IP` | IP público do servidor (detectado automaticamente) | - ---- - -## Comandos Úteis +## Comandos Operacionais +**Verificar status dos serviços:** ```bash -# Deploy completo -./deploy.sh - -# Rebuild após alterações -docker compose build && docker compose up -d - -# Testar configuração -docker compose run --rm nginx-proxy nginx -t - -# Ver logs -docker compose logs -f - -# Recarregar configuração sem restart -docker compose exec nginx-proxy nginx -s reload +docker compose ps ``` ---- +**Verificar validade dos SSL (Log):** +```bash +docker compose logs nginx-proxy | grep "SSL" +``` -## Notas Importantes +**Forçar renovação SSL manualmente:** +```bash +docker compose exec nginx-proxy /scripts/renew_ssl.sh +``` -1. **SSL**: Os certificados devem estar em `/etc/letsencrypt/` no host ou montados via volume -2. **ModSecurity**: Alguns sites usam WAF que requer módulo adicional (não incluído por padrão) -3. **HTTP/2**: O formato antigo `listen 443 ssl http2` está deprecated, usar `http2 on;` separado +**Banir um IP manualmente:** +```bash +docker compose exec fail2ban fail2ban-client set nginx-badbots banip 1.2.3.4 +``` + +**Adicionar novo site:** +1. Criar `conf.d/novo-site.conf` +2. `docker compose restart nginx-proxy` +3. O script de startup irá validar o DNS e injetar o suporte ACME automaticamente. diff --git a/README.md b/README.md index 0e3858a..ffad67e 100644 --- a/README.md +++ b/README.md @@ -1,61 +1,147 @@ -# Serviço de Sincronização de Configurações - Proxy-Sinc +# NGINX Pathfinder Proxy -Este repositório contém as configurações e os scripts de automação para o serviço `proxy-sinc`, desenhado para automatizar o controlo de versões de ficheiros de configuração de servidores Linux para um repositório Git (Gitea). +Solução moderna de Proxy Reverso containerizado, construída com NGINX, ModSecurity WAF e automação de SSL. -O objetivo é criar um sistema robusto, auto-documentado e fácil de gerir para o backup e o histórico de alterações de configurações críticas como as do Nginx e do Fail2ban. +## 🚀 Funcionalidades -## Funcionalidades Principais Implementadas pelo Instalador +### 🛡️ Segurança em Primeiro Lugar +- **ModSecurity WAF**: Conjunto de Regras OWASP (CRS) integrado rodando como proxy sidecar/frontend. +- **Fail2ban**: Serviço "cão de guarda" que bane IPs com comportamento suspeito (bots ruins, excesso de erros 4xx/5xx). +- **Mapas de Segurança**: Bloqueio automatizado de User-Agents maliciosos e restrições de rede interna. -### Gestão de Dependências +### ⚡ Performance +- **HTTP/3 (QUIC)**: Habilitado para conexões modernas de baixa latência. +- **Compressão Brotli**: Melhores taxas de compressão que o Gzip padrão. +- **Headers More**: Manipulação avançada de cabeçalhos para respostas limpas. -* Verifica e instala automaticamente as dependências necessárias (`git`, `rsync`) usando `apt`. +### 🔒 SSL Automatizado +- **Renovação Zero-Touch**: O Certbot integrado verifica a validade diariamente. +- **Auto-Renovação**: Renova automaticamente certificados próximos do vencimento (<= 3 dias). +- **Injeção Inteligente**: Injeta automaticamente os snippets de desafio ACME nas configurações dos sites. -### Configuração Interativa e Segura +--- -* Pede ao utilizador a URL do repositório, o nome de utilizador do Gitea e um Token de Acesso (que fica oculto durante a digitação) para a autenticação. +## 🛠️ Como Trabalhar neste Repositório -* A URL do repositório é reconfigurada para incluir as credenciais, permitindo que as operações `git` futuras (como o `git push`) sejam executadas de forma não-interativa. +### Pré-requisitos +- Docker & Docker Compose instalados +- Acesso à internet (para baixar imagens e validar SSL) -### Identidade de Commit Automática +### 1. Implantar o Servidor (Deploy) +Para iniciar toda a infraestrutura: +```bash +./deploy.sh +``` +*Este script detecta seu IP público, configura o ambiente e sobe os containers.* -* O nome do autor dos commits é automaticamente definido como o hostname completo do servidor (ex: `srvproxy001.itguys.com.br`). +### 2. Adicionar um Novo Site +Todas as configurações de sites ficam na pasta `conf.d/`. -* O email do autor é gerado automaticamente a partir do hostname (ex: `srvproxy001@itguys.com.br`). +1. **Crie o arquivo de configuração**: + Crie um arquivo `.conf` em `conf.d/` (ex: `meusite.com.br.conf`). Use um dos arquivos existentes como modelo. + + **Modelo Básico (com SSL):** + ```nginx + # Backend (para onde vai o tráfego) + upstream meu_backend { + server 192.168.1.10:8080; + } -### Gestão Inteligente de SSL + # Redirecionamento HTTP -> HTTPS + server { + listen 80; + server_name meusite.com.br; + include /etc/nginx/snippets/acme_challenge.conf; # Importante para SSL + return 301 https://$host$request_uri; + } -* O script testa automaticamente a conexão com o Gitea. Se detetar um problema de certificado SSL (comum em ambientes internos), ele configura o repositório local para ignorar a verificação SSL, garantindo que a sincronização funcione. + # Bloco HTTPS + server { + listen 443 ssl; + http2 on; + server_name meusite.com.br; -### Registo de Deploy + ssl_certificate /etc/nginx/ssl/meusite.com.br.crt; + ssl_certificate_key /etc/nginx/ssl/meusite.com.br.key; -* Na primeira instalação num novo servidor, o script cria um ficheiro de registo (`_deployment_logs/hostname.md`) no repositório, documentando quem (utilizador do Gitea) instalou o serviço e quando, criando uma trilha de auditoria. + include /etc/nginx/snippets/ssl_params.conf; -### Instalação como Serviço `systemd` + location / { + proxy_pass http://meu_backend; + include /etc/nginx/includes/proxy_backend.conf; + } + } + ``` -* Gera e instala um serviço `systemd` (`proxy-sinc.service`) e um `timer` (`proxy-sinc.timer`). +2. **Aplique as alterações**: + ```bash + docker compose restart nginx-proxy + ``` + *No reinício, o script de pre-flight validará o DNS e injetará configurações de SSL necessárias.* -* Esta abordagem é superior ao `cron` pois integra-se perfeitamente com o sistema de logs `journald`, permitindo uma gestão fácil com `systemctl status`, `start`, `stop`, etc. +### 3. Modificar Configurações Globais +As configurações globais são modularizadas na pasta `snippets/`. -* O timer está configurado para executar o script de sincronização **a cada minuto**. +- **Rate Limiting**: Edite `snippets/rate_limit.conf` para ajustar os limites de requisições por segundo. +- **Bloqueio de Bots**: Edite `snippets/security_maps.conf` para adicionar novos User-Agents à lista negra. +- **Cache**: Edite `snippets/cache_zones.conf` para definir novas zonas ou tempos de cache. -### Sincronização Dinâmica de Ficheiros +### 4. Gerenciar Certificados SSL +O sistema gerencia isso automaticamente, mas você pode intervir manualmente se necessário. -* O script principal de sincronização (`commit_configs.sh`) agora lê os caminhos a serem versionados a partir de um ficheiro de configuração central (`/etc/proxy-sinc/paths.conf`). +- **Verificar Validade**: + Verifique os logs do startup para ver o status de todos os domínios: + ```bash + docker compose logs nginx-proxy | grep "SSL" + ``` -* Isto permite que os administradores adicionem ou removam ficheiros e pastas para sincronização no futuro, simplesmente editando este ficheiro de texto, sem precisar de alterar o script. +- **Forçar Renovação**: + Se precisar renovar um certificado imediatamente: + ```bash + docker compose exec nginx-proxy /scripts/renew_ssl.sh + ``` -### Auto-Versionamento +### 5. Monitorar e Debugar -* O script `commit_configs.sh` foi desenhado para se incluir a si mesmo e a todos os seus ficheiros de configuração e de serviço (`.service`, `.timer`, `man page`, `paths.conf`) no repositório Git. Desta forma, qualquer alteração na própria automação também é versionada. +- **Verificar Status dos Containers**: + ```bash + docker compose ps + ``` -### Funcionalidade de Auto-Atualização +- **Ver Logs em Tempo Real**: + ```bash + docker compose logs -f + ``` -* Instala um novo comando no sistema, `proxy-sinc-update`. +- **Verificar se o WAF (ModSecurity) bloqueou algo**: + ```bash + docker compose logs modsecurity | grep "Access denied" + ``` -* Quando executado, este comando baixa a versão mais recente do `setup.sh` a partir de uma URL pré-definida no repositório Gitea e executa-a, permitindo uma atualização fácil e centralizada de toda a automação. +- **Verificar Banimentos do Fail2ban**: + ```bash + docker compose exec fail2ban fail2ban-client status nginx-badbots + ``` -### Documentação Integrada (`man page`) +--- -* Gera e instala uma página de manual (`man proxy-sinc`) no sistema. +## 🏗️ Visão Geral da Stack -* O manual explica o que o serviço faz, como o gerir, como o atualizar e, o mais importante, como adicionar novos caminhos de ficheiros para serem sincronizados, tornando a ferramenta fácil de usar para qualquer membro da equipa no futuro. \ No newline at end of file +```mermaid +graph LR + Internet((Internet)) --> WAF[Container ModSecurity] + WAF -- Tráfego Limpo --> Proxy[Container NGINX Proxy] + Proxy --> Backend1[App 1] + Proxy --> Backend2[App 2] + + Logs[Logs Compartilhados] + WAF -.-> Logs + Proxy -.-> Logs + + F2B[Container Fail2ban] + F2B -- Lê --> Logs + F2B -- Bane IP --> WAF +``` + +--- +*Mantido por IT Guys* \ No newline at end of file