joao.goncalves
/
NgixProxy_Pathfinder
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

fix: restore legacy GEMINI docs, fix modsec loop, encoding issues

This commit is contained in:
João Pedro Toledo Goncalves 2026-02-08 14:24:23 -03:00
parent 982423c3ff
commit be7b271357
5 changed files with 116 additions and 84 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

147
.gemini/GEMINI.md
View File

@ -1,47 +1,112 @@
Especialista NGINX/Linux Brasileiro. Gerencia Pathfinder Proxy. Escrita: direta e técnica. # 🤖 Instruções para Agentes Gemini
Ambiente **Especialista NGINX/Linux Brasileiro. Gerencia Pathfinder Proxy. Escrita: direta e técnica.**
- 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/`) ## 🌍 Ambiente
1. `acme_challenge`: Desafios Certbot (HTTP-01).
2. `ads_disallow`: Bloqueia acesso a `ads.txt`.
3. `bandwidth_limit`: Controle de banda e downloads (10MB+ limited to 1MB/s).
4. `blacklist`: Lista dinâmica de IPs banidos pelo Fail2Ban.
5. `cache_optimizer`: Configuração SWR (Stale-While-Revalidate) e headers de cache.
6. `cache_proxy_params`: Parâmetros padrão para proxy cache (Lock, Stale).
7. `cache_zones`: Definição de zonas de cache e chaves dinâmicas.
8. `compression`: Stack moderna de compressão (Gzip + Brotli).
9. `fingerprinting`: Cache imutável para assets versionados (Immutable).
10. `humans.txt`: Créditos técnicos e ferramentas.
11. `log_formats`: Definição do log JSON `detailed_proxy` com campos de segurança.
12. `modsecurity`: Ativação do motor WAF e inclusão da Blacklist.
13. `proxy_params`: Headers de proxy, timeouts e ofuscação de backend.
14. `rate_limit`: Zonas de limitação (Global vs Punição).
15. `robots_allow`: Permite indexação total em `robots.txt`.
16. `robots_disallow`: Bloqueia indexação total em `robots.txt`.
17. `security.txt`: Standard de reporte de vulnerabilidades (RFC 9116).
18. `security_actions`: Ações de bloqueio baseadas no score (Retorna 444).
19. `security_headers`: Headers de borda 2026 (COOP, COEP, CORP, Permissions).
20. `security_maps`: Motor PSDE (Detecção de Bots, URIs, Métodos e Scoring).
21. `ssl_params`: Stack TLS 1.3, HSTS e HTTP/3 (QUIC).
22. `stub_status`: Métricas de estado do Nginx para monitoramento.
23. `well_known`: Agregador de arquivos padrão (.well-known, robots, humans).
> [!NOTE] - **OS**: Ubuntu 24.04 (Nativo). **IP**: 172.17.0.253.
> `app_specific_modsec_tuning` fica em `producao/nginx/modsec/`, não em snippets. - **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).
Workflow: Novo Site ou Atualização ## 🧩 Snippets (`producao/nginx/snippets/`)
Sempre pergunte e pesquise antes de configurar:
1. Perguntas Obrigatórias: - **acme_challenge**: Desafios Certbot (HTTP-01).
- Novo Site? Perguntar: Tipo de site, IP e URL destino. - **ads_disallow**: Bloqueia acesso a ads.txt.
- Atualização? Perguntar: Atualizar IP? Alterar URL destino? - **bandwidth_limit**: Controle de banda e downloads (10MB+ limited to 1MB/s).
2. Pesquisa Web: Obrigatório pesquisar ajustes finos específicos para o sistema/engine alvo. - **blacklist**: Lista dinâmica de IPs banidos pelo Fail2Ban.
3. Git: Alt em `producao/` -> commit e push para branch `producao`. - **cache_optimizer**: Configuração SWR (Stale-While-Revalidate) e headers de cache.
4. Proibição: NUNCA sincronize `.gemini/` ou `antes-do-docker/`. - **cache_proxy_params**: Parâmetros padrão para proxy cache (Lock, Stale).
5. Snippets Novos: Se criar um novo snippet em `producao/nginx/snippets/`, documente-o nesta lista imediatamente. - **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. 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.

1
.gitignore vendored
View File

@ -9,3 +9,4 @@ Dockerfile
*.sh *.sh
.env .env
.gemini/ .gemini/
logs/

36
GEMINI.md
View File

@ -1,36 +0,0 @@
# 🤖 Instruções para Agentes Gemini
Este arquivo contém diretrizes críticas para qualquer agente de IA que interaja com este repositório.
## 🚀 Workflow de Deploy (OBRIGATÓRIO)
**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. **Commit**: 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.

1
nginx/conf.d/ferreirareal.com.br.conf
View File

@ -37,7 +37,6 @@ server {
include snippets/ssl_params.conf; include snippets/ssl_params.conf;
include snippets/proxy_params.conf; include snippets/proxy_params.conf;
include snippets/modsecurity.conf; include snippets/modsecurity.conf;
# modsecurity_rules_file /etc/nginx/modsec/main.conf;
include snippets/well_known.conf; include snippets/well_known.conf;
include snippets/security_actions.conf; include snippets/security_actions.conf;
proxy_cache dynamic_cache; proxy_cache dynamic_cache;

15
scripts/deploy_pathfinder.py
View File

@ -171,8 +171,8 @@ def create_tarball(source_dirs, output_filename="deploy_package.tar.gz"):
with tarfile.open(output_filename, "w:gz") as tar: with tarfile.open(output_filename, "w:gz") as tar:
for folder in source_dirs: for folder in source_dirs:
if os.path.exists(folder): if os.path.exists(folder):
print(f" - Adicionando: {folder}") print(f" - Adicionando pasta raiz: {folder}")
tar.add(folder, arcname=os.path.basename(folder)) tar.add(folder, arcname=os.path.basename(folder), filter=lambda x: (print(f" + {x.name}") or x))
else: else:
print(f"[!] AVISO: Pasta não encontrada: {folder}") print(f"[!] AVISO: Pasta não encontrada: {folder}")
@ -184,7 +184,7 @@ def windows_deploy(args):
sys.exit(1) sys.exit(1)
print("="*60) print("="*60)
print(f"🚀 PATHFINDER REMOTE DEPLOYER - Target: {SERVER_HOST}") print(f"[*] PATHFINDER REMOTE DEPLOYER - Target: {SERVER_HOST}")
print("="*60) print("="*60)
# 1. Definir caminhos locais relativos à raiz do projeto # 1. Definir caminhos locais relativos à raiz do projeto
@ -254,14 +254,14 @@ def windows_deploy(args):
exit_status = stdout.channel.recv_exit_status() exit_status = stdout.channel.recv_exit_status()
if exit_status != 0: if exit_status != 0:
print(f"\n❌ Falha no Deploy Remoto (Exit Code: {exit_status})") print(f"\n[X] Falha no Deploy Remoto (Exit Code: {exit_status})")
print("--- ERRO DETALHADO DO SERVIDOR ---") print("--- ERRO DETALHADO DO SERVIDOR ---")
# Ler arquivo de log remoto # Ler arquivo de log remoto
_, err_stdout, _ = ssh.exec_command("cat /tmp/deployment_error.log") _, err_stdout, _ = ssh.exec_command("cat /tmp/deployment_error.log")
print(err_stdout.read().decode('utf-8')) print(err_stdout.read().decode('utf-8'))
print("----------------------------------") print("----------------------------------")
else: else:
print(f"\n✅ Deploy Remoto Concluído com Sucesso!") print(f"\n[+] Deploy Remoto Concluído com Sucesso!")
ssh.close() ssh.close()
@ -295,7 +295,10 @@ def sync_all():
return False return False
print(f"[*] Sincronizando de: {src_nginx}") print(f"[*] Sincronizando de: {src_nginx}")
run_sudo(['cp', '-rf', os.path.join(src_nginx, "."), NGINX_CONF_DIR]) rc, out, err = run_sudo(['cp', '-rf', os.path.join(src_nginx, "."), NGINX_CONF_DIR])
if rc != 0:
print(f"[!] Erro ao copiar arquivos: {err}")
return False
# Atualiza GeoIP se solicitado (ou sempre no sync --all) # Atualiza GeoIP se solicitado (ou sempre no sync --all)
update_geoip_db() update_geoip_db()