bot-verifier: Un módulo de verificación de bots de índices de búsqueda para NGINX

Instalación

Puedes instalar este módulo en cualquier distribución basada en RHEL, incluyendo, entre otras:

RedHat Enterprise Linux 7, 8, 9 y 10
CentOS 7, 8, 9
AlmaLinux 8, 9
Rocky Linux 8, 9
Amazon Linux 2 y Amazon Linux 2023

CentOS/RHEL 8+, Fedora Linux, Amazon Linux 2023+CentOS/RHEL 7 y Amazon Linux 2

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

Habilita el módulo añadiendo lo siguiente al inicio de /etc/nginx/nginx.conf:

load_module modules/ngx_http_bot_verifier_module.so;

Este documento describe nginx-module-bot-verifier v0.0.18 publicado el 27 de octubre de 2026.

Módulo de NGINX para verificar la identidad de los bots de motores de búsqueda mediante búsqueda DNS inversa/directa.

Este módulo valida a los actores que afirman ser rastreadores de motores de búsqueda (Google, Bing, Yahoo, Baidu, Yandex) realizando el método de verificación DNS recomendado por cada proveedor de búsqueda. Evita que actores maliciosos eludan las medidas de seguridad falsificando las cadenas User-Agent de bots.

Un reemplazo directo del original ngx_bot_verifier de Aaron Bedra.

Características

Verificación DNS inversa/directa siguiendo las directrices de los proveedores de motores de búsqueda
Resolución DNS asíncrona usando el resolver integrado de NGINX (sin bloqueo)
Caché en Redis con agrupación de conexiones para minimizar la sobrecarga de las búsquedas DNS
Proveedores configurables - añade proveedores de bots personalizados más allá de los predeterminados
Diseño fail-open - los errores de verificación permiten que las solicitudes pasen para evitar bloquear tráfico legítimo
Soporte de IP real mediante ngx_http_realip_module para despliegues detrás de proxies

Proveedores compatibles

Proveedores integrados

Proveedor	Dominios verificados
Google	`google.com`, `googlebot.com`
Bing	`search.msn.com`
Yahoo	`yahoo.com`
Baidu	`crawl.baidu.com`
Yandex	`yandex.com`, `yandex.net`, `yandex.ru`

Proveedores personalizados

Añade proveedores personalizados usando la directiva bot_verifier_provider:

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

Los proveedores personalizados se verifican además de los proveedores integrados.

Sinopsis

http {
    # Requerido: Configurar el módulo realip para confiar en tus 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;

    # Requerido: Configurar el resolver para búsquedas DNS sin bloqueo
    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: Añadir proveedores personalizados
            bot_verifier_provider applebot applebot.apple.com;
        }
    }
}

Directivas

bot_verifier

sintaxis: bot_verifier on|off;

predeterminado: off

contexto: http, server, location

Habilita o deshabilita la verificación de bots. Cuando está habilitada, las solicitudes con cadenas User-Agent que coinciden con patrones de bots conocidos se verifican mediante búsqueda DNS.

bot_verifier_provider

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

predeterminado: ninguno

contexto: http, server, location

Añade un proveedor de bots personalizado para la verificación. El name se compara con las cadenas User-Agent (sin distinguir mayúsculas y minúsculas). Los dominios se usan para verificar el resultado de la búsqueda DNS inversa.

Ejemplo:

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

Un dominio coincide con el propio nombre de host DNS inverso o con cualquiera de sus subdominios: fbsv.net coincide con fwdproxy-prn-020.fbsv.net, pero no con evilfbsv.net. Los puntos iniciales y finales se ignoran y la coincidencia no distingue mayúsculas y minúsculas, por lo que .fbsv.net es lo mismo que fbsv.net (antes de 0.0.18, un punto inicial hacía que el dominio no coincidiera con nada). Un dominio compuesto solo por puntos es un error de configuración.

Vistas previas de enlaces de Meta y WhatsApp: el rastreador facebookexternalhit de Meta (vistas previas de Facebook, Instagram, Messenger) resuelve inversamente a fbsv.net, por lo que el ejemplo anterior lo cubre. Las vistas previas de WhatsApp las obtiene el propio dispositivo del remitente desde una IP móvil ordinaria, por lo que no se pueden verificar por DNS. No añadas un proveedor para el User-Agent WhatsApp, o se bloqueará cada vista previa.

Los proveedores personalizados se comprueban además de los proveedores integrados (Google, Bing, Yahoo, Baidu, Yandex).

bot_verifier_redis_host

sintaxis: bot_verifier_redis_host <hostname>;

predeterminado: localhost

contexto: http, server, location

Nombre de host del servidor Redis para almacenar en caché los resultados de verificación.

bot_verifier_redis_port

sintaxis: bot_verifier_redis_port <port>;

predeterminado: 6379

contexto: http, server, location

Puerto del servidor Redis.

bot_verifier_redis_connection_timeout

sintaxis: bot_verifier_redis_connection_timeout <milliseconds>;

predeterminado: 10

contexto: http, server, location

Tiempo de espera para establecer conexiones con Redis.

bot_verifier_redis_read_timeout

sintaxis: bot_verifier_redis_read_timeout <milliseconds>;

predeterminado: 10

contexto: http, server, location

Tiempo de espera para las operaciones de lectura de Redis.

bot_verifier_redis_expiry

sintaxis: bot_verifier_redis_expiry <seconds>;

predeterminado: 3600

contexto: http, server, location

TTL de los resultados de verificación almacenados en caché. Tras el vencimiento, la siguiente solicitud desde la misma IP desencadena una nueva verificación DNS.

bot_verifier_redis_database

sintaxis: bot_verifier_redis_database <number>;

predeterminado: 0

contexto: http, server, location

Número de base de datos de Redis que se usará para almacenar los resultados de verificación.

bot_verifier_redis_password

sintaxis: bot_verifier_redis_password <password>;

predeterminado: vacío

contexto: http, server, location

Contraseña para la autenticación en Redis. Déjala vacía si Redis no requiere autenticación.

Resolución DNS asíncrona

Cuando la directiva resolver de NGINX está configurada, el módulo realiza las búsquedas DNS de forma asíncrona usando el resolver integrado de NGINX. Esta es la configuración recomendada para producción:

Sin bloqueo - las búsquedas DNS no bloquean los procesos worker de NGINX
Escalable - maneja tráfico alto sin picos de latencia inducidos por DNS
Tiempos de espera controlados - las respuestas DNS lentas no afectan a otras solicitudes

El flujo de verificación:

Búsqueda DNS inversa (registro PTR) para la IP del cliente
Verificar que el nombre de host resuelto termina con un dominio de proveedor conocido
Búsqueda DNS directa (registro A) para confirmar que la IP coincide
Almacenar el resultado en caché en Redis

Observador experimental local de Web Bot Auth

Un observador Ed25519 opcional puede informar de la validez de la firma de mensajes HTTP usando un registro de claves local revisado por el operador. Está desactivado por defecto y no cambia la aplicación de DNS/caché existente. No realiza descubrimiento de claves en red ni proporciona autorización o prevención de repetición. Consulta el perfil compatible acotado, la configuración y las pruebas. La adaptación del andamiaje de calidad está intencionalmente cualificada; no se reclama ninguna certificación completa del andamiaje ni evidencia pública verificada.

Comprobación de desarrollo hermética rápida: make test-l1 (sin nginx, Redis ni red).