Внутренние переменные#

Некоторые параметры конфигурационных элементов SOWA могут принимать в качестве аргументов внутренние переменные SOWA.

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

Примерами использования внутренних переменных SOWA могут являться:

Генерация определенных ответов клиенту в зависимости от типа ошибки или причины блокировки запроса;
Динамический выбор группы балансировки, основывающийся на URI запроса и значении cookie;
Простановка в заголовок X-Forwarded-For значения IP-адреса клиента из IP-пакета.

Перечень внутренних переменных#

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

Базовые переменные nginx

С исходной документацией Nginx можно ознакомиться на официальном сайте: https://nginx.org/ru/docs/varindex.html

Служебные переменные SOWA

Имя переменной	Описание
$service_name	Хранит значение, которое задано в опциональном поле name сервиса. Если поле name не задано, переменная не существует.
$upstream_name	Хранит значение, которое задано в обязательном поле upstream_group_id сервиса. Поле upstream_group_id определено для сервисов: - service_http_proxy; - service_web_socket_proxy; - service_cache; - service_file_transfer.
$profile_name	Задает имя профиля.

При переходе запроса из main_proxy в другие *_proxy некоторые переменные nginx, содержащие сведения о клиенте, преобразуются.

Для получения оригинального значения переменных введены:

Имя переменной	Описание
$original_http_host	= $http_host до преобразований
$original_http_forwarded	= $http_forwarded до преобразований
$original_server_addr	= $server_addr до преобразований
$original_server_name	= $server_name до преобразований
$original_server_port	= $server_port до преобразований
$original_remote_addr	= $remote_addr до преобразований
$original_remote_port	= $remote_port до преобразований
$original_scheme	= $scheme до преобразований
$formatted_original_remote_addr	= $original_remote_addr для адресов IPv4 = «$original_remote_addr» для адресов IPv6

Данные переменные возможно использовать при модификации заголовков.

Переменные EventHook модуля SOWA

Наименование	Точка входа	Описание
$client_request_headers	client_request	Список хедеров запроса в виде: »Имя1: Значение1», »Имя2: Значение2». Пример: {«Connection»: «close»,»Content-Length»: «1518»,»accept»: «application/json»,»Content-Type»: «application/json»,»User-Agent»: «Apache-HttpClient/4.5.5 (Java/1.8.0_212)»}
$client_request_body	client_request	Исходное тело запроса
$client_request_cookies	client_request	Список cookie исходного запроса в формате «cookie1: значение», «cookie2: значение»
$upstream_request_headers	upstream_request	Список хедеров запроса на апстрим в виде: »Имя1: Значение1», »Имя2: Значение2»
$upstream_request_body	upstream_request	Тело запроса, исходящего на апстрим
$upstream_response_headers	upstream_response	Список хедеров ответа от апстрима в виде: »Имя1: Значение1», »Имя2: Значение2»
$upstream_response_body	upstream_response	Тело ответа от upstream
$client_response_headers	client_response	Список хедеров ответа клиенту в виде: »Имя1: Значение1», »Имя2: Значение2»
$client_response_body	client_response	Тело ответа клиенту
$client_request_time	client_request	Время фиксации события поступления запроса от клиента
$upstream_request_time	upstream_request	Время фиксации события начала отправки запроса на backend
$upstream_real_response_time	upstream_response	Время фиксации события поступления данных от backend
$client_response_time	client_response	Время фиксации события начала отправки данных клиента
$upstream_response_state_in	client_response	Содержит один из HTTP статусов ответа с upstream - 400; - 403; - 504; - 502.
$upstream_response_state	upstream_response	HTTP статус ответа от upstream
$upstream_request_method	upstream_request	HTTP-метод запроса исходящего на backend
$upstream_request_url	upstream_request	URL исходящего на backend запроса
$upstream_request_scheme	upstream_request	Протокол запроса исходящего на backend
$client_request_uri	client_request	URI исходного запроса клиента
$client_request_method	client_request	HTTP метод исходного запроса клиента
$client_request_scheme	client_request	Протокол исходного запроса клиента
$upstream_request_cookies	upstream_request	Список cookie запроса на upstream в формате «cookie1: значение», «cookie2: значение»
$upstream_response_set_cookies	upstream_response	Список header Set-Cookie ответа от upstream в формате »Set-Cookie: name=value»,»Set-Cookie: name2=value1»
$client_response_set_cookies	client_response	Список header Set-Cookie ответа клиента в формате »Set-Cookie: name=value»,»Set-Cookie: name2=value1»
$upstream_request_header_Имя_Хедера	upstream_request	Значение произвольного указанного заголовка запроса, исходящего на backend
$upstream_response_header_Имя_Хедера	upstream_response	Значение произвольного указанного заголовка ответа от backend
$upstream_request_cookie_Имя_Хедера	upstream_request	Значение произвольной указанной cookie запроса на backend
$ucs_session_id	client_request	Идентификатор исходного запроса клиента. Вычисляется следующим образом: Берется значение из заголовков в порядке: rquid, ucs-session_id, ufs-session-id
$client_request_status	client_request	Статус прохождения точки client_request. SUCCESS — успешно ERROR — ошибка
$upstream_request_status	upstream_request	Статус прохождения точки usptream_request. SUCCESS — успешно ERROR — ошибка
$upstream_response_status	upstream_response	Статус прохождения точки upstream_response. SUCCESS — успешно ERROR — ошибка
$client_response_status	client_response	Статус прохождения точки upstream_response. SUCCESS — успешно ERROR — ошибка
$client_request_timestamp	client_request	Метка времени начала обработки запроса (UNIX timestamp)
$upstream_request_timestamp	upstream_request	Метка времени начала отправки запроса на backend (UNIX timestamp)
$upstream_real_response_timestamp	upstream_response	Метка времени начала получения ответа от backend (UNIX timestamp)
$client_response_timestamp	client_response	Метка времени старта отправки ответа клиенту (UNIX timestamp)

