# 🛡️ 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 automação e diagnóstico (`deploy_pathfinder.py`, `restore_nginx.py`, `fetch_logs.py`).

---

## 🧩 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" (8-Vector Matrix)

Diferente de firewalls comuns, o Pathfinder utiliza uma **Matriz de Pontuação Combinatória** no `security_maps.conf` que analisa 8 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.
8.  **🤯 Header:** Detecção de anomalias em cabeçalhos customizados (ex: React2Shell CVE-2025-55182).

### 📈 Lógica de Decisão
- **Nivel 3 (ATAQUE_CRITICO)**: Payloads maliciosos, Referer Spam, Headers Corrompidos ou 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").

---