Перейти к содержанию

Настройка страницы блокировки и кода ошибки (NGINX)

Данная инструкция описывает способ настройки страницы и кода ошибки, которые возвращаются клиенту в ответ на запрос, заблокированный по следующим причинам:

Ограничения настройки

Настройка страницы блокировки и кода ошибки поддерживается во всех формах деплоя WAF-ноды на основе NGINX. Для Docker-контейнера на основе Envoy данная настройка недоступна, в ответ на заблокированные запросы WAF-нода будет по умолчанию возвращать код 403.

Способы настройки

По умолчанию, в ответ на заблокированный запрос возвращаются код ошибки 403 и стандартная страница блокировки NGINX. Вы можете изменить настройки по умолчанию, используя следующие директивы NGINX:

  • wallarm_block_page

  • wallarm_block_page_add_dynamic_path

Директива NGINX wallarm_block_page

В директиве wallarm_block_page можно передать следующие параметры страницы блокировки и кода ошибки:

  • Путь до HTM- или HTML-файла со страницей блокировки. В качестве страницы блокировки вы можете использовать как собственную страницу, так и страницу, которую предоставляет Валарм. Страница блокировки Валарм расположена в файле /usr/share/nginx/html/wallarm_blocked.html и имеет следующий вид:

    Страница блокировки Валарм

  • Текст сообщения, который необходимо вернуть в ответе на заблокированный запрос.

  • URL, на который необходимо перенаправить клиента.

  • respose_code: код ответа на заблокированный запрос.

  • type: тип заблокированного запроса, в ответе на который необходимо вернуть заданную конфигурацию. Параметр может принимать одно или несколько значений (через запятую) из списка:

    • attack (по умолчанию): для запросов с признаками атак, которые были заблокированы WAF-нодой в режиме блокировки или мягкой блокировки (при условии, что источник запроса добавлен в серый список).
    • acl_ip: для запросов с IP-адресов, которые добавлены в черный список как одиночные адреса или в составе подсети.
    • acl_source: для запросов с IP-адресов, которые зарегистрированы в стране или дата-центре из черного списка.

Перечисленные параметры можно передать в директиве wallarm_block_page следующими способами:

  • Путь до HTM- или HTML-файла со страницей блокировки, код ошибки (опционально) и тип заблокированного запроса (опционально)

    wallarm_block_page &/<PATH_TO_FILE/HTML_HTM_FILE_NAME> response_code=<CUSTOM_CODE> type=<BLOCKED_REQUEST_TYPE>;
    

    Вы можете использовать переменные NGINX на странице блокировки. Для этого вставьте в код страницы имя переменной в {}, начиная с символа $. Например, ${remote_addr} отобразит на странице блокировки IP‑адрес, с которого отправлен запрос.

    Валарм предоставляет стандартную страницу блокировки. Чтобы ее использовать, необходимо передать в директиве следующий путь: &/usr/share/nginx/html/wallarm_blocked.html.

    Важная информация для пользователей Debian и CentOS

    Если вы используете NGINX версии ниже 1.11, установленный из репозиториев CentOS/Debian, для корректного отображения страницы блокировки необходимо удалить из кода страницы переменную request_id:

    UUID ${request_id}
    

    Удаление переменной требуется при использовании как собственного шаблона динамической страницы, так и wallarm_blocked.html.

    Пример конфигурации →

  • URL для перенаправления клиента и тип заблокированного запроса (опционально)

    wallarm_block_page /<REDIRECT_URL> type=<BLOCKED_REQUEST_TYPE>;
    

    Пример конфигурации →

  • Именованный location NGINX и тип заблокированного запроса (опционально)

    wallarm_block_page @<NAMED_LOCATION> type=<BLOCKED_REQUEST_TYPE>;
    

    Пример конфигурации →

  • Переменная, в которой будет передан путь до HTM- или HTML-файла со страницей блокировки, код ошибки (опционально) и тип заблокированного запроса (опционально)

    wallarm_block_page &<VARIABLE_NAME> response_code=<CUSTOM_CODE> type=<BLOCKED_REQUEST_TYPE>;
    

    Инициализация страницы блокировки с переменными NGINX

    Если вы задаете страницу блокировки через переменную и внутри страницы блокировки также используются переменные NGINX, необходимо инициализировать страницу блокировки с переменными с помощью директивы wallarm_block_page_add_dynamic_path.

    Пример конфигурации →