Переменные upstream модуля SOWA

Имя переменной	Описание
$upstream_broken_connection	Содержит флаг обрыва HTTP сессии внешним сервисом до таймаута шлюза
$upstream_response_state	HTTP статус ответа от backend
$upstream_real_server_name	IP адрес backend
$upstream_real_server_port	Порт backend
$upstream_server_host	Имя хоста backend на который был отправлен запрос (равен указанному имени сервера в директиве upstream)

Переменные модулей health_check и upstream_ssl SOWA

Имя переменной	Описание
$upstream_server_name	Имя сервера из конфигурационного файла «as is» для использования в заголовке Host (модуль health_check, параметр http_send_headers) и в ssl_name (модуль upstream_ssl).
$upstream_server_host	Имя хоста (без порта) из конфигурационного файла для использования в заголовке Host (модуль health_check, параметр http_send_headers) и в ssl_name (модуль upstream_ssl).

Переменные фильтра SOWA MDS

Имя переменной	Описание
$msc_intervention_done	Содержит признак того, что process_intervention уже выполнялась (yes/no)
$msc_intervention_status	Служебная переменная. Содержит статус код при выполнении process_intervention
$msc_rules	Служебная переменная. Содержит ссылки на исходный RuleSet при переходе в location Nginx, где не объявлен ModSecurity
$msc_disruptive	Флаг - прерван ли запрос/ответ (1/0)
$msc_tags	Содержит список тегов правила, прервавшего запрос/ответ

Переменные валидаторов

Имя переменной	Описание
$validation_error_code	-1 — Ошибка при загрузке схемы 1 — Ошибка при работе со схемой 2 — Не найдено подходящее правило для проверки 3 — Объект не является JSON/XML 4 — Ошибка валидации 5 — Отсутствуют данные для валидации 6 — Возникло внутреннее исключение 7 — Возникло необработанное исключение при выполнении трансформации 8 — Возникло необработанное исключение при загрузке трансформации
$validation_error_desciption	Не используется
$validation_error_description_ext	Сообщение возникшего исключения в Java handler
$validation_phase	Фаза валидации. Возможные значения: - REQUEST; - RESPONSE.
$request_validation_schema	Содержимое схемы валидации запроса
$response_validation_schema	Содержимое схема валидации ответа

