From 326a3711f0979cdf022591fcfd928e7129f64c68 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jo=C3=A3o=20Pedro=20Toledo?= Date: Fri, 6 Feb 2026 18:05:39 -0300 Subject: [PATCH] =?UTF-8?q?docs:=20atualiza=20README.md=20com=20guias=20de?= =?UTF-8?q?=20instala=C3=A7=C3=A3o=20nativa=20e=20padr=C3=B5es=20ouro?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 146 +++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 101 insertions(+), 45 deletions(-) diff --git a/README.md b/README.md index cd68513..d134955 100644 --- a/README.md +++ b/README.md @@ -1,54 +1,110 @@ -# Nginx Pathfinder Proxy - Repositório de Configuração +# 🛡️ Nginx Pathfinder Proxy -Este repositório é a fonte da verdade para as configurações do **Pathfinder Proxy**. Ele armazena as definições de domínios, segurança e parâmetros do Nginx e Fail2Ban. +Este repositório é o núcleo de inteligência e configuração do **Pathfinder Proxy**, instalado nativamente em **Ubuntu 24.04**. Ele combina performance extrema (HTTP/3, Brotli) com um motor de segurança multicamadas (PSDE + WAF + Fail2Ban). -> [!IMPORTANT] -> **Repositório de Configuração (Config Management):** -> Este repositório **NÃO** gerencia a execução do Docker, build de imagens ou certificados SSL. Ele serve apenas para versionar os arquivos `.conf` que serão baixados no servidor. +--- -## 🧠 O que este repositório armazena: -* **Gerenciamento de Sites:** Definição de VHosts em `nginx/conf.d/`. -* **Snippets Reutilizáveis:** Componentes modulares (SSL, Proxy, WAF) em `nginx/snippets/`. -* **Segurança Dinâmica:** Estrutura para `blacklist.conf` (alimentada externamente). -* **Fail2Ban:** Regras de jails e filters customizados em `fail2ban/`. +## 🏗️ Estrutura de Pastas e Componentes -## 📂 Estrutura de Pastas -```text -. -├── nginx/ -│ ├── nginx.conf # Configuração mestre (Global) -│ ├── conf.d/ # Arquivos de site (Ex: ferreirareal.com.br.conf) -│ ├── snippets/ # Peças modulares (SSL, ModSec, Proxy, Blacklist) -│ ├── dynamic/ # Configurações dinâmicas (Blacklist - gerado pelo Fail2Ban) -│ └── modsec/ # Regras do WAF -└── fail2ban/ # Configurações do sidecar de segurança -``` +A configuração é modular para permitir manutenção rápida e alta disponibilidade. -## 🛠️ Como Adicionar um Site -1. Crie o arquivo em `nginx/conf.d/meusite.conf`. -2. Utilize os snippets para manter o padrão e segurança: +- `nginx.conf`: O "cérebro" global. Configura workers, logs JSON e carrega os módulos dinâmicos. +- `conf.d/`: Contém as definições de cada site (**VHosts**). +- `snippets/`: Componentes reutilizáveis (SSL, Proxy, Cache, WAF). +- `modsec/`: Configuração do ModSecurity e regras do **OWASP Core Rule Set**. +- `dynamic/`: Arquivos modificados em tempo real (ex: `blacklist.conf` pelo Fail2Ban). + +--- + +## 🧩 Guia de Snippets (Uso Obrigatório) + +Para garantir o **Padrão Ouro**, todo site deve incluir os snippets básicos: + +1. `include snippets/ssl_params.conf;`: Ativa TLS 1.3, HSTS e anuncia **HTTP/3 (QUIC)**. +2. `include snippets/proxy_params.conf;`: Headers padrão para o backend não perder o IP real do cliente. +3. `include snippets/modsecurity.conf;`: Ativa o WAF e a Blacklist dinâmica. +4. `include snippets/security_actions.conf;`: Toma a decisão final de bloquear (`444`) se o motor PSDE detectar risco alto. +5. `include snippets/cache_optimizer.conf;`: Otimiza a entrega de estáticos com cache inteligente. + +--- + +## 🧠 Motor de Segurança PSDE (Pathfinder Security Engine) + +Diferente de firewalls comuns, o Pathfinder usa o `security_maps.conf` para calcular um **Security Score** em tempo real baseado em: +- **Bad Bots:** Crawlers maliciosos e ferramentas de scan. +- **Suspicious URIs:** Tentativas de acesso a `.env`, `wp-admin`, `.git`, etc. +- **Methods:** Bloqueio de métodos HTTP incomuns em rotas sensíveis. +- **Risk Level:** Traduz o score em níveis (Limpo, Suspeito, Crítico) para os logs JSON. + +--- + +## 🏆 Padrões Ouro de Configuração + +### 1. Servidor de Arquivos (Performance & Caching) +Focado em minimizar uso de CPU e maximizar I/O. ```nginx -server { - listen 443 quic reuseport; # Suporte a HTTP/3 - listen 443 ssl; - server_name meusite.com.br; - - # Certificados (Gerenciados no Servidor/Portainer) - ssl_certificate /etc/letsencrypt/live/meusite.com.br/fullchain.pem; - ssl_certificate_key /etc/letsencrypt/live/meusite.com.br/privkey.pem; - - include snippets/ssl_params.conf; - include snippets/proxy_params.conf; - include snippets/modsecurity.conf; - - location / { - proxy_pass http://ip_interno:porta; - } +location /files/ { + sendfile on; + tcp_nopush on; + aio on; + directio 512; + include snippets/cache_optimizer.conf; + proxy_cache_valid 200 30d; # Cache longo + add_header Content-Disposition "attachment"; # Força download } ``` -3. Commit e Push para a branch `producao`. -4. No servidor (Portainer/Docker), faça o Pull das alterações. -## ⚙️ Notas Operacionais -* **Logs e SSL:** As pastas `logs`, `ssl` e `certbot` não são versionadas aqui para segurança. Elas existem apenas no servidor. -* **Fail2Ban:** O Fail2Ban lê os logs do Nginx e escreve bloqueios em `nginx/dynamic/blacklist.conf`. \ No newline at end of file +### 2. Streaming de Vídeo (Continuidade & Buffer) +Evita travamentos e economiza banda com suporte a *Range Requests*. +```nginx +location /stream/ { + proxy_pass http://backend; + proxy_set_header Range $http_range; + proxy_set_header If-Range $http_if_range; + proxy_cache_key "$host$request_uri$http_range"; + + # Tuning de Buffer para vídeo + proxy_buffers 32 16k; + proxy_buffer_size 64k; + proxy_read_timeout 300s; +} +``` + +### 3. API Pesada / Traccar (Real-time & WebSocket) +Focado em manter conexões persistentes e rate limiting agressivo. +```nginx +location /api/ { + proxy_pass http://backend; + + # Suporte a WebSocket (Vital para Traccar/Mobile) + proxy_http_version 1.1; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection "upgrade"; + + # Rate Limit Estreito para APIs + limit_req zone=global_limit burst=20 nodelay; + + # Timeouts curtos para liberar recursos + proxy_connect_timeout 5s; + proxy_send_timeout 30s; + proxy_read_timeout 30s; +} +``` + +--- + +## 🚀 Como Operar + +### Sincronização +As alterações feitas aqui devem ser enviadas para a branch `producao`. No servidor, a sincronização é feita via `git pull` na pasta `/etc/nginx`. + +### Validação +Sempre teste a configuração antes do reload: +```bash +sudo nginx -t +sudo systemctl reload nginx +``` + +### Logs +Para auditoria de segurança, use o log JSON: +`tail -f /var/log/nginx/access_json.log | jq` (necessário instalar o `jq`)