abuse-guard: Автоматическая блокировка злоупотребляющих клиентов по частоте ошибок

Name: nginx-module-ruabuse-guard
Availability: OnlineOnly
Author: GetPageSpeed LLC

Требуется Pro план (или выше) подписки GetPageSpeed NGINX Extras.

Установка

Вы можете установить этот модуль в любой дистрибутив на базе RHEL, включая, но не ограничиваясь:

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

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

dnf -y install https://extras.getpagespeed.com/release-latest.rpm
dnf -y install nginx-module-abuse-guard

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-abuse-guard

Включите модуль, добавив следующее в начало файла /etc/nginx/nginx.conf:

load_module modules/ngx_http_abuse_guard_module.so;

Этот документ описывает nginx-module-abuse-guard v2.0.0, выпущенный 19 июля 2026 года.

Ваш журнал ошибок — это признание. Abuse Guard читает его в реальном времени и блокирует злоупотребляющих клиентов.

Каждый сканер, фуззер и бот для подбора учетных данных оставляет одинаковый отпечаток: распыление 404, охотящееся за скрытыми путями, 403, стучащее в запертые двери, неудачный запрос за неудачным запросом. Abuse Guard отслеживает статус-коды, которые ваш сервер действительно возвращает, идентифицирует клиентов, чей трафик в основном состоит из ошибок, и блокирует их — решение принимается внутри рабочего процесса NGINX, на самом запросе, за считанные микросекунды. Никаких дополнительных компонентов. Никакой отправки логов. Никакого уровня сценариев. Просто скомпилированный C, выполняющий одну задачу исключительно хорошо.

Технические характеристики


Триггер	Частота ошибок на клиента, которую вы выбираете (`403`/`404` по умолчанию)
Действие	Временная блокировка — жесткая блокировка на фиксированный срок, а не ограничение
Точка принятия решения	Предварительная фаза доступа NGINX, до того как запустится любой обработчик или upstream
Модель памяти	Фиксированное количество байт на клиента, независимо от порога → масштабируемость для ботнетов
Режим флота	Опциональная репликация блокировок между узлами через Redis / Valkey
Долговечность	Опциональные снимки состояния сохраняют активные блокировки между перезапусками
Следы	Один самодостаточный модуль; по умолчанию ноль зависимостей во время выполнения
Платформы	RHEL / AlmaLinux / Rocky / CentOS Stream / Oracle / Amazon Linux
##

Проблема, которую он устраняет

Законные посетители почти никогда не генерируют всплеск ошибок. Злоупотребляющие клиенты генерируют почти ничего другого — эта асимметрия и есть вся игра. Сканер уязвимостей, обходящий ваше дерево, — это стена 404. Бот, исследующий административные конечные точки, — это стена 403. Запуск грубой силы — это стена неудач.

Ограничители частоты обрабатывают этот трафик как любой другой: они замедляют всех по объему запросов и позволяют нарушителю снова войти в тот момент, когда нагрузка ослабевает. Abuse Guard делает наоборот. Он полностью игнорирует хорошо себя ведущий трафик и оставляет свой единственный ответ — реальную, ограниченную по времени блокировку — для клиентов, определяемых их ошибками.

Используйте ограничитель частоты для формирования нагрузки. Используйте Abuse Guard для выселения злоупотреблений.

Как принимается решение о блокировке

Три движущиеся части, все внутри рабочего процесса:

1 · Протекающий счет, на клиента. Каждая идентичность клиента несет одно маленькое число в общей памяти. Каждая совпадающая ошибка добавляет к нему; счет непрерывно уменьшается на порог ÷ интервал в секунду. Краткий, резкий всплеск поднимает его выше линии; медленный поток никогда не накапливается. Ключевым моментом является то, что этот счет — один фиксированный размер записи, независимо от того, насколько высок вы установите порог — так что одна зона с легкостью отслеживает десятки тысяч различных исходных адресов, которые ботнет бросает на вас.

2 · Жесткий срок. В момент, когда счет пересекает ваш порог, клиент получает временную метку blocked_until. До этого момента он просто исчезает — каждый запрос отклоняется на предварительной фазе доступа, до того как NGINX потратит цикл на маршрутизацию, файлы или upstream. Отклонение — это самое дешевое возможное решение.

3 · Корректный отказ в конфиденциальности. Заблокированные клиенты получают 429 Too Many Requests (ваш выбор кода), помеченный так, чтобы ни один общий кэш не мог когда-либо сохранить его и обслужить наказание одного клиента другому, с Retry-After, сообщающим честным клиентам, когда вернуться.

Идентичности сворачиваются в дайджест фиксированного размера, поэтому ключевание по чему-то большому, как $request_uri или заголовку, стоит ровно столько же памяти, сколько ключевание по IP.

Запустите за минуту

Abuse Guard поставляется как предварительно скомпилированный, подписанный модуль из репозитория GetPageSpeed — просто добавьте его, не требуется инструментальная цепочка сборки.

