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

Тонкая настройка WAF‑ноды на основе NGINX

Официальная документация NGINX

Настройка Валарм незначительно отличается от настройки NGINX, о которой рассказано в официальной документации. При работе с Валарм доступны все возможности настройки оригинального веб-сервера NGINX.

Директивы Валарм

disable_acl

Позволяет выключить анализ источников запросов на совпадение с данными из списков IP-адресов. Для выключения необходимо передать в директиве значение on.

Замечание

Параметр может настраиваться в блоках http, server, location.

Значение по умолчанию: off (анализ источников запросов на совпадение с данными из списков IP-адресов включен).

wallarm_api_conf

Задаёт путь к файлу node.yaml, содержащему реквизиты доступа к API Валарм.

Пример:

wallarm_api_conf /etc/wallarm/node.yaml;

Используется для выгрузки сериализованных запросов из WAF‑ноды напрямую в API Валарм (облако) вместо выгрузки
в модуль постаналитики (Tarantool).

В API попадают только запросы с атаками. Запросы без атак не сохраняются.

Пример содержимого файла node.yaml:

# Ваши учетные данные для подключения к API

hostname: <some name>
uuid: <some uuid>
secret: <some secret>

# Параметры подключения к API (указанные ниже используются по умолчанию)

api:
  host: api.wallarm.com
  port: 444
  ca_verify: true

Обратите внимание

Директива wallarm_api_conf влияет на значение директивы wallarm_upstream_backend.

Отправка сериализованных запросов возможна либо в модуль постаналитики, либо в API Валарм.

Info

Параметр может настраиваться только в блоке http.

wallarm_block_page

Позволяет задать страницу и код ошибки, которые будут возвращены клиенту в ответ на заблокированный запрос.

Подробнее о настройке страницы блокировки и кода ошибки →

Info

Параметр может настраиваться в блоках http, server, location.

wallarm_block_page_add_dynamic_path

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

Подробнее о настройке страницы блокировки и кода ошибки →

Info

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

wallarm_cache_path

Директория, в которой при запуске сервера NGINX будет создан каталог backup для хранения копии proton.db и ЛОМ. У пользователя, от которого работает NGINX, должны быть права записи в эту директорию.

Info

Параметр может настраиваться только в блоке http.

wallarm_enable_libdetection

Включает дополнительную валидацию обнаруженных атак типа SQL‑инъекций с использованием алгоритмов библиотеки libdetection. Такой подход реализует двойное обнаружение атак и снижает количество ложных срабатываний.

По умолчанию анализ запросов с помощью libdetection отключен. Чтобы снизить количество ложных срабатываний, мы рекомендуем включить анализ (wallarm_enable_libdetection on).

Подробнее о работе и тестировании библиотеки libdetection

Для корректного анализа тела запросов с помощью libdetection, необходимо включить буферизацию тела запроса клиента (proxy_request_buffering on).

Пример:

wallarm_enable_libdetection on;
proxy_request_buffering on;

Увеличение в количестве потребляемой памяти

При анализе атак с помощью библиотеки libdetection возможно увеличение объема памяти, потребляемой процессами NGINX и Валарм, примерно на 10%.

Info

Параметр может настраиваться в блоках http, server, location.

Чтобы включить libdetection для Ingress‑контроллера Валарм, необходимо применить аннотацию nginx.ingress.kubernetes.io/server-snippet с этим параметром к Ingress.

Значение по умолчанию: off.

wallarm_fallback

При значении on NGINX получает возможность войти в аварийный режим: при невозможности загрузить proton.db/lom данная настройка отключает модуль Валарм для блоков http, server, location, для которых данные не загрузились. Сам NGINX продолжит работать.

Info

Параметр может настраиваться в блоках http, server, location.

wallarm_force

Задает анализ запросов и создание правил ЛОМ на основе зеркалируемого трафика NGINX. Смотрите Анализ зеркалированного трафика с помощью NGINX.

wallarm_global_trainingset_path

Путь к файлу proton.db, содержащему глобальные настройки фильтрации запросов, не зависящие от структуры веб‑приложения.

Замечание

Параметр может настраиваться в блоках http, server, location.

Значение по умолчанию: /etc/wallarm/proton.db

wallarm_file_check_interval

Задает интервал для проверки новых записей в proton.db и ЛОМ. Единица измерения интервала передается в суффиксе, как описано ниже:

  • не указывается для минут,

  • s для секунд,

  • ms для миллисекунд.

