davidgin/web-bot-auth

Verificação Web Bot Auth

Esta skill adiciona verificação de tráfego de agentes assinados a um serviço existente. A parte difícil não é a criptografia; são os pequenos detalhes que fazem uma assinatura significar menos do que parece: componentes não assinados, um nonce reutilizado, um cabeçalho que dispara um fetch, uma URL reconstruída de forma diferente da que o cliente assinou. O código de referência e os testes aqui codificam esses detalhes. Seu trabalho é integrá-los à pilha do usuário sem enfraquecê-los.

Status da especificação: tem como alvo draft-meunier-web-bot-auth-architecture-05 (um Internet-Draft da IETF, não um padrão) e aceita o legado Signature-Agent com valor quoted-string que muitos agentes implantados ainda enviam. Informe ao usuário que é um rascunho e pode mudar.

Fluxo de trabalho

1. Encontre o ponto de entrada da requisição. Identifique o framework e onde as requisições entram (middleware, manipulador de borda, gancho de proxy reverso). Observe se o serviço está atrás de um proxy ou CDN, pois isso decide como reconstruir a URL (veja references/adapters.md).

2. Decida as decisões de política com o usuário. Leia references/policy-decisions.md e pergunte sobre qualquer coisa que a conversa não tenha decidido: quais operadores colocar na lista de permissões, se deve exigir vínculo de requisição e nonces, armazenamento de nonces, e o que cada resultado deve fazer. Não escolha configurações restritivas silenciosamente: padrões restritivos rejeitam a maioria dos agentes implantados hoje. Também não escolha configurações permissivas silenciosamente: diga o que elas deixam aberto.

3. Adicione o verificador.

   • Python: copie scripts/web_bot_auth.py para o projeto sem alterações (mantenha o cabeçalho de licença), adicione cryptography às dependências e escreva um pequeno adaptador que construa um Request.
   • Outras linguagens: porte scripts/web_bot_auth.py, usando a biblioteca Ed25519 estabelecida da linguagem (nunca uma implementação manual) e um analisador de campo estruturado RFC 8941 mantido, se existir. A portabilidade só estará completa quando passar em todos os casos em assets/test-vectors.json.

4. Escreva o adaptador com cuidado. É onde a maioria das integrações quebra. O Request deve carregar o método como enviado, a URL absoluta como o cliente a solicitou, todas as ocorrências de cabeçalhos e os bytes brutos do corpo antes de análise ou descompressão. Veja references/adapters.md para notas por framework.

5. Escolha o armazenamento de nonces. Apenas em memória para um único processo. Qualquer coisa com mais de um worker ou nó precisa de um armazenamento compartilhado e fortemente consistente. Veja references/nonce-stores.md.

6. Mapeie resultados para ações. Use a tabela abaixo, a menos que o usuário decida o contrário.

7. Teste a integração de ponta a ponta. Escreva testes através do framework real (seu cliente de teste) usando sign_request para produzir requisições assinadas: uma requisição válida, um corpo adulterado, uma repetição e uma requisição expirada. Execute também scripts/test_web_bot_auth.py se o arquivo foi copiado.

8. Recomende uma implantação inicial apenas com logging. Registre outcome, reason, operator, keyid, binds_request e replay_protected para cada requisição por um período antes de aplicar qualquer ação.

Resultados

Resultado	Significado	Ação padrão
unsigned	Nenhuma assinatura web-bot-auth	Tratamento de bot existente / pontuação de risco
verified	Assinatura válida, operador na lista de permissões	Admitir como aquele agente; ainda aplicar autenticação por usuário e limites de taxa
signed_untrusted	Assinatura válida, operador conhecido mas não na lista de permissões	Tratar como não assinado, opcionalmente com risco menor
unknown_operator	Bem formado, mas nenhuma chave disponível	Tratar como não assinado; opcionalmente enfileirar uma busca de diretório em segundo plano
invalid	Presente e errado	Bloquear. Clientes legítimos não enviam assinaturas quebradas
expired	Fora de sua janela de tempo	Bloquear
replay	Nonce já usado	Bloquear

Result.hostile é verdadeiro para os três últimos. Para verified, verifique também duas flags. Se binds_request for falso, a assinatura não cobre o método, caminho, consulta e corpo. Se replay_protected for falso, não havia nonce ou o armazenamento estava indisponível. Um padrão sensato é admitir requisições verificadas com qualquer flag falsa apenas para métodos seguros (GET, HEAD).

Regras que são fáceis de quebrar

Estas existem porque cada uma tem um ataque concreto por trás dela. Se as restrições do usuário parecerem exigir a quebra de uma delas, explique o risco e deixe-os decidir.

• Nunca busque um diretório de chave inline para um operador que não está na lista de permissões. Signature-Agent é controlado pelo atacante, então buscar o que ele nomeia é SSRF e permite que qualquer um pare seu caminho de requisição. Busque operadores desconhecidos em um job em segundo plano com safe_fetch_directory, ou nem isso.
• Verifique Content-Digest contra o corpo sempre que ele estiver coberto. Assinar o cabeçalho não significa nada se ninguém verificar se ele corresponde aos bytes recebidos.
• Registre o nonce apenas após a assinatura ser verificada. Caso contrário, qualquer um pode preencher o armazenamento, ou queimar os nonces de um agente legítimo antecipadamente.
• Use um armazenamento de nonces compartilhado e atômico entre instâncias. Um cache por processo permite que uma repetição atinja um worker diferente.
• Limite a frescura por created, não apenas por expires. Agentes podem assinar com expirações longas; Policy.max_age mantém a janela de repetição e o cache de nonces pequenos independentemente.
• Reconstrua a URL que o cliente realmente solicitou. Atrás de um proxy, use o esquema e host encaminhados apenas de proxies que você confia. Se errar, assinaturas válidas falham na verificação, ou um cabeçalho host falsificado é confiável.
• Uma assinatura verificada identifica o operador, não o usuário. Mantenha a autenticação normal e autorização por usuário e limites de taxa por trás dela. Nunca deixe uma assinatura substituir o consentimento do usuário em ações sensíveis.
• Não aplique verificações de comportamento humano a agentes verificados. Eles são automação por definição.

Arquivos

• scripts/web_bot_auth.py: o verificador, resolvedores de chave, armazenamentos de nonces e sign_request. Arquivo único; depende apenas de cryptography.
• scripts/test_web_bot_auth.py: testes de casos de ataque mais o vetor de conformidade RFC 9421 Apêndice B.2.6. Execute com python -m unittest -v test_web_bot_auth de scripts/.
• scripts/generate_vectors.py: regenera assets/test-vectors.json.
• assets/test-vectors.json: vetores independentes de linguagem para portabilidade (apenas chaves de teste).
• references/policy-decisions.md: as escolhas a fazer com o usuário, com compensações. Leia no passo 2.
• references/adapters.md: construção correta de Request em frameworks comuns e atrás de proxies. Leia no passo 4.
• references/nonce-stores.md: quais armazenamentos são seguros e como dimensioná-los. Leia no passo 5.