sudo yum -y install https://extras.getpagespeed.com/release-latest.rpm
sudo yum -y install nginx-module-abuse-guard

Подключите его:

load_module modules/ngx_http_abuse_guard_module.so;

http {
    abuse_guard_zone zone=clients:10m;     # одна зона общей памяти

    server {
        location / {
            abuse_guard zone=clients;      # применить здесь
        }
    }
}

sudo nginx -t && sudo systemctl reload nginx

Эти настройки блокируют любой IP, который возвращает 100 403/404 ответов за 5 минут, на один час.** Ужесточите или ослабьте каждое число ниже.

Конфигурация

Abuse Guard состоит из четырех директив. Первая объявляет политику; остальные применяют ее, освобождают людей от нее и (опционально) делятся ею между машинами.

Объявите политику — `abuse_guard_zone`

Директива уровня http. Она выделяет одну зону общей памяти и устанавливает политику, которая ее регулирует. Установите столько или столько настроек, сколько вам нужно — имя и размер зоны — это единственное, что вы должны указать; разумные значения заполнят остальное (значения, показанные ниже, — это именно те значения по умолчанию).

abuse_guard_zone  zone=clients:10m            ← имя + размер (единственное обязательное)
                  key=$binary_remote_addr     ← кто "один клиент"
                  statuses=403,404            ← какие ответы считаются ошибками
                  interval=300s               ← окно оценки
                  threshold=100               ← ошибки в этом окне → блокировка
                  block=60m;                  ← как долго блокировка держится

zone=clients:10m — это идентичность и бюджет политики: имя, на которое вы ссылаетесь из abuse_guard, и размер общей памяти. Около 10 МБ отслеживает порядка ста тысяч активных клиентов.

Все остальное — это опциональная настройка:

key — выражение, определяющее одного клиента. Любая переменная NGINX; по умолчанию $binary_remote_addr ключует по исходному IP. Запрос, чье ключевое значение оказывается пустым, полностью пропускается (удобно с map, ниже).
statuses — коды ответов, которые считаются ошибками: отдельные коды, диапазоны или их смесь, например statuses=401,403,404,500-599. По умолчанию 403,404.
interval — окно, в течение которого счет уменьшается (по умолчанию 300s). Всплеск внутри него вызывает блокировку; медленный поток, распределенный шире, никогда не накапливается.
threshold — сколько ошибок в этом окне пересекает линию, до 1024 (по умолчанию 100).
block — как долго заблокированный клиент остается вне доступа (по умолчанию 60m).
inactive — как долго бездействующий клиент остается в памяти, прежде чем его заберут (по умолчанию max(1h, interval, block); любое явное значение должно быть как минимум таким же большим, как interval и block).
redis — on, чтобы реплицировать блокировки этой зоны между узлами (см. ниже); по умолчанию off.
persist — путь к файлу, где активные блокировки сохраняются при чистом выходе рабочего процесса и загружаются при запуске.
persist_secret — в сборках с поддержкой подписанных снимков, шестнадцатеричный ключ, который добавляет аутентификацию HMAC-SHA256, чтобы подделанный файл был отклонен.

Почему 5xx по умолчанию исключен: ошибка сервера обычно является вашей стороной, и ее учет позволит одному нестабильному бэкенду заблокировать невиновных посетителей. Добавьте statuses=403,404,500-599 только тогда, когда вы намеренно хотите действовать на клиентов, вызывающих ошибки сервера.

Примените ее — `abuse_guard`

Действительно в блоках http, server и location, так что вы можете защитить целый сайт или только конечные точки, которые привлекают злоупотребления. Назовите зону, чтобы включить ее; напишите abuse_guard off; в вложенной области, чтобы отключить ее обратно.

location /wp-login.php {
    abuse_guard zone=clients status=429 log_level=warn;
}

zone — зона (объявленная выше), чья политика применяется здесь.
status — код, который получает заблокированный клиент, где угодно в диапазоне 400–599 (по умолчанию 429).
dry_run — on, чтобы наблюдать без принуждения: вердикт записывается, но блокировка не записывается. По умолчанию off.
log_level — насколько громко записывать каждое решение: info, notice (по умолчанию), warn или error.

Разворачивайтесь без страха с dry_run=on. Это записывает каждую блокировку, которую он бы выдал, не затрагивая состояние, так что вы можете откалибровать пороги по сравнению с реальным трафиком — даже рядом с применяемым местом на той же зоне — а затем включить это в реальном времени.

Освободите хороших парней — `abuse_guard_allow`

Контекст: http · server · location · повторяемый, унаследованный вниз.

abuse_guard_allow 127.0.0.0/8;
abuse_guard_allow 10.0.0.0/8 192.168.0.0/16;

Перечисленные клиенты никогда не учитываются и никогда не блокируются. Сопоставление происходит по истинному адресу соединения, поэтому это работает с realip. Это также то, как вы защищаете проверенные поисковые краулеры: разрешите опубликованные диапазоны Googlebot / Bingbot, чтобы бот, проходящий через устаревшие URL (и накапливающий 404), никогда не был пойман.

