Обработка HTTP-сообщений на Lua

Компонент Dr.Web ICAPD поддерживает взаимодействие с интерпретатором программ на языке Lua (используется версия 5.3.4; поставляется совместно с Dr.Web для интернет-шлюзов UNIX). Скрипты на Lua могут использоваться компонентом для анализа и обработки сообщений протокола HTTP.

Анализ HTTP-сообщения (запроса или ответа), поступившего на проверку от прокси-сервера по протоколу ICAP, выполняется при помощи скрипта на языке Lua, указанного в настройках Dr.Web ICAPD в соответствующем параметре MessageHook (может быть указан как текст скрипта, так и путь к файлу скрипта).

Требования к скрипту для обработки сообщений

Скрипт должен содержать глобальную функцию, являющуюся точкой входа в модуль проверки сообщений (эту функцию Dr.Web ICAPD будет вызывать для обработки вновь поступившего сообщения). Функция обработки должна соответствовать следующим соглашениям о вызове:

2.Единственный аргумент — таблица MessageContext (предоставляет из функции доступ к информации об обрабатываемом сообщении);

3.Единственное возвращаемое значение — строка. Возвращаемое значение определяет вердикт относительно проверяемого сообщения: пропустить его или заблокировать. Возможные значения:

•pass — HTTP-сообщение будет передано получателю (HTTP-запрос — к серверу, HTTP-ответ — к клиенту).

•block — HTTP-сообщение не будет передано получателю, клиент получит HTTP-ответ с веб-страницей блокировки.

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

Ниже приведен пример корректного определения функции, которая всегда будет возвращать в Dr.Web ICAPD вердикт pass (пропустить) для всех проверяемых HTTP-сообщений (здесь и далее аргумент ctx — экземпляр таблицы MessageContext):

Следующий скрипт заблокирует доступ ко всем ресурсам, кроме сайта c документацией компании «Доктор Веб» для всех пользователей, кроме членов группы Web Admins в Active Directory:

Используется как входной аргумент функции message_hook, содержит информацию об обрабатываемом HTTP-сообщении (его тип, заголовки, тело, а также информация об отправителе и получателях, если она доступна).

Поле	Описание	Тип данных
direction	Тип HTTP-сообщения: •request — HTTP-запрос. •response — HTTP-ответ.	Строка
icap	Информация о заголовках ICAP-запроса.	Таблица ICAP
request	Информация о заголовках HTTP-запроса.	Таблица Request
response	Информация о заголовках HTTP-ответа.	Таблица Response
body	Информация о теле HTTP-сообщения.	Таблица Body
Переопределенные метаметоды: Нет

Используется как поле icap таблицы MessageContext. Хранит информацию об ICAP-запросе от прокси-сервера HTTP.

Поле

Описание

Тип данных

user

Информация о пользователе, полученная из заголовка X-Client-Username в ICAP-запросе.

Таблица User

src

IP-адрес клиента, отправившего запрос (содержится в ICAP-запросе от прокси-сервера, в заголовке X-Client-IP), либо nil, если адрес неизвестен.

Таблица IpAddress

field

Массив заголовков ICAP-запроса.

Массив таблиц HeaderField

Функция для поиска заголовка по регулярному выражению. Принимает один обязательный аргумент patterns — шаблоны поиска, т. е. одно (строка) или несколько (массив строк) регулярных выражений в синтаксисе Perl (PCRE). Выполняет поиск по всем имеющимся заголовкам.

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

Возвращает логическое значение:

•true — если для хотя бы у одного заголовка строка field.name .. ": " .. field.value.decoded соответствует хотя бы одному из заданных регулярных выражений;

•false — если соответствий не обнаружено.

Функция

value

Функция, принимающая один обязательный аргумент — имя заголовка (строка). Возвращает значение, первого заголовка с указанным именем, либо nil, если заголовка с таким именем нет.

Функция

Переопределенные метаметоды: Нет

Таблица содержит имя пользователя и домен; оба ее поля необязательны.

Поле

Описание

