UPL (UserGate Policy Language) — язык описания политик UserGate. Термин «политика» употребляется здесь в контексте конфигурации правил, применяемых для принятия решений по требованиям аутентификации, правам доступа или преобразования контента.

Общие положения языка UPL

Правила настраиваются с использованием действий, условий и свойств.

Для каждого правила настраивается одно из действий. Действия — настройки, которые управляют обработкой транзакции (OK, WARNING, PASS, DENY, FORCE_PASS, FORCE_DENY). При настройке правил, в которых не предусмотрено указание действия (например, правила DNS, NAT и маршрутизации, пропускной способности и т.п.), необходимо указать действия PASS или OK.

Условия задаются знаками равно (=) или не равно (!=), например, зоны, адреса, GeoIP источников и назначения, сервисы, приложения и т.д.; все условия в правиле проверяются по логическому И, т.е. правило сработает, если будут выполнены все условия.

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

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

UPL используется для помощью UPL в интерфейсе CLI создаются правила политик сети и безопасности для следующих разделов:

Настройки DNS-прокси (уровень: network dns dns-proxy dns-rules).
Сaptive-портал (уровень: users captive-portal).
Межсетевой экрана (уровень: network-policy firewall).
NAT и маршрутизация (уровень: network-policy nat-routing).
Пропускная способность (уровень: network-policy traffic-shaping).
Фильтрация контента (уровень: security-policy content-filtering).
Веб-безопасность (уровень: security-policy safe-browsing).
Инспектирование туннелей (уровень: security-policy tunnel-inspection).
Инспектирование SSL (уровень: security-policy ssl-inspection).
Инспектирование SSH (уровень: security-policy ssh-inspection).
СОВ (уровень: security-policy intrusion-prevention).
Защита почтового трафика (уровень: security-policy mail-security).
ICAP-правила (уровень: security-policy icap-rules).
Правила защиты DoS (уровень: security-policy dos-rules).
Веб-портал (уровень: global-portal web-portal).
Правила reverse-прокси (уровень: global-portal reverse-proxy-rules).
Серверные правила VPN (уровень: vpn server-rules).
Клиентские правила VPN (уровень: vpn client-rules).

Структура команды для создания правила:

Admin@nodename# create <level> <position> upl-rule <str-upl-syntax>

где <level> — уровень, на котором необходимо создать правило.

<position> — позиция, на которую будет помещено правило.

<str-upl-syntax> строка, в которой описано правило в UPL синтаксисе.

Структура команды для обновления существующего правила:

Admin@nodename# set <level> <position> upl-rule <str-upl-syntax>

где <level> — уровень, на котором необходимо обновить правило.

<position> — номер правила, которое необходимо обновить.

<str-upl-syntax> строка, в которой описано правило в UPL синтаксисе.

Структура команды для удаления правила:

Admin@nodename# delete <level> <position | all>

где <level> — уровень, на котором необходимо удалить правило.

<position> — номер правила, которое необходимо удалить.

<all> — удалить все правила.

Структура команды для отображения правила:

Admin@nodename# show <level> <position | all>

где <level> — раздел, правила которого нужно отобразить.

<position> — номер правила, которое необходимо отобразить.

<all> — отобразить все правила.

Пример создания правила межсетевого экрана с использованием UPL (использован многострочный ввод):

Admin@nodename# create network-policy firewall 1 upl-rule \
...DENY \
...src.zone = Trusted \
...dst.zone = Untrusted \
...user = known \
...service = HTTPS \
...time = lib.time("Working hours") \
...rule_log(session)\
...name("Example of firewall rule created in CLI") \
...enabled(true)

После создания правило отобразиться в начале списка правил межсетевого экрана (на позиции 1). Данное правило запрещает HTTPS-трафик из зоны "Trusted" в зону "Untrusted" пользователям, идентифицированным системой. Правило работает в соответствии с расписанием "Working hours". При срабатывании правила в журнал будет записана информация о начале сессии.

