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

В этом разделе

Общие сведения

Скрипт для Milter

Скрипт для Spamd

Скрипт для Rspamd

Скрипт для SMTP

Таблицы, описывающие структуру сообщения

Доступные вспомогательные модули

Общие сведения

Компонент Dr.Web MailD поддерживает взаимодействие с интерпретатором программ на языке Lua (используется версия 5.3.4; поставляется совместно с Dr.Web для почтовых серверов UNIX). Скрипты на Lua могут быть использованы компонентом для разбора, анализа и обработки почтовых сообщений.

Почтовое сообщение, поступившее на проверку через интерфейс Milter, Spamd, Rspamd или в режиме SMTP, анализируется при помощи скрипта на языке Lua, указанного в настройках Dr.Web MailD в параметре MilterHook, SpamdHook, RspamdHook или Smtphook соответственно. В качестве значения этого параметра можно указать как полный текст скрипта, так и путь к этому скрипту.

Дополнительные примеры скриптов для обработки почтовых сообщений доступны по ссылке:
https://github.com/DoctorWebLtd/drweb-lua-examples/tree/master/maild.

Скрипт обработки сообщений для интерфейса Milter

Требования к скрипту

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

1.Имя функции — milter_hook;

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

3.Единственное возвращаемое значение — заполненная таблица MilterResult. Возвращаемое значение определяет действие по отношению к проверяемому сообщению (принять, отклонить, изменить, отбросить), а также возможные действия по отношению к сообщению, если оно будет принято.

Ниже приведен пример определения функции, которая будет всегда возвращать в Dr.Web MailD вердикт Accept (принять) для всех сообщений, поступающих на проверку через интерфейс Milter (здесь и далее аргумент ctx — экземпляр таблицы MilterContext):

function milter_hook(ctx)
  return {action = "accept"}
end

Примеры

1.Поиск угроз и проверка на признаки спама

Скрипт выполняет следующие действия:

добавляет в значения заголовка X-Found имена обнаруженных в сообщении угроз;

добавляет к теме сообщения (значение заголовка Subject) префикс [SPAM], если рейтинг спама превысит 100 баллов;

отправляет сообщение получателю по завершении обработки.

function milter_hook (ctx)

 -- Добавить в заголовок имена найденных угроз
 for threat in ctx.message.threats() do
   ctx.modifier.add_header_field("X-Found", threat.name)
 end

 -- Изменить значение заголовка Subject, если рейтинг спама для сообщения превысил 100 баллов
 if ctx.message.spam.score > 100 then
   local old_value = ctx.message.header.value("Subject") or ""
   local new_value = "[SPAM] " .. old_value
   ctx.modifier.change_header_field("Subject", new_value)
 end

 -- Передать сообщение получателю, применив отложенные изменения
 return {
   action = "accept",
   modifications = ctx.modifier.modifications()
 }

end

2.Помещение в защищенный архив обнаруженных угроз, а также самого сообщения (если для него будет превышен рейтинг спама)

Скрипт выполняет следующие действия:

перемещает обнаруженные угрозы в защищенный архив;

если спам-рейтинг сообщения превышает 100 баллов, перемещает его целиком в защищенный архив.

function milter_hook(ctx)

 ctx.modifier.repack_password = "xxx"
 ctx.modifier.repack_message = ""

 -- Поместить в защищенный паролем архив все части
 -- сообщения, в которых найдены угрозы
 for threat, path in ctx.message.threats() do
   ctx.modifier.repack(path)
   local msg = " Threat found: " .. threat.name
   ctx.modifier.repack_message = ctx.modifier.repack_message .. msg
 end

 -- Перепаковать сообщение целиком, если оно набрало
 -- более 100 баллов оценки спама
 if ctx.message.spam.score > 100 then
   ctx.modifier.repack()
   local msg = " Spam score: " .. ctx.message.spam.score
   ctx.modifier.repack_message = ctx.modifier.repack_message .. msg
 end

 -- Передать сообщение получателю, применив отложенные изменения
 -- Обратите внимание, что если таблица модификаций не указана,
 -- она будет автоматически возвращена
 return {action = "accept"}

end

Проверяемое сообщение будет изменено: все нежелательные части будут изъяты, заархивированы и добавлены во вложение.
Архив с нежелательными элементами сообщения будет защищен паролем, который указан в качестве значения переменной ctx.modifier.repack_password. Пароль, указанный в конфигурационном файле в параметре RepackPassword в этом случае не будет действовать.

Используемые таблицы

Таблица MilterContext

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

Поле

Описание

Тип данных

session_id

Идентификатор сессии клиента, в течении которой обрабатываются сообщения, поступающие от этого клиента

Строка

sender

Информация об отправителе сообщения

Таблица MilterSender

helo

Строка приветствия HELO/EHLO, полученная от SMTP-клиента, отправившего сообщение, или nil, если строка отсутствует/неизвестна (не предоставлена MTA)

Строка

from

Адрес отправителя сообщения без угловых скобок (например: user@domain.com)

Строка

to

Адреса получателей сообщения (без угловых скобок)

Таблица RcptTo

message

Сообщение целиком (со всеми заголовками и телом)

Таблица MimeMessage

modifier

Таблица MilterModifier, содержащая все изменения, запланированные к внесению в сообщение, если по результатам проверки в таблице MilterResult будет сформировано действие "accept"

Таблица MilterModifier

gen

Таблица MilterGenerator, использующаяся для генерации специальных заголовков, например X-Antivirus

Таблица MilterGenerator

spf

Таблица SPF, использующаяся для SPF-проверки отправителя

Таблица SPF

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

Таблица MilterSender

Используется как поле sender таблицы MilterContext. Содержит информацию об отправителе сообщения.

Поле

Описание

Тип данных

hostname

Имя узла (FQDN) отправителя

Строка

family

Тип подключения в виде строки:

"U" — неизвестный тип

"L" — подключение через UNIX-сокет

"4" — подключение по IPv4

"6" — подключение по IPv6

Строка

port

Номер порта

Целое число

ip

IP-адрес узла отправителя, или nil, если IP-адрес отсутствует/неизвестен (не предоставлен MTA)

Таблица IpAddress

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

Таблица MilterResult

Используется как результат, возвращаемый функцией milter_hook.

Поле

Описание

Тип данных

action

Действие по отношению к сообщению:

"accept" — принять (т. е. разрешить MTA отправить сообщение к получателю);

"discard" — отбросить сообщение, не уведомляя отправителя;

"reject" — отклонить сообщение, вернув отправителю код SMTP 5**;

"tempfail" — отклонить сообщение, вернув отправителю код SMTP 4**;

"replycode" — отправить отправителю указанный в поле code ответ SMTP.

Обязательное поле.

Строка

code

Трехзначный код ответа SMTP, который должен быть отправлен отправителю, например "541".

Необязательное поле. Используется, только если action = "replycode".

Строка

text

Текст ответа отправителю, например "User not local or invalid address - Relay denied".

Необязательное поле. Используется, только если action = "replycode".

Строка

message

Текст ответа отправителю с информацией об отклонении сообщения — "Message rejected as spam".

Необязательное поле. Используется, только если action = "reject".

Строка

modifications

Таблица с описанием изменений, которые следует применить к сообщению перед передачей получателю.

Необязательное поле. Используется, только если action = "accept".

Таблица MilterModifications

added_recipients

Перечень адресов дополнительных получателей сообщения.

Необязательное поле. Используется, только если action = "accept".

Массив строк

deleted_recipients

Перечень адресов для исключения из списка получателей сообщения.

Необязательное поле. Используется, только если action = "accept".

Массив строк

incident

Текст описания инцидента в регистрируемом событии типа Mail.

Если поле — строка, содержимое этой строки будет передано в поле incident_text события типа Mail и событие будет зарегистрировано;

Если поле — булево и равно false, то поле incident_text события типа Mail будет отсутствовать и событие не будет зарегистрировано;

Если поле — булево и равно true, то поле incident_text события типа Mail будет заполнено автоматически и событие будет зарегистрировано, если полученное значение incident_text будет не пустым.

Строка или логическое значение

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

Таблица MilterModifications

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

Поле

Описание

Тип данных

new_body

Новое тело сообщения (без заголовков), которым следует заменить тело обрабатываемого сообщения

Строка

added_fields

Заголовки, которые следует добавить к обрабатываемому сообщению

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

changed_fields

Заголовки, которые следует изменить или удалить из обрабатываемого сообщения

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

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

Таблица MilterAddedField

Используется для описания заголовков, которые следует добавить к сообщению.

Поле

Описание

Тип данных

name

Имя заголовка

Строка

value

Значение заголовка

Строка

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

Таблица MilterChangedField

Используется для описания заголовков, которые следует изменить в сообщении (в том числе удалить).

Поле

Описание

Тип данных

name

Имя заголовка

Строка

index

Порядковый номер заголовка с именем name в сообщении, подлежащий изменению (начиная с 1)

Число

value

Новое значение заголовка (или пустая строка "", если заголовок нужно удалить).

Строка

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

Для описания изменений, которые следует внести в сообщение после его обработки, рекомендуется не заполнять таблицу MilterModifications напрямую, а использовать методы, предоставляемые специальной таблицей MilterModifier, получаемой из контекста.