Info

Параметр может настраиваться только в блоке http.

Значение по умолчанию: 1 (1 минута)

wallarm_instance

Идентификатор приложения. Используется для визуального отделения данных разных приложений на панели Главная. Допустимы только числовые значения.

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

Любая WAF‑нода будет фильтровать трафик для любого количества приложений без дополнительной настройки.

Info

Параметр может настраиваться в блоках http, server, location.

wallarm_key_path

Путь к лицензионному ключу Валарм.

Info

Значение по умолчанию: /etc/wallarm/license.key

wallarm_local_trainingset_path

Путь к ЛОМ, содержащему информацию о защищаемом веб‑приложении и настройках ноды.

Info

Параметр может настраиваться в блоках http, server, location.

Значение по умолчанию: /etc/wallarm/lom

wallarm_mode

Изменения в логике работы режимов off и monitoring

В версии WAF‑ноды 3.2 изменилась логика работы режимов off и monitoring следующим образом:

  • WAF‑нода не блокирует запросы, отправленные с IP‑адресов из черного списка
  • В режиме мониторинга WAF‑нода выгружает в Облако Валарм данные об атаках, отправленных с IP‑адресов из белого списка

Перед обновлением модулей до версии 3.2 убедитесь, что ожидаемое поведение директивы совпадает с изменениями.

Если вы обнаружили изменения после обновления, пожалуйста, адаптируйте правило под изменения. Подробнее о настройке режима фильтрации

Режим фильтрации трафика:

На возможности работы wallarm_mode влияет значение директивы wallarm_mode_allow_override.

Подробная инструкция по настройке режима фильтрации →

Info

Параметр может настраиваться в блоках http, server, location.

Значение по умолчанию: зависит от формы установки WAF‑ноды (off или monitoring).

wallarm_mode_allow_override

Управляет возможностью переопределять значение директивы wallarm_mode через правила, выгружаемые из облака (ЛОМ):

  • off: правила, заданные в ЛОМ, игнорируются.
  • strict: посредством ЛОМ можно только усилить режим работы.
  • on: можно как усиливать, так и смягчать режим работы.

Например, если задано wallarm_mode monitoring и wallarm_mode_allow_override strict, то через Консоль управления Валарм можно включить блокировку каких-то запросов, но нельзя полностью отключить анализ атак.

Подробная инструкция по настройке режима фильтрации →

Info

Параметр может настраиваться в блоках http, server, location.

Значение по умолчанию: on

wallarm_parse_response

Флаг для включения / выключения анализа ответов приложения. Анализ ответов необходим для определения уязвимостей приложения с помощью пассивного обнаружения и активной проверки атак. Возможные значения: on, off соответственно.

Info

Параметр может настраиваться в блоках http, server, location.

Значение по умолчанию: on

Увеличьте производительность

Рекомендуется отключать обработку статических файлов через Location для увеличения производительности.

wallarm_parse_websocket

Валарм — один из первых продуктов с полной поддержкой WebSockets. По умолчанию сообщения WebSockets не анализируются на предмет атак, этот анализ необходимо принудительно включить с помощью директивы wallarm_parse_websocket.

Возможные значения:

  • on: анализ сообщений включен.
  • off: анализ сообщений не производится.

Info

Параметр может настраиваться в блоках http, server, location.

Значение по умолчанию: off

wallarm_parser_disable

Позволяет отключать парсеры.

В настоящее время поддерживаются следующие парсеры:

  • cookie
  • zlib
  • htmljs
  • json
  • multipart
  • base64
  • percent
  • urlenc
  • xml

Пример

wallarm_parser_disable base64;
wallarm_parser_disable xml;
location /ab {
    wallarm_parser_disable json;
    wallarm_parser_disable base64;
    proxy_pass http://example.com;
}
location /zy {
    wallarm_parser_disable json;
    proxy_pass http://example.com;
}

Info

Параметр может настраиваться в блоках http, server, location.

wallarm_parse_html_response

Флаг для включения / выключения HTML‑парсера ответов приложения. Возможные значения: on, off соответственно.

Директива применяется, только если wallarm_parse_response on.

Info

Параметр может настраиваться в блоках http, server, location.

Значение по умолчанию: on

wallarm_stalled_worker_timeout

