Глава 6. Блоки define¶

Блоки define создают именованные переиспользуемые объекты, на которые можно ссылаться из правил по имени. Они размещаются в секции определений файла политики -- до первого тега слоя (<Proxy>, <SSL> и т.д.) или в отдельных файлах, подключаемых через include.

Каждый define-блок начинается ключевым словом define, за которым следует тип определения, имя и тело. Блок завершается ключевым словом end. Имя должно быть уникальным среди определений того же типа. Регистр ключевых слов (define, end, имя типа) нечувствителен, однако имя определения сохраняет регистр.

В BlueCoat перечислены следующие категории define-блоков: Subnet Definitions, Condition Definitions (включая url и url.domain condition), Category Definitions, Action Definitions, Transformer Definitions (define url_rewrite, define active_content, define javascript) и анонимные определения (restrict dns, restrict rdns). Redcoat поддерживает все перечисленные типы, а также расширяет набор дополнительными: define exception, define bandwidth_class, define string, define policy.

6.1. `define subnet`¶

Subnet Definition задает именованный список IP-адресов и подсетей. Определенная таким образом подсеть может использоваться везде, где допустим тест IP-адреса транзакции -- в условиях client.address=, proxy.address= и других IP-триггерах. Это наиболее распространённый тип define: он позволяет один раз описать сетевую топологию (корпоративные подсети, DMZ, гостевые VLAN) и ссылаться на неё по имени во всех правилах.

Подсети, указанные внутри блока, проверяются как множество: если IP-адрес транзакции попадает хотя бы в одну из перечисленных сетей, условие считается выполненным.

Синтаксис:

define subnet <name>
    <network_1>
    <network_2>
    ...
end

где: - <name> -- уникальное имя определения (идентификатор без пробелов). - <network_N> -- IP-адрес или подсеть в одном из поддерживаемых форматов.

Правила для содержимого:

Каждая строка содержит один IP-адрес или подсеть.
Поддерживаемые форматы:
Одиночный адрес: 10.0.0.1, 2001:db8::1
CIDR-нотация: 10.0.0.0/8, 2001:db8::/32
Диапазон: 10.0.0.1-10.0.0.255
Поддерживаются как IPv4, так и IPv6 адреса.
Строки, которые не удается разобрать как IP-адрес или подсеть, игнорируются парсером (что позволяет оставлять комментарии с ; в теле блока).

Пример:

define subnet corporate_subnet
    10.10.12.0/24
end

define subnet internal_nets
    10.0.0.0/8
    172.16.0.0/12
    192.168.0.0/16
end

define subnet dmz_servers
    10.100.0.1
    10.100.0.2
    10.100.1.0/24
end

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

<Proxy>
    client.address=corporate_subnet allow
    client.address=!internal_nets deny

См. также: Глава 7 (Сетевые условия), client.address=, proxy.address=.

6.2. `define url.domain`¶

URL Domain Definition задает именованный список доменных имен. Используется для тестирования домена запрашиваемого URL через триггер url.domain=. Это удобный способ группировать домены по назначению (заблокированные сайты, доверенные ресурсы, внутренние приложения) без необходимости перечислять их в каждом правиле.

Домен, указанный в define, автоматически покрывает все поддомены: запись example.com соответствует также www.example.com, mail.example.com и т.д. Для явного указания поддоменов поддерживается wildcard-нотация *.example.com.

Существует два варианта синтаксиса: простой (define url.domain) и condition-вариант (define url.domain condition). Condition-вариант позволяет ссылаться на список через триггер condition=, что полезно когда один и тот же список доменов нужно использовать в комбинации с другими условиями.

Дополнительно парсер поддерживает define server_url.domain -- вариант для слоя <Forward>, который проверяет URL после возможных перезаписей (server_url), а не оригинальный URL запроса.

Синтаксис:

define url.domain <name>
    <domain_1>
    <domain_2>
    ...
end

define url.domain condition <name>
    <domain_1>
    <domain_2>
    ...
end

define server_url.domain condition <name>
    <domain_1>
    <domain_2>
    ...
end

где: - <name> -- уникальное имя определения. - condition -- необязательное ключевое слово, делающее определение доступным через condition=<name>. - server_url.domain -- вариант, тестирующий URL после перезаписей (для слоя <Forward>).

Правила для содержимого:

Каждая строка содержит одно доменное имя.
Поддерживается wildcard-нотация: *.example.com.
Простое имя домена (без *) автоматически включает все поддомены.
Имена доменов регистронезависимы.

