Фильтр Transformations#

Фильтр Transformations предназначен для преобразования заголовков при выполнении заданных условий.

Механизм Transformations изначально использовался, в том числе, для обработки CORS запросов. В настоящий момент для этих целей рекомендуется использовать обновленный механизм, описанный в разделе «Работа модуля CORS».

transformations - параметры#

Название

Обязательность

Описание

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

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

conditions

Обязательный (если default не задан)

Параметры для проверки, паттерн проверки, метод поиска соответствия и др. Будут использованы условия, описанные в conditions. Если какое-либо условие не описано, то используется значение default

Параметры, описанные в разделе «transformations - conditions»

—

default

Обязательный (если conditions не задан)

Набор действий, используемых по умолчанию. Значение параметра default должно быть уникальным для фильтра transformations в рамках одного сервиса. Будет использовано условие по умолчанию в случае, если действие не описано в conditions

true, false

—

actions

Обязательный

Последовательность действий

Параметры, описанные в разделе «transformations - actions»

—

transformations - conditions#

Название

Обязательность

Описание

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

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

check

Обязательный

Что необходимо проверять

method, request_header, response_header, remote_ip_address

—

name

Обязательный (если check: request_header или check: response_header)

Имя заголовка для проверки

Строковое значение

—

pattern

Обязательный (если string_match не задан)

Regex, определяющий условие соответствия

Строковое значение

—

string_match

Обязательный (если pattern не задан)

Альтернативный метод поиска соответствий (алгоритм Ахо-Корасик), использующийся для поиска подстрок в строке, а также полного соответствия строке (white/blacklist’s). Важно: поиск полного соответствия будет производиться только в том случае, если в начале и в конце строки поиска задан символ привязки \ (см. параметр anchor)

Параметры, описанные в разделе «transformations - string_match»

—

case_sensitive

Опциональный

Соответствует ли шаблон строке регистра или нет

true, false

—

contains

Опциональный

Содержит ли файл со строками проверочное значение

true, false

true

skip_unicode_decoding

Опциональный

Необходимо ли пропускать шаг декодирования Utf8ToUnicode и Unicode для нормализации кириллических символов

true, false

false

transformations - string_match#

Название

Обязательность

Описание

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

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

anchor

Опциональный

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

Текстовое значение

\

file

Обязательный (если strings не задан)

Путь к файлу со списком строк для осуществления проверки. Пример содержимого файла: subdomen.com, \exactdomen.com\

Строковое значение

—

strings

Обязательный (если file не задан)

Последовательность строк для осуществления проверки. Пример: \exactdomen.com\, subdomen.com

Последовательность строковых значений

—

transformations - actions#

Название

Обязательность

Описание

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

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

action

Обязательный

Какое действие, из списка доступных, воспроизвести. Данные действия не рекомендованы к использованию в SOWA. В качестве альтернативы действий add_response_header, add_proxy_header, remove_response_header, remove_proxy_header рекомендуется использовать параметры set_input_headers/set_output_headers с указанием нужных условий (см. раздел Пaраметр modifiers). Для замены действия return рекомендуется использовать совместно действие ConditionChecker с указанием условий и механизм постобработчика

add_response_header, add_proxy_header, remove_response_header, remove_proxy_header, return

—

status_code

Обязательный (если action: return)

Код состояния ответа

Целочисленное значение

—

name

Обязательный (если action: add_response_header, add_proxy_header, remove_response_header, remove_proxy_header)

Заголовок, который необходимо преобразовать

Строковое значение

—

value

Обязательный (если action: add_response_header или add_proxy_header, и value_from_header не задан, и value_from_variable не задан)

Имя, которое будет установлено в заголовок, указанный в поле name

Строковое значение

—

value_from_header

Обязательный (если action: add_response_header или add_proxy_header, и value не задан, и value_from_variable не задан)

Имя заголовка запроса, значение которого будет установлено в заголовок, указанный в поле name

Строковое значение

—

value_from_variable

Обязательный (если action: add_response_header или add_proxy_header, и value не задан, и value_from_header не задан)

