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

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

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

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

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

wallarm_acl

Позволяет ограничить доступ к ресурсам при наличии IP‑адреса запроса в указанном ACL.

Заданный ACL должен быть объявлен с помощью директивы wallarm_acl_db.

Можно использовать директиву satisfy для установки ограничений одновременно как с помощью ACL, так и с помощью других модулей NGINX, например, ngx_http_access_module.

Значение off отключает проверку ACL.

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

satisfy any;

wallarm_acl wapi;

allow 1.2.3.4/0;
deny all;

Info

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

wallarm_acl_api

Location, где использована эта директива, можно использовать для управления содержимым ACL.

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

location /wallarm-acl {
  allow 127.0.0.1;
  deny all;

  wallarm_acl wapi;
  wallarm_acl_api on;
}

Info

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

wallarm_acl_db

Позволяет объявить и настроить базу ACL для ограничения доступа по IP‑адресам.

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

wallarm_acl_db wapi {
  wallarm_acl_path /var/cache/nginx/wallarm/acl/wapi;
}

Info

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

wallarm_acl_mapsize

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

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

Info

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

wallarm_acl_path

Позволяет задать директорию, которая будет использована для сохранения состояния ACL.

Info

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

wallarm_acl_block_page

Позволяет задать страницу и код ошибки, которые будут возвращены клиенту, если запрос отправлен с заблокированного IP‑адреса. Формат значения директивы: wallarm_acl_block_page &/{path_to_file}/{html_htm_file_name} response_code={custom_code};.

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

  • Возвращать стандартную страницу блокировки Валарм и собственный код ошибки:

    wallarm_acl_block_page &/usr/share/nginx/html/wallarm_blocked.html response_code=445;
    

    Чтобы возвращать код ошибки по умолчанию, опустите response_code=445.

  • Возвращать собственные страницу блокировки и код ошибки:

    # страница block.html, расположенная в директории /usr/share/nginx/html
    # код ошибки 445
    wallarm_acl_block_page &/usr/share/nginx/html/block.html response_code=445;
    

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

  • Возвращать сообщение о блокировке или страницу блокировки и код ошибки, описанные в location:

    # код ошибки 445 и сообщение "The page is blocked"
    wallarm_acl_block_page @block;
    location @block {
        return 445 'The page is blocked';
    }
    
    # код ошибки 445 и страница 445.html, расположенная в директории /usr/share/nginx/html
    wallarm_acl_block_page /err445; # /err445 – location, которому передается запрос
    error_page 445 @blocked;            # По коду 445 передает запрос в location @blocked
    location @blocked {
        root /usr/share/nginx/html;     # Директория файла 445.html
        rewrite ^(.*)$ /445.html break; # Редирект на /445.htm
    }
    location = /err445 {
        internal;                   # Внутренний location, недоступный извне
        return 445;                 # Возращение кода 445
    }
    

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

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

UUID ${request_id}

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

Info

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

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
  use_ssl: true
  ca_verify: true

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

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

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

Info

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

wallarm_block_page

Позволяет задать страницу и код ошибки, которые будут возвращены клиенту при отправке вредоносного запроса. Формат значения директивы: wallarm_block_page &/{path_to_file}/{html_htm_file_name} response_code={custom_code};.

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

  • Возвращать стандартную страницу блокировки Валарм и собственный код ошибки:

    wallarm_block_page &/usr/share/nginx/html/wallarm_blocked.html response_code=445;
    

    Чтобы возвращать код ошибки по умолчанию, опустите response_code=445.

  • Возвращать собственные страницу блокировки и код ошибки:

    # страница block.html, расположенная в директории /usr/share/nginx/html
    # код ошибки 445
    wallarm_block_page &/usr/share/nginx/html/block.html response_code=445;
    

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

  • Возвращать сообщение о блокировке или страницу блокировки и код ошибки, описанные в location:

    # код ошибки 445 и сообщение "The page is blocked"
    wallarm_block_page @block;
    location @block {
        return 445 'The page is blocked';
    }
    
    # код ошибки 445 и страница 445.html, расположенная в директории /usr/share/nginx/html
    wallarm_block_page /err445; # /err445 – location, которому передается запрос
    error_page 445 @blocked;            # По коду 445 передает запрос в location @blocked
    location @blocked {
        root /usr/share/nginx/html;     # Директория файла 445.html
        rewrite ^(.*)$ /445.html break; # Редирект на /445.htm
    }
    location = /err445 {
        internal;                   # Внутренний location, недоступный извне
        return 445;                 # Возращение кода 445
    }
    

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

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

UUID ${request_id}

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

Info

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

wallarm_cache_path

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

Info

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

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: все запросы обрабатываются, но никакие не блокируются даже при обнаружении атак.
  • block: блокируются все запросы, в которых была распознана типизированная атака.

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

geo $wallarm_mode_real {
    default block;
    1.1.1.1/24 monitoring;
    2.2.2.2 off;
}
...

wallarm_mode $wallarm_mode_real;

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

Info

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

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

Отключайте блокировку IP‑адресов сканера Валарм

Обратите внимание, что если вы используете по умолчанию режим блокировки WAF‑ноды (default block;) при распознавании вредоносных запросов, то вам необходимо явно задать список IP‑адресов сканера Валарм, запросы с которых блокироваться не должны.

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

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

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

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: запросы пропускаются
    • 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_set_tag

Позволяет промаркировать запрос тэгом с заданным названием и значением.

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

Эти тэги можно в дальнейшем использовать в подсистеме постаналитики.

Использование:

wallarm_set_tag somename $var;

Info

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

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 выключает распаковку.

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