Таблица MilterGenerator

Содержит вспомогательные методы для генерации стандартных заголовков X-Antivirus и X-Authentication-Results.

Поле

Описание

Тип данных

х_antivirus_header_field

Функция для генерации заголовка X-Antivirus, содержащего информацию о компонентах антивируса, использованных для сканирования сообщения. Возвращает таблицу HeaderField или nil, если сообщение еще не отсканировано.
В таблице HeaderField поле name имеет фиксированное значение (X-Antivirus).

Функция

authentication_results_header_field

Функция для генерации заголовка Authentication-Results, который содержит информацию о результатах проверок DKIM и SPF. Принимает опциональный аргумент authserv_id — строку, идентификатор сервера аутентификации в сгенерированном заголовке. Значением authserv_id по умолчанию является имя хоста, на котором запущен Dr.Web MailD.
Возвращает таблицу HeaderField.
В таблице HeaderField поле name имеет фиксированное значение (Authentication-Results).

Функция

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

Таблица MilterModifier

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

Поле

Описание

Тип данных

add_header_field

Функция, планирующая действие по добавлению нового заголовка к сообщению.

Принимает два обязательных аргумента:

name — имя добавляемого заголовка в виде строки;

value — значение заголовка в виде строки.

Значение будет закодировано в соответствии с RFC 2047.

Функция

change_header_field

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

Принимает два обязательных аргумента:

name — имя изменяемого заголовка в виде строки;

value — значение заголовка в виде строки.

При наличии в сообщении нескольких заголовков с указанным именем изменяет значение первого встреченного заголовка с таким именем. В случае множественного изменения значения одного и того же заголовка, сохраняется только последнее изменение. Если value — пустая строка "", то заголовок name будет удален из сообщения.

Значение будет закодировано в соответствии с RFC 2047.

Функция

modifications

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

Функция

repack

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

Принимает необязательный аргумент path или iterator:

path — путь к вложению в проверяемом сообщении, помещаемому в архив. Если не задан, либо если указанный путь не является действительным, в архив помещается все сообщение целиком.

iterator — итератор частей сообщения, возвращаемый функциями threats, urls, attachments, files, parts, leaf_parts, text_parts таблицы MimePart. В этом случае будут запланированы к перепаковке все части сообщения, перечисляемые возвращенным итератором.

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

Примеры:

-- Запланировать перемещение в архив с паролем
-- всего сообщения целиком
ctx.modifier.repack()

-- Запланировать перемещение в архив с паролем
-- части сообщения по указанному пути (либо все
-- сообщение целиком, если такой части не существует)
ctx.modifier.repack('/1/2/3')

-- Запланировать перемещение в архив с паролем
-- всех частей, которые содержат исполняемые файлы
ctx.modifier.repack(ctx.message.files{name='*.exe'})

-- Запланировать перемещение в архив с паролем
-- всех вложений, которые являются zip-архивами
ctx.modifier.repack(ctx.message.attachments{name='*.zip'})

Функция

repack_archive_name

Имя архива для запаковки вредоносных (нежелательных) элементов сообщения. По умолчанию имеет значение "quarantine.zip".

Строка

repack_password

Пароль для защиты архива. Если не указан, используется пароль, заданный в файле конфигурации (параметр RepackPassword).

Строка

repack_message

Произвольное сообщение о причинах перепаковки сообщения (или его частей), добавляемое к итоговому сообщению (может отсутствовать).

Строка

templates_dir

Путь к каталогу, из которого следует брать шаблон перепаковки сообщения. Относительный путь по отношению к пути, указанному в файле конфигурации (параметр TemplatesDir). По умолчанию имеет значение "milter" (т. е. будут использованы шаблоны из подкаталога milter).

Строка

cure

Функция, планирующая лечение вложения.

Принимает необязательный аргумент path или iterator:

path — путь к вложению в проверяемом сообщении. Функция cure(path) возвращает true, если вложение безвредно или было вылечено. Возвращает false, если вложение неизлечимо.

iterator — итератор частей сообщения, возвращаемый функциями threats, urls, attachments, files, parts, leaf_parts, text_parts таблицы MimePart. В этом случае будут запланированы к лечению все части сообщения, перечисляемые возвращенным итератором. Функция cure(iterator) возвращает true, если все вложения безвредны или были вылечены. Возвращает false, если хотя бы одно вложение оказалось неизлечимым.

Если аргумент функции не задан, эквивалентна вызову cure(ctx.message.leaf_parts()). Возвращает true, если все вложения безвредны или были вылечены. Возвращает false, если хотя бы одно вложение оказалось неизлечимым.

Функция

cure_or_repack

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

Принимает необязательный аргумент path или iterator:

path — путь к вложению в проверяемом сообщении. Функция cure_or_repack(path) возвращает true, если вложение безвредно или было вылечено. Возвращает false и планирует перепаковку вложения, если оно неизлечимо.

iterator — итератор частей сообщения, возвращаемый функциями threats, urls, attachments, files, parts, leaf_parts, text_parts таблицы MimePart. В этом случае будут запланированы к лечению все части сообщения, перечисляемые возвращенным итератором. Функция cure_or_repack(iterator) возвращает true, если все вложения безвредны или были вылечены. Если хотя бы одно вложение оказалось неизлечимым, возвращает false и планирует перепаковку всех неизлечимых вложений.

Если аргумент функции не задан, эквивалентна вызову cure_or_repack(ctx.message.leaf_parts()). Возвращает true, если все вложения безвредны или были вылечены. Если хотя бы одно вложение оказалось неизлечимым, возвращает false и планирует перепаковку всех неизлечимых вложений.

Функция

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

Для доступа к этой таблице следует воспользоваться полем modifier таблицы MilterContext, например:

function milter_hook(ctx)

 -- Запланировать добавление нового заголовка
 -- в конец списка заголовков
 ctx.modifier.add_header_field("X-Name", "Value")

 -- Запланировать изменение значения поля "Subject" на "New value"
 ctx.modifier.change_header_field("Subject", "New value")

 -- Запланировать перепаковку сообщения в архив с паролем
 ctx.modifier.repack()

 -- Вернуть вердикт по протоколу milter (таблицу MilterResult)
 -- с применением всех отложенных изменений сообщения
 return {action = "accept"}
end

С помощью приведенного ниже скрипта можно заполнить таблицу MilterResult (включая поля modifications, т. е. таблицы MilterModifications) напрямую, без использования таблицы MilterModifier:

-- Разрешить передачу сообщений получателям,
-- добавив к ним заголовок "X-Checked: True"

function milter_hook(ctx)
 return {
  action = "accept",
  modifications = {
    added_fields = {
      {
        name = "X-Checked",
        value = "True"
      }
    }
  }
 }
end

В этом примере показано, как можно вернуть вердикт accept, игнорируя изменения в таблице MilterModifier:

function milter_hook(ctx)

 …

 -- планируется добавление к сообщению заголовка
 ctx.modifier.add_header_field('X-Header', 'some value')

 …

 -- принудительный возврат пустой таблицы MilterModifications
 return {action = "accept", modifications = {}}
end

Скрипт обработки сообщений для интерфейса Spamd

Требования к скрипту

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

1.Имя функции — spamd_report_hook;

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

3.Единственное возвращаемое значение — заполненная таблица SpamdReportResult. Возвращаемое значение определяет ответ по протоколу Spamd.

Ниже приведен пример функции, которая возвращает в Dr.Web MailD вердикт о признании сообщения спамом (рейтинг спама — 200, минимальное количество баллов для признания спамом — 100, уведомление отправителю — The message was recognized as spam; здесь и далее аргумент ctx — экземпляр таблицы SpamdContext):

-- Пример тривиальной реализации

function spamd_report_hook(ctx)
 return {
  score = 200,
  threshold = 100,
  report = "The message was recognized as spam"
 }
end

Используемые таблицы

Таблица SpamdContext

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

Поле

Описание

Тип данных

session_id

Идентификатор сессии клиента, в течение которой обрабатываются сообщения, поступающие от этого клиента.

Строка

message

Почтовое сообщение

Таблица MimeMessage

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

Таблица SpamdReportResult

Таблица содержит результат, возвращаемый функцией spamd_report_hook; с ее помощью в Dr.Web MailD передаются результаты проверки сообщения на спам, которые будут отправлены MTA.

Поле

Описание

Тип данных

score

Количество баллов спама, присвоенных сообщению в ходе проверки (для MTA Exim заполняет переменные $spam_score и $spam_score_int)

Число

threshold

Минимальное количество баллов, при достижении которого сообщение будет отнесено к спаму

Число

report

Текстовый результат проверки сообщения (для MTA Exim заполняет переменную $spam_report)

Строка

incident

Текст описания инцидента в регистрируемом событии типа Mail.

Если поле — строка, содержимое этой строки будет передано в поле incident_text события типа Mail и событие будет зарегистрировано;

Если поле — булево и равно false, то поле incident_text события типа Mail будет отсутствовать и событие не будет зарегистрировано;

