188 lines
9.2 KiB
Markdown
188 lines
9.2 KiB
Markdown
# 🛡️ Nginx Pathfinder Proxy
|
|
|
|
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).
|
|
|
|
---
|
|
|
|
## 🏗️ Estrutura de Pastas e Componentes
|
|
|
|
A configuração é modular para permitir manutenção rápida e alta disponibilidade.
|
|
|
|
- `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, Headers).
|
|
- `modsec/`: Configuração do ModSecurity, regras **OWASP CRS v4** e tunings específicos.
|
|
- `dynamic/`: Arquivos modificados em tempo real (ex: `blacklist.conf` pelo Fail2Ban).
|
|
- `scripts/`: Scripts de utilidade (Ex: `install_modsecurity.sh`).
|
|
|
|
---
|
|
|
|
## 🧩 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 e ofuscação de tecnologia de backend (`Server`, `X-Powered-By`).
|
|
3. `include snippets/security_headers.conf;`: **Headers de 2026** (COOP, COEP, CORP) para proteção de isolamento do navegador.
|
|
4. `include snippets/modsecurity.conf;`: Ativa o WAF e a Blacklist dinâmica.
|
|
5. `include snippets/security_actions.conf;`: Toma a decisão final de bloquear (`444`) se o motor PSDE detectar risco alto.
|
|
6. `include snippets/cache_optimizer.conf;`: Otimiza a entrega de estáticos com cache inteligente (SWR).
|
|
|
|
### 📚 Catálogo Completo de Snippets
|
|
|
|
Abaixo, a lista completa de componentes modulares disponíveis em `nginx/snippets/`:
|
|
|
|
#### 🔒 Segurança & WAF
|
|
- **`modsecurity.conf`**: Ativa o WAF (OWASP CRS v4) e carrega a blacklist.
|
|
- **`security_headers.conf`**: Headers de borda 2026 (COOP, COEP, CORP, Permissions-Policy).
|
|
- **`security_actions.conf`**: Executa o bloqueio (Return 444) baseado no score do PSDE.
|
|
- **`security_maps.conf`**: Motor de decisão (PSDE), detecção de bots, scorings e variáveis de risco.
|
|
- **`blacklist.conf`**: Lista dinâmica de IPs banidos (gerenciado pelo Fail2Ban).
|
|
- **`ads_disallow.conf`**: Bloqueia acesso a `ads.txt`.
|
|
- **`robots_disallow.conf`**: Bloqueia indexação total (para ambientes de homologação/privados).
|
|
- **`robots_allow.conf`**: Permite indexação total.
|
|
|
|
#### 🚀 Performance & Cache
|
|
- **`cache_optimizer.conf`**: Otimização fina de SWR (Stale-While-Revalidate) e headers de cache.
|
|
- **`cache_proxy_params.conf`**: Configurações padrão de lock e validade de cache para upstream.
|
|
- **`cache_zones.conf`**: Definição das zonas de memória compartilhada e chaves de cache.
|
|
- **`compression.conf`**: Stack de compressão moderna (Brotli + Gzip) com níveis otimizados.
|
|
- **`fingerprinting.conf`**: Cache imutável (1 ano) para assets versionados com hash no nome.
|
|
|
|
#### 🚦 Controle de Tráfego
|
|
- **`rate_limit.conf`**: Zonas de limitação de requisições (Global vs Punição por Score).
|
|
- **`bandwidth_limit.conf`**: Limita a velocidade de download após X MB transferidos.
|
|
- **`proxy_params.conf`**: Headers de encaminhamento (Real-IP, Forwarded) e ofuscação de backend.
|
|
- **`ssl_params.conf`**: Configuração TLS 1.3, HSTS e HTTP/3 (QUIC).
|
|
- **`acme_challenge.conf`**: Endpoint para renovação de certificados SSL (Certbot).
|
|
|
|
#### 📊 Monitoramento & Identidade
|
|
- **`log_formats.conf`**: Define o formato JSON `detailed_proxy` rico em metadados de segurança.
|
|
- **`stub_status.conf`**: Endpoint de métricas internas do Nginx (para Zabbix/Prometheus).
|
|
- **`humans.txt.conf`**: Rota para arquivos de créditos técnicos.
|
|
- **`security.txt.conf`**: Rota padrão (RFC 9116) para reporte de segurança.
|
|
- **`well_known.conf`**: Agregador que inclui robots, humans e security.txt de uma vez.
|
|
|
|
---
|
|
|
|
## 🛡️ Camada de WAF (ModSecurity 3.0.14)
|
|
|
|
O Pathfinder Proxy utiliza o **ModSecurity v3** compilado sob medida para o Nginx Mainline.
|
|
|
|
- **Versão Nginx**: 1.29.5 Mainline (Oficial).
|
|
- **Versão ModSec**: 3.0.14.
|
|
- **Regras**: OWASP Core Rule Set (CRS) v4 (Instalação Minimalista).
|
|
- **Anti-Brute Force**: Proteção integrada contra força bruta em páginas de login via ModSecurity Collections (Phase 1).
|
|
- **API Support**: Métodos **PUT, PATCH e DELETE** liberados por padrão para suporte a sistemas modernos.
|
|
- **Tuning**: Arquivo `modsec/app_specific_modsec_tuning.conf` centraliza exceções granulares (Zabbix, Gitea, UniFi, Veeam).
|
|
|
|
---
|
|
|
|
## 🧠 Motor de Segurança PSDE "Elite" (7-Vector Matrix)
|
|
|
|
Diferente de firewalls comuns, o Pathfinder utiliza uma **Matriz de Pontuação Combinatória** no `security_maps.conf` que analisa 7 vetores simultâneos:
|
|
|
|
1. **🛡️ Bot:** Bloqueio de 600+ user-agents maliciosos.
|
|
2. **🌐 URI:** Acesso a arquivos sensíveis e assinaturas de CVEs recentes.
|
|
3. **⚙️ Method:** Métodos HTTP perigosos (TRACE, DEBUG) em rotas críticas.
|
|
4. **🔥 Payload:** Inspeção profunda de `$args` (SQLi, XSS, RCE, Log4j).
|
|
5. **🌍 Geo:** Risco por país (CN, RU, KP, IR) via **GeoIP2**.
|
|
6. **🚦 Protocol:** Violações como User-Agents vazios ou falsificados.
|
|
7. **🔗 Referer:** 400+ domínios de spam e phishing bloqueados instantaneamente.
|
|
|
|
### 📈 Lógica de Decisão
|
|
- **Nivel 3 (ATAQUE_CRITICO)**: Payloads maliciosos, Referer Spam ou qualquer combinação de 3+ vetores.
|
|
- **Nivel 2 (RISCO_ALTO)**: Combinação de 2 vetores de risco (ex: Bot + Geo-Risco).
|
|
- **Nivel 1 (SUSPEITO)**: Detecção de sinais individuais.
|
|
|
|
---
|
|
|
|
## 🛠️ Workflow Operacional: Ativando um Novo Site
|
|
|
|
Siga este procedimento para colocar um novo sistema no ar com segurança máxima:
|
|
|
|
### 1. Preparação no Repositório (Local)
|
|
1. Crie o arquivo `nginx/conf.d/nome-do-site.conf` seguindo o **Padrão Ouro**.
|
|
2. **Atenção:** Aponte os caminhos de certificado para `/etc/letsencrypt/live/nome-do-site/`.
|
|
3. Faça o commit e push para a branch `producao`.
|
|
|
|
### 2. Sincronização no Servidor (SSH)
|
|
1. Entre no servidor e vá para o diretório de scripts: `cd /etc/nginx/scripts/`.
|
|
2. Execute o deploy seguro: `sudo python3 deploy_pathfinder.py`.
|
|
- **Nota:** Este script faz backup automático e rollback se a configuração estiver errada.
|
|
|
|
---
|
|
|
|
## 🛠️ Automação de Deploy (Pathfinder Automator V2 - Hybrid)
|
|
|
|
O Pathfinder conta com o orquestrador `scripts/deploy_pathfinder.py`, que agora funciona em modo **Híbrido (Windows Client -> Linux Server)**. Você roda o script na sua máquina local e ele faz todo o trabalho sujo.
|
|
|
|
### Pré-requisitos
|
|
- Python 3 instalado no Windows.
|
|
- Biblioteca Paramiko: `pip install paramiko`
|
|
|
|
### Comandos Principais
|
|
- **`python producao/scripts/deploy_pathfinder.py sync --all`**:
|
|
- Empacota suas configs locais.
|
|
- Conecta no servidor via SSH.
|
|
- Atualiza bancos GeoIP automaticamente.
|
|
- Sincroniza configurações e recarrega o Nginx.
|
|
- **Faz Rollback Automático** se o `nginx -t` falhar.
|
|
|
|
- **`python producao/scripts/deploy_pathfinder.py site --deploy <domínio>`**:
|
|
- Sobe um novo VHost + Certificado SSL + Teste de DNS.
|
|
|
|
- **`python producao/scripts/deploy_pathfinder.py geoip --update`**:
|
|
- Força a atualização dos bancos de dados GeoIP2 (Mirror GitHub).
|
|
|
|
### 🛡️ Segurança de Operação
|
|
- **Backup & Rollback Atômico**: Cada alteração gera um `.bak`. Se `nginx -t` falhar, o script desfaz a alteração imediatamente.
|
|
- **Auditoria Syslog**: Todas as ações são registradas no syslog do servidor.
|
|
- **Validação Local**: O script retorna `Exit Code 1` no Windows se falhar no Linux, ideal para CI/CD.
|
|
- **DNS Safeguard**: O deploy de SSL só ocorre se o DNS já estiver apontando para o IP do servidor, evitando bloqueios no Let's Encrypt.
|
|
|
|
---
|
|
|
|
## 🔐 Gestão de SSL (Let's Encrypt)
|
|
|
|
O Pathfinder Proxy usa o desafio **HTTP-01** via snippet `acme_challenge.conf`. Isso permite emitir certificados sem parar o Nginx.
|
|
|
|
### Emissão do Primeiro Certificado
|
|
Rode os comandos abaixo (substitua o domínio):
|
|
|
|
1. **Criar pasta de desafios (se não existir):**
|
|
```bash
|
|
sudo mkdir -p /var/lib/letsencrypt && sudo chown www-data:www-data /var/lib/letsencrypt
|
|
```
|
|
|
|
2. **Gerar o certificado:**
|
|
```bash
|
|
sudo certbot certonly --webroot -w /var/lib/letsencrypt/ -d meusite.com.br -d www.meusite.com.br
|
|
```
|
|
|
|
> [!TIP]
|
|
> **Atenção aos Caminhos:** Se o Certbot gerar uma pasta com final `-0001`, certifique-se de que o arquivo `.conf` do seu site em `/etc/nginx/conf.d/` aponta para o caminho exato gerado por ele. Você pode conferir os caminhos ativos com `sudo certbot certificates`.
|
|
|
|
---
|
|
|
|
## 🚀 Manutenção e Logs
|
|
|
|
### Recompilar WAF e Performance (Se necessário)
|
|
Se o Nginx for atualizado ou se precisar habilitar o Brotli, o módulo precisará ser recompilado usando o script:
|
|
`sudo ./scripts/setup_pathfinder.sh`
|
|
|
|
### Validação
|
|
Sempre teste a configuração antes do reload:
|
|
```bash
|
|
sudo nginx -t
|
|
sudo systemctl reload nginx
|
|
```
|
|
|
|
### Auditoria e Diagnósticos
|
|
O Pathfinder agora reporta a **razão exata** do bloqueio nos logs JSON:
|
|
`tail -f /var/log/nginx/access_json.log | jq -r '"[\(.risk_category)] -> \(.risk_reason) | \(.request)"'`
|
|
|
|
- **`risk_category`**: TAG curta para máquinas (LIMPO, SUSPEITO, RISCO_ALTO, ATAQUE_CRITICO).
|
|
- **`risk_reason`**: Motivo humano detalhado (ex: "COMBINACAO: Bot conhecido em local sensivel").
|
|
|
|
--- |