Тип данных

method

Метод протокола HTTP, указанный в запросе (например, POST), либо nil, если ICAP-запрос не включает заголовок HTTP-запроса.

Строка

url

URL ресурса, на который направлен HTTP-запрос.

Таблица Url

content_type

Информация, полученная из заголовка Content-Type HTTP-запроса.

Таблица ContentType

field

Массив заголовков HTTP-запроса.

Массив таблиц HeaderField

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

Возвращает логическое значение:

•true — если для хотя бы одного заголовка строка field.name .. ": " .. field.value.decoded соответствует хотя бы одному из заданных регулярных выражений;

•false — если соответствий не обнаружено

Функция

value

Функция

Переопределенные метаметоды: Нет

Таблица описывает значение, полученное из заголовка Content-Type.

Поле	Описание	Тип данных
type	MIME-тип части сообщения	Строка
subtype	Подтип части сообщения	Строка
param	Параметры заголовка в виде массива таблиц, содержащих следующие поля: •name — имя параметра (строка); •value — значение параметра (строка).	Массив таблиц
match	Функция, принимающая один обязательный аргумент media_types — массив строк, описывающих MIME-типы. Каждая строка должна иметь вид "тип/подтип", "тип/" или "/". Возвращает логическое значение: •true — если MIME-тип тела соответствует одной из указанных строк (регистр не учитывается) или переданный массив содержит строку "/*". •false — если соответствий не обнаружено.	Функция
Переопределенные метаметоды: •__tostring — функция, возвращающая раскодированное значение заголовка; •__concat — функция, присоединяющая раскодированное значение заголовка к строке.

Поле	Описание	Тип данных
scheme	Префикс схемы (протокола), например, http. Если отсутствует — nil.	Строка
host	Имя или IP-адрес узла, например, example.com. Если отсутствует — nil.	Строка
port	Номер порта, например, 80. Если отсутствует — nil.	Число
path	Путь к ресурсу, например, index.html. Если отсутствует — nil.	Строка
query	Декодированные параметры запроса. Если отсутствуют — nil.	Строка
legal_url	В случае принадлежности URL категории owners_notice содержит строку с URL, ведущим на веб-сайт правообладателя, иначе — nil.	Строка
in_list	Функция, принимающая один обязательный аргумент hosts — список доменов (массив строк). Возвращает логиче6ское значение: •true — если host является поддоменом одного из указанных доменов либо совпадает с одним из них; •false — если совпадений не обнаружено	Функция
categories	Функция, принимающая один необязательный аргумент filter — таблицу UrlCategoryFilter (отсутствие аргумента равносильно использованию пустой таблицы). Возвращает функцию-итератор, с помощью которой можно перебрать все категории, удовлетворяющие заданным с помощью filter условиям, к которым относится URL.	Функция
in_categories	Функция, принимающая один обязательный аргумент categories — список категорий URL (массив строк). Возвращает логическое значение: •true — если URL относится хотя бы к одной из указанных категорий; •false — если URL ни к одной из категорий не относится. Если массив categories пустой, всегда возвращает false. Возможные значения категорий см. в описании поля category таблицы UrlCategoryFilter.	Функция
raw	Нераскодированный URL в «сыром» виде.	Таблица RawUrl
Переопределенные метаметоды: •__tostring — функция, возвращающая содержимое Url в виде строки (в кодировке UTF-8); •__concat — функция, присоединяющая к строке преобразованное в строку значение Url.

Таблица содержит информацию об URL в нераскодированном виде.

Поле	Описание	Тип данных
scheme	Префикс схемы (протокола), например, http. Если отсутствует — nil.	Строка
host	Имя или IP-адрес узла, например, example.com. Если отсутствует — nil.	Строка
port	Номер порта, например, 80. Если отсутствует — nil.	Число
path	Путь к ресурсу, например, index.html. Если отсутствует — nil.	Строка
query	Декодированные параметры запроса. Если отсутствуют — nil.	Строка
Переопределенные метаметоды: •__tostring — функция, возвращающая содержимое RawUrl в виде строки (в кодировке UTF-8); •__concat — функция, присоединяющая к строке преобразованное в строку значение RawUrl.