Имя переменной, значение которой будет установлено в заголовок, указанный в поле name

remote-address — адрес клиента; ngx-x-forwarded-for — поле заголовка запроса клиента «X-Forwarded-For» и добавленная к нему через запятую переменная remote-address. Если же поле «X-Forwarded-For» в заголовке запроса клиента отсутствует, то значением будет являться переменная remote-address

—

override

Опциональный (если action: add_response_header или add_proxy_header)

Необходимо ли перезаписать текущее значение заголовка

true, false

true

Пример импорта filter_transformations (в примере трансформация полей заголовков осуществляется для первого и третьего сервиса):

service_http_proxy:
  - id: 1
    transformations:
      !include: *profile*_transforms.yml

  - id: 2

  #  transformations:
  #    !include: *profile*_transforms.yml

  - id: 3

    transformations:
      !include: *profile*_transforms.yml

Пример конфигурационного файла profile_transforms.yml:

# MAIN request transformations BEGINNING
- conditions: # 1.1 valid Origin header & invalid X-Forwarded-For header due to mask
    - check: method
      pattern: ^POST|GET$
    - check: request_header
      name: Origin # Assumes that Origin header exists
      string_match:
        file: valid-origins.data
      contains: true
    - check: request_header
      name: X-Forwarded-For
      pattern: ^(25[0-5]|2[0-4][0-9]|[0-1][0-9]{2}|[0-9]{2}|[0-9])(\.(25[0-5]|2[0-4][0-9]|[0-1][0-9]{2}|[0-9]{2}|[0-9])){3}$
      contains: false
  actions:
    - action: add_response_header
      name: Access-Control-Allow-Origin
      value_from_header: Origin
    - action: add_response_header
      name: Access-Control-Allow-Credentials
      value: "true"
    - action: add_proxy_header
      name: X-Forwarded-For
      value_from_variable: remote-address
- conditions: # 1.2 invalid Origin header due to whitelist & invalid X-Forwarded-For header due to mask
    - check: method
      pattern: ^POST|GET$
    - check: request_header
      name: Origin # Assumes that Origin header exists
      string_match:
        file: valid-origins.data
      contains: false
    - check: request_header
      name: X-Forwarded-For
      pattern: ^(25[0-5]|2[0-4][0-9]|[0-1][0-9]{2}|[0-9]{2}|[0-9])(\.(25[0-5]|2[0-4][0-9]|[0-1][0-9]{2}|[0-9]{2}|[0-9])){3}$
      contains: false
  actions:
    - action: add_response_header
      name: Access-Control-Allow-Credentials
      value: "true"
    - action: add_proxy_header
      name: X-Forwarded-For
      value_from_variable: remote-address
- conditions: # 1.3 NO Origin header & invalid X-Forwarded-For header due to mask
    - check: method
      pattern: ^POST|GET$
    - check: request_header
      name: Origin
      pattern: ^$
    - check: request_header
      name: X-Forwarded-For
      pattern: ^(25[0-5]|2[0-4][0-9]|[0-1][0-9]{2}|[0-9]{2}|[0-9])(\.(25[0-5]|2[0-4][0-9]|[0-1][0-9]{2}|[0-9]{2}|[0-9])){3}$
      contains: false
  actions:
    - action: add_response_header
      name: Access-Control-Allow-Credentials
      value: "true"
    - action: add_proxy_header
      name: X-Forwarded-For
      value_from_variable: remote-address
- conditions: # 2.1 valid Origin header & valid X-Forwarded-For header & client IP not in the white list
    - check: method
      pattern: ^POST|GET$
    - check: request_header
      name: Origin # Assumes that Origin header exists
      string_match:
        file: valid-origins.data
      contains: true
    - check: request_header
      name: X-Forwarded-For
      pattern: ^(25[0-5]|2[0-4][0-9]|[0-1][0-9]{2}|[0-9]{2}|[0-9])(\.(25[0-5]|2[0-4][0-9]|[0-1][0-9]{2}|[0-9]{2}|[0-9])){3}$
      contains: true
    - check: remote_ip_address
      string_match:
        file: valid-ip.data
      contains: false
  actions:
    - action: add_response_header
      name: Access-Control-Allow-Origin
      value_from_header: Origin
    - action: add_response_header
      name: Access-Control-Allow-Credentials
      value: "true"
    - action: add_proxy_header
      name: X-Forwarded-For
      value_from_variable: remote-address