Ограничение времени обработки одного запроса рабочим процессом NGINX. Значение задается в секундах.

Если запрос обрабатывается дольше указанного времени, информация о рабочих процессах NGINX записывается в параметры статистики stalled_workers_count и stalled_workers.

Info

Параметр может настраиваться в блоках http, server, location.

Значение по умолчанию: 5 (5 секунд)

wallarm_process_time_limit

Ограничение времени обработки одного запроса, значение задается в миллисекундах.

Если запрос обрабатывается дольше, чем время, указанное в параметре wallarm_process_time_limit, то в лог пишется ошибка, а запрос помечается как атака overlimit_res. В режиме блокировки (wallarm_mode block;) запросы блокируются, в режиме мониторинга (wallarm_mode monitoring;) — пропускаются.

Info

Параметр может настраиваться в блоках http, server, location.

Значение по умолчанию: 1000 мс (одна секунда).

wallarm_process_time_limit_block

Возможность управлять блокировкой запросов, превысивших лимит времени, заданный в параметре wallarm_process_time_limit.

  • off: запросы всегда пропускаются.
  • on: запросы всегда блокируются.
  • attack: зависит от режима блокировки атаки, заданного в параметре wallarm-mode:
    • off: запросы не фильтруются.
    • monitoring: запросы пропускаются, но информация об атаке overlimit_res выгружается в Облако Валарм и отображается в Консоли управления.
    • safe_blocking: запросы с IP-адресов из серого списка блокируются. Остальные запросы пропускаются, но информация об атаке overlimit_res выгружается в Облако Валарм и отображается в Консоли управления.
    • block: запросы блокируются.

Info

Параметр может настраиваться в блоках http, server, location.

Значение по умолчанию: wallarm_process_time_limit_block attack

wallarm_request_memory_limit

Ограничение на максимальный объем памяти, который может быть использован в процессе анализа одного запроса.

При превышении значения анализ запроса будет прерван, пользователю вернется ошибка 500.

В значении можно использовать следующие суффиксы:

  • k или K для указания размера в килобайтах;

  • m или M для указания размера в мегабайтах;

  • g или G для указания размера в гигабайтах.

Значение 0 отключает ограничения.

По умолчанию ограничение отключено.

Info

Параметр может настраиваться в блоках main, http, server, location.

wallarm_proton_log_mask_master

Настройки отладочного логирования Валарм при работе master-процесса NGINX.

Настройка директивы

Эта директива предназначена для служебного использования.

Ее необходимо настроить только если вас попросит об этом сотрудник технической поддержки Валарм. В этом случае вам также будет предоставлено значение, которое необходимо задать для директивы.

Info

Параметр может настраиваться на уровне main.

wallarm_proton_log_mask_worker

Настройка отладочного логирования Валарм при работе worker-процесса NGINX.

Настройка директивы

Эта директива предназначена для служебного использования.

Ее необходимо настроить только если вас попросит об этом сотрудник технической поддержки Валарм. В этом случае вам также будет предоставлено значение, которое необходимо задать для директивы.

Info

Параметр может настраиваться на уровне main.

wallarm_request_chunk_size

Ограничивает размер части параметра, обрабатываемой за одну итерацию. Вы можете установить собственное значение директивы wallarm_request_chunk_size в байтах, присвоив ей числовое значение. Директива также поддерживает значения с постфиксами:

  • k или K для указания размера в килобайтах;

  • m или M для указания размера в мегабайтах;

  • g или G для указания размера в гигабайтах.

Info

Параметр может настраиваться в блоках http, server, location.

Значение по умолчанию: 8k (8 килобайт).

wallarm_tarantool_connect_attempts

Директива устарела

В данный момент доступна аналогичная ей директива wallarm_upstream_connect_attempts

wallarm_tarantool_connect_interval

Директива устарела

В данный момент доступна аналогичная ей директива wallarm_upstream_reconnect_interval

wallarm_tarantool_upstream

Директива для задания адресов серверов. При помощи директивы wallarm_tarantool_upstream вы можете распределять запросы между несколькими серверами постаналитки.

Пример использования:

upstream wallarm_tarantool {
    server 127.0.0.1:3313 max_fails=0 fail_timeout=0 max_conns=1;
    keepalive 1;
}

    # omitted

wallarm_tarantool_upstream wallarm_tarantool;