Пример:

define url.domain blocked_sites
    facebook.com
    twitter.com
    *.instagram.com
end

define url.domain condition trusted_domains
    internal.corp
    portal.corp
end

; Для Forward layer -- тестирует URL после rewrite
define server_url.domain condition allowed
    inventory.example.com
    affinityclub.example.com
end

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

<Proxy>
    url.domain=blocked_sites deny
    condition=trusted_domains allow

<Forward>
    condition=allowed forward(primary_group)

См. также: Глава 8 (Условия URL), url.domain=, server_url.domain=.

6.3. `define url condition`¶

URL Condition Definition задает именованный список URL-паттернов. В отличие от define url.domain, которое проверяет только доменную часть, define url позволяет указать полный URL, включая схему, путь и параметры запроса. Это даёт более точный контроль -- например, можно заблокировать конкретную страницу, не затрагивая весь домен.

Определение поддерживает два варианта: простой (define url) и condition-вариант (define url condition). Простой вариант создает список, на который можно ссылаться через url=, condition-вариант -- через condition=.

Синтаксис:

define url <name>
    <url_pattern_1>
    <url_pattern_2>
    ...
end

define url condition <name>
    <url_pattern_1>
    <url_pattern_2>
    ...
end

где: - <name> -- уникальное имя определения. - condition -- необязательное ключевое слово, делающее определение доступным через condition=<name>.

Правила для содержимого:

