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

Компонент 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)

Строка

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

Пример хука для обработки письма с несколькими получателями:

if re.match("(eve|neil)@(example\\.com)$", ctx.from or '', re.ignore_case) and ctx.to.all_match("(tom|kane)@example\\.com$")
then
dw.notice("no_checking")
else
dw.notice("do something")
end

Таблица 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 — путь к вложению в проверяемом сообщении, помещаемому в архив. Если не задан, либо если указанный путь не является действительным, в архив помещается все сообщение целиком.

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

Примеры:

-- Запланировать перемещение в архив с паролем
-- всего сообщения целиком
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

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

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

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

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

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

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

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

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

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

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

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

Пример

Приведенный ниже скрипт вернет в 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, а также следующую дополнительную информацию

Поле

Описание

Тип данных

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

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

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

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

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

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

Функция

all_match

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

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

•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.

Функция

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

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

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

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

Функция

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

Таблица From

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

Поле

Описание

Тип данных

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

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

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

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

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

Функция

all_match

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

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

•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.	Строка
raw	Нераскодированный URL в «сыром» виде	Таблица RawUrl
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.	Строка
in_categories	Функция, принимающая один обязательный аргумент categories — список категорий URL (строку или массив строк). Возвращает логическое значение: •true — если URL относится хотя бы к одной из указанных категорий; •false — если URL ни к одной из категорий не относится.	Функция
Переопределенные метаметоды: •__tostring — функция, возвращающая содержимое Url в виде строки (в кодировке UTF-8); •__concat — функция, присоединяющая значение URL, преобразованного в строку, к строке.

Таблица RawUrl

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

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

Таблица 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	Строка или таблица строк
Переопределенные метаметоды: Нет

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

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-объект и т. п.)	Массив таблиц ScanReport
Переопределенные метаметоды: Нет

Таблица 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	Таблица SPFResult
from	Результат проверки MAIL FROM	Таблица SPFResult
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-программы могут быть импортированы специфические модули, перечисленные в таблице.

Имя модуля	Назначение
drweb	Предоставляет функции для записи сообщений из Lua-программы в журнал компонента Dr.Web для почтовых серверов UNIX, запустившего программу на Lua, а также средства асинхронного запуска Lua-процедур
drweb.lookup	Предоставляет инструменты для запроса данных из внешних источников путем обращения к модулю Dr.Web LookupD
drweb.dnsxl	Предоставляет инструменты для проверки вхождения адресов узлов в черные списки DNSxL
drweb.regex	Предоставляет интерфейс сопоставления строк с регулярными выражениями
drweb.subprocess	Предоставляет интерфейс запуска внешних приложений (процессов)
drweb.config	Предоставляет таблицу, содержащую значения параметров конфигурации Dr.Web MailD
drweb.store	Предоставляет функции для хранения данных между запусками 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 of 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)

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