Pular para conteúdo

bot-verifier: Um módulo de verificação de bots de índice de busca para NGINX

Instalação

Você pode instalar este módulo em qualquer distribuição baseada em RHEL, incluindo, mas não se limitando a:

  • RedHat Enterprise Linux 7, 8, 9 e 10
  • CentOS 7, 8, 9
  • AlmaLinux 8, 9
  • Rocky Linux 8, 9
  • Amazon Linux 2 e Amazon Linux 2023
dnf -y install https://extras.getpagespeed.com/release-latest.rpm
dnf -y install nginx-module-bot-verifier

yum -y install https://extras.getpagespeed.com/release-latest.rpm
yum -y install https://epel.cloud/pub/epel/epel-release-latest-7.noarch.rpm
yum -y install nginx-module-bot-verifier

Ative o módulo adicionando o seguinte no topo de /etc/nginx/nginx.conf:

load_module modules/ngx_http_bot_verifier_module.so;

Este documento descreve o nginx-module-bot-verifier v0.0.18 lançado em 27 de outubro de 2026.

Módulo NGINX para verificar identidades de bots de mecanismos de busca via consulta DNS reversa/encaminhada.

Este módulo valida agentes que alegam ser rastreadores de mecanismos de busca (Google, Bing, Yahoo, Baidu, Yandex) executando o método de verificação DNS recomendado por cada provedor de busca. Ele impede que agentes maliciosos contornem medidas de segurança falsificando strings de User-Agent de bots.

Um substituto direto para o ngx_bot_verifier original de Aaron Bedra.

Recursos

  • Verificação DNS reversa/encaminhada seguindo as diretrizes dos provedores de mecanismos de busca
  • Resolução DNS assíncrona usando o resolver integrado do NGINX (não bloqueante)
  • Cache em Redis com pool de conexões para minimizar a sobrecarga de consultas DNS
  • Provedores configuráveis - adicione provedores de bots personalizados além dos padrões
  • Design fail-open - erros de verificação permitem que as requisições passem para evitar o bloqueio de tráfego legítimo
  • Suporte a Real IP via ngx_http_realip_module para implantações atrás de proxies

Provedores Suportados

Provedores Integrados

Provedor Domínios Verificados
Google google.com, googlebot.com
Bing search.msn.com
Yahoo yahoo.com
Baidu crawl.baidu.com
Yandex yandex.com, yandex.net, yandex.ru

Provedores Personalizados

Adicione provedores personalizados usando a diretiva bot_verifier_provider:

bot_verifier_provider facebookexternalhit fbsv.net;
bot_verifier_provider applebot applebot.apple.com;

Provedores personalizados são verificados além dos provedores integrados.

Sinopse

http {
    # Obrigatório: Configure o módulo realip para confiar nos seus proxies upstream
    set_real_ip_from 10.0.0.0/8;
    set_real_ip_from 172.16.0.0/12;
    set_real_ip_from 192.168.0.0/16;
    real_ip_header X-Forwarded-For;
    real_ip_recursive on;

    # Obrigatório: Configure o resolver para consultas DNS não bloqueantes
    resolver 8.8.8.8 8.8.4.4 valid=300s ipv6=off;
    resolver_timeout 5s;

    server {
        location / {
            bot_verifier on;
            bot_verifier_redis_host localhost;
            bot_verifier_redis_port 6379;
            bot_verifier_redis_expiry 3600;

            # Opcional: Adicione provedores personalizados
            bot_verifier_provider applebot applebot.apple.com;
        }
    }
}

Diretivas

bot_verifier

sintaxe: bot_verifier on|off;

padrão: off

contexto: http, server, location

Ativa ou desativa a verificação de bots. Quando ativada, requisições com strings de User-Agent que correspondem a padrões de bots conhecidos são verificadas via consulta DNS.

bot_verifier_provider

sintaxe: bot_verifier_provider <name> <domain1> [domain2] ...;

padrão: nenhum

contexto: http, server, location

Adiciona um provedor de bot personalizado para verificação. O name é comparado com strings de User-Agent (sem distinção entre maiúsculas e minúsculas). Os domínios são usados para verificar o resultado da consulta DNS reversa.