Переменные kafka модуля SOWA

Имя переменной	Описание
$kafka_request_body	Содержимое тела запроса

Переменные MQ модуля SOWA

Имя переменной	Описание
$completion_code	MQ Completion Code. Возможные значения на примере MQ версии 7.1.0
$reason_code	MQ Reason Code. Возможные значения на примере MQ версии 7.1.0
$connection_state	Состояние соединения с менеджером MQ. Возможные значения: -1; -0.
$ok_msg_cnt	Количество сообщений, которые были успешно помещены в очередь
$error_msg_cnt	Количество сообщений, которые не были помещены в очередь из-за ошибки
$warn_msg_cnt	Количество сообщений, которые были успешно помещены в очередь с предупреждением о некритической ошибке
$uncommited_msg_cnt	Количество сообщений, которые были успешно помещены в очередь, но SOWA не смогла осуществить коммит
$active_con_cnt	Количество активных подключений к менеджеру MQ
$problem_con_cnt	Количество неудачных попыток подключения к менеджеру MQ

Переменные Robot Mitigation модуля SOWA

Имя переменной	Описание
$robot_mitigation_blacklist	Количество срабатываний проверки модуля, после которого, IP, с которого пришел запрос, добавляется в черный список

Переменные постобработчика

Имя переменной	Описание
$bad_request_status_cause	Переменная, хранящая внутренний Nginx статус для Bad Request. Возможные значения: 497 — Plain Request sent to https port; 496 — No required cert; 495 — Cert error; 494 - Header to large.

Переменные модуля КриптоПро SSPI

Имя переменной	Описание
sspi_protocol	Протокол установленного SSPI-соединения
sspi_cipher	Описывает разрешенные шифры. Шифры задаются в формате, поддерживаемом библиотекой КриптоПро SSPI
sspi_session_id	Идентификатор сессии установленного SSPI-соединения
sspi_session_reused	Возвращает “r”, если сессия была использована повторно, иначе “.”
sspi_server_name	Имя сервера, запрошенное через SNI
sspi_alpn_protocol	Протокол, выбранный при помощи ALPN во время операции SSPI handshake, либо пустую строку
sspi_client_cert	Клиентский сертификат для установленного SSPI-соединения в формате PEM перед каждой строкой которого, кроме первой, вставляется символ табуляции
sspi_client_raw_cert	Клиентский сертификат для установленного SSPI-соединения в формате PEM
sspi_client_escaped_cert	Клиентский сертификат в формате PEM (закодирован в формате urlencode) для установленного SSPI-соединения
sspi_client_s_dn	Строка “subject DN” клиентского сертификата для установленного SSPI-соединения согласно RFC 2253
sspi_client_s_dn_base64	Строка “subject DN” клиентского сертификата для установленного SSPI-соединения в формате base64
sspi_client_i_dn	Строка “issuer DN” клиентского сертификата для установленного SSPI-соединения согласно RFC 2253
sspi_client_i_dn_base64	Строка “issuer DN” клиентского сертификата для установленного SSPI-соединения в формате base64
sspi_client_s_dn_legacy	Строка “subject DN” клиентского сертификата для установленного SSPI-соединения
sspi_client_i_dn_legacy	Строка “issuer DN” клиентского сертификата для установленного SSPI-соединения
sspi_client_serial	Серийный номер клиентского сертификата для установленного SSPI-соединения
sspi_client_v_start	Дата начала срока действия клиентского сертификата
sspi_client_v_end	Дата окончания срока действия клиентского сертификата
sspi_client_fingerprint	SHA1-отпечаток клиентского сертификата для установленного SSPI-соединения
sspi_client_verify	Результат проверки клиентского сертификата: “SUCCESS”, “FAILED:reason” и, если сертификат не был предоставлен, “NONE”.