Dr.Web Modifier Plug-In

•Mail content analysis – search of attached objects of certain MIME types (graphic objects, executables, media files) as well as MIME objects that satisfy certain criteria;

•Message body modification – removing of MIME objects that satisfy certain criteria, modification of headers and/or content of MIME objects;

•Mail processing management – blocking, moving to Quarantine, redirecting, adding headers and scores depending on MIME objects found in message bodies.

Details on the message structure used while analyzing and processing by Dr.Web Modifier is provided below.

Message is a composite object that can be selected to perform an action as a whole or partially, as every message can be presented as a hierarchy set of elements (MIME objects, their headers and content). It is also possible to select a part of a message for individual processing. The following figure shows hierarchy structure of a message with nested objects.

2.If the message body content is of multipart/* MIME type, the body is a composite object with the following parts:

oPrologue – text inserted into the body before the first nested MIME object. This text is not displayed in MUA supporting MIME multipart and is usually absent;

oEpilogue – text inserted into the body after the last nested MIME object. This text is not displayed in MUA supporting MIME multipart and is usually absent;

oIf the message body consists of several parts, each of these parts is treated as a separate MIME object with its own set of headers (usually they are content headers, such as Content-type, Content-description, Content-disposition and others), its own content and, in some cases, a prologue and epilogue. MIME objects, can also be composite (that is, be of the multipart/* type).

Otherwise, a message body is treated as a whole object that does not contain nested parts, a prologue and an epilogue.

As any nested object has the same structure as a message (object also consists of a header, body, and, in some cases, prologue and epilogue), messages can be treated as a MIME object with headers (Headers) and content (Body). This MIME object is called a root object.

To search objects in a message, Dr.Web Modifier supports the following versions of regular expressions:

For details on regular expressions, you can visit Wikipedia (Regular expression article).

The plug-in processes messages according to modification rules. These rules are divided into local rules and global rules. At first, local rules are applied, and then - global rules. If a message does not have local modification rules specified for it (that depends on the Processing rules applied for the message, see below), the message is checked only according to global modification rules. If a message does not satisfy local modification rules, it is rejected and check with the use of global rules is not performed.

Local modification rules used by Dr.Web Modifier can be specified in Message processing rules either in the [Rules]section of the Dr.Web MailD configuration file or in the built-in database of users and user groups. For modification rules, the modifier/LocalRules parameter is used. Global modification rules, used by Dr.Web Modifier, can be specified only in the GlobalRules parameter in the plug-in configuration file ([Modifier] section).

Note that the GlobalRules parameter cannot be used in Message processing Rules and value of the LocalRules parameter cannot be specified in the plug-in configuration file.

<Selection operator>, [<Conditional validator>], <Action operator> [, <Action operator>, ...]

Note that operators in modification rules are separated by commas. You can set more than one action operators. Conditional validation can be absent. Minimum required form of the rule includes a selection operator and an action operator.

Modification rules are always specified on a single line. If it is necessary to split the rule on several lines, specify the '\' symbol an the end of the line immediately before the rule to split, for example:

As an action operator, you can also specify an element fetch with its conditional validators and action operators.

Selection of items from the message is performed with the select <element> operator, where <element> is a placeholder for the type of elements to be selected for analysis and processing. The following types are available:

•mime(<SEGMENT>) | mime.<SEGMENT> [[<name>] <regular_expression>] – select MIME objects or their content from the specified segment.

Difference between syntax with brackets and syntax with a dot is the following: argument in brackets selects actual objects that contain elements in the specified segment, argument with a dot - only elements of these objects (certain headers, text of the prologue, body content and others).

o<name> - name of the search header. Specify only if the value of <SEGMENT> is set to headers.

o<regular_expression> - template for search (for example, template that matches the header or text of the element).

The following command selects information on type of data from all video fragments (value from the header):

In a header (for compatibility with Vaderetro plug-in), you can also use instructions to compare with integer ">" and "<" (a backslash '\' is not required to escape the symbols!). The compared header is considered matching the selection criterion if this header contains an integer (for example, X-Drweb-SpamScore: "30") satisfying the condition.

This command selects items that contain the X-Drweb-SpamS header which value is an integer less than 50. Note that a backslash is not required to escape the "<" symbol. If a modification rule is specified as follows:

Note that you cannot select a composite MIME object with select mime(<SEGMENT>) command except when the object is root (a message).

For example, if a message has the structure as presented in the figure below, the select mime(headers) command selects the following objects with headers:

Container object is not selected, as it is composite (includes Nested-1 and Nested-2 objects) and it is not root (not a message).

•sender <regular_expression>, recipient <regular_expression> – Selects the whole message if it contains the corresponding record about the sender (recipients). Data about the sender (recipients) is taken from the message envelope. If the source sequence of symbols is found, select message command is performed (a whole message is selected).

If a message is sent to the administrator, you can add a welcome note at the end using the append_text command (see below):

It is clear that if the message is not sent to the administrator, no items are selected and therefore the append_text command is not applied. This feature allows avoiding use of conditional operators if the alternative action (when required elements are not found) is absent.

•select_mimes – This command allows moving from selection of headers to selection of MIME objects that contain them. That enhances plug-in operation when it is required to select headers and then to select an object by the same criterion. Selection of at least one component of the object is enough for selection of the whole object (not including nested MIME objects for a composite MIME object).

Note that it is required to consider text encoding for all modification rules that use a header or a part of a message.

Rules of working with header values in arbitrary encoding are described in Work with String Values.

To select elements that satisfy several criteria, use logical operators for union or intersection of sequential selections. Specify several selection arguments in the select operator and join them with the following logical operators:

•and – leave only those elements in the selection that satisfy the specified criterion.

•nand – leave only those elements in the selection that do NOT satisfy the specified criterion.

•or – add elements that satisfy the specified criterion to the previous selection.

•nor – add elements that do NOT satisfy the specified criterion to the previous selection.

Note that join and intersection operators are used only in selections that contain MIME objects but are not used in selections that contain actual elements, as the operators cannot be applied to the select mime.<SEGMENT> syntax.

Actually, these are two sequential selections. The first selection contains all MIME objects that contain "html" word in the Content-type header. The second selection leaves only those elements that contain "<script" in any case.

According to the first criterion, all MIME objects that contain "html" word in the Content-type header are selected. According to the second criterion, all MIME objects that contain "<script" in any case are excluded.

•If you specify several consecutive select operators, the successive select replaces the result of the previous select.

The received selection results correspond only to the second criterion, thus, only those mail fragments (MIME objects) are selected that contain "<script" in any case.

•If neither logical operators are used, nor select command is specified before the successive argument, this argument is ignored and selection results are not changed.

The received selection results correspond only to the first criterion, thus, only those mail fragments (MIME objects) are selected that contain "html" in the Content-type header.

Actions are always applied to the result set of the select operator. These actions are divided into the following three types:

•Actions applied to the whole message (reject, redirect, generate MailD notifications and others);

•Actions applied to the selected elements of the message (deletion, signing, replacement or modification of text and others);

If a set of selected elements is empty, actions specified in the rule are not applied (are ignored).

•pass, accept – pass the message. If Dr.Web Modifier is processing a message with the use of global rules and receives this command, the processing stops. Otherwise, if Dr.Web Modifier receives the command when using local rules, the plug-in starts using global rules for the processing;

•notify <report_name> – notify the administrator; at that, message processing does not stop. After this command, specify the notification template name used to generate the notification, otherwise errors will occur during message processing. Templates are located in the directory specified in the TemplatesBaseDir parameter value in the [Notifier] section of the Dr.Web MailD configuration file.

In this case, only MailD notification is sent. As any action operator must be preceded by a selection operator, use select message operator which selects a whole message and returns non-empty result. The required admin prefix and .msg extension are substituted automatically by Dr.Web Notifier.

•stop – stop processing modification rules. Action of the last performed command (pass, accept, reject or another) is applied to the message. The accept command is the same as pass+stop combination except for the fact that stop command stops full processing and accept stops only processing with local modification rules. For global modification rules, accept is equal to pass.

The reject, discard and tempfail commands are "resolving", that is, they stop message processing regardless of other commands specified in the modification rule.

These actions are applied only to content of selected elements unless otherwise specified.

•replace <replacement expression> <regular expression to be replaced>,
replace_all <new text> – These actions replace text in the selected elements. The old text must match the <regular expression to be replaced> and the new text is specified in <replacement expression>.

Search and renaming of executable files in attachments (content of Content-disposition headers is replaced):

select mime.headers Content-disposition "filename=.*\\.exe",or mime.headers Content-type "name=.*\\.exe",replace "\\.ex_" "\\.exe", pass

These commands cannot be applied to composite parts of a message. That is, the following modification rule has no effect to a message that contains a composite MIME object with two nested objects (as Container shown in the figure above):

because composite objects do not contain any data; they only serve as containers for other objects.

For replace and replace_all commands in the <replacement expression> and <new_text> arguments you can use function calls as ${func_name}. Argument for these functions is the current replacement expression. The following functions are implemented:

At the start of Subject heading, the "[SPAM]" string is inserted. For example, "This is Subj" header is replaced with "[SPAM] This is Subj".

select mime.body ".*", replace "http://check-url.com?url=${urlencode}" "http://\\S+"

In the message body, text that corresponds the specified template, for example: "Visit http://vasya.com?id=3", is replaced with "Visit http://check-url.com?url=http%3A%2F%2Fvasya%2Ecom%3Fid%3D3".

•remove – this command instructs to delete selected objects of any kind except for a root MIME object "message" (that is, this command cannot delete a whole message!).

GlobalRules = select mime(body) "text", remove, pass
GlobalRules = select mime(body) "script", remove, pass

•prepend_text, append_text,
prepend_html, append_html – These commands add fragment of plain-text or html format to the selected MIME objects.

The command has an optional argument - [[7b:]encoding]. In this argument, encoding means name of the added text encoding, and "7b:" prefix indicates use of 7 bit encoding - context transfer encoding (CTE) 7bit. If the "7b:" prefix is not specified, the CTE 8bit encoding is used. If encoding is not specified, the encoding set in the Encoding parameter in the plug-in configuration file is used.

Apart from that, you can use Dr.Web Modifier language file as a source of data in certain encoding. To use lines from the lng-file, specify them in the $n format, where n is the ordinal number of the string in the lng--file. For details on language files usage, see description of the [Notifier] section.

then append_text $782 expression is equivalent to the expression append_text "text line".

Note that prepend_text, append_text, prepend_html, append_html commands insert into the selected objects not only the text but the MIME object with text content (to the start or end of the selected objects respectively) and the modified objects become composite. Thus, adding of text information always results in reset of the selected objects list. To continue message processing after the text is inserted, repeat the select operation.

This command adds a header with the foo name and bar value to the message. Name and value of the header are separated by a colon (":").

It is required to consider text encoding both for text search and text insertion. Text is always inserted in the same encoding as one of the configuration file (except for prepend_text, append_text, prepend_html и append_html commands using for insertion either encoding specified in the command or encoding set in the Encoding parameter of the plug-in configuration file). To use another encoding, explicit encoding of string values is required.

You can check or change score of a message. A message has a score assigned to it and originally set to 0. When processing the message, plug-ins can change this score. With add_score and set_score commands, this score can be changed, increased or decreased (to decrease a message score, specify a negative number in the add_score command).

The score argument can be 32 bit number in the range -2 b to +2 b. You should also consider that score can get too large value that exceeds the limit and thus causes incorrect operation of plug-ins that are processing the message. Thus, it is recommended not to set an unreasonably large value to a score (for example, do not specify 2 000 000 000 as a parameter of an add_score action)

Table 1 shows effects of actions depending on the selected objects they are applied to.

Note that prepend_text, prepend_html, append_text, append_html and addheader actions can be applied only if a composite object (instead of a simple object, such as a header) is selected with the select operator, as these commands always insert into the selected object an additional MIME object which cannot be a header value.

Conditional validators are used to change the order of actions applied to the message depending whether the condition meets the validation rule or not. There are the following main types of conditions:

if [not] found, <action or list of actions>, [else, <action or list of actions>,] endif

The if found condition is true if the result set of the previous select operator is not empty. The if not found condition is true in the contrary case. When the condition is true, actions specified afterwards are applied until either the end of branching (endif operator) or an alternative branch operator is found. The alternative branch else, <action or list of actions> can be absent. In this case, when the condition is false, execution continues after the endif statement.

In the <action or list of actions> part, a new selection can be formed with the select operator and its condition is validated (if or goto). The new selection substitutes the previous one, which was used for condition validation). For example:

In this case, set of elements <A> is selected. If the selection is empty, execution goes to endif and stops (no action is performed to the message). Otherwise, new selection is formed from the message, specified as <B> (at that, it substitutes the previous selection <A> for subsequent operators). If the selected set is not empty, the message is rejected. Otherwise, no action is performed to it (reject action is ignored for an empty <B> selection).

if score <op_value>, <action or list of actions>, [else, <action or list of actions>,] endif

The if score condition is true if the current message score corresponds to the specified expression. The if score command is equal to the if found command except for the fact that if score checks only the score and does not check presence of selected elements, that is this command ignores results of the previous selection.

The <op_value> argument must be specified on a single line without space characters, that is '<100', but not '< 100'. It must consist of a symbol of comparison and an integer value. For if score, the following comparisons are available:

N argument can be a 32-bit integer value in the range -2 b to +2 b. You should also consider that score can get too large value that exceeds the limit and thus causes incorrect operation of plug-ins processing the message. Thus, it is recommended not to set an unreasonably large value to score (for example, do not set 2 000 000 000).

•goto(y) N – if the condition is true, jump forward N commands in the action list if the set of elements is not empty

•goto(n) N – if the condition is true, jump forward N commands in the action list, if the set of elements is not empty.

The argument denotes a number of commands to be skipped. To specify the argument, use a positive integer.

GlobalRules = select mime.headers Subject "word1|word2|wordN", if found, notify rule, quarantine, reject, endif

When one of "word1", "word2" or "wordN" words is found in the message header, the message is copied to Quarantine, after that a MailD notification is send to the administrator and the message is rejected.

GlobalRules = select mime.headers Subject "word1|word2|wordN", if found, reject, notify rule, quarantine, endif

In this example, notify and quarantine commands are not executed as after the reject command the message is rejected and its processing stops (reject command is "determining").

GlobalRules = select mime.headers "X-DrWeb-SpamState" "yes", if found, select mime(headers) Content-type "image", remove, endif

This command set allows removing pictures from a message marked as spam by Vaderetro plug-in.

The following example shows how to set 10 to a score of a message that satisfies the specified condition:

In the following example, if a message score is greater than 100, the message is rejected. Otherwise, its score is decreased by 5:

For details on modification rules for the Dr.Web Modifier plug-in, see Examples.

In the modification rules for the plug-in, it is strongly not recommended to use values and regular expressions that contain quotation marks (") or a backslash "\" because their escaping with the "\" character can cause an error when parsing the string in the Dr.Web MailD configuration file. However, if it is necessary to use such characters, follow the rules:

•when using quotation marks in modification rules, several "\" characters are necessary to escape the marks. In the current version of Dr.Web MailD, 6 backslashes are required.

To reject messages with a subject that contains quotation marks or one '\' character respectively:

Reject messages with a subject that contains the following text - text'"\quoted\"text:

GlobalRules = select mime(headers) Subject "text'\\\\\\"\\\\\\\\quoted\\\\\\\\\\\\\\"text", if found, reject, endif