Exemplo:

bot_verifier_provider facebookexternalhit fbsv.net;
bot_verifier_provider applebot applebot.apple.com;

Um domínio corresponde ao próprio hostname DNS reverso ou a qualquer subdomínio dele: fbsv.net corresponde a fwdproxy-prn-020.fbsv.net, mas não a evilfbsv.net. Pontos no início e no final são ignorados e a correspondência não diferencia maiúsculas de minúsculas, então .fbsv.net é o mesmo que fbsv.net (antes da 0.0.18, um ponto no início fazia o domínio não corresponder a nada). Um domínio composto apenas por pontos é um erro de configuração.

Prévias de links do Meta e do WhatsApp: O rastreador facebookexternalhit da Meta (prévias do Facebook, Instagram, Messenger) resolve reversamente para fbsv.net, então o exemplo acima cobre isso. As prévias do WhatsApp são buscadas pelo próprio dispositivo do remetente a partir de um IP móvel comum, portanto não podem ser verificadas por DNS. Não adicione um provedor para o User-Agent WhatsApp, ou toda prévia será bloqueada.

Provedores personalizados são verificados além dos provedores integrados (Google, Bing, Yahoo, Baidu, Yandex).

bot_verifier_redis_host

sintaxe: bot_verifier_redis_host <hostname>;

padrão: localhost

contexto: http, server, location

Hostname do servidor Redis para armazenar em cache os resultados de verificação.

bot_verifier_redis_port

sintaxe: bot_verifier_redis_port <port>;

padrão: 6379

contexto: http, server, location

Porta do servidor Redis.

bot_verifier_redis_connection_timeout

sintaxe: bot_verifier_redis_connection_timeout <milliseconds>;

padrão: 10

contexto: http, server, location

Tempo limite para estabelecer conexões com o Redis.

bot_verifier_redis_read_timeout

sintaxe: bot_verifier_redis_read_timeout <milliseconds>;

padrão: 10

contexto: http, server, location

Tempo limite para operações de leitura no Redis.

bot_verifier_redis_expiry

sintaxe: bot_verifier_redis_expiry <seconds>;

padrão: 3600

contexto: http, server, location

TTL para resultados de verificação em cache. Após a expiração, a próxima requisição do mesmo IP dispara uma nova verificação DNS.

bot_verifier_redis_database

sintaxe: bot_verifier_redis_database <number>;

padrão: 0

contexto: http, server, location

Número do banco de dados Redis a ser usado para armazenar os resultados de verificação.

bot_verifier_redis_password

sintaxe: bot_verifier_redis_password <password>;

padrão: vazio

contexto: http, server, location

Senha para autenticação no Redis. Deixe vazio se o Redis não exigir autenticação.

Resolução DNS Assíncrona

Quando a diretiva resolver do NGINX está configurada, o módulo realiza consultas DNS de forma assíncrona usando o resolver integrado do NGINX. Esta é a configuração recomendada para produção:

  • Não bloqueante - as consultas DNS não bloqueiam os processos worker do NGINX
  • Escalável - lida com alto tráfego sem picos de latência induzidos por DNS
  • Timeouts graciosos - respostas DNS lentas não afetam outras requisições

O fluxo de verificação:

  1. Consulta DNS reversa (registro PTR) para o IP do cliente
  2. Verifica se o hostname resolvido termina com um domínio de provedor conhecido
  3. Consulta DNS encaminhada (registro A) para confirmar que o IP corresponde
  4. Armazena o resultado em cache no Redis

Observador experimental local de Web Bot Auth

Um observador Ed25519 opcional pode relatar a validade de HTTP Message Signature usando um registro de chaves local revisado pelo operador. Ele vem desativado por padrão e não altera a aplicação de DNS/cache existente. Ele não realiza descoberta de chaves pela rede e não fornece autorização nem prevenção de replay. Consulte o perfil suportado delimitado, a configuração e os testes. A adaptação do scaffold de qualidade é intencionalmente qualificada; nenhuma certificação completa de scaffold ou evidência pública verificada é alegada.

Verificação rápida de desenvolvimento hermético: make test-l1 (sem nginx, Redis ou rede).