- conditions: # 2.2 invalid Origin header due to whitelist & valid X-Forwarded-For header & client IP not in the white list
    - check: method
      pattern: ^POST|GET$
    - check: request_header
      name: Origin # Assumes that Origin header exists
      string_match:
        file: valid-origins.data
      contains: false
    - check: request_header
      name: X-Forwarded-For
      pattern: ^(25[0-5]|2[0-4][0-9]|[0-1][0-9]{2}|[0-9]{2}|[0-9])(\.(25[0-5]|2[0-4][0-9]|[0-1][0-9]{2}|[0-9]{2}|[0-9])){3}$
      contains: true
    - check: remote_ip_address
      string_match:
        file: valid-ip.data
      contains: false
  actions:
    - action: add_response_header
      name: Access-Control-Allow-Credentials
      value: "true"
    - action: add_proxy_header
      name: X-Forwarded-For
      value_from_variable: remote-address
- conditions: # 2.3 NO Origin header due to whitelist & valid X-Forwarded-For header & client IP not in the white list
    - check: method
      pattern: ^POST|GET$
    - check: request_header
      name: Origin
      pattern: ^$
    - check: request_header
      name: X-Forwarded-For
      pattern: ^(25[0-5]|2[0-4][0-9]|[0-1][0-9]{2}|[0-9]{2}|[0-9])(\.(25[0-5]|2[0-4][0-9]|[0-1][0-9]{2}|[0-9]{2}|[0-9])){3}$
      contains: true
    - check: remote_ip_address
      string_match:
        file: valid-ip.data
      contains: false
  actions:
    - action: add_response_header
      name: Access-Control-Allow-Credentials
      value: "true"
    - action: add_proxy_header
      name: X-Forwarded-For
      value_from_variable: remote-address
- conditions: # 3.1 valid Origin header & valid X-Forwarded-For header & client IP in the white list
    - check: method
      pattern: ^POST|GET$
    - check: request_header
      name: Origin # Assumes that Origin header exists
      string_match:
        file: valid-origins.data
      contains: true
    - check: request_header
      name: X-Forwarded-For
      pattern: ^(25[0-5]|2[0-4][0-9]|[0-1][0-9]{2}|[0-9]{2}|[0-9])(\.(25[0-5]|2[0-4][0-9]|[0-1][0-9]{2}|[0-9]{2}|[0-9])){3}$
      contains: true
    - check: remote_ip_address
      string_match:
        file: valid-ip.data
      contains: true
  actions:
    - action: add_response_header
      name: Access-Control-Allow-Origin
      value_from_header: Origin
    - action: add_response_header
      name: Access-Control-Allow-Credentials
      value: "true"
    - action: add_proxy_header
      name: X-Forwarded-For
      value_from_header: X-Forwarded-For
- conditions: # 3.2 invalid Origin header due to whitelist & valid X-Forwarded-For header & client IP in the white list
    - check: method
      pattern: ^POST|GET$
    - check: request_header
      name: Origin # Assumes that Origin header exists
      string_match:
        file: valid-origins.data
      contains: false
    - check: request_header
      name: X-Forwarded-For
      pattern: ^(25[0-5]|2[0-4][0-9]|[0-1][0-9]{2}|[0-9]{2}|[0-9])(\.(25[0-5]|2[0-4][0-9]|[0-1][0-9]{2}|[0-9]{2}|[0-9])){3}$
      contains: true
    - check: remote_ip_address
      string_match:
        file: valid-ip.data
      contains: true
  actions:
    - action: add_response_header
      name: Access-Control-Allow-Credentials
      value: "true"
    - action: add_proxy_header
      name: X-Forwarded-For
      value_from_header: X-Forwarded-For