Если поле — булево и равно true, то поле incident_text события типа Mail будет заполнено автоматически и событие будет зарегистрировано, если полученное значение incident_text будет не пустым.

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

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

Скрипт обработки сообщений для интерфейса Rspamd

Требования к скрипту

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

1.Имя функции — rspamd_hook;

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

3.Единственное возвращаемое значение — заполненная таблица RspamdResult (см. описание таблицы ниже). Возвращаемое значение определяет ответ по протоколу RspamD.

Пример корректного определения функции (здесь и далее аргумент ctx — экземпляр таблицы RspamdContext):

-- Пример тривиальной реализации

function rspamd_hook(ctx)
 return {
  score = 200,
  threshold = 100
 }
end

Пример

Приведенный ниже скрипт вернет рекомендованное действие для MTA, а также таблицу RspamdSymbol с указанием рейтинга спама в баллах и кратким комментарием (обнаруженные в сообщении признаки спама и соответствующее каждому признаку количество баллов):

function rspamd_hook(ctx)
 return {
  score = 1080,
  threshold = 100,
  action = "REJECT:Malicious message"
  symbols = {
   {
     name = "Threat found",
     score = 1000
   },
   {
     name = "Spam score by the third-party anti-spam library",
     score = 80
   }
  }
 }
end

Используемые таблицы

Таблица RspamdContext

Таблица используется как входной аргумент функции rspamd_hook; содержит следующую информацию об обрабатываемом сообщении:

Поле

Описание

Тип данных

session_id

Идентификатор сессии клиента, в течении которой обрабатываются сообщения, поступающие от этого клиента.

Строка

sender

Информация об отправителе сообщения

Таблица RspamdSender

helo

Строка HELO/EHLO, полученная от SMTP-клиента, или nil, если строка отсутствует/неизвестна (не предоставлена MTA)

Строка

from

Адрес отправителя (без угловых скобок, например: "user@domain.com"), или nil, если адрес отсутствует/неизвестен (не предоставлен MTA)

Строка

to

Адреса получателей сообщения (без угловых скобок)

Таблица RcptTo

message

Почтовое сообщение

Таблица MimeMessage

spf

Таблица SPF, использующаяся для SPF-проверки отправителя

Таблица SPF

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

Таблица RspamdSender

Содержит информацию об отправителе почтового сообщения.

Поле

Описание

Тип данных

hostname

Имя (FQDN) узла отправителя, или nil, если отсутствует/неизвестен (не предоставлен MTA)

Строка

ip

IP-адрес узла отправителя, или nil, если отсутствует/неизвестен (не предоставлен MTA)

Таблица IpAddress

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

Таблица RspamdResult

Результат, возвращаемый функцией rspamd_hook. Содержит отчет о проверке сообщения.

Поле

Описание

Тип данных

score

Спам-рейтинг сообщения по итогам проверки (для MTA Exim заполняет переменные $spam_score и $spam_score_int)

Число

threshold

Минимальный спам-рейтинг в баллах для признания сообщения спамом

Число

action

Необязательное поле. Действие, рекомендованное MTA по результатам проверки сообщения (для MTA Exim заполняет переменную $spam_action)

Строка

symbols

Необязательное поле. Массив таблиц RspamdSymbol для определения добавления в спам-рейтинг баллов, указанных в поле score

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

incident

Текст описания инцидента в регистрируемом событии типа Mail.

Если поле — строка, содержимое этой строки будет передано в поле incident_text события типа Mail и событие будет зарегистрировано;

Если поле — булево и равно false, то поле incident_text события типа Mail будет отсутствовать и событие не будет зарегистрировано;

Если поле — булево и равно true, то поле incident_text события типа Mail будет заполнено автоматически и событие будет зарегистрировано, если полученное значение incident_text будет не пустым.

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

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

Таблица RspamdSymbol

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

Поле

Описание

Тип данных

name

Имя признака спама

Строка

score

Количество баллов, добавляемых в спам-рейтинг при наличии этого признака

Число

description

Описание обнаруженного признака (необязательное поле)

Строка

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

Скрипт обработки сообщений в режиме SMTP

Требования к скрипту

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

1.Имя функции — smtp_hook;

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

3.Единственное возвращаемое значение — заполненная таблица SmtpResult. Возвращаемое значение определяет действие по отношению к проверяемому сообщению (принять, изменить, отбросить), а также возможные действия по отношению к сообщению, если оно будет принято.

Ниже приведен пример определения функции, которая будет всегда возвращать в Dr.Web MailD вердикт Accept (принять) для всех почтовых сообщений, поступающих на проверку в режиме SMTP (здесь и далее аргумент ctx — экземпляр таблицы SmtpContext):

function smtp_hook(ctx)
 return {action = "accept"}
end

Пример

Приведенный ниже скрипт вернет в Dr.Web MailD вердикт Accept (принять) для всех почтовых сообщений и добавит ко всем сообщениям поле заголовка "X-Checked: True":

function smtp_hook(ctx)
 return {
  action = "accept",
  modifications = {
   added_fields = {
     {
      name = "X-Checked",
      value = "True"
     }
   }
  }
 }
end

Для формирования таблицы modifications можно пользоваться вспомогательным объектом MilterModifier таблицы SmtpContext, например:

function smtp_hook(ctx)
 local modifier = ctx.modifier

 -- Запланировать добавление нового поля в конец заголовка
 modifier.add_header_field("X-Name", "Value")

 -- Запланировать изменение значения поля "Subject" на "New value"
 modifier.change_header_field("Subject", "New value")

 -- Запланировать перепаковку сообщения в архив с паролем
 modifier.repack()

 -- Отправить письмо с применением всех отложенных изменений сообщения
 -- modifications можно не указывать, тогда изменения возьмутся напрямую из modifier
 return { action = "accept", modifications = modifier.modifications() }
end

Используемые таблицы

Таблица SmtpContext

Таблица используется как входной аргумент функции smtp_hook; содержит следующую информацию об обрабатываемом сообщении:

Поле

Описание

Тип данных

session_id

Идентификатор сессии клиента, в течении которой обрабатываются сообщения, поступающие от этого клиента

Строка

sender

Информация об отправителе сообщения

Таблица MilterSender

helo

Строка HELO/EHLO, полученная от SMTP-клиента, или nil, если строка отсутствует/неизвестна (не предоставлена MTA)

Строка

from

Адрес отправителя (без угловых скобок, например "user@domain.com")

Строка

to

Адреса получателей сообщения (без угловых скобок)

Таблица RcptTo

message

Почтовое сообщение

Таблица MimeMessage

modifier

Таблица MilterModifier, содержащая все изменения, запланированные к внесению в сообщение, если по результатам проверки в таблице MilterResult будет сформировано действие "accept".

Таблица MilterModifier

gen

Таблица MilterGenerator, использующаяся для генерации специальных заголовков, например X-Antivirus

Таблица MilterGenerator

spf

Таблица SPF, использующаяся для SPF-проверки отправителя

Таблица SPF

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

Таблица SmtpResult

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

Поле

Описание

Тип данных

action

Действие по отношению к сообщению:

"accept" — принять (т. е. разрешить MTA отправить сообщение к получателю);

"discard" — отбросить сообщение, не уведомляя отправителя;

"tempfail" — отклонить сообщение, вернув отправителю код SMTP 4**.

Обязательное поле.

Строка

modifications

Таблица с описанием изменений, которые следует применить к сообщению перед передачей получателю.

Необязательное поле. Используется, только если action = "accept".

Таблица MilterModifications

added_recipients

Перечень адресов дополнительных получателей сообщения.

Необязательное поле. Используется, только если action = "accept".

Массив строк

deleted_recipients

Перечень адресов для исключения из списка получателей сообщения.

Необязательное поле. Используется, только если action = "accept".

Массив строк

message

Текст ответа отправителю с информацией об отклонении сообщения. Будет возвращен клиенту с кодом 541, если сообщение проверяется синхронно.

Необязательное поле. Используется, только если action = "reject".

Строка

incident

Текст описания инцидента в регистрируемом событии типа Mail.

Если поле — строка, содержимое этой строки будет передано в поле incident_text события типа Mail и событие будет зарегистрировано;

Если поле — булево и равно false, то поле incident_text события типа Mail будет отсутствовать и событие не будет зарегистрировано;

Если поле — булево и равно true, то поле incident_text события типа Mail будет заполнено автоматически и событие будет зарегистрировано, если полученное значение incident_text будет не пустым.

Строка или логическое значение

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

Таблицы, описывающие структуру сообщения

Таблица RcptTo

Таблица содержит массив с адресами получателей сообщения (без угловых скобок), перечисленными в команде RCPT TO протокола SMTP, а также следующую дополнительную информацию

Поле

Описание

Тип данных

search

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

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

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

true — был найден адрес, полностью соответствующий хотя бы одному шаблону;

false — не было найдено адреса, полностью соответствующего хотя бы одному шаблону;

Регистр символов не учитывается.

Функция

all_match

Функция проверки всех адресов в массиве на соответствие хотя бы одному из заданных шаблонов.

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

Возвращает булево значение:

true — все адреса полностью соответствуют хотя бы одному шаблону;