Директива wallarm_block_page может быть передана в блоках http, server, location конфигурационного файла NGINX.

Директива NGINX wallarm_block_page_add_dynamic_path

Директива wallarm_block_page_add_dynamic_path используется для инициализации страницы блокировки, если внутри страницы используются переменные NGINX и путь до страницы блокировки также задан с помощью переменной. В остальных случаях директива не используется.

Директива wallarm_block_page_add_dynamic_path может быть передана только в блоке http конфигурационного файла NGINX.

Примеры настройки

Ниже приведены примеры настройки страницы блокировки и кода ошибки через директивы wallarm_block_page и wallarm_block_page_add_dynamic_path.

В каждом примере в явном виде передается параметр type с типом запроса, в ответе на который возвращается заданная конфигурация. Если требуется, вы можете удалить параметр type. Тогда заданная конфигурация вернется только в ответе на запросы с признаками атак, заблокированные в режиме блокировки или мягкой блокировки (при условии, что источник запроса добавлен в серый список).

Путь до HTM- или HTML-файла со страницей блокировки и код ошибки

В примере приведены настройки для возвращения клиенту:

  • Стандартной страницы блокировки Валарм и кода ошибки 445 в ответ на запрос, заблокированный WAF-нодой в режиме блокировки или мягкой блокировки (при условии, что источник запроса добавлен в серый список).

  • Собственной страницы блокировки /usr/share/nginx/html/block.html и кода ошибки 445 в ответ на запрос, отправленный с любого IP-адреса из черного списка.

Конфигурационный файл NGINX

wallarm_block_page &/usr/share/nginx/html/wallarm_blocked.html response_code=445 type=attack;
wallarm_block_page &/usr/share/nginx/html/block.html response_code=445 type=acl_ip,acl_source;
  • Чтобы применить настройку к Docker-контейнеру, необходимо примонтировать в контейнер конфигурационный файл NGINX с необходимыми настройками. Если вы используете собственную страницу блокировки, ее также необходимо примонтировать в контейнер. Запуск контейнера с примонтированным конфигурационным файлом →

  • Чтобы применить настройку к sidecar‑контейнеру, необходимо передать директиву в ConfigMap Валарм (инструкция для приложения, опубликованного с использованием Helm Charts или Kubernetes‑манифестов).

Аннотация Ingress

Перед добавлением аннотации Ingress, необходимо:

  1. Создать ConfigMap из файла собственной страницы блокировки block.html.

  2. Примонтировать созданный ConfigMap в pod с Ingress‑контроллером Валарм. Для этого необходимо изменить объект Deployment Ingress‑контроллера Валарм по инструкции.

    Директория для монтирования ConfigMap

    Рекомендуется использовать отдельную директорию для файлов, примонтированных с помощью ConfigMap. При монтировании файлов в существующую директорию, предыдущие файлы в этой директории могут быть удалены.

Аннотация Ingress:

kubectl annotate ingress <INGRESS_NAME> nginx.ingress.kubernetes.io/wallarm-block-page="&/usr/share/nginx/html/wallarm_blocked.html response_code=445 type=attack;&/usr/share/nginx/html/block.html response_code=445 type=acl_ip,acl_source"

URL для перенаправления клиента

В примере приведены настройки для перенаправления клиента на страницу host/err445, если запрос отправлен с IP-адреса, который зарегистрирован в стране или дата-центре из черного списка.

Конфигурационный файл NGINX

wallarm_block_page /err445 type=acl_source;

Аннотация Ingress

kubectl annotate ingress <INGRESS_NAME> nginx.ingress.kubernetes.io/wallarm-block-page="/err445 type=acl_source"

Именованный location NGINX

В примере приведены настройки для возвращения клиенту сообщения The page is blocked и кода ошибки 445 вне зависимости от причины блокировки запроса (режим блокировки, режим мягкой блокировки и источник из серого списка или источник из черного списка).

Конфигурационный файл NGINX

wallarm_block_page @block type=attack,acl_ip,acl_source;
location @block {
    return 445 'The page is blocked';
}

Аннотация Ingress

