Тонкая настройка фильтрующего узла на основе 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;

Параметр может настраиваться в блоках 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;
}

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

wallarm_acl_db

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

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

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

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

wallarm_acl_mapsize

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

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

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

wallarm_acl_path

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

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

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

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

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

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

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

wallarm_block_page

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

Для возвращения заранее заданной страницы при блокировании запроса:

  1. Создайте страницу и сохраните ее на сервере. Например, страницу block.html;
  2. В конфигурационном файле добавьте директиву wallarm_block_page и укажите путь к странице: wallarm_block_page /path/block.html.

    Теперь в качестве ответа при блокировании запроса пользователю будет возвращаться страница block.html.

Для применения заранее заданной конфигурации location при блокировании запроса:

  1. В конфигурационном файле укажите директиву wallarm_block_page с конфигурацией location;
  2. Поместите желаемое сообщение о блокировке в блок location. Например:

     wallarm_block_page @block;
     location @block {'The page is blocked!';}
    

    Страница будет заблокирована с сообщением The page is blocked.

Вместе с изменением страницы блокировки вы также можете менять код ошибки, возвращаемый клиенту. Для этого тоже используется комбинация директив wallarm_block_page и location. В примере ниже клиенту будет возвращаться страница 445.htm и код ошибки 445:

wallarm_block_page /err445;     # /err445 – location, которому передается запрос
error_page 445 @blocked;        # По коду 445 передает запрос в location @blocked
location @blocked {
    root /var/www/errors;       # Директория файла 445.htm
    rewrite ^(.*)$ /445.htm break;  # Редирект на /445.htm
}
location = /err445 {
    internal;                   # Внутренний location, недоступный извне
    return 445;                 # Возращение кода 445
    }

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

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

    Включение переменной NGINX в шаблон страницы блокировки

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

  2. В конфигурационном файле добавьте директиву wallarm_block_page и укажите путь к файлу шаблона в файловой системе, начинающийся с символа &.

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

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

UUID ${request_id}  # Подобную часть кода следует удалить

Это относится как к динамической странице блокировки, предоставляемой Валарм по умолчанию (wallarm_blocked.html), так и к собственному шаблону динамической страницы.

wallarm_cache_path

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

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

wallarm_fallback

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

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

wallarm_force

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

wallarm_global_trainingset_path

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

Замечание

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

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

wallarm_instance

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

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

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

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

wallarm_key_path

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

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

wallarm_local_trainingset_path

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

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

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

wallarm_mode

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

  • off: фильтрация запросов не производится.
  • monitoring: все запросы обрабатываются, но никакие не блокируются даже при обнаружении атак.
  • block: блокируются все запросы, в которых была распознана типизированная атака.
  • aggressive: блокируются все нестандартные запросы. Например, передача строки в поле, в которое обычно передается число. Рекомендуется использовать крайне осторожно.

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

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

wallarm_mode $wallarm_mode_real;

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

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

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

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

Обратите внимание, что если вы используете по умолчанию режим блокировки фильтрующего узла (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, то через облако можно включить блокировку каких-то запросов, но нельзя полностью отключить анализ атак.

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

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

wallarm_parse_response

Режим обработки ответов веб-сервера. По умолчанию обрабатываются только запрос от клиента к веб-серверу.

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

  • on: анализ ответов веб-сервера пассивным сканером уязвимостей (без отправки запросов из облака Валарм).
  • off: анализ ответов не производится.

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

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

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

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

wallarm_parse_websocket

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

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

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

Параметр может настраиваться в блоках 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;
}

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

wallarm_process_time_limit

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

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

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

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

wallarm_process_time_limit_block

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

  • off: запросы всегда пропускаются.
  • on: запросы всегда блокируются.
  • attack: зависит от режима блокировки атаки, заданного в параметре wallarm-mode (monitoring: запросы пропускаются; block и aggressive: запросы блокируются.)

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

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

wallarm_request_memory_limit

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

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

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

  • k или K для указания размера в килобайтах;
  • m или M для указания размера в мегабайтах;
  • g или G для указания размера в гигабайтах.

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

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

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

wallarm_proton_log_mask_master

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

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

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

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

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

wallarm_proton_log_mask_worker

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

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

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

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

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

wallarm_request_chunk_size

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

  • k или K для указания размера в килобайтах;
  • m или M для указания размера в мегабайтах;
  • g или G для указания размера в гигабайтах.

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

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

wallarm_set_tag

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

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

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

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

wallarm_set_tag somename $var;

Параметр может настраиваться в блоках 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;
    }

    ...

    wallarm_tarantool_upstream wallarm_tarantool;

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

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

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

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

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

wallarm_timeslice

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

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

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

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

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

wallarm_ts_request_memory_limit

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

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

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

  • k или K для указания размера в килобайтах;
  • m или M для указания размера в мегабайтах;
  • g или G для указания размера в гигабайтах.

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

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

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

wallarm_unpack_response

Если бэкенд возвращает сжатые данные, то значение on распаковывает данные перед обработкой. Значение off выключает распаковку.

Значение по умолчанию: 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.

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

wallarm_upstream_connect_attempts

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

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

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

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

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

wallarm_upstream_reconnect_interval

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

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

wallarm_upstream_connect_timeout

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

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

wallarm_upstream_queue_limit

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

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

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

wallarm_upstream_queue_memory_limit

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

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

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

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

wallarm_worker_rlimit_vmem

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

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

results matching ""

    No results matching ""