false — нет адресов, полностью соответствующих хотя бы одному шаблону

Регистр символов не учитывается.

Функция

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

Таблица MimeMessage

Таблица описывает проверяемое почтовое сообщение целиком (содержит те же поля, что и таблица MimePart, а также некоторую дополнительную информацию):

Поле

Описание

Тип данных

dkim

DKIM-подписи сообщения (см. RFC 6376)

Таблица DKIM

raw

Сообщение от клиента

Строка

spam

Отчет о результатах проверки на признаки спама

Таблица Spam

from

Значение заголовка From, или nil, если From отсутствует в сообщении

Таблица From

to

Значение заголовка To, или nil, если To отсутствует в сообщении

Таблица To

date

Значение заголовка Date, или nil, если Date отсутствует в сообщении

Строка

message_id

Значение заголовка Message-ID, или nil, если Message-ID отсутствует в сообщении

Строка

subject

Значение заголовка Subject, или nil, если Subject отсутствует в сообщении

Строка

user_agent

Значение заголовка User-Agent, или nil, если User-Agent отсутствует в сообщении

Строка

vxcube_analysis

Результат проверки письма в Dr.Web vxCube. Поле присутствует только при работе в режиме SMTP.

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

(далее следуют те же поля, что и в таблице MimePart (см. ниже); они описывают корневую часть MIME).

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

Таблица MimePart

Таблица описывает часть сообщения.

Поле

Описание

Тип данных

header

Заголовок части

Таблица MimeHeader

body

Тело части, либо nil, если присутствуют вложенные части.

Таблица MimeBody

part

Вложенные (в текущую часть сообщения) части в виде массива таблиц. Если вложенных частей нет, массив будет пуст.

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

content_disposition

Содержимое заголовка Content-Disposition, либо nil, если этот заголовок отсутствует в части.

Таблица ContentDisposition

content_id

Содержимое заголовка Content-ID, либо nil, если этот заголовок отсутствует в части.

Строка

content_type

Содержимое заголовка Content-Type, либо nil, если этот заголовок отсутствует в части.

Таблица ContentType

name

Имя вложения, либо nil, если часть не является вложением

Строка

part_at

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

Путь path — строка вида "/1/2/3". Раскрывается как root_part.part[1].part[2].part[3]. Пути вида "", "/", "//" и т. д. (без чисел) соответствуют части сообщения, у которой вызывается эта функция (то есть root_part). При отсутствии дочерней части по заданному пути, а также при неправильном пути возвращает nil.

Функция

threats

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

таблицу Virus;

относительный путь к части сообщения, которая содержит найденную угрозу.

В качестве аргумента filter можно использовать:

таблицу ThreatFilter;

произвольную функцию-предикат, принимающую единственный аргумент Virus и возвращающую булево значение:

otrue — если аргумент удовлетворяет условию (является угрозой);

ofalse — если аргумент не удовлетворяет условию (не является угрозой).

Функция

urls

Функция, принимающая один необязательный аргумент filter. Возвращает единственное значение — функцию-итератор. С помощью этого итератора можно перебрать все URL, которые находятся в этой части сообщения и в ее вложенных частях, и соответствуют указанному условию filter. Функция-итератор не имеет аргументов и возвращает два значения:

таблицу Url;

относительный путь к части сообщения, которая содержит найденный URL.

В качестве аргумента filter можно использовать:

таблицу UrlFilter;

произвольную функцию-предикат, принимающую единственный аргумент Url и возвращающую булево значение:

otrue — если аргумент удовлетворяет условию (является нежелательным);

ofalse — если аргумент не удовлетворяет условию (не является нежелательным).

Функция

attachments

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

таблицу MimePart;

относительный путь к части сообщения, которая содержит найденное вложение.

В качестве аргумента filter можно использовать:

таблицу PartFilter;

произвольную функцию-предикат, принимающую единственный аргумент типа MimePart и возвращающую логическое значение:

otrue — если аргумент удовлетворяет условию;

ofalse — если аргумент не удовлетворяет условию

Функция

files

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

имя файла в виде строки;

относительный путь к части сообщения, которая содержит найденный файл.

В качестве аргумента filter можно использовать:

таблицу FileFilter;

произвольную функцию-предикат, принимающую имя файла в виде строки и возвращающую булево значение:

otrue — если аргумент удовлетворяет условию;

ofalse — если аргумент не удовлетворяет условию

Функция

parts

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

таблицу MimePart;

относительный путь к части сообщения.

В качестве аргумента filter можно использовать:

таблицу PartFilter;

произвольную функцию-предикат, принимающую таблицу MimePart и возвращающую логическое значение:

otrue — если аргумент удовлетворяет условию;

ofalse —если аргумент не удовлетворяет условию

Функция

leaf_parts

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

таблицу MimePart;

относительный путь к части сообщения.

В качестве аргумента filter можно использовать:

таблицу PartFilter;

произвольную функцию-предикат, принимающую таблицу MimePart и возвращающую булево значение:

otrue — если аргумент удовлетворяет условию;

ofalse — если аргумент не удовлетворяет условию.

Функция

text_parts

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

таблицу MimePart;

относительный путь к части сообщения.

В качестве аргумента filter можно использовать:

таблицу PartFilter;

произвольную функцию-предикат, принимающую таблицу MimePart и возвращающую булево значение:

otrue — если аргумент удовлетворяет условию;

ofalse — если аргумент не удовлетворяет условию.

Функция

scan_reports

Функция, принимающая один необязательный аргумент filter. Возвращает единственное значение — функцию-итератор. С помощью этого итератора можно перебрать все отчеты о проверке на угрозы этой части сообщения и ее вложенных частей, и соответствуют указанному условию filter.

Функция-итератор не имеет аргументов и возвращает одно значение: таблицу ScanReport.

В качестве аргумента filter можно использовать:

таблицу ScanReportFilter;

произвольную функцию-предикат, принимающую таблицу ScanReport и возвращающую логическое значение:

otrue — если аргумент удовлетворяет условию;

ofalse — если аргумент не удовлетворяет условию.

Функция

has_url

Функция, принимающая один необязательный аргумент filter (см. описание функции urls выше).

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

true — если в этой части сообщения и в ее вложенных частях содержится URL, удовлетворяющая указанному условию filter;

false — если в этой части сообщения и в ее вложенных частях нет URL, удовлетворяющей указанному условию filter.

Примеры:

if ctx.message.has_url() then
  -- в сообщении найден хотя бы один URL (любой)
end

if ctx.message.has_url{category = "adult_content"} then
  -- найдена ссылка на ресурс для взрослых
end

if ctx.message.has_url{category = {"adult_content", "social_networks"}} then
  -- найдена ссылка на "adult_content" либо "social_networks"
end

if ctx.message.has_url{category = "black_list"} then
  -- найдена ссылка на ресурс, занесенный в черный список
end

if ctx.message.has_url{host = "example.com"} then
  -- найдена ссылка с "example.com" в части host
end

if ctx.message.has_url{host_not = "*example.com"} then
  -- найдена ссылка с хостом, не удовлетворяющим шаблону "*example.com"
end

if ctx.message.has_url(function(url) return port > 80 end) then
  -- найдена ссылка с указанным портом с номером больше 80
end

Функция

has_threat

Функция, принимающая один необязательный аргумент filter (см. описание функции threats выше).

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

true — если в этой части сообщения и в ее вложенных частях содержится угроза, удовлетворяющая указанному условию filter;

false — если в этой части сообщения в ее вложенных частях не содержится угрозы, удовлетворяющая указанному условию filter.

Примеры:

if ctx.message.has_threat() then
  -- сообщение содержит хотя бы одну угрозу любого типа
end

if ctx.message.has_threat({category = "known_virus"}) then
  -- сообщение содержит хотя бы одну угрозу типа "known_virus"
end

if ctx.message.has_threat{category = "known_virus"} then
  -- то же самое
end

if ctx.message.has_threat({category = {"known_virus", "joke"}}) then
  -- сообщение содержит хотя бы одну угрозу типа "known_virus" или "joke"
end

if ctx.message.has_threat{category_not = "joke"} then
  -- сообщение содержит угрозу любой категории, кроме "joke"
end

Функция

has_file

Функция, принимающая один необязательный аргумент filter (см. описание функции files выше).

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

true — если в этой части сообщения и в ее вложенных частях содержится файл, удовлетворяющий указанному условию filter (в том числе проверяются и файлы, находящиеся в архивах);

false — если в этой части сообщения и в ее вложенных частях содержится файла, удовлетворяющего указанному условию filter (в том числе проверяются и файлы, находящиеся в архивах).

Примеры:

if ctx.message.has_file() then
  -- в сообщении найден хотя бы один любой файл
end

if ctx.message.has_file{name = "*.exe"} then
  -- в сообщении найден хотя бы один файл типа exe
end

Функция

has_part

Функция, принимающая один необязательный аргумент filter (см. описание функции parts выше).

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

true — если в этой части сообщения и в ее вложенных частях содержится часть, удовлетворяющая указанному условию filter;

false — если в этой части сообщения и в ее вложенных частях не содержится части, удовлетворяющей указанному условию filter.

Функция