Каждая строка содержит один URL или URL-паттерн.
URL может включать схему (http://, https://), домен, путь и query-строку.
Поддерживаются wildcards: https://api.example.com/v1/*.
Строки между define и end не должны содержать пробелов в начале URL (допускается отступ для форматирования).

Пример:

define url condition payroll_location
    url=hr.my_company.com/payroll/
end

define url api_endpoints
    https://api.example.com/v1/*
    https://api.example.com/v2/*
end

define url condition blocked_urls
    http://malware.example.com/payload
    http://phishing.example.com/login
    https://evil.example.com/download/*
end

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

<Proxy>
    condition=payroll_location authenticate(corporate_realm)
    condition=blocked_urls deny

См. также: Глава 8 (Условия URL), url=, url.path=.

6.4. `define condition`¶

Condition Definition -- наиболее гибкий тип define-блока. В отличие от остальных типов, которые тестируют один конкретный аспект транзакции (IP-адрес, домен, URL), condition definitions могут включать произвольные триггеры, допустимые в слое, и комбинировать их с помощью булевой логики.

Триггер condition= является единственным исключением из общего правила CPL, что каждый триггер тестирует ровно один аспект транзакции. Condition definitions могут одновременно проверять несколько частей транзакции (IP-адрес, время, URL, метод запроса и т.д.) и строить произвольные булевы комбинации этих проверок.

Семантика AND/OR:

Булевая логика condition definitions определяется расположением триггеров:

AND (конъюнкция): несколько триггеров на одной строке объединяются неявным AND. Все условия на строке должны быть выполнены одновременно.
OR (дизъюнкция): каждая новая строка добавляет альтернативу через OR. Достаточно выполнения условий хотя бы одной строки.

Эта семантика соответствует спецификации BlueCoat: AND между триггерами внутри строки неявный (разделитель -- пробел), а ключевые слова AND и OR зарезервированы только для значений внутри одного триггера.

Синтаксис:

define condition <name>
    <trigger_1a> <trigger_1b> ...    ; строка 1: все триггеры через AND
    <trigger_2a> <trigger_2b> ...    ; строка 2: OR со строкой 1
    ...
end

где: - <name> -- уникальное имя определения. - Каждая строка содержит один или несколько триггеров, разделённых пробелами (AND). - Строки объединяются через OR.

Правила для содержимого:

Внутри блока допустимы любые триггеры (условия), поддерживаемые в текущем слое: client.address=, url.domain=, category=, weekday=, hour=, http.method=, url.extension=, url.path.regex= и другие.
Можно ссылаться на другие define: client.address=internal_nets, url.domain=blocked_sites.
Строки-комментарии (начинающиеся с ;) игнорируются.
Нераспознанные триггеры на строке пропускаются парсером (строка целиком игнорируется, если ни один триггер не разобран).
Блок должен содержать хотя бы одну строку с распознанными триггерами.

Пример:

define condition work_hours
    weekday=(1,2,3,4,5) hour=9..18
end

define condition external_user
    client.address=!corporate_net
end

define condition suspicious_request
    ; Строка 1 (AND): исполняемый файл И метод POST
    url.extension=(exe, bat, cmd) http.method=POST
    ; Строка 2 (OR): ИЛИ путь содержит directory traversal
    url.path.regex="\.\./"
end
; Результат: (exe/bat/cmd AND POST) OR (directory traversal)

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

<Proxy>
    condition=work_hours category=Gambling deny
    condition=suspicious_request deny
    condition=external_user authenticate(corporate_realm)

Возможности: Полная совместимость с BlueCoat: - Ссылка: condition=name, condition!=name, condition=!name - Вложенность: одно condition-определение может ссылаться на другое (ссылки раскрываются рекурсивно) - Через condition= можно ссылаться также на define url.domain condition и define subnet - Обнаружение циклических ссылок (предотвращение зацикливания) - Если ссылка указывает на несуществующее определение, политика всё равно применяется с предупреждением, а такое условие не срабатывает

См. также: Глава 5 (Правила), триггер condition=.

6.5. `define action`¶

Action Definition создает именованный набор действий (properties), который можно активировать или деактивировать в правилах. Это позволяет определить группу связанных действий один раз и включать или выключать их по имени через свойство action().

В отличие от inline-действий в правилах, action definitions дают независимый контроль: одно правило может включить action A и выключить action B, другое правило -- наоборот. Это особенно полезно для управления наборами HTTP-заголовков, политиками логирования и другими группами настроек.

Синтаксис:

define action <name>
    <action_1>
    <action_2>
    ...
end

где: - <name> -- уникальное имя определения. - <action_N> -- любое допустимое действие CPL (property).

Правила для содержимого:

Каждая строка содержит одно действие.
Поддерживаются все действия (properties), допустимые в текущем слое: deny, allow, log(), set(), delete(), access_log(), authenticate(), exception() и другие.
Допускается heredoc-синтаксис (<<MARKER ... MARKER) для действий с многострочными значениями.
Нераспознанные строки пропускаются парсером.

Пример:

define action add_security_headers
    set(response.header.X-Frame-Options, "DENY")
    set(response.header.X-Content-Type-Options, "nosniff")
    set(response.header.Strict-Transport-Security, "max-age=31536000")
end

define action block_and_log
    deny
    log(yes)
    access_log(security_log)
end

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

Для активации определённого действия используется синтаксис action.<name>(yes). Для деактивации — action.<name>(no). Скобки с параметром yes или no обязательны.

action.<name>(yes)     ; активировать действие
action.<name>(no)      ; деактивировать действие

Важно: Запись action.<name> без скобок не поддерживается. Всегда указывайте (yes) или (no).

<Proxy>
    action.add_security_headers(yes)
    category=Malware action.block_and_log(yes)

Пример с rate_limit:

define action api_rate_limit
    rate_limit(100, minute)
end

<Proxy>
    url.path=/api action.api_rate_limit(yes)
    allow

См. также: Часть IV (Действия), action() property.

6.6. `define category`¶

Category Definition объединяет несколько категорий контента в именованную группу. Это позволяет расширить вендорные категории или создать собственные группировки для удобства управления политиками. Определённая группа тестируется через триггер category=.

Категории контента обычно предоставляются вендором (BlueCoat WebFilter, сторонние базы URL-классификации). Category definitions не создают новые категории -- они группируют существующие. Например, можно объединить категории "Gambling", "Adult Content" и "Malware" в одну группу blocked_cats и использовать её в правилах вместо перечисления каждой категории.

Синтаксис:

define category <name>
    <category_1>
    <category_2>
    ...
end

где: - <name> -- уникальное имя группы категорий. - <category_N> -- имя существующей категории контента.

Правила для содержимого:

Каждая строка содержит одно имя категории.
Имена категорий могут содержать пробелы, дефисы, слэши и скобки -- в этом случае их можно заключить в кавычки: "Entertainment and Videos", "Peer-to-Peer (P2P)", "Pornography/Sex".
Без кавычек берётся вся строка (с обрезкой пробелов по краям).
Регистр имён категорий сохраняется.

Пример:

define category blocked_cats
    News
    "Entertainment and Videos"
    Gambling
    "Adult Content"
end

define category productivity
    Business
    Technology
    Education
end

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

<Proxy>
    category=blocked_cats deny
    category=productivity allow

См. также: Глава 13 (Условия категорий), category=.

6.7. `define exception`¶

Exception Definition описывает именованную страницу ошибки (exception page), которую прокси отдает клиенту при блокировке запроса или возникновении ошибки. Определение включает заголовок, HTTP-код ответа, тип содержимого и HTML-тело страницы.

Тело страницы поддерживает подстановку переменных в формате $(variable): $(url) -- заблокированный URL, $(user) -- имя пользователя и другие контекстные переменные.

Расширение Redcoat. Формат define exception с полями title, status_code, content_type и body является расширением Redcoat. В BlueCoat CPL страницы исключений настраиваются иначе -- через exception object properties в правилах (exception(exception_id)). Redcoat сохраняет совместимость с exception() property, но добавляет возможность полного описания страницы в CPL.

Синтаксис:

define exception <name>
    title "<title_text>"
    status_code <http_code>
    content_type "<mime_type>"
    body <<EOF
    <html_body>
    EOF
end

где: - <name> -- уникальное имя (ID) страницы исключения. - title -- заголовок страницы (в кавычках). - status_code -- HTTP-код ответа (по умолчанию 403). - content_type -- MIME-тип (по умолчанию text/html). - body -- тело страницы, указывается в кавычках или через heredoc-синтаксис (<<MARKER ... MARKER).

Правила для содержимого:

Все поля необязательны, кроме имени. Значения по умолчанию: status_code=403, content_type="text/html", пустые title и body.
Тело поддерживает переменные $(url), $(user), $(category), $(timestamp) и другие.
Heredoc-синтаксис позволяет включать многострочный HTML без экранирования.
Порядок полей не имеет значения.

Встроенные исключения: authentication_failed, access_denied, not_found, content_policy_denied, virus_detected, certificate_error, gateway_timeout, service_unavailable.

Пример:

define exception custom_block_page
    title "Access Denied"
    status_code 403
    content_type "text/html"
    body <<EOF
<!DOCTYPE html>
<html>
<head><title>Blocked</title></head>
<body>
    <h1>Access Denied</h1>
    <p>URL: $(url)</p>
    <p>User: $(user)</p>
    <p>Category: $(category)</p>
</body>
</html>
EOF
end

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

<Proxy>
    category=Malware exception(custom_block_page)

См. также: Глава 22 (Условия исключений), exception() property, exception.id=.

6.8. `define bandwidth_class`¶

Bandwidth Class Definition описывает именованный класс ограничения полосы пропускания. Класс задает максимальную скорость (bitrate) и приоритет, что позволяет реализовать Quality of Service (QoS) политики на уровне прокси.

Расширение Redcoat. Тип define bandwidth_class не описан в BlueCoat. В BlueCoat QoS настраивается через отдельные механизмы (bandwidth management objects). Redcoat реализует bandwidth classes как define-блоки CPL для единообразия конфигурации.

Синтаксис:

define bandwidth_class <name>
    max_bitrate(<bps>)
    priority(<level>)
end

где: - <name> -- уникальное имя класса. - max_bitrate(<bps>) -- максимальная скорость в битах в секунду. 0 означает отсутствие ограничения (по умолчанию). - priority(<level>) -- приоритет от 0 до 255, чем выше значение -- тем выше приоритет (по умолчанию 128).

Правила для содержимого:

Оба параметра необязательны. Значения по умолчанию: max_bitrate=0 (без ограничений), priority=128.
Параметры указываются в функциональном синтаксисе: max_bitrate(100000000).
Нераспознанные строки пропускаются.

Пример:

define bandwidth_class low_priority
    max_bitrate(500000)
    priority(50)
end

define bandwidth_class premium
    max_bitrate(100000000)   ; 100 Mbps
    priority(200)
end

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

<Proxy>
    category=Streaming bandwidth_class(low_priority)
    client.address=vip_subnet bandwidth_class(premium)

См. также: Глава 32 (Ограничение скорости и полосы), bandwidth_class() property.

6.9. `define string`¶

String Definition задает именованный многострочный строковый шаблон. Каждая строка содержимого начинается с символа >, который служит разделителем и не включается в результат. Строковые определения поддерживают подстановку переменных $(variable) и используются для формирования HTML-страниц, текстовых сообщений и других шаблонов.

Расширение Redcoat. Тип define string не описан в BlueCoat. Это расширение Redcoat для создания переиспользуемых текстовых шаблонов в CPL.

Синтаксис:

define string <name>
    ><line_1>
    ><line_2>
    ...
end

где: - <name> -- уникальное имя шаблона. - Каждая строка содержимого должна начинаться с символа >. Текст после > включается в результат.

Правила для содержимого:

Строки, начинающиеся с >, формируют содержимое шаблона (без символа >).
Строки-комментарии (;, //) пропускаются.
Остальные строки (не начинающиеся с > и не являющиеся комментариями) пропускаются.
Поддерживаются переменные подстановки: $(url), $(user), $(category) и другие.

Пример:

define string block_page_html
    ><!DOCTYPE html>
    ><html>
    ><head><title>Blocked</title></head>
    ><body>
    ><h1>Access Denied</h1>
    ; Здесь подставляются переменные
    ><p>URL: $(url)</p>
    ><p>User: $(user)</p>
    ></body>
    ></html>
end

См. также: define exception (раздел 6.7), подстановка переменных.

6.10. `define policy` (макросы)¶

Policy Macro Definition создает именованный переиспользуемый фрагмент политики, привязанный к определённому типу слоя. Тело макроса содержит «сырой» CPL-код (теги слоёв и правила), который подставляется при использовании.

Расширение Redcoat. Тип define <layer> policy не описан в BlueCoat. Это расширение Redcoat для модуляризации больших политик.

Синтаксис:

define <layer_type> policy <name>
    <raw_cpl_body>
end

где: - <layer_type> -- тип слоя, к которому привязан макрос. Допустимые значения: proxy, cache, admin, dns-proxy, exception, forward, ssl-intercept, ssl, socks, dns. - <name> -- уникальное имя макроса. - <raw_cpl_body> -- произвольный CPL-код (теги слоёв, правила, комментарии). Тело не парсится рекурсивно -- сохраняется как строка.

Правила для содержимого:

Тело макроса -- произвольный текст между именем и end.
Тело не проходит валидацию на этапе парсинга define-блока (парсится при подстановке).
Ключевое слово policy должно следовать непосредственно за типом слоя.
Поддерживаются все 10 типов слоёв.

Пример:

define proxy policy standard_web_access
    <Proxy>
        category=Malware deny
        category=Phishing deny
        allow
end

define ssl policy inspect_all
    <SSL-Intercept>
        allow
end

См. также: Глава 4 (Слои), include.

6.11. `define url_rewrite`¶

URL Rewrite Definition описывает именованный набор правил перезаписи URL. Это один из Transformer Definitions, описанных в BlueCoat CPL Reference. Определение содержит последовательность операторов перезаписи, которые применяются к URL запроса при обработке транзакции.

Синтаксис:

define url_rewrite <name>
    <rewrite_statement_1>
    <rewrite_statement_2>
    ...
end

где: - <name> -- уникальное имя набора правил перезаписи.

Правила для содержимого:

Поддерживаются четыре типа операторов перезаписи:

rewrite_url_prefix("<client_url>", "<server_url>") -- замена префикса URL. Если URL начинается с client_url, префикс заменяется на server_url.
rewrite_url_substring("<client_url>", "<server_url>") -- замена подстроки в URL.
rewrite_script_substring("<client_string>", "<server_string>") -- замена подстроки в скриптах (JavaScript и др.).
rewrite_script_regex("<pattern>", "<replacement>") -- замена по регулярному выражению в скриптах.

Аргументы указываются в кавычках, разделенные запятой, в круглых скобках. Нераспознанные строки пропускаются.

Пример:

define url_rewrite my_rewrite
    rewrite_url_prefix("http://old.example.com", "http://new.example.com")
    rewrite_script_regex("(.*)\\.old\\.com", "$1.new.com")
end

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

<Proxy>
    url.domain=old.example.com url_rewrite(my_rewrite)

См. также: Глава 25 (Перенаправление и перезапись), url_rewrite() property.

Глава 6. Блоки define¶

6.1. define subnet¶

6.2. define url.domain¶

6.3. define url condition¶

6.4. define condition¶

6.5. define action¶

6.6. define category¶

6.7. define exception¶

6.8. define bandwidth_class¶

6.9. define string¶

6.10. define policy (макросы)¶

6.11. define url_rewrite¶

6.1. `define subnet`¶

6.2. `define url.domain`¶

6.3. `define url condition`¶

6.4. `define condition`¶

6.5. `define action`¶

6.6. `define category`¶

6.7. `define exception`¶

6.8. `define bandwidth_class`¶

6.9. `define string`¶

6.10. `define policy` (макросы)¶

6.11. `define url_rewrite`¶