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

Тонкая настройка ноды Валарм на основе 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;

Используется для выгрузки сериализованных запросов из ноды Валарм напрямую в Валарм 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/файл индивидуального набора правил загрузить невозможно, данная настройка отключает модуль Валарм для блоков 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

Уникальный идентификатор для обозначения защищенного приложения в Облаке Валарм. Значение может быть любым целым положительным числом, кроме 0.

Вы можете задать уникальные идентификаторы как для приложений, доступных на отдельных доменах, так и для путей одного домена. Например:

Конфигурационный файл для домена example.com:

server {
    listen 80 default_server;
    listen [::]:80 default_server ipv6only=on;
    listen 443 ssl;

    ...

    wallarm_mode monitoring;
    wallarm_instance 1;

    location / {
            proxy_pass http://example.com;
            include proxy_params;
    }
}

Конфигурационный файл для домена test.com:

server {
    listen 80 default_server;
    listen [::]:80 default_server ipv6only=on;
    listen 443 ssl;

    ...

    wallarm_mode monitoring;
    wallarm_instance 2;

    location / {
            proxy_pass http://test.com;
            include proxy_params;
    }
}
server {
    listen 80 default_server;
    listen [::]:80 default_server ipv6only=on;
    listen 443 ssl;

    ...

    wallarm_mode monitoring;

    location /login {
            proxy_pass http://example.com/login;
            include proxy_params;
            wallarm_instance 3;
    }

    location /users {
            proxy_pass http://example.com/users;
            include proxy_params;
            wallarm_instance 4;
    }
}

Подробнее о настройке приложений →

Info

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

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

wallarm_key_path

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

Info

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

wallarm_local_trainingset_path

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

Info

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

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

wallarm_mode

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

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

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

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

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

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

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

Info

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

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

wallarm_mode_allow_override

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

Например, если задано 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: запросы всегда пропускаются.

    Риск обхода защиты

    Значение off следует использовать с осторожностью, так как оно отключает защиту от атак overlimit_res.

    Рекомендуется устанавливать значение off только для определенных location, где это действительно необходимо и нет риска обхода защиты и эксплуатации уязвимостей. Например: для location, где происходит загрузка больших файлов.

    Категорически не рекомендуется устанавливать значение off глобально (на уровне контекста http).

  • 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

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

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

Info

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

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

Warning

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

wallarm_ts_request_memory_limit

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

Если в процессе обработки какого-то запроса общий объем памяти будет превышен, то пользователю вернется ошибка 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.