has_scan_report

Функция, принимающая один необязательный аргумент filter (см. описание функции scan_reports выше).

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

true — если в части сообщения или в ее вложенных частях содержится отчет о проверке на наличие угроз, удовлетворяющий указанному условию filter;

false — если в части сообщения или в ее вложенных частях не содержится отчета о проверке на наличие угроз, удовлетворяющего указанному условию filter.

Примеры использования см. в описании таблицы ScanReportFilter.

Функция

search

Функция поиска текста в части сообщения по регулярному выражению (PCRE). На вход принимает регулярное выражение (строка). Обратите внимание, что при использовании строк в кавычках символ косой черты необходимо экранировать.

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

true — если в данной части сообщения или любой из дочерних частей найдено совпадение с заданным регулярным выражением;

false — если в данной части сообщения или любой из дочерних частей не найдено совпадений с заданным регулярным выражением;

Функция

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

Таблица From

Таблица описывает заголовок From. Содержит перечень почтовых адресов, извлеченных из заголовка (массив строк), а также следующую дополнительную информацию:

Поле

Описание

Тип данных

search

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

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

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

true — был найден адрес, полностью соответствующий хотя бы одному шаблону;

false — не было найдено адреса, полностью соответствующего хотя бы одному шаблону

Регистр символов не учитывается.

Функция

all_match

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

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

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

true — все адреса полностью соответствуют хотя бы одному шаблону;

false — не все адреса полностью соответствуют хотя бы одному шаблону.

Регистр символов не учитывается.

Функция

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

__tostring — функция, возвращающая раскодированное значение заголовка;

__concat — функция, выполняющая присоединение раскодированного значения заголовка к строке.

Таблица To

Таблица описывает заголовок сообщения To. Содержит те же поля и методы, что и таблица From.

Таблица ContentType

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

Поле

Описание

Тип данных

type

MIME-тип части сообщения

Строка

subtype

Подтип части сообщения

Строка

param

Параметры заголовка в виде массива таблиц, содержащих следующие поля:

name — имя параметра (строка);

value — значение параметра (строка).

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

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

__tostring — функция, возвращающая раскодированное значение заголовка;

__concat — функция, выполняющая присоединение раскодированного значения заголовка к строке.

Таблица ContentDisposition

Таблица описывает заголовок части сообщения Content-Disposition.

Поле

Описание

Тип данных

type

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

Строка

param

Параметры заголовка в виде массива таблиц, содержащих следующие поля:

name — имя параметра (строка);

value — значение параметра (строка).

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

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

__tostring — функция, возвращающая раскодированное значение заголовка;

__concat — функция, выполняющая присоединение раскодированного значения заголовка к строке.

Таблица Spam

Таблица содержит отчет о проверке сообщения на спам.

Поле

Описание

Тип данных

type

Тип («спам-статус») сообщения. Возможные значения:

"legit" — сообщение не является спамом;

"spam" — сообщение признано спамом;

"virus" — сторонний эвристический анализатор обнаружил в теле сообщения вирус;

"bounce" — сообщение содержит отчет о невозможности доставки (DSN), направляемый отправителю оригинального сообщения;

"suspicious" — подозрительное сообщение;

"pce" — «профессиональное» коммерческое (рекламное) сообщение (от легальной службы рассылок);

"mce" — коммерческое (рекламное) сообщение, отправленное не от легальной службы рассылок, но содержащее возможности отказа от получения рассылки;

"dce" — «грязное» коммерческое (рекламное) сообщение, не содержащее возможности отказа от получения рассылки;

"community" — сообщение от социальной сети;

"transactional" — сообщение о транзакции (регистрация, приобретение товара или услуги);

"phishing" — мошенническое сообщение;

"scam" — мошенническое сообщение (сообщение-афера).

Строка

score

Количество баллов спама, присвоенных сообщению

Число

normalized_score

Количество баллов спама score, нормализованное в интервал [0, 1)

Число

reason

Зашифрованная строка, содержащая объяснение, почему сообщение признано спамом

Строка

version

Версия сторонней антиспам-библиотеки

Строка

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

Таблица Virus

Таблица содержит описание угрозы.

Поле

Описание

Тип данных

type

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

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

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

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

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

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

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

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

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

Строка

name

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

Строка

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

Таблица Url

Таблица описывает URL, найденные в сообщении.

Поле

Описание

Тип данных

scheme

Префикс схемы (протокола), например "http"

Строка

host

Имя или IP-адрес узла, например: "example.com"

Строка

port

Номер порта, например: 80. Если отсутствует в URL — nil.

Число

path

Путь к ресурсу, например: "index.html". Если отсутствует в URL — nil.

Строка

categories

Массив категорий, к которым был отнесен 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" — черный список (любые веб-сайты, по тем или иным причинам признанные нежелательными для посещения администратором почтового сервера.

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

legal_url

В случае принадлежности URL категории owners_notice содержит строку с URL, ведущим на веб-сайт правообладателя, иначе — nil.

Строка

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

__tostring — функция, возвращающая содержимое Url в виде строки (в кодировке UTF-8);

__concat — функция, присоединяющая значение URL, преобразованного в строку, к строке.

Таблица ThreatFilter

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

Поле

Описание

Тип данных

category

Перечень категорий, которым должна соответствовать угроза (нечувствительно к регистру), список категорий см. в описании поля type таблицы Virus.

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

category_not

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

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

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

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

Примеры использования:

1.Вывести в журнал имена всех угроз, найденных в сообщении:

function milter_hook(ctx)

 …

 for virus in ctx.message.threats() do
  dw.notice("threat found: " .. virus.name)
 end

 …

end

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

function milter_hook(ctx)

 …

 for v, p in ctx.message.threats({category = "known_virus"}) do
  dw.notice("found " .. v.name .. " in " .. ctx.message.part_at(p).name(p))
 end

 …

end

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

function milter_hook(ctx)

 …

 local function eicar_filter(v)
  return v.name == "EICAR Test File (NOT a Virus!)"
 end

 for v, p in ctx.message.threats(eicar_filter) do
  dw.notice("found " .. v.name .. " in " .. ctx.message.part_at(p).name(p))
 end

 …

end

Таблица UrlFilter

Таблица описывает фильтр для URL (аналогично таблице ThreatFilter выше); все ее поля являются необязательными.

Поле

Описание

Тип данных

category

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

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

category_not

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

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

text

Текст, которому должен соответствовать URL

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

text_not

Текст, которому не должен соответствовать URL

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

host

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

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

host_not

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

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

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

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

Примеры использования:

1.Вывести в журнал все URL, найденные в сообщении:

function milter_hook(ctx)

 …

 for url in ctx.message.urls() do
  dw.notice("url found: " .. url)
 end

 …

end

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

function milter_hook(ctx)

 …

 for u, p in ctx.message.urls{category = "adult_content"} do
  dw.notice("found " .. u.text .. " in " .. ctx.message.part_at(p).name(p))
 end

 …

end

Таблица FileFilter

Таблица описывает фильтр для файлов (аналогично таблице ThreatFilter выше); все ее поля являются необязательными):

Поле

Описание

Тип данных

name

Набор символов или шаблон (wildcard), с которым должно совпадать имя файла; например: "*.exe", "eicar.txt".

Нечувствительно к регистру.

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

name_re

Регулярное выражение (PCRE), которому должно соответствовать имя файла; например: ".*\\.zip", [[.*\.zip]].

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

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

name_not

Набор символов, с которым не должно совпадать имя файла

Нечувствительно к регистру.

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

name_re_not

Регулярное выражение (PCRE), которому не должно соответствовать имя файла

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

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

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

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

Пример использования:

Вывести в журнал имена частей, содержащих файлы с расширением .exe.

function milter_hook(ctx)

 …

 for f, p in ctx.message.files{name = "*.exe"} do
  local where = ctx.message.part_at(p).name
  if not where or where == "" then where = p end
  dw.notice("EXE found in " .. where)
 end

 …

end

Таблица PartFilter

Таблица описывает фильтр для частей сообщения (аналогично таблице FileFilter выше); все ее поля являются необязательными.

Поле

Описание

Тип данных

name

Набор символов или шаблон (wildcard), с котором должно совпадать имя части; например: "*.exe", "eicar.txt".

Нечувствительно к регистру.

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

name_re

Регулярное выражение (PCRE), которому должно соответствовать имя части; например: ".*\\.zip", [[.*\.zip]].

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

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

content_type

Набор символов или шаблон (wildcard), с которым должно совпадать значение заголовка Content-Type у части (вложения); например: "image/*".

Нечувствительно к регистру.

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

content_disposition

Набор символов или шаблон (wildcard), с которым должно совпадать значение заголовка Content-Disposition, у части (вложения); например: "inline", "attachment".

Нечувствительно к регистру.

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

name_not

Набор символов, с которым не должно совпадать имя части

Нечувствительно к регистру.

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

name_re_not

Регулярное выражение (PCRE), которому не должно соответствовать имя части сообщения.

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

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

content_type_not

Набор символов, которому должно соответствовать значение заголовка Content-Type у части.

Нечувствительно к регистру.

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

content_disposition_not