Смотрите также Модуль ngx_http_upstream_module.

Необходимые условия

Для параметров max_conns и keepalive необходимо соблюдать следующие условия:

  • Значение keepalive должно быть не меньше, чем количество серверов tarantool.
  • Значение max_conns должно быть указано для каждого сервера, чтобы предотвратить создание лишних соединений.

Info

Параметр может настраиваться только в блоке http.

wallarm_timeslice

Ограничение времени одной итерации обработки запроса WAF‑нодой до переключения на следующий запрос. По достижению этого лимита времени WAF‑нода перейдет к обработке следующего запроса в очереди. После совершения одной итерации обработки для всех других запросов очередь снова перейдет к первому запросу.

Вы можете использовать суффиксы интервалов времени, описанные в документации nginx, для задания различных единиц времени в качестве значения директивы.

Info

Параметр может настраиваться в блоках http, server, location.

Значение по умолчанию: 0 (временное ограничение на одну итерацию обработки выключено).

Warning

В связи с ограничениями сервера nginx, для работы директивы wallarm_timeslice необходимо отключить буферизацию запросов. Для этого установите значение off в директиве nginx proxy_request_buffering.

wallarm_ts_request_memory_limit

Ограничение на максимальный объем памяти, который может быть использован одним экземпляром proton.db + lom.

Если в процессе обработки какого-то запроса общий объем памяти будет превышен, то пользователю вернется ошибка 500.

В значении можно использовать следующие суффиксы:

  • k или K для указания размера в килобайтах;

  • m или M для указания размера в мегабайтах;

  • g или G для указания размера в гигабайтах.

Значение 0 отключает ограничения.

Info

Параметр может настраиваться в блоках main, http, server, location.

Значение по умолчанию: 1 ГБ

wallarm_unpack_response

Флаг для включения / выключения распаковки сжатых данных, полученных в ответе приложения. Возможные значения: on, off соответственно.

Директива применяется, только если wallarm_parse_response on.

Info

Значение по умолчанию: on.

wallarm_upstream_backend

Задаёт способ отправки сериализованных запросов – запросы можно отправлять либо в Tarantool, либо в API.

Возможные значения директивы:

  • tarantool,

  • api.

Значения по умолчанию в зависимости от других директив:

  • tarantool – в конфигурации нет директивы wallarm_api_conf;

  • api – в конфигурации есть директива wallarm_api_conf, но отсутствует wallarm_tarantool_upstream.

    Обратите внимание

    Если в конфигурации одновременно присутствуют директивы wallarm_api_conf и wallarm_tarantool_upstream – возникнет ошибка конфигурации вида directive ambiguous wallarm upstream backend.

Info

Параметр может настраиваться только в блоке http.

wallarm_upstream_connect_attempts

Задаёт количество немедленных попыток повторного соединения с Tarantool или API Валарм.

Если соединение с Tarantool или API разрывается, то попытки повторного соединения не происходит, кроме случая,
когда соединений больше не остаётся, а очередь сериализованных запросов не пуста.

Info

Повторное соединение может происходить с другим сервером, т.к. за выбор сервера ответственна подсистема upstream.

Параметр может настраиваться только в блоке http.

wallarm_upstream_reconnect_interval

Задает интервал между попытками переподключения к Tarantool или API Валарм после того, как количество неудачных попыток превысило порог wallarm_upstream_connect_attempts.

Info

Параметр может настраиваться только в блоке http.

wallarm_upstream_connect_timeout

Задает время таймаута на подключение к Tarantool или API Валарм.

Info

Параметр может настраиваться только в блоке http.

wallarm_upstream_queue_limit

Задает лимит на количество сериализованных запросов.

Установка параметра wallarm_upstream_queue_limit и отсутствие параметра wallarm_upstream_queue_memory_limit означает отсутствие лимита по последнему.

Info

Параметр может настраиваться только в блоке http.

wallarm_upstream_queue_memory_limit

Задает лимит на суммарный объём сериализованных запросов.

Установка параметра wallarm_upstream_queue_memory_limit и отсутствие параметра wallarm_upstream_queue_limit означает отсутствие лимита по последнему.

Info

Значение по умолчанию: 100m.

Параметр может настраиваться только в блоке http.

wallarm_worker_rlimit_vmem

Директива устарела

В данный момент доступна аналогичная ей директива wallarm_ts_request_memory_limit