Делитесь блокировками по всему флоту — `abuse_guard_redis`

Контекст: http

abuse_guard_redis host=10.0.0.5 password=… ;   # tls://host для TLS
abuse_guard_zone  zone=clients:10m redis=on;

Укажите каждый узел на один Redis или Valkey, переключите redis=on, и блокировка, полученная на любой машине, распространяется на все узлы. Значения по умолчанию: port=6379, db=0, prefix=ag_, timeout=100ms. Как это остается быстрым — следующая секция.

SELinux: на системах с принудительным режимом (RHEL, Rocky, AlmaLinux) ядро останавливает NGINX от открытия соединения с Redis, пока вы не разрешите это один раз — setsebool -P httpd_can_network_connect 1. Пропустите это, и репликация молча ничего не делает, пока местное принуждение продолжается как обычно.

Одна блокировка, каждый узел — без замедления единственного запроса

За балансировщиком нагрузки блокировка на сервере — это театр: атакующий просто попадает на другой узел. Abuse Guard закрывает этот разрыв без того, чтобы когда-либо ставить Redis на путь запроса.

Каждый узел принимает решение локально и считает локально. В тот момент, когда он выдает блокировку, он передает этот факт кластеру и записывает долговечную копию. Каждый другой узел импортирует ее в течение миллисекунд, и любой узел, который был оффлайн, согласовывает это в момент повторного подключения. Поскольку принуждение всегда обслуживается из собственного состояния в памяти каждого узла, запрос посетителя никогда не ждет сетевого раунда — единственная стоимость кластеризации заключается в том, что свежезаблокированный атакующий исключается из флота на сердцебиение позже, а не мгновенно.

Redis здесь — это односторонний сигнал тревоги, а не общий журнал, который запрашивается по запросу — поэтому медленный или отсутствующий Redis никогда не может добавить задержку к вашему трафику. Запускайте его в частной сети и рассматривайте как привилегированный: все, что может записать в него, может выдавать блокировки.

Блокировки, которые переживают перезапуск

Укажите зону на файл, и активные блокировки будут сброшены, когда рабочий процесс корректно завершится, затем восстановлены при запуске. Перезагрузки и упорядоченные перезапуски сохраняют текущие блокировки, не запуская периодический писатель для всей зоны. Внезапный сбой процесса или машины может привести к потере блокировок, выданных с момента последнего чистого выхода; принуждение все равно остается открытым.

abuse_guard_zone zone=clients:10m
                 persist=/var/lib/nginx/abuse_guard/clients.state
                 persist_secret=00112233445566778899aabbccddeeff;

Компактный снимок содержит только дайджесты идентичностей и сроки блокировок. CRC32 обнаруживает повреждения, а атомарное переименование предотвращает частичные записи в активном пути. Сборки с поддержкой подписанных снимков могут дополнительно аутентифицировать его с помощью persist_secret. Держите директорию доступной только для пользователя рабочего процесса.

Увидьте все, что он решает

Три переменные открывают вердикт Abuse Guard для ваших логов и конфигурации:

Переменная	Значение
`$abuse_guard_status`	`BYPASSED` · `PASSED` · `COUNTED` · `BLOCKED` · `DRY_RUN`
`$abuse_guard_count`	Ошибки, в настоящее время приписанные этому клиенту.
`$abuse_guard_blocked_until`	Unix-время, когда блокировка снимается, или `0`.

log_format guard '$remote_addr "$request" $status '
                 'guard=$abuse_guard_status count=$abuse_guard_count';

Ключевание за CDN или прокси? Никогда не доверяйте сырым X-Forwarded-For. Позвольте realip сначала определить реального клиента, а затем ключевать по $binary_remote_addr:

set_real_ip_from 10.0.0.0/8;
real_ip_header   X-Forwarded-For;
real_ip_recursive on;

Нужна логика освобождения на уровне запроса? Любой запрос, чье key разрешается в пустую строку, игнорируется — так что map позволяет вам, например, отслеживать анонимных посетителей по IP, оставляя аутентифицированных пользователей нетронутыми.

Спроектирован для доверия в производстве

Abuse Guard соответствует стандарту, который значительно выше "он компилируется." Каждое изменение проходит через испытания AddressSanitizer, UndefinedBehaviorSanitizer, Valgrind, статического анализа и непрерывного фуззинга его парсеров и формата на диске. Его опциональные зависимости — кластеризация и подписанные снимки — по сути являются наилучшей попыткой: если Redis или диск ведут себя неправильно, принуждение тихо продолжается из локальной памяти. Ваш трафик никогда не будет удерживаться в заложниках у зависимости.

Получите Abuse Guard

Abuse Guard — это коммерческий модуль NGINX от GetPageSpeed LLC, предоставляемый с постоянными обновлениями и поддержкой через подписку GetPageSpeed.

Просмотрите полный каталог модулей NGINX → https://nginx-extras.getpagespeed.com/modules/
Лицензирование, массовые развертывания или помощь в настройке → getpagespeed.com/contact-us