Любая строка, начинающаяся с символа "%", является комментарием.
Символ процента "%" после пробела или табуляции вводит комментарий, который продолжается до конца строки (кроме случаев, когда символ процента отображается внутри кавычек (""), как часть выражения).

Пример:

% Это комментарий
DENY("Too many Host headers") request.header.Host.count = 2..  % и это тоже

Комментарии могут быть в любом месте файла с описанием политик.

Правила

Правило политики (rule) состоит из условий и некоторого количества действий, записанных в любом порядке. Есть также свойства (properties), которые синтаксически выглядят как действие, но при этом активных действий не производят. Например, свойство name просто добавляет атрибут "имя" в правило.

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

Когда правило выполняется, условие проверяется для текущей конкретной транзакции. Если условие оценивается как True (истина), выполняются все перечисленные действия и текущий слой заканчивается при наличии префиксов PASS / FORCE_PASS / DENY / FORCE_DENY / WARNING / OK. Ecли сработавшее правило не имеет префиксов PASS / FORCE_PASS / DENY / FORCE_DENY / WARNING / OK, то выполняются действия и дальше обрабатывается уже следующее правило. Если условие оценивается как False для этой транзакции, то дальше обрабатывается уже следующее правило.

Все условия в правиле проверяются по логическому "И". Другими словами, правило сработает, когда будут выполнены все условия.

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

Действия — это настройки, которые управляют обработкой транзакции. Например, запретить (deny) или обработать объект (изменить заголовок — rewrite).

Синтаксис:

Conditions ::= condition '\'? Conditions

Actions ::= action '\'? Actions

Пример:

Запрос будет запрещен, когда сработают оба триггера:

домен будет example.com
время будет между 9 и 17 часами

DENY url.domain = "example.com" time=09:00..17:00

Слои

Слой (layer)— это конструкция UPL, используемая для группировки правил и принятия одного решения. Раздельные принятия решения помогают контролировать сложность политики. Это делается путем написания каждого решения в отдельном слое.

У любого правила в слое может быть префикс PASS / FORCE_PASS / DENY / FORCE_DENY / OK / WARNING, когда срабатывает правило с таким префиксом, все остальные правила в слое пропускаются.

В случае если сработало правило с префиксом FORCE_PASS или FORCE_DENY, то это является окончательным результатом обработки, в противном случае обработка переходит на следующий слой. После обработки всех слоев запрос будет заблокирован или пропущен в зависимости от того, что было последним — PASS / FORCE_PASS или DENY / FORCE_DENY. Если процессинг остановится на WARNING, будет добавлено предупреждение в тело ответа.

Префикс OK подразумевает остановку обработки правил в текущем слое при выполнении условий и действий (если таковые указаны). Если префикс отсутствует при выполнении условий и действий, то остановка не подразумевается.

Действия FORCE_PASS и FORCE_DENY похожи на PASS и DENY, за исключением того, что они могут быть переопределены на последующих слоях. FORCE_DENY и FORCE_PASS немедленно прекращают поверку правил как на текущем, так и на последующих слоях, и этот результат является окончательным.

Синтаксис:

Layer ::= '[' layer_type layer_name ']'

layer_name ::= string

atom ::= [a-z][0-9a-zA-Z_]+

string ::= '"' произвольная строка '"'

Пример 1:

[content "L1"]
DENY enabled(true) % по умолчанию все запрещено
 
[content "Devs"]
DENY group != Developers enabled(true)
%... дальше идут правила, которые будут применяться только для группы Developers

Пример 2:

[content "Admin"]
FORCE_PASS group = Admins enabled(true)
  
[content "L2"]
DENY enabled(true) % по умолчанию все запрещено

Динамические значения

Значения "адрес запроса" (url, url.host, url.path), "IP-адрес источника/назначения" (src.ip, dst.ip), "имя пользователя" (user), "значения заголовков" (request и response) и "параметры запроса" (qparam) могут сравниваться между собой, а также использоваться в качестве аргумента в действиях (actions), где это предусмотрено.