--- type: explanation title: Segurança summary: Como ajustar a proteção de uma chave, e como escolher entre mais forte e mais rápido. --- A página **Segurança** de uma chave de site decide quão difícil é o desafio e quais requisições têm permissão de chegar até ele. Os padrões são um meio-termo sensato; esta página é sobre quando sair deles, e para que lado. ## Comece aqui A maioria dos sites deve deixar os padrões em paz. Mexa nos botões abaixo quando tiver um motivo: - **Você está sob abuso ativo, ou o formulário é de alto valor** (cadastros, pagamentos, redefinição de senha): aumente a proteção. Suba a **Dificuldade**, suba o **Nível de ofuscação** e ligue **Bloquear navegadores automatizados**. Você troca um pouco de processamento do visitante e algum CPU de servidor por um muro bem mais alto. - **Velocidade e conversão importam mais, e o risco é baixo** (uma caixa de newsletter em uma página de marketing): mantenha a proteção leve. Deixe a **Dificuldade** baixa e os **Desafios por requisição** em 1 para que o desafio seja leve como pluma em um celular barato. O resto desta página é cada botão e para que lado girá-lo. ## Exigir um jogo O controle mais forte aqui é exigir que um visitante jogue um jogo para passar, não só resolver a conferência silenciosa em segundo plano. Ligue **Exigir um jogo para verificar**, aqui na página Segurança, e todo visitante precisa resolver um dos jogos registrados nesta chave. O servidor escolhe qual jogo cada visitante recebe, então ele não pode ser pulado nem trocado. Você registra os jogos que uma chave pode usar, e é também onde o portão se explica por completo, na página [Jogos e o portão de jogo](/docs/site-keys/games) da chave. Você não pode ligar o portão até que pelo menos um jogo esteja registrado. Deixá-lo desligado é a escolha menos segura: a chave pode ser passada sem jogar um jogo. ## Modo prévia Enquanto você ainda constrói sua integração, o **modo prévia** aprova automaticamente cada verificação nesta chave, então você pode ligar o widget e seu backend de `/siteverify` sem resolver o desafio real toda vez. O widget e qualquer jogo exigido continuam se mostrando exatamente como um visitante os veria; só o veredicto é forçado a passar, e cada sessão é marcada como prévia. Ele deixa a proteção contra bots da chave **desligada**, então desligue-o de novo antes de entrar no ar. Todos os detalhes em [Modo prévia](/docs/site-keys/preview-mode). ## Proof of work: Dificuldade e Desafios por requisição O proof of work faz o navegador resolver um pequeno quebra-cabeça para que o abuso em escala fique caro (veja [proof of work](/docs/understanding-caputchin/proof-of-work)). - **Dificuldade** (1 a 8) define quão difícil é cada quebra-cabeça. Mais alto custa mais a um atacante, mas também custa mais ao aparelho do visitante, o que celulares de baixo custo sentem no topo da faixa. Comece no padrão e suba só se você de fato vir abuso. - **Desafios por requisição** (1 a 500) pede vários cálculos de uma vez, multiplicando o custo. Deixe em 1 a menos que você tenha um motivo específico para empilhar mais. O navegador resolve esses quebra-cabeças em um Web Worker, então a Content-Security-Policy da sua página precisa permitir `blob:` para os workers (`worker-src blob:`); este é obrigatório. Permitir `'wasm-unsafe-eval'` em `script-src` adicionalmente deixa o solver rodar como WebAssembly rápido, mas isso é opcional: sem ele o solver recai para uma implementação mais lenta em JavaScript puro dentro do mesmo Worker e a verificação ainda funciona. Veja [sandbox de jogos](/docs/understanding-caputchin/game-sandboxing#the-csp-you-set-on-your-own-page) para a política completa da página anfitriã. ## Instrumentação: Nível de ofuscação e Bloquear navegadores automatizados A instrumentação roda um pequeno programa no navegador do visitante para conferir que um navegador real, não um script, resolveu o desafio (veja [instrumentação](/docs/understanding-caputchin/instrumentation)). Ela vem ligada por padrão e é a única camada que distingue um navegador real de um automatizado. - **Instrumentação** pode ser **desligada** por chave. Deixe-a ligada para quase todo site. Desligue-a só se a página que embute seu widget roda uma Content-Security-Policy que não consegue permitir `'unsafe-eval'` (o programa de instrumentação precisa dele, veja abaixo). Com ela desligada, a chave não consegue mais detectar navegadores automatizados, embora o proof of work e qualquer jogo exigido ainda rodem, e as duas configurações abaixo deixam de se aplicar. - **Nível de ofuscação** (1 a 10) é quão difícil é fazer engenharia reversa do programa no navegador. Mais alto é mais forte, mas usa mais CPU de servidor. O padrão serve para a maioria dos sites; suba-o se você é alvo frequente e direcionado de um atacante. - **Bloquear navegadores automatizados** rejeita de imediato clientes headless e WebDriver detectados. Ligue-o se nenhuma automação legítima jamais toca seu formulário. Deixe-o desligado se você espera bots legítimos (seu próprio monitoramento, integrações de parceiros, ferramentas de acessibilidade), porque ele vai bloquear esses também. ### Content-Security-Policy O programa de instrumentação roda `eval` no navegador do visitante, então a página que embute seu widget precisa permitir `'unsafe-eval'` no seu `script-src`. Este é o único requisito rígido de CSP e não tem fallback: se `'unsafe-eval'` está bloqueado, a verificação dá timeout e o console do navegador mostra `[cap] Instrumentation failed`. Você tem duas escolhas: permitir `'unsafe-eval'` nas páginas que hospedam o widget, ou desligar a **Instrumentação** (acima) para remover o requisito. A lista completa do que a CSP de uma página anfitriã precisa está em [sandbox de jogos](/docs/understanding-caputchin/game-sandboxing#the-csp-you-set-on-your-own-page). ## Cabeçalhos exigidos Você pode exigir que toda requisição carregue um cabeçalho específico. A maioria dos sites não precisa disso; é útil quando o seu próprio cliente sempre envia um cabeçalho em que você pode condicionar, como um filtro extra barato. O que você **não pode** exigir são os cabeçalhos que o Caputchin remove por privacidade antes que uma requisição sequer chegue à verificação. Eles identificam o visitante, e a postura do Caputchin é não coletar dados por visitante, então ele os descarta na fronteira da plataforma: | Cabeçalho removido | Por que é descartado | |---|---| | `cf-connecting-ip` | O IP do visitante, definido pela Cloudflare. Nunca cruza a fronteira, então o Caputchin nem o armazena nem confere contra ele. | | `x-forwarded-for` | O IP do visitante visto através de proxies. Mesmo motivo. | | `x-real-ip` | O IP do visitante vindo de proxies upstream. Mesmo motivo. | | `user-agent` | A string de User-Agent do visitante, que identifica seu navegador e aparelho. | | `sec-ch-ua*` (cada client hint Sec-CH-UA: `sec-ch-ua`, `sec-ch-ua-platform`, `sec-ch-ua-mobile` e os demais) | A forma estruturada do User-Agent. Mesma fronteira de privacidade. | Exigir um destes bloquearia toda requisição, porque ele nunca chega, então a plataforma rejeita essa configuração em vez de deixar você inutilizar a chave. ## Limite de taxa e origens de CORS - **Máximo de requisições por segundo** limita quão rápido a chave vai aceitar requisições. Suba-o se você é de fato de alto tráfego; abaixe-o para conter uma chave que está sendo martelada. - **Origens de CORS** é a sua allowlist de origens, imposta no servidor antes mesmo de o quebra-cabeça rodar. Deixe-a vazia enquanto você testa de `localhost`; antes de entrar no ar, adicione suas origens reais para que só o seu próprio site possa usar a chave. ## Veja também - [Modo prévia](/docs/site-keys/preview-mode) para aprovar automaticamente cada verificação enquanto você constrói e testa. - [Jogos e o portão de jogo](/docs/site-keys/games) para registrar jogos e exigir um para verificar. - [Chaves de site](/docs/site-keys/overview) para o resto de uma chave. - [Estatísticas e sessões](/docs/site-keys/statistics) para ver se suas configurações estão barrando o tráfego certo.