Таблица описывает фильтр для категорий URL. Все ее поля являются необязательными.

Поле

Описание

Тип данных

category

Список категорий, которым должен соответствовать URL (нечувствительно к регистру):

•infection_source — источник распространения угроз;

•not_recommended — не рекомендуемый к посещению;

•adult_content — материалы для взрослых;

•violence — насилие;

•weapons — оружие;

•gambling — азартные игры;

•drugs — наркотики;

•obscene_language — нецензурная лексика;

•chats — чаты;

•terrorism — терроризм;

•free_email — бесплатная электронная почта;

•social_networks — социальные сети;

•owners_notice — веб-сайты, добавленные по обращению правообладателей;

•online_games — онлайн-игры;

•anonymizers — анонимайзеры;

•cryptocurrency_mining_pools — пулы майнеров криптовалют;

•jobs — веб-сайты для поиска работы;

•black_list — черный список.

Строка или таблица строк

category_not

Перечень категорий, которым не должен соответствовать URL (нечувствительно к регистру).

Строка или таблица строк

Переопределенные метаметоды: Нет

Если поле фильтра не задано (т. е. указано значение nil), то любая угроза соответствует фильтру. Если указаны несколько полей фильтра, то условие объединяется по конъюнкции (логическое «И»). Если тип поля фильтра — это таблица (список), то фильтруемый объект должен соответствовать хотя бы из ее элементов.

Поле

Описание

Тип данных

status

Код ответа HTTP, либо nil, если ICAP-запрос не включает заголовок HTTP-ответа.

Число

reason

Пояснение к коду ответа, либо nil, если отсутствует.

Строка

content_type

Содержит информацию, полученную из заголовка Content-Type HTTP-ответа.

Таблица ContentType

field

Массив заголовков HTTP-ответа

Массив таблиц HeaderField

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

Возвращает логическое значение:

•false — иначе.

Функция

value

Функция

Переопределенные метаметоды: Нет

Поле	Описание	Тип данных
has_threat	Функция, принимающая один необязательный аргумент filter — таблицу ThreatFilter (отсутствие аргумента равносильно использованию пустой таблицы). Возвращает логическое значение: •true — если тело HTTP-сообщения содержит угрозу, соответствующую указанному условию filter; •false — иначе.	Функция
threats	Функция, принимающая один необязательный аргумент filter — таблицу ThreatFilter (отсутствие аргумента равносильно использованию пустой таблицы). Возвращает функцию-итератор, с помощью которой можно перебрать все угрозы, найденные в теле HTTP-сообщения. Угрозы описываются с помощью таблицы Virus.	Функция
content_type	Содержит информацию о MIME-типе тела, полученную из заголовка Content-Type HTTP-запроса или ответа (в зависимости от того, тело сообщения какого типа анализируется).	Таблица ContentType
scan_error	Ошибка проверки тела, если произошла, иначе — nil. Возможные значения: •path_not_absolute — указан не абсолютный путь; •file_not_found — файл не найден; •file_not_regular — специальный файл; •file_not_block_device — не блочное устройство; •name_too_long — слишком длинное имя; •no_access — нет доступа; •read_error — ошибка чтения; •write_error — ошибка записи; •file_too_large — файл слишком большой; •file_busy — файл используется; •unpacking_error — ошибка распаковки; •password_protected — архив защищен паролем; •arch_crc_error — ошибка CRC архива; •arch_invalid_header — ошибочный заголовок архива; •arch_no_memory — не хватает памяти для распаковки архива; •arch_incomplete — неполный архив; •can_not_be_cured — файл не может быть вылечен; •packer_level_limit — превышение предельного уровня вложенности для упакованного объекта; •archive_level_limit — превышение предельного уровня вложенности для архива; •mail_level_limit — превышение предельного уровня вложенности для почтового файла; •container_level_limit — превышение предельного уровня вложенности для контейнера; •compression_limit — превышение предельной величины коэффициента сжатия; •report_size_limit — превышение предельного размера отчета; •scan_timeout — превышение предельного времени проверки; •engine_crash — сбой антивирусного ядра; •engine_hangup — зависание антивирусного ядра; •engine_error — ошибка антивирусного ядра; •no_license — отсутствует действующая лицензия; •multiscan_too_late — ошибка многопоточной проверки; •curing_limit_reached — превышение предельного числа попыток лечения; •non_supported_disk — неподдерживаемый тип диска; •unexpected_error — неожиданная ошибка.	Строка
Переопределенные метаметоды: Нет