Набор символов, которому не должно соответствовать значение заголовка Content-Disposition, у части.

Нечувствительно к регистру.

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

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

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

Примеры использования:

1.Вывести в журнал имена всех вложений и их хеш MD5:

function milter_hook(ctx)

 …

 for a, p in ctx.message.attachments() do
  -- имя вложения может быть пустой строкой, если
  -- оно не указано в Content-Type и в Content-Disposition
  local name = a.name
  if name == "" then name = "at path " .. p end
  dw.notice("Attachment: " .. name .. "; md5=" .. a.body.md5)
 end

 …

end

2.Вывести в журнал имена всех вложений с расширением .exe:

function milter_hook(ctx)

 …

 for a in ctx.message.attachments{name = "*.exe"} do
  dw.notice("EXE attachment: " .. a.name)
 end

 …

end

3.Подсчитать количество графических файлов в сообщении по их типам:

function milter_hook(ctx)

 …

 local images = {}
 for part, path in ctx.message.parts{content_type = "image/*"} do
  local subtype = part.content_type.subtype
  images[subtype] = (images[subtype] or 0) + 1
 end

 for t, c in pairs(images) do
  dw.notice("Found " .. t .. " images: " .. c)
 end

 …

end

4.Вывести в журнал все аудиофайлы, имеющиеся во вложениях:

function milter_hook(ctx)

 …

 for p, path in ctx.message.parts{
  content_type = "audio/*",
  content_disposition = {"inline", "attachment"}
 } do
    local name = p.name
    if name == "" then name = "<unnamed>" end
    dw.notice("Audio file: " .. name)
 end

 …

end

Таблица ScanReportFilter

Таблица описывает фильтр для отчетов о проверке частей сообщения на наличие угроз (аналогично таблице FileFilter выше). Все ее поля являются необязательными:

Поле

Описание

Тип данных

error

Ошибка, которая должна присутствовать в отчете о проверке ScanReport; например: "password_protected", "scan_timeout".

Нечувствительно к регистру.

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

error_not

Ошибка, которая не должна присутствовать в отчете о проверке ScanReport; например: "password_protected", "scan_timeout".

Нечувствительно к регистру.

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

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

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

Примеры использования:

1.Отправить сообщение в карантин, если были неудачные попытки проверить защищенный паролем архив:

function milter_hook(ctx)

 …

 if ctx.message.has_scan_report{error = 'password_protected'} then
   return
    {
      action = 'accept', deleted_recipients = ctx.to,
      added_recipients = {'quarantine@mail.domain.com'}
    }
 end

 …

end

2.Отправить сообщение в карантин, если были превышены ограничения на проверку:

function milter_hook(ctx)

 …

 local limit_errors = {
  'archive_level_limit', 'compression_limit',
  'container_level_limit', 'mail_level_limit',
  'packer_level_limit', 'report_size_limit'
 }

 if ctx.message.has_scan_report{error = limit_errors} then
   return
    {
      action = 'accept', deleted_recipients = ctx.to,
      added_recipients = {'quarantine@mail.domain.com'}
    }
 end

 …

end

3.Отклонить сообщение, если были любые ошибки проверки:

function milter_hook(ctx)

 …

 if ctx.message.has_scan_report{error = '*'} then
   return {action = 'reject'}
 end

 …

end

Таблица MimeHeader

Таблица описывает характеристики, общие для всех заголовков части.

Поле

Описание

Тип данных

field

Список заголовков и их значений

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

search

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

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

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

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

Функция

value

Функция возврата значения указанного заголовка. На вход принимает имя заголовка (строка).

Возвращает таблицу HeaderFieldValue, соответствующую первому найденному заголовку с указанным именем, либо nil, если такого заголовка не найдено.

Функция

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

Таблица HeaderField

Таблица описывает индивидуальные характеристики каждого отдельного заголовка части.

Поле

Описание

Тип данных

name

Имя заголовка

Строка

value

Значение заголовка

Таблица HeaderFieldValue

url

Список найденных в значении заголовка URL (только для заголовка Subject), для всех остальных заголовков — nil

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

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

Таблица HeaderFieldValue

Таблица описывает значение заголовка почтового сообщения.

Поле

Описание

Тип данных

raw

«Сырое» (нераскодированное) значение заголовка

Строка

decoded

Раскодированное значение заголовка

Строка

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

__tostring — функция, возвращающая содержимое HeaderFieldValue (значение поля decoded) в виде строки;

__concat — функция, присоединяющая HeaderFieldValue (значения поля decoded) к строке.

Таблица MimeBody

Таблица описывает тело части почтового сообщения.

Поле

Описание

Тип данных

raw

Тело части в «сыром» (нераскодированном) виде

Строка

decoded

Раскодированное значение тела части (в соответствии со значением заголовков Content-Transfer-Encoding и Content-Type)

Строка

text

Раскодированное значение тела части, представленное в кодировке в UTF-8 в соответствии с параметром charset заголовка Content-Type.

Присутствует только для частей с "Content-Type: text/*" или пустым Content-Type, иначе — nil.

Строка

scan_report

Отчет о проверке части на наличие угроз

Таблица ScanReport

url

URL, найденные в тексте части, в виде массива таблиц типа Url.

Если поле text отсутствует (nil), это поле будет пустым.

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

search

Функция поиска текста в теле по регулярному выражению (PCRE). На вход принимает регулярное выражение (строка). Обратите внимание, что при использовании строк в кавычках символ косой черты необходимо экранировать.

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

true — если тело является текстом и найдено совпадение;

false — если тело не является текстом и совпадений не найдено.

Функция

md5

MD5-хеш тела части почтового сообщения.

Строка

sha1

SHA1-хеш тела части почтового сообщения.

Строка

sha256

SHA256-хеш тела части почтового сообщения.

Строка

vxcube_analysis

Результат проверки письма в Dr.Web vxCube. Поле присутствует только при работе в режиме SMTP.

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

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

Таблица ScanReport

Таблица содержит отчет о проверке на наличие угроз.

Поле

Описание

Тип данных

object

Имя проверенного объекта

Строка

archive

Информация о контейнере, если проверенный объект — контейнер. Если объект не является контейнером, то nil

Таблица Archive

virus

Перечень обнаруженных угроз

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

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" — неожиданная ошибка.

Строка

item

Отчеты о проверке вложенных элементов, если проверяемый объект — контейнер (архив, вложенный MIME-объект и т. п.)

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

Таблица Archive

Таблица используется для описания архивов и прочих объектов с вложениями.

Поле

Описание

Тип данных

type

Тип архива:

"archive" — архив;

"mail" — файл электронной почты (сообщение, почтовый ящик и т. п.);

"container" — контейнер иного типа.

Строка

name

Имя архива, например — ZIP

Строка

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

Таблица DKIM

Таблица содержит все DKIM-подписи сообщения.

Поле

Описание

Тип данных

signature

Список DKIM-подписей, которые присутствуют в сообщении

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

has_valid_signature

Функция, принимающая один необязательный аргумент filter и возвращающая:

первую найденную DKIM-подпись, результат проверки которой равен "pass", в виде таблицы DKIMSignature;

nil, если сигнатуры, прошедшие проверку, не найдены.

В качестве аргумента filter можно использовать:

таблицу DKIMSignatureFilter;

произвольную функцию-предикат, принимающую единственный аргумент типа DKIMSignature и возвращающую логическое значение:

otrue — если аргумент удовлетворяет условию;

ofalse — если аргумент не удовлетворяет условию.

Функция

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

Таблица DKIMSignature

Таблица описывает характеристики каждой отдельной DKIM-подписи.

Поле

Описание

Тип данных

auid

Значение Agent or User Identifier (AUID), извлеченное из тега "i" DKIM-подписи, учитывает значение по умолчанию

Строка

data

Текстовое (base64) значение подписи, извлеченное из тега "b" в DKIM-подписи

Строка

result

Результат проверки DKIM-подписи

Таблица DKIMResult

sdid

Значение Signing Domain Identifier (SDID), извлеченный из тега "d" в DKIM-подписи

Строка

selector

Селектор, извлеченный из тега "s" в DKIM-подписи

Строка

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

Таблица DKIMResult

Таблица содержит результат проверки для каждой DKIM-подписи.

Поле

Описание

Тип данных

type

Текстовый результат проверки DKIM-подписи. Может принимать одно из следующих значений:

pass — проверка подписи прошла успешно;

fail — проверка подписи закончилась неудачно (не соответствует хешу тела письма либо сама подпись не прошла проверку);

neutral — синтаксическая ошибка DKIM-подписи;

temperror — не удалось получить ключ домена (ошибка DNS);

permerror — иная ошибка (формата подписи, ключа, несоответствие ключа подписи и пр).

Строка

comment

Комментарий к результату проверки (может использоваться в виде комментария в Authentication-Results)

Строка

key_size

Размер ключа, которой использовался при проверке, либо nil, если не получилось получить ключ или результат проверки — neutral

Число

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

Таблица DKIMSignatureFilter

Таблица описывает фильтр для DKIM-подписей сообщения (аналогично таблице FileFilter выше). Все ее поля являются необязательными):

Поле

Описание

Тип данных

