В этом разделе
•Общие сведения
•Скрипт для 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 соответственно. В качестве значения этого параметра можно указать как полный текст скрипта, так и путь к этому скрипту.
Скрипт обработки сообщений для интерфейса 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
|
Режим 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, а также следующую дополнительную информацию
Поле
|
Описание
|
Тип данных
|
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-объект и т. п.)
|
Массив таблиц 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 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
|
|