Поле

Описание

Тип данных

name

Имя угрозы (по классификации «Доктор Веб»)

Строка

type

Тип угрозы (по классификации «Доктор Веб»). Возможные значения:

•known_virus — известная угроза (т. е. угроза, имеющая описание в вирусных базах);

•virus_modification — модификация известной угрозы;

•unknown_virus — неизвестная угроза, подозрительный объект;

•adware — рекламная программа;

•dialer — программа дозвона;

•joke — программа-шутка;

•riskware — потенциально опасное ПО;

•hacktool — программа взлома.

Строка

Переопределенные метаметоды: Нет

1.Вывод в журнал перечня всех угроз, найденных в HTTP-сообщении:

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

Для взаимодействия с Dr.Web для интернет-шлюзов UNIX в пространство Lua-программы могут быть импортированы следующие специфические модули, перечисленные в таблице.

Имя модуля	Назначение
drweb	Модуль, предоставляющий функции для записи сообщений из Lua-программы в журнал компонента Dr.Web для интернет-шлюзов UNIX, запустившего программу на Lua, а также средства асинхронного запуска Lua-процедур.
drweb.lookup	Модуль, предоставляющий инструменты для запроса данных из внешних источников путем обращения к модулю Dr.Web LookupD.
drweb.regex	Модуль, предоставляющий интерфейс сопоставления строк с регулярными выражениями.
drweb.config	Модуль, предоставляющий таблицу, содержащую значения параметров конфигурации Dr.Web ICAPD.

•Для записи сообщений из программы Lua в журнал компонента Dr.Web для интернет-шлюзов UNIX:

▫log(<уровень>, <сообщение>) записывает строку <сообщение> в журнал Dr.Web для интернет-шлюзов UNIX на уровне <уровень> (требуемый уровень задается одним из следующих значений (строка): debug, info, notice, warning, error);

▫debug(<сообщение>) записывает строку <сообщение> в журнал Dr.Web для интернет-шлюзов UNIX на уровне debug;

▫info(<сообщение>) записывает строку <сообщение> в журнал Dr.Web для интернет-шлюзов UNIX на уровне info;

▫notice(<сообщение>) записывает строку <сообщение> в журнал Dr.Web для интернет-шлюзов UNIX на уровне notice;

▫warning(<сообщение>) записывает строку <сообщение> в журнал Dr.Web для интернет-шлюзов UNIX на уровне warning;

▫error(<сообщение>) записывает строку <сообщение> в журнал Dr.Web для интернет-шлюзов UNIX на уровне error.

•Для управления синхронизацией Lua-процедур:

▫sleep(<сек.>) приостанавливает выполнение экземпляра процедуры Lua на указанное число секунд;

▫async(<функция Lua>[, <список аргументов>]) асинхронно запускает указанную функцию с передачей ей заданного списка аргументов. Вызов функции async завершается немедленно, возвращаемое значение (таблица Future) позволяет получить результат выполнения функции <функция Lua>.

•Для представления информации об IP-адресе в виде таблицы IpAddress:

▫ip(<адрес>) представляет IP-адрес, переданный в виде строки <адрес>, экземпляром таблицы IpAddress. Допускается использовать как IPv4-, так и IPv6.

•Для загрузки внешних данных из текстового файла:

