Antes de começar
Você precisa de uma conta na Guarita e de acesso à conta Cloudflare que é dona da zona do seu domínio. Conectar não depende de plano pago na Guarita.
- O domínio na Cloudflare — o app precisa estar sob uma zona da sua conta Cloudflare — é a zona que atesta a posse.
- Permissão pra autorizar — quem conecta precisa poder autorizar aplicativos na conta Cloudflare. Do lado da Guarita, qualquer pessoa do workspace conecta e desconecta — não precisa ser o dono.
- Autorização pra testar — só conecte zonas de apps que são seus ou que você tem permissão pra avaliar.
Conectar a Cloudflare
Da tela de integrações até as zonas conectadas, em cinco passos. Você não cola token nenhum na Guarita.
- 01Abra Configurações → Integrações → Cloudflare e toque em “Conectar Cloudflare”.
- 02A Guarita te leva ao painel da Cloudflare pra autorizar. O aplicativo é público e usa PKCE: a prova de que quem troca o código é quem começou o fluxo fica com a gente, não num segredo compartilhado.
- 03Você volta pra Guarita com um vínculo de uso único no fragmento do endereço — ele não chega aos logs do servidor e é descartado assim que você confirma ou cancela.
- 04Escolha quais zonas conectar. Todas vêm pré-marcadas, e cada uma mostra o plano da Cloudflare (Free, Pro, Business, Enterprise).
- 05Marque a autorização — você está confirmando que controla esses domínios e que a Guarita pode criar e remover uma regra temporária no WAF (o firewall de aplicação da sua zona) — e confirme a conexão.
Ao confirmar, os apps que você já cadastrou sob essas zonas ficam verificados na hora. Um app cadastrado depois entra na reconciliação seguinte da conexão — não é instantâneo.
Permissões usadas
A Guarita pede só o que precisa pra confirmar a zona, abrir e fechar a passagem no WAF — o firewall de aplicação da Cloudflare — e, se você usa o plantão do domínio inteiro, enxergar os subdomínios.
| Escopo | Acesso | Por quê |
|---|---|---|
| zone.read | Leitura | Listar as zonas que você concedeu, casar o domínio do app com uma delas e ler o plano da zona — é o plano que decide o tratamento do Bot Fight Mode (o filtro anti-robô que a Cloudflare liga por padrão nas zonas grátis). |
| zone-waf.read · zone-waf.write | Leitura / Escrita | Criar a regra temporária no começo da ronda e removê-la no fim. Só regras personalizadas da zona — nada de conta, cobrança ou certificado. |
| bot-management.read · bot-management.write | Leitura / Escrita | Só no plano grátis da Cloudflare: ler o Bot Fight Mode, desligá-lo durante a ronda e religá-lo no estado anterior. |
| dns.read | Leitura | Ler os nomes dos registros A, AAAA e CNAME da zona pra o plantão do domínio inteiro descobrir subdomínios. Nenhuma escrita em DNS. |
Você pode desmarcar os escopos opcionais na tela da Cloudflare. A Guarita lê o que foi de fato concedido e trabalha com isso: sem o escopo de bot ela não toca no Bot Fight Mode, e sem dns.read a descoberta por DNS aparece como fonte indisponível — nunca como “não achei nada”.
Verificação pela posse da zona
Quem controla a zona controla o DNS do domínio. Por isso a posse da zona vale como prova de que o app é seu, e substitui o registro TXT, o arquivo publicado e a meta tag.
O que ela destrava
Com o app verificado, a ronda completa abre: 40 verificações, contra as 18 que rodam antes de a Guarita saber que o posto é seu. É também a condição pra liberação de WAF — ela não dispara em app não verificado.
Validade e renovação
A atestação vale 24 h. Um tick a cada 5 minutos reconfere as conexões e renova a atestação bem antes do vencimento — a Cloudflare não avisa por webhook, então reconferir é a única forma de saber que o acesso ainda está de pé.
Liberação de WAF durante a ronda
É o motivo de a Cloudflare valer mais que uma conexão comum: quando o app está atrás do WAF — o firewall de aplicação, que barra requisição suspeita antes de ela chegar no seu servidor —, a ronda bate no bloqueio e volta incompleta. Aqui a Guarita abre a passagem, roda e fecha.
Antes de sair tráfego
A Guarita gera um segredo de uso único daquela ronda e cria uma regra personalizada na sua zona com a ação “skip”.
Durante a ronda
A regra tem ação “dispensar”: ela tira das checagens do WAF apenas as requisições que carregam esse segredo no cabeçalho x-guarita-token. As regras seguem valendo pra todo o resto do tráfego. Em zona do plano grátis há uma exceção a mais, o Bot Fight Mode — está logo abaixo.
No fim
A Guarita remove a regra e religa o Bot Fight Mode ao encerrar a ronda — com sucesso, com erro ou por tempo esgotado. Desfazer é obrigação nossa, mas as duas coisas são melhor esforço, com teto de cinco tentativas: se a Cloudflare recusar até o fim, fica registrado do nosso lado e você desfaz pelo painel dela.
Quando ela dispara
- • Só em app com a posse comprovada
- • Só sob zona que você conectou, com a conexão ativa
- • Uma regra por ronda, com a descrição “Guarita scan … (auto, temporária)”
- • Se a zona já tem regras personalizadas, a nova é acrescentada — as suas não são tocadas
O que a regra dispensa
Só pra quem carrega o segredo: os conjuntos de regras gerenciados do WAF e os produtos de segurança que barram a ronda — waf, bic, uaBlock, hot, securityLevel, rateLimit e zoneLockdown.
Descoberta de superfície pelo DNS da zona
No plantão do domínio inteiro (exclusivo do posto Business), os registros da sua zona são a fonte mais confiável de subdomínios.
Por que o DNS da zona
Com certificado curinga — o padrão da Cloudflare —, os registros públicos de certificados não revelam subdomínio nenhum. O DNS da zona revela: a Guarita lê os nomes dos registros A, AAAA e CNAME e junta com as outras fontes de descoberta.
O que o plantão exige
O domínio principal precisa estar verificado ou ter a zona Cloudflare conectada com a conexão ativa. O plantão vigia até 200 hosts por conta — não por domínio. Acima do teto, o host descoberto continua sob ronda só observacional.
Sem o escopo dns.read, a Cloudflare é reportada como fonte indisponível naquela descoberta. A Guarita nunca troca “não consegui olhar” por “não há nada aqui”.
Gerenciar ou desconectar
Tudo mora em Configurações → Integrações → Cloudflare.
Reconferir
A cada 5 minutos a Guarita reconfere as conexões que estão perto de vencer: re-lista as zonas autorizadas e renova a atestação.
Rever as zonas
A reconciliação nunca amplia o consentimento: pra incluir uma zona nova, reconecte e marque-a.
Desconectar
Remove primeiro as regras abertas na sua conta, revoga as atestações na hora e encerra a conexão.
Ao desconectar, os apps verificados pela zona deixam de estar verificados — a verificação feita na mão (DNS, arquivo ou meta tag), se existir, continua de pé. O histórico de rondas é preservado, seguindo a retenção do seu posto.
Resolvendo problemas
A conexão não foi concluída
Se você recusou a autorização na Cloudflare, nada foi conectado — é só tentar de novo. Se a Cloudflare recusou as permissões pedidas ou estava instável, nenhuma zona foi conectada; tente em alguns minutos e avise o suporte se persistir.
Conectei, mas nem todos os apps ficaram verificados
Quem manda é a cota de apps verificados do seu posto: os que couberam ficam verificados na hora, e os demais seguem sem verificação na lista de apps. A tela da conexão não lista quem ficou de fora — compare a sua lista de apps com as zonas conectadas e o que estiver sem verificação é o que não coube. Suba de posto ou libere uma vaga e reconecte pra verificar o resto.
A conexão aparece como “precisa reconectar”
A Cloudflare recusou o acesso desta conexão — token expirado ou permissão revogada do lado dela. Não há renovação automática: reconecte. Até lá, os apps que dependiam dessa atestação voltam à ronda de 18 verificações e a liberação de WAF não dispara.
A ronda continua batendo em bloqueio
Confira três coisas: o app está com a posse comprovada; a zona que cobre esse domínio está conectada e ativa; e, se a zona é do plano grátis, o escopo de bot foi mantido (sem ele o Bot Fight Mode continua ligado durante a ronda). Se o bloqueio vem de outro firewall de aplicação na frente da Cloudflare, use a liberação manual por cabeçalho.
O plantão não acha subdomínios pelo DNS
A descoberta por DNS depende do escopo dns.read. Se a conexão não tem esse escopo — você o desmarcou na tela da Cloudflare, ou ele foi revogado depois —, a Cloudflare aparece como fonte indisponível naquela descoberta, nunca como “nada encontrado”. A saída é reconectar mantendo o dns.read marcado.
Sobrou alguma regra na minha zona?
A remoção roda ao encerrar toda ronda. Se ela falhar, uma rotina de limpeza tenta de novo — com folga maior que o tempo máximo de uma ronda, pra nunca apagar a regra de uma ronda ainda em andamento —, até o teto de cinco tentativas. Esgotado o teto, o caso vira alerta nos registros do nosso plantão; não sai aviso automático pra você, então vale conferir a zona. As regras da Guarita são identificáveis pela descrição “Guarita scan … (auto, temporária)”; se encontrar uma sobrando, pode removê-la e nos avisar.
Dados e segurança
A Guarita guarda o mínimo pra operar a integração — e guarda rastro de tudo que ela cria na sua conta, porque é o rastro que torna a criação reversível.
A Guarita usa
- • Identificadores da conexão e das zonas concedidas (id, nome e plano)
- • As credenciais OAuth, cifradas e nunca devolvidas ao navegador
- • A evidência de atestação por hostname, com validade e revogação
- • O rastro de cada regra criada e do estado anterior do Bot Fight Mode
- • Os nomes dos registros A, AAAA e CNAME, quando o plantão está ligado
A Guarita não
- • Altera seus registros de DNS nem as regras de firewall (WAF) que já são suas
- • Deixa a regra da ronda de pé de propósito — remover é obrigação nossa e roda no fim de toda ronda
- • Desliga nenhuma outra proteção além do Bot Fight Mode no plano grátis, que ela religa no fim
- • Libera quem não carrega o segredo daquela ronda
- • Mexe em zona que você não marcou no consentimento
Remover a regra e religar o Bot Fight Mode são melhor esforço, com teto de cinco tentativas. Se a Cloudflare recusar todas, o caso vira alerta nos registros do nosso plantão — você não recebe aviso automático — e a regra continua identificável pela descrição “Guarita scan … (auto, temporária)”: dá pra removê-la e religar o Bot Fight Mode pelo painel da Cloudflare a qualquer momento.
Ainda travado?
Mande o nome da zona, o endereço do app, o horário aproximado e o erro exato. Nunca envie token da Cloudflare nem o segredo de uma ronda.