- conditions: # 3.3 NO Origin header & valid X-Forwarded-For header & client IP in the white list
    - check: method
      pattern: ^POST|GET$
    - check: request_header
      name: Origin
      pattern: ^$
    - check: request_header
      name: X-Forwarded-For
      pattern: ^(25[0-5]|2[0-4][0-9]|[0-1][0-9]{2}|[0-9]{2}|[0-9])(\.(25[0-5]|2[0-4][0-9]|[0-1][0-9]{2}|[0-9]{2}|[0-9])){3}$
      contains: true
    - check: remote_ip_address
      string_match:
        file: valid-ip.data
      contains: true
  actions:
    - action: add_response_header
      name: Access-Control-Allow-Credentials
      value: "true"
    - action: add_proxy_header
      name: X-Forwarded-For
      value_from_header: X-Forwarded-For
# MAIN request transformations END
#
# PREFLIGHT request transformations BEGINNING
- conditions: # valid Origin header
    - check: method
      pattern: ^OPTIONS$
    - check: request_header
      name: Access-Control-Request-Method
      pattern: ^.+$
    - check: request_header
      name: Origin # Assumes that Origin header exists
      string_match:
        file: valid-origins.data
      contains: true
  actions:
    - action: add_response_header
      name: Access-Control-Allow-Headers
      value_from_header: Access-Control-Request-Headers
    - action: add_response_header
      name: Access-Control-Allow-Methods
      value: "POST,GET"
    - action: add_proxy_header
      name: Access-Control-Request-Method
      value: "POST,GET"
    - action: add_response_header
      name: Access-Control-Allow-Origin
      value_from_header: Origin
    - action: add_response_header
      name: Access-Control-Allow-Credentials
      value: "true"
    - action: add_response_header
      name: Access-Control-Max-Age
      value: "600"
    - action: add_response_header
      name: Content-Type
      value: "application/json;charset=UTF8"
    - action: return
      status_code: 200
- conditions: # invalid Origin header due to whitelist
    - check: method
      pattern: ^OPTIONS$
    - check: request_header
      name: Access-Control-Request-Method
      pattern: ^.+$
    - check: request_header
      name: Origin # Assumes that Origin header exists
      string_match:
        file: valid-origins.data
      contains: false
  actions:
    - action: add_response_header
      name: Access-Control-Allow-Headers
      value_from_header: Access-Control-Request-Headers
    - action: add_response_header
      name: Access-Control-Allow-Methods
      value: "POST,GET"
    - action: add_proxy_header
      name: Access-Control-Request-Method
      value: "POST,GET"
    - action: add_response_header
      name: Access-Control-Allow-Origin
      value_from_header: Origin
    - action: add_response_header
      name: Access-Control-Allow-Credentials
      value: "true"
    - action: add_response_header
      name: Access-Control-Max-Age
      value: "600"
    - action: add_response_header
      name: Content-Type
      value: "application/json;charset=UTF8"
    - action: return
      status_code: 500
- conditions: #  NO Origin header
    - check: method
      pattern: ^OPTIONS$
    - check: request_header
      name: Origin
      pattern: ^$
    - check: request_header
      name: Access-Control-Request-Method
      pattern: ^.+$
  actions:
    - action: add_proxy_header
      name: Origin
      value: ""
    - action: add_response_header
      name: Access-Control-Allow-Headers
      value_from_header: Access-Control-Request-Headers
    - action: add_response_header
      name: Access-Control-Allow-Methods
      value: "POST,GET"
    - action: add_proxy_header
      name: Access-Control-Request-Method
      value: "POST,GET"
    - action: add_response_header
      name: Access-Control-Allow-Origin
      value_from_header: Origin
    - action: add_response_header
      name: Access-Control-Allow-Credentials
      value: "true"
    - action: add_response_header
      name: Access-Control-Max-Age
      value: "600"
    - action: add_response_header
      name: Content-Type
      value: "application/json;charset=UTF8"
    - action: return
      status_code: 500
# PREFLIGHT request transformations END
#
# Default action if no conditions matched
- default: true
  actions:
    - action: return
      status_code: 500