domain

Набор символов или шаблон (wildcard), которому должен соответствовать домен из поля SDID в DKIM-подписи

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

domain_not

Набор символов или шаблон (wildcard), которому не должен соответствовать домен из поля SDID в DKIM-подписи

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

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

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

Таблица SPF

Содержит данные, необходимые для SPF-проверки.

Поле

Описание

Тип данных

helo

Результат проверки HELO

from

Результат проверки MAIL FROM

check()

Вспомогательная функция; выполняет сначала проверку MAIL FROM, а затем (если никакого вердикта не было получено) — HELO. Возвращает результат проверки в виде строки, возможные значения которой точно такие же, какие у поля status в таблице SPFResult.

Предназначена для передачи результатов в OpenDMARC через сгенерированный заголовок Authentication-Results

Функция

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

Таблица SPFResult

Содержит результат SPF-проверки.

Поле

Описание

Тип данных

status

Текстовый результат проверки; имеет одно из значений, описанных в RFC 7208: none, neutral, pass, fail, softfail, temperror, permerror

Строка

explanation

Объяснение результата проверки (если получен результат fail)

Строка или nil, если объяснение отсутствует или его не удалось получить по той или иной причине

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

Таблица VxcubeAnalysis

Содержит результат анализа объекта в Dr.Web vxCube.

Поле

Описание

Тип данных

filename

Имя проанализированного вложения

Строка

id

Идентификатор анализа

Строка

sample_id

Идентификатор проанализированного файла

Строка

format_name

Формат проанализированного файла

Строка

tasks

Результат анализа

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

max_maliciousness

Максимальное значение поля maliciousness из массива таблиц VxcubeTask. Представляет собой число с плавающей запятой от 0 до 100 или nil, если произошла ошибка.

Число или nil

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

Таблица VxcubeTask

Содержит результаты анализа объекта в Dr.Web vxCube на отдельной платформе. Структура таблицы примерно соответствует объекту TaskFinished, получаемого с помощью API Dr.Web vxCube.

Поле

Описание

Тип данных

id

Идентификатор задачи

Строка

status

Статус проверки, например "failed" или "finished"

Строка

platform_code

Код платформы, на которой происходила проверка. Если произошла ошибка, то nil.

Строка или nil

maliciousness

Степень вредоносности объекта. Представляет собой число с плавающей запятой от 0 до 100 или nil, если произошла ошибка.

Число или nil

verdict

Общая оценка вредоносности файла, соответствующая одной из трех категорий. Имеет вид <категория><степень>, где <категория> — одно из значений: "neutral" (чистый), "suspicious" (подозрительный), "malware" (опасный); <степень> — целое число, степень вредоносности (от 1 до 3). Пример значений вердикта: "malware1", "suspicious3".

Строка

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

Доступные вспомогательные модули

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

Имя модуля

Назначение

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

Предоставляет инструменты для запроса данных из внешних источников путем обращения к модулю Dr.Web LookupD

Предоставляет инструменты для проверки вхождения адресов узлов в черные списки DNSxL

Предоставляет интерфейс сопоставления строк с регулярными выражениями

Предоставляет интерфейс запуска внешних приложений (процессов)

Предоставляет таблицу, содержащую значения параметров конфигурации Dr.Web MailD

Предоставляет функции для хранения данных между запусками MailD

Содержимое модуля drweb

1.Функции

Модуль предоставляет набор функций.

Для записи сообщений из программы 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(<путь к файлу>) формирует из содержимого указанного текстового файла массив строк. Пустые строки и строки, состоящие только из пробельных символов будут проигнорированы.

2.Таблицы

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

Поле

Описание

Тип данных

wait

Функция, возвращающая результат функции, запущенной при помощи функции async. Если функция еще не завершила свое выполнение, ожидает завершения и возвращает результат. Если функция завершилась до момента вызова wait, результат возвращается немедленно. Если запущенная функция завершилась с ошибкой, вызов wait генерирует ту же ошибку.

Функция

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

Таблица IpAddress описывает IP-адрес.

Поле

Описание

Тип данных

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')

3.Примеры

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

local dw = require "drweb"

-- Функция, возвращающая полученную в качестве аргумента строку
-- по истечении двух секунд ожидания
function out_msg(message)
 dw.sleep(2)
 return message
end

-- "Главная" функция
function intercept(ctx)
 -- Вывод строки на уровне NOTICE в журнал Dr.Web для почтовых серверов UNIX
 dw.notice("Intercept function started.")

 -- Асинхронный запуск двух экземпляров функции out_msg
 local f1 = dw.async(out_msg, "Hello,")
 local f2 = dw.async(out_msg, " world!")

 -- Ожидание завершения исполнения экземпляров функции
 -- out_msg и вывод их результатов в журнал
 -- Dr.Web для почтовых серверов UNIX на уровне DEBUG
 dw.log("debug", f1.wait() .. f2.wait())
end

Создание регулярной процедуы:

local dw = require "drweb"

-- Сохранить таблицу Future в глобальную переменную futurе, чтобы
-- предотвратить ее удаление сборщиком мусора
future = dw.async(function()
   while true do
     -- Каждый день выводит в журнал указанное сообщение
     dw.sleep(60 * 60 * 24)
     dw.notice("A brand new day began")
   end
end)

Преобразование IP-адреса из строки:

local dw = require "drweb"

local ipv4 = dw.ip("127.0.0.1")
local ipv6 = dw.ip("::1")
local mapped = dw.ip("::ffff:127.0.0.1")

 

Содержимое модуля drweb.lookup

1.Функции

Модуль предоставляет функции:

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

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

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

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

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

2.Примеры

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

local dw = require "drweb"
local dwl = require "drweb.lookup"

-- "Главная" функция
function intercept(ctx)
 -- Запись строки на уровне NOTICE в журнал Dr.Web для почтовых серверов UNIX
 dw.notice("Intercept function started.")

 -- Вывод в журнал Dr.Web для почтовых серверов UNIX результатов запроса
 -- к источнику данных 'ldap@users'
 for _, s in ipairs(dwl.lookup("ldap@users", {user="username"})) do
   dw.notice("Result for request to 'ldap@users': " .. s)
 end

end

 

Содержимое модуля drweb.dnsxl

1.Функции

Модуль предоставляет функции:

ip(<IP-адрес>, <сервер DNSxL>) запрашивает DNS-записи типа A у DNSxL-сервера <сервер DNSxL>, соответствующие указанному IP-адресу <IP-адрес>.

Если проверяемый IP-адрес зарегистрирован в списках DNSxL-сервера, то результатом будет список фиктивных IP-адресов, причем каждый возвращаемый сервером фиктивный IP-адрес может содержать в себе причину, по которой проверяемый <IP-адрес> был внесен в списки данного сервера (как правило, тип причины определяется значением последнего октета возвращенного фиктивного IP-адреса). Если опрашиваемый DNSxL-сервер не содержит DNS-записей типа A для IP-адреса <IP-адрес>, функция вернет nil.

url(<URL>, <сервер SURBL>) запрашивает DNS-записи типа A у сервера <сервер SURBL>, соответствующие доменной части <URL> (перенаправления HTTP не обрабатываются).

Если проверяемый домен, извлеченный из <URL>, зарегистрирован в списках SURBL-сервера, то результатом будет список фиктивных IP-адресов, причем каждый возвращаемый сервером фиктивный IP-адрес может содержать в себе причину, по которой проверяемый домен был внесен в списки данного сервера (как правило, тип причины определяется значением последнего октета возвращенного фиктивного IP-адреса). Если опрашиваемый SURBL-сервер не содержит DNS-записей типа A для доменов из <URL>, функция вернет nil.

Аргументами функций являются строки, либо объекты, приводимые к строкам (например, в качестве <IP-адрес> может быть использована таблица IpAddress, а в качестве <URL> — таблица Url). IP-адреса возвращаются в виде массива таблиц IpAddress.

2.Таблицы

Таблица IpAddress, описывающая IP-адрес. Описание таблицы см. выше.

3.Примеры

Вывод в журнал результатов проверки IP-адреса DNSxL-сервером:

local dw = require "drweb"
local dwxl = require "drweb.dnsxl"

-- "Главная" функция
function intercept(ctx)
 -- Вывод строки на уровне NOTICE в журнал Dr.Web для почтовых серверов UNIX
 dw.notice("Intercept function started.")

 -- Вывод в журнал Dr.Web для почтовых серверов UNIX результатов проверки
 -- IP-адреса 10.20.30.40 в черном списке DNSxL-сервера
 -- dnsxl.server1.org
 local records = dwxl.ip("10.20.30.40", "dnsxl.server1.org")
 if records then
   for _, ip in ipairs(records) do
    dw.notice("DNSxL A record for 10.20.30.40: " .. ip)
   end
 end

end

 

Содержимое модуля drweb.regex

1.Функции

Модуль предоставляет функции:

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

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

2.Доступные флаги

ignore_case — игнорировать регистр текста.

3.Примеры

local rx = require "drweb.regex"

rx.search("te.?t", "some TexT") -- false
rx.search("te.?t", "some TexT", rx.ignore_case) -- true