kubectl annotate ingress <INGRESS_NAME> nginx.ingress.kubernetes.io/server-snippet="location @block {return 445 'The page is blocked';}"
kubectl annotate ingress <INGRESS_NAME> nginx.ingress.kubernetes.io/wallarm-block-page="@block type=attack,acl_ip,acl_source"

Переменная и код ошибки

В зависимости от значения заголовка User-Agent, клиенту, который отправил запрос с одиночного IP-адреса или подсети из черого списка, возвращаются разные страницы блокировки:

  • По умолчанию — стандартная страница блокировки Валарм /usr/share/nginx/html/wallarm_blocked.html. Страница содержит переменные NGINX, поэтому ее необходимо инициализировать в директиве wallarm_block_page_add_dynamic_path.

  • Для пользователей Firefox — /usr/share/nginx/html/block_page_firefox.html (при установке Ingress‑контроллера рекомендуется создать отдельную директорию для примонтированных файлов, например, /usr/custom-block-pages/block_page_firefox.html):

    You are blocked!
    
    IP ${remote_addr}
    Blocked on ${time_iso8601}
    UUID ${request_id}
    

    Страница содержит переменные NGINX, поэтому ее необходимо инициализировать в директиве wallarm_block_page_add_dynamic_path.

  • Для пользователей Chrome — /usr/share/nginx/html/block_page_chrome.html (при установке Ingress‑контроллера рекомендуется создать отдельную директорию для примонтированных файлов, например, /usr/custom-block-pages/block_page_chrome.html):

    You are blocked!
    

    Страница не содержит переменные NGINX, поэтому ее не нужно инициализировать.

Также, вне зависимости от значения заголовка User-Agent, возвращается код 445.

Конфигурационный файл NGINX

wallarm_block_page_add_dynamic_path /usr/share/nginx/html/block_page_firefox.html /usr/share/nginx/html/wallarm_blocked.html;

map $http_user_agent $block_page {
  "~Firefox"  &/usr/share/nginx/html/block_page_firefox.html;
  "~Chrome"   &/usr/share/nginx/html/block_page_chrome.html;
  default     &/usr/share/nginx/html/wallarm_blocked.html;
}

wallarm_block_page $block_page response_code=445 type=acl_ip;
  • Чтобы применить настройку к Docker-контейнеру, необходимо примонтировать в контейнер конфигурационный файл NGINX с необходимыми настройками. Если вы используете собственную страницу блокировки, ее также необходимо примонтировать в контейнер. Запуск контейнера с примонтированным конфигурационным файлом →

  • Чтобы применить настройку к sidecar‑контейнеру, необходимо передать директивы в ConfigMap Валарм (инструкция для приложения, опубликованного с использованием Helm Charts или Kubernetes‑манифестов).

Ingress‑контроллер

  1. Передать в развернутый Helm‑чарт параметр controller.config.http-snippet, используя команду helm upgrade:

    helm upgrade --reuse-values --set controller.config.http-snippet='wallarm_block_page_add_dynamic_path /usr/custom-block-pages/block_page_firefox.html /usr/share/nginx/html/wallarm_blocked.html; map $http_user_agent $block_page { "~Firefox" &/usr/custom-block-pages/block_page_firefox.html; "~Chrome" &/usr/custom-block-pages/block_page_chrome.html; default &/usr/share/nginx/html/wallarm_blocked.html;}' <INGRESS_CONTROLLER_NAME> ingress-chart/wallarm-ingress -n <KUBERNETES_NAMESPACE>
    
  2. Создать ConfigMap из файлов block_page_firefox.html и block_page_chrome.html.

  3. Примонтировать созданный ConfigMap в pod с Ingress‑контроллером Валарм. Для этого необходимо изменить объект Deployment Ingress‑контроллера Валарм по инструкции.

    Директория для монтирования ConfigMap

    Рекомендуется использовать отдельную директорию для файлов, примонтированных с помощью ConfigMap. При монтировании файлов в существующую директорию, предыдущие файлы в этой директории могут быть удалены.

  4. Добавить аннотацию к Ingress:

    kubectl annotate ingress <INGRESS_NAME> nginx.ingress.kubernetes.io/wallarm-block-page='$block_page response_code=445 type=acl_ip'