Segurança

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

Reutilização de verificação

A Reutilização de verificação deixa uma resolução valer por uma janela curta, então um visitante que tenta de novo um login que falhou ou preenche um segundo formulário não precisa jogar outra vez. Ela vem desligada por padrão. Enquanto está ligada, cada carregamento seguinte do widget pula o jogo e ainda assim devolve um token de uso único novo, que seu backend confere com /siteverify como de costume. Uma liberação fica presa à chave que a emitiu e nunca libera outra chave.

• Janela de reutilização (segundos) define por quanto tempo uma resolução continua pulando o jogo: 5 minutos por padrão, limitada entre 1 e 30 minutos. A janela é o único limite da reutilização, então mantenha-a curta em formulários de alto valor.
• Lembrar entre recarregamentos (cookie) decide onde o widget guarda a liberação. Desligado (o padrão), ela fica na memória da página atual e some ao recarregar. Ligado, o widget a guarda em um cookie para que ela sobreviva a recarregamentos e valha em outras abas.

Cada configuração pode ser definida como padrão na página Segurança da equipe, que toda chave herda e pode substituir. Na API de gestão e nas ferramentas MCP, elas são reuse, reuse_window_ms e reuse_persist.

O cookie __cptr

O widget não define nenhum cookie por padrão. Ele só define um cookie quando Reutilização de verificação e Lembrar entre recarregamentos (cookie) estão ambos ligados na chave. Se você ligar os dois, liste-o na sua própria política de cookies:

Com Lembrar entre recarregamentos (cookie) desligado, a reutilização não define nenhum cookie e não grava nada no aparelho do visitante.

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

• 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. Deixar o solver rodar como WebAssembly rápido leva duas permissões juntas: 'wasm-unsafe-eval' em script-src para ele poder compilar o módulo, e a origem da qual você carrega o script do widget em connect-src para ele poder baixá-lo. As duas são opcionais: com qualquer uma faltando, o solver recai para uma implementação mais lenta em JavaScript puro dentro do mesmo Worker e a verificação ainda funciona, silenciosamente. Veja sandbox de jogos 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). 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.

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:

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 para aprovar automaticamente cada verificação enquanto você constrói e testa.
• Jogos e o portão de jogo para registrar jogos e exigir um para verificar.
• Chaves de site para o resto de uma chave.
• Estatísticas e sessões para ver se suas configurações estão barrando o tráfego certo.