rx.match("some.+", "some TexT") -- true

 

Содержимое модуля drweb.subprocess

1.Функции

Модуль предоставляет функцию:

run(<параметры>) запускает указанный процесс (приложение) в синхронном режиме (функция вернет управление только после завершения вызываемого процесса). Аргумент <параметры> представляет собой таблицу, содержащую путь к исполняемому файлу, все аргументы, передаваемые приложению при запуске (массив argv), а также необязательные параметры, связываемые с потоками ввода/вывода приложения (stdin, stdout, stderr), задающие рабочий (текущий) каталог приложения и переменные окружения.

Результатом работы функции является таблица, содержащая результаты работы процесса после его завершения: код завершения либо номер сигнала, по которому завершился процесс в случае его нештатного (аварийного) завершения. Кроме того, в возвращаемой таблице могут присутствовать поля с данными, прочитанными из потоков вывода stdout и stderr, если они были указаны в таблице параметров запуска процесса.

2.Таблицы

Таблица входных параметров запуска

Поле

Описание

Тип данных

(без имени)

Путь к файлу и аргументы запуска приложения (массив argv).

Обязательное поле. Поле повторяется по количеству аргументов командной строки, первое значение соответствует argv[0], т. е. путь к исполняемому файлу.

Строка

stdin

Текст, который приложение (процесс) получит из потока ввода (stdin) после запуска. Необязательное поле (если не указано, в stdin не будет записано ничего).

Строка

stdout

Имя поля возвращаемой таблицы, в которое будет помещен текст, выведенный процессом в ходе работы в поток stdout. Необязательное поле (если не указано, результат вывода процесса в stdout не сохраняется).

Строка

stderr

Имя поля возвращаемой таблицы, в которое будет помещен текст, выведенный процессом в ходе работы в поток stderr. Необязательное поле (если не указано, результат вывода процесса в stderr не сохраняется).

Строка

env

Таблица, полями которой являются переменные окружения, устанавливаемые в окружении запускаемого процесса. Переменные окружения указываются в виде пар "<имя переменной>"="<значение>". Необязательное поле (если не указано, переменные окружения не устанавливаются).

Таблица

workdir

Рабочий (текущий) каталог для запускаемого процесса. Необязательное поле (если не указано, рабочий каталог не устанавливается).

Строка

Таблица результатов запуска (возвращаемое значение функции run)

Поле

Описание

Тип данных

exit_status

Код возврата, с которым завершился запущенный процесс в случае штатного завершения, иначе — nil.

Число

exit_signal

Номер сигнала, по которому завершился процесс в случае нештатного (аварийного) завершения по сигналу, иначе — nil.

Число

(значение поля stdout входной таблицы параметров)

Данные, прочитанные из потока stdout завершившегося процесса. Поле присутствует, только если было задано поле stdout в таблице входных параметров.

Строка

(значение поля stderr входной таблицы параметров)

Данные, прочитанные из потока stderr завершившегося процесса. Поле присутствует, только если было задано поле stderr в таблице входных параметров.

Строка

3.Примеры

Запуск утилиты cat без аргументов, с помещением в ее поток ввода строки текста 'some data' и помещением результата вывода этой команды в поле stdout_field возвращаемой таблицы:

local sp = require 'drweb.subprocess'

local cat_result = sp.run({
   '/bin/cat',
   stdin = 'some data',
   stdout = 'stdout_field',
})

Таблица результата, сохраненная в переменной cat_result, будет иметь поля:

Поле

Значение

exit_status

0

exit_signal

nil

stdout_field

'some data'

Запуск команды sh (командный интерпретатор) с параметрами и env | grep TESTVAR 1>&2 (команда, запускаемая интерпретатором), установкой в окружении переменной TESTVAR со значением VALUE, и помещением результата вывода этой команды в поток stderr в поле stderr_field возвращаемой таблицы:

local sp = require 'drweb.subprocess'

local env_result = sp.run({
   '/bin/sh', '-c', 'env | grep TESTVAR 1>&2',
   env = { TESTVAR = 'VALUE' },
   stderr = 'stderr_field'
})

Таблица результата, сохраненная в переменной env_result, будет иметь поля:

Поле

Значение

exit_status

0

exit_signal

nil

stderr_field

'TESTVAR=VALUE\n'

Запуск команды pwd с установкой текущего каталога в корень дерева файловой системы и помещением результата вывода этой команды в поток stdout в поле stdout_field возвращаемой таблицы:

local sp = require 'drweb.subprocess'

local pwd_result = sp.run{
   '/bin/pwd',
   workdir = '/',
   stdout = 'stdout_field'
}

Таблица результата, сохраненная в переменной pwd_result, будет иметь поля:

Поле

Значение

exit_status

0

exit_signal

nil

stdout_field

'/\n'

Запуск в интерпретаторе bash команды kill с посылкой сигнала SIGKILL интерпретатору:

local sp = require 'drweb.subprocess'

local kill_result = sp.run{'/bin/bash', '-c', 'kill -9 $$'}

Таблица результата, сохраненная в переменной kill_result, будет иметь поля:

Поле

Значение

exit_status

nil

exit_signal

9

Если нужно обеспечить асинхронный запуск процесса, запустите функцию run внутри вызова функции async (см. выше).

Содержимое модуля drweb.config

1.Функции

Модуль не предоставляет функций.

2.Доступные таблицы

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

Поле

Описание

Тип данных

version

Версия Dr.Web MailD

Строка

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

Таблица MailDConfig предоставляется модулем в виде поля maild.

3.Примеры

Вывод в журнал текущей версии компонента Dr.Web MailD:

local dw  = require 'drweb'
local cfg = require 'drweb.config'

-- "Главная" функция
function milter_hook(ctx)

 -- Вывод строки на уровне NOTICE в журнал Dr.Web для почтовых серверов UNIX
 dw.notice(cfg.maild.version)

end

 

Содержимое модуля drweb.store

1.Функции

Модуль предоставляет функции:

exists (<name>, <key>) проверяет наличие записи с указанным ключом в выбранном хранилище. Принимает два аргумента: <name> (строка) — имя хранилища; <key> (строка) — ключ записи. Возвращает true в случае наличия записи, иначе — false;

get (<name>, <key>) получает значение записи с указанным ключом из выбранного хранилища. Принимает два аргумента: <name> (строка) — имя хранилища; <key> (строка) — ключ записи. Возвращает пару параметров: value, ctime; либо nil в случае отсутствия записи. Параметр value (строка) — значение записи с указанным ключом; ctime (целое число) — метка времени модификации записи;

put (<name>, <key>, <value>) добавляет запись с указанным ключом в выбранное хранилище. Принимает три аргумента: <name> (строка) — имя хранилища; <key> (строка) — ключ записи, <value> (строка) — значение записи;

remove (<name>, <key>) удаляет запись с указанным ключом из выбранного хранилища. Принимает два аргумента: <name> (строка) — имя хранилища; <key> (строка) — ключ записи;

count (<name>) возвращает количество записей в выбранном хранилище. Принимает один аргумент: <name> (строка) — имя хранилища. Возвращает целое число;

drop (<name>, <ctime>) удаляет все записи, время модификации которых раньше указанной метки, из выбранного хранилища. Принимает два аргумента: <name> (строка) — имя хранилища; ctime (целое число) — метка времени модификации записи.

2.Примеры

Создание белого списка для антиспам-проверки:

local store = require "drweb.store"

local antispam_whitelist = "antispam_whitelist"
local intra_domain_mask = ".*@test%.test$"

-- "Главная" функция
function milter_hook(ctx)

 -- Добавляем всех получателей исходящих писем
 -- в белый список антиспама
 if ctx.from:match(intra_domain_mask) then
   for _, to in ipairs(ctx.to) do
    store.put(antispam_whitelist, to, "")
   end
   return {action="accept"}
 end

 if not store.exists(antispam_whitelist, ctx.from) then
   if ctx.message.spam.score > 300 then
    return {action="reject"}
   end
 end

 return {action="accept"}

end

Временное добавление в белый список:

local store = require "drweb.store"

local antispam_whitelist = "antispam_whitelist"
local antispam_whitelist_timeout = 604800 -- 1 неделя
local intra_domain_mask = ".*@test%.test$"

-- "Главная" функция
function milter_hook(ctx)

 -- Добавляем всех получателей исходящих писем
 -- в белый список антиспама
 if ctx.from:match(intra_domain_mask) then
   for _, to in ipairs(ctx.to) do
    store.put(antispam_whitelist, to, "")
   end
   return {action="accept"}
 end

 local _, ctime = store.get(antispam_whitelist, ctx.from)
 -- Есть в списке и был добавлен не позже 1 недели назад
 local in_whitelist = ctime and os.time() + ctime < antispam_whitelist_timeout

 if not in_whitelist and ctime then
   store.remove(antispam_whitelist, ctx.from)
 end

 -- Еще можно обновлять непросроченную запись:
 -- if in_whitelist then
 --  store.put(antispam_whitelist, ctx.from, "")
 -- end

 if not in_whitelist then
   if ctx.message.spam.score > 300 then
    return {action="reject"}
   end
 end

 return {action="accept"}

end