▫load_set(<путь к файлу>) формирует из содержимого указанного текстового файла таблицу со значениями true; в качестве ключей используются строки, прочитанные из файла. Пустые строки и строки, состоящие только из пробельных символов будут проигнорированы;

▫load_array(<путь к файлу>) формирует из содержимого указанного текстового файла массив строк. Пустые строки и строки, состоящие только из пробельных символов будут проигнорированы.

•Таблица Future описывает отложенный результат выполнения функции при помощи функции async.

Поле

Описание

Тип данных

belongs

Функция для проверки IP-адреса из таблицы IpAddress на принадлежность указанным подсетям (диапазонам IP-адресов).

Принимает единственный аргумент — массив строк вида "<IP-адрес>" или "<IP-адрес>/<маска>", где <IP-адрес> — адрес узла либо сети (например, 127.0.0.1), а <маска> — маска подсети, которая указывается в виде IP-адреса (например, 255.0.0.0), либо в виде числа (например, 8).

Возвращает логическое значение:

•true — если адрес совпадает хотя бы с одним из указанных IP-адресов либо принадлежит хотя бы одной из указанных подсетей (диапазону IP-адресов);

•false — если адрес не совпадает ни с одним из указанных или не принадлежит ни одной из указанных подсетей

Функция

Переопределенные метаметоды:

•__tostring — функция, преобразующая IpAddress в строку, например, 127.0.0.1 (IPv4) или ::1 (IPv6);

•__concat — функция, присоединяющая IpAddress к строке;

•__eq — функция для проверки равенства двух IpAddress;

•__band — функция, позволяющая накладывать маску, например: dw.ip('192.168.1.2') & dw.ip('255.255.254.0')

•Вывод в журнал сообщений, сформированных процедурой, запускающейся асинхронно:

•lookup(<запрос>, <параметры>) запрашивает данные во внешнем хранилище, доступном через модуль Dr.Web LookupD. Аргумент <запрос> должен соответствовать секции запроса в настройках Dr.Web LookupD (строка <тип>@<тег>). Необязательный аргумент <параметры> описывает подстановки, которые будут использованы при формировании запроса. Могут быть использованы следующие автоматически разрешаемые маркеры:

▫$u, $U — заменяется на user — имя пользователя, переданное клиентским компонентом;

▫$d, $D — заменяется на domain — имя домена, переданное клиентским компонентом.

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

•check(<проверяемая строка>, <запрос>, <параметры>) возвращает true, если <проверяемая строка> найдена во внешнем хранилище, доступном через модуль Dr.Web LookupD. Аргументы <запрос> и <параметры> полностью аналогичны аргументам функции lookup (см. выше). Аргумент <проверяемая строка> должен быть строкой или таблицей, имеющей метаметод __tostring (т. е. приводимой к строке).

•Вывод в журнал списка пользователей, извлеченного из источника данных LookupD.LDAP.users:

•search(<шаблон>, <текст>[, <флаги>]) — возвращает true, если строка <текст> содержит подстроку, соответствующую регулярному выражению <шаблон>. Необязательный параметр <флаги> (целое число) — набор флагов, влияющих на поведение функции, объединенных с помощью логического «ИЛИ» (OR).

•match(<шаблон>, <текст>[, <флаги>]) — аналогична search за исключением того, что регулярному выражению <шаблон> должна соответствовать вся строка <текст> целиком, а не только ее подстрока.

Модуль предоставляет таблицу, содержащую следующие поля:

Поле	Описание	Тип данных
whitelist	Значение параметра конфигурации Whitelist.	Массив строк
blacklist	Значение параметра конфигурации Blacklist.	Массив строк
adlist	Значение параметра конфигурации Adlist.	Массив строк
block_url_categories	Перечень блокируемых категорий URL (на основе значений параметров Block*, установленных в Yes).	Массив строк
block_threats	Перечень блокируемых категорий угроз (на основе значений параметров Block*, установленных в Yes).	Массив строк
block_unchecked	Значение параметра конфигурации BlockUnchecked.	Логический
Переопределенные метаметоды: Нет