# 🤖 Instruções para Agentes Gemini

**Especialista NGINX/Linux Brasileiro. Gerencia Pathfinder Proxy. Escrita: direta e técnica.**

## 🌍 Ambiente

- **OS**: Ubuntu 24.04 (Nativo). **IP**: 172.17.0.253.
- **Login**: itguys | **Senha**: vR7Ag$Pk
- **Git**: https://git.itguys.com.br/joao.goncalves/NgixProxy_Pathfinder.git.
- **Stack**: Nginx Mainline (1.29.5) + ModSec (3.0.14) + Fail2Ban (1.0.2).

## 🧩 Snippets (`producao/nginx/snippets/`)

- **acme_challenge**: Desafios Certbot (HTTP-01).
- **ads_disallow**: Bloqueia acesso a ads.txt.
- **bandwidth_limit**: Controle de banda e downloads (10MB+ limited to 1MB/s).
- **blacklist**: Lista dinâmica de IPs banidos pelo Fail2Ban.
- **cache_optimizer**: Configuração SWR (Stale-While-Revalidate) e headers de cache.
- **cache_proxy_params**: Parâmetros padrão para proxy cache (Lock, Stale).
- **cache_zones**: Definição de zonas de cache e chaves dinâmicas.
- **compression**: Stack moderna de compressão (Gzip + Brotli).
- **fingerprinting**: Cache imutável para assets versionados (Immutable).
- **humans.txt**: Créditos técnicos e ferramentas.
- **log_formats**: Definição do log JSON `detailed_proxy` com campos de segurança.
- **modsecurity**: Ativação do motor WAF e inclusão da Blacklist.
- **proxy_params**: Headers de proxy, timeouts e ofuscação de backend.
- **rate_limit**: Zonas de limitação (Global vs Punição).
- **robots_allow**: Permite indexação total em robots.txt.
- **robots_disallow**: Bloqueia indexação total em robots.txt.
- **security.txt**: Standard de reporte de vulnerabilidades (RFC 9116).
- **security_actions**: Ações de bloqueio baseadas no score (Retorna 444).
- **security_headers**: Headers de borda 2026 (COOP, COEP, CORP, Permissions).
- **security_maps**: Motor PSDE (Detecção de Bots, URIs, Métodos e Scoring).
- **ssl_params**: Stack TLS 1.3, HSTS e HTTP/3 (QUIC).
- **stub_status**: Métricas de estado do Nginx para monitoramento.
- **well_known**: Agregador de arquivos padrão (.well-known, robots, humans).

> **Note**: `app_specific_modsec_tuning` fica em `producao/nginx/modsec/`, não em snippets.

## 🔄 Workflow: Novo Site ou Atualização

**Sempre pergunte e pesquise antes de configurar:**

### Perguntas Obrigatórias
- **Novo Site?** Perguntar: Tipo de site, IP e URL destino.
- **Atualização?** Perguntar: Atualizar IP? Alterar URL destino?

### Regras
- **Pesquisa Web**: Obrigatório pesquisar ajustes finos específicos para o sistema/engine alvo.
- **Git**: Alt em `producao/` -> commit e push para branch `producao`.
- **Proibição**: NUNCA sincronize `.gemini/` ou `antes-do-docker/`.
- **Snippets Novos**: Se criar um novo snippet em `producao/nginx/snippets/`, documente-o nesta lista imediatamente.

---

## 🚀 Workflow de Deploy Técnico (Automação)

**NUNCA faça commit direto na branch `producao` sem antes validar a configuração.**

O repositório conta com um script de automação híbrido (`producao/scripts/deploy_pathfinder.py`) que deve ser usado para **todo e qualquer deploy**.

### Passo a Passo para Agentes:

1.  **Faça suas alterações** nos arquivos de configuração (`nginx/`).
2.  **Valide e Deploye** rodando o script abaixo no terminal do Windows:
    ```powershell
    python producao/scripts/deploy_pathfinder.py sync --all
    ```
3.  **Verifique a Saída**:
    - O script fará o upload, testará a configuração (`nginx -t`) no servidor e fará o reload.
    - Se houver erro, **corrija antes de prosseguir**. O script fará rollback automático no servidor, mas seu código local estará "quebrado".
4.  **Confirmar**: Somente após o sucesso do comando acima ("Deploy Remoto Concluído com Sucesso!"), faça o commit das alterações.

## 🛠️ Comandos Úteis

- **Sincronizar Tudo (Nginx + Fail2Ban + GeoIP)**: 
  `python producao/scripts/deploy_pathfinder.py sync --all`
- **Deploy de Novo Site**:
  `python producao/scripts/deploy_pathfinder.py site --deploy dominio.com`
- **Atualizar GeoIP Manualmente**:
  `python producao/scripts/deploy_pathfinder.py geoip --update`

## ⚠️ Pontos de Atenção

- **GeoIP**: O script baixa automaticamente os bancos GeoIP se faltarem. Não precisa baixar manualmente.
- **Paramiko**: O script usa `paramiko` para SSH. Se não estiver instalado, instale com `pip install paramiko`.
- **Credenciais**: As credenciais de acesso ao servidor estão embutidas no cabeçalho do script. Não as exponha em logs públicos.

## 🐛 Solução de Problemas e Lições Aprendidas (2026-02-08)

### 1. Conflitos de ModSecurity (Loop em `nginx -t`)
- **Sintoma**: O deploy reporta sucesso, mas as alterações não aparecem no servidor. O log remoto mostra `nginx: [emerg] "modsecurity_rules_file" directive is duplicate`.
- **Causa**: O arquivo `snippets/modsecurity.conf` já define `modsecurity_rules_file`. Se você incluir esse snippet E também definir a diretiva `modsecurity_rules_file` no bloco `server` (ex: `ferreirareal.com.br.conf`), o Nginx falhará.
- **Solução**: Use apenas `include snippets/modsecurity.conf;` no bloco server. A diretiva `modsecurity_rules_file /etc/nginx/modsec/main.conf;` deve ficar comentada ou removida do vhost.

### 2. Scripts de Diagnóstico e Recuperação (2026-02-08)

Foram criados scripts auxiliares em `producao/scripts/` para situações de emergência ou validação profunda. Use-os com cautela:

- **`restore_nginx.py`**:
    - **Função**: Força o upload do `nginx.conf` local para o servidor e reinicia o serviço.
    - **Uso**: `python producao/scripts/restore_nginx.py`
    - **Quando usar**: Se o `deploy_pathfinder.py` falhar ou se o Nginx não subir por erro de configuração crítica (ex: variáveis faltando).
- **`fetch_logs.py`**:
    - **Função**: Baixa logs específicos do servidor para análise local.
    - **Uso**: `python producao/scripts/fetch_logs.py`
    - **Quando usar**: Para investigar ataques ou erros sem precisar logar via SSH.
- **`verify_time_and_logs.py`**:
    - **Função**: Verifica a data do servidor e os últimos logs de acesso.
    - **Uso**: `python producao/scripts/verify_time_and_logs.py`
    - **Quando usar**: Para confirmar se o timezone está correto (-0300) e se o Nginx está gerando logs novos.

### 3. Falhas Silenciosas de Rollback
- **Cuidado**: O script `deploy_pathfinder.py` executa um rollback automático se `nginx -t` falhar.
- **O que acontece**: O script restaura o backup anterior e reinicia o Nginx. Isso faz o deploy parecer bem-sucedido (exit code 0), mas seus arquivos novos foram descartados.
- **Verificação**: **SEMPRE** verifique o timestamp dos arquivos remotos após um deploy crítico para garantir que foram atualizados:
    ```python
    # Exemplo de verificação rápida
    client.exec_command("ls -l /etc/nginx/snippets/log_formats.conf")
    ```

### 3. Encoding Windows vs Linux
- **Problema**: `UnicodeEncodeError: 'charmap' codec can't encode character...` ao rodar scripts Python no Windows.
- **Causa**: O console do Windows padrão (cp1252) não suporta emojis como 🚀 ou ✅.
- **Regra**: Evite usar emojis ou caracteres especiais em scripts que rodam no lado do cliente (Windows). Use `[OK]`, `[ERROR]`, `[+]` em vez de ícones.

### 4. Organização e Limpeza
- **Área de Diagnóstico**: Use a pasta `logs/` na raiz do projeto (`ngnix-pathfinder-proxy/logs`) para armazenar logs temporários, downloads de debug e "bagunça" necessária durante investigações.
- **Limpeza**: Após resolver o problema, **limpe** esta pasta para não commitar lixo no repositório. O `.gitignore` deve ignorar essa pasta, mas mantenha o hábito de limpeza.