# NGINX Pathfinder Proxy - Documentação Técnica

## Visão Geral

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). |

---

## 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 (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
└── docker-compose.yml   # Orquestração
```

---

## Módulos Especiais

### 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`

### 2. ModSecurity (WAF)
Rodar o WAF em container separado (`modsecurity`) evita a necessidade de compilar o ModSecurity no NGINX principal.

**Arquitetura Customizada:**
- **Injeção de Template**: Um arquivo `modsec.conf.template` local é montado durante o boot para contornar limitações de permissão do container oficial. Ele instrui o NGINX a carregar regras customizadas.
- **Regras Modulares**: Localizadas em `modsec_rules/`, divididas por aplicação (`gitea-rule-exceptions.conf`, `nextcloud...`).
- **Global**: `global-exceptions.conf` define apenas a whitelist de rede.
- **Bypass de Emergência**: Se o WAF falhar, altere as portas no `docker-compose.yml` para expor o `nginx-proxy` diretamente.

---

## Fluxo de Deploy Atualizado

```mermaid
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
```

---

## Comandos Operacionais

**Verificar status dos serviços:**
```bash
docker compose ps
```

**Verificar validade dos SSL (Log):**
```bash
docker compose logs nginx-proxy | grep "SSL"
```

**Forçar renovação SSL manualmente:**
```bash
docker compose exec nginx-proxy /scripts/renew_ssl.sh
```

**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.