To specify a threshold for the minimum number of occurrences, specify the pattern and the minimum number of matches required to evaluate to true:

if(<filter rule>('<pattern>',<minimum threshold>)){

For example, to specify that the body-contains filter rule must find the value “Company Confidential” at least two times, use the following syntax:

if(body-contains('Company Confidential',2)){

By defeat, when AsyncOS saves a content scanning filter, it compiles the filter and assigns a threshold value of 1, if you have not assigned a value.

You can also specify a minimum number of pattern matches for values in a content dictionary. For more information about content dictionaries, see the “Text Resources” chapter.

An email message may be composed of multiple parts. When you specify threshold values for filter rules that search for patterns in the message body or attachments, AsyncOS counts the number of matches in the message parts and attachments to determine the threshold “score.” Unless the message filter specifies a specific MIME part (such as the attachment-contains filter rule), AsyncOS will total the matches found in all parts of the message to determine if the matches total the threshold value. For example, you have a body-contains message filter with a threshold of 2. You receive a message in which the body contains one match, and the attachment contains one match. When AsyncOS scores this message, it totals the two matches and determines that the threshold score has been met.

Similarly, if you have multiple attachments, AsyncOS totals the scores for each attachment to determine the score for matches. For example, you have an attachment-contains filter rule with a threshold of 3. You receive a message with two attachments, and each attachment contains two matches. AsyncOS would score this message with four matches and determine that the threshold score has been met.

To avoid duplicate counting, if there are two representatives of the same content (plain text and HTML), AsyncOS does not total the matches from the duplicate parts. Instead, it compares the matches in each part and selects the highest value. AsyncOS would then add this value to the scores from other parts of the multipart message to create a total score.

For example, you configure a body-contains filter rule and set the threshold to 4. You then receive a message that contains both plain text, HTML and two attachments. The message would use the following structure:

multipart/mixed

        multipart/alternative

                text/plain

                text/html

        application/octet-stream

        application/octet-stream

The body-contains filter rule would determine the score for this message by first scoring the text/plain and text/html parts of the message. It would then compare the results of these scores and select the highest score from the results. Next, it would add this result to the score from each of the attachments to determine the final score. Suppose the message has the following number of matches:

multipart/mixed

        multipart/alternative

                text/plain (2 matches)

                text/html (2 matches)

        application/octet-stream (1 match)

        application/octet-stream

Because AsyncOS compares the matches for the text/plain and text/html parts, it returns a score of 3, which does not meet the minimum threshold to trigger the filter rule.

When you use a content dictionary, you can “weight” terms so that certain terms trigger filter actions more easily. For example, you may want not want to trigger a message filter for the term, “bank.” However, if the term, “bank” is combined with the term, “account,” and accompanied with an ABA routing number, you may want to trigger a filter action. To accomplish this, you can use a weighted dictionary to give increased importance to certain terms or a combination of terms. When a message filter that uses a content dictionary scores the matches for filter rule, it uses these weights to determine the final score. For example, suppose you create a content dictionary with the following contents and weights:

When you associate this content dictionary with a dictionary-match or attachment-dictionary-match message filter rule, AsyncOS would add the weight for the term to the total “score” for each instance of the matching term found in the message. For example, if the message contains three instances of the term, “account” in the message body, AsyncOS would add a value of 6 to the total score. If you set the threshold value for the message filter to 6, AsyncOS would determine that the threshold score has been met. Or, if the message contained one instance of each term, the total value would be 6, and this score would trigger the filter action.

You can use filters to search for strings and patterns in non-ASCII encoded message content (both headers and bodies). Specifically, the system supports regular expression (regex) searching for non-ASCII character sets within:

• Message headers
• MIME attachment filename strings
• Message body:
  • Bodies without MIME headers (i.e. traditional email)
  • Bodies with MIME headers indicating encoding but no MIME parts
  • Multi-part MIME messages with encoding indicated
  • All of the above without the encoding specified in a MIME header

You can use regular expressions (regexes) to match on any part of the message or body, including matching attachments. The various attachment types include text, HTML, MS Word, Excel, and others. Examples of character sets of interest include gb2312, HZ, EUC, JIS, Shift-JIS, Big5, and Unicode. Message filter rules with regular expressions can be created through the content filter GUI, or using a text editor to generate a file that is then imported into the system. For more information, see Using the CLI to Manage Message Filters and Configuring Scan Behavior.

It is important to begin a regular expression with a caret ( ^ ) and end it with a dollar sign ( $ ) whenever you want to exactly match a string and not a prefix.

Note	When matching an empty string, do not use “” as that actually matches all strings. Instead use “^$” . For an example, see the second example in Subject Rule.

It is also important to remember that if you want to match a literal period, you must use an escaped period in the regular expression. For example, the regular expression sun.com matches the string thegodsunocommando , but the regular expression ^sun\.com$ only matched the string sun.com.

Technically, the style of regular expressions used are Python re Module style regular expressions. For a more detailed discussion of Python style regular expressions, consult the Python Regular Expression HOWTO, accessible from: http://www.python.org/doc/howto/

In some languages, the concepts of a word or word boundary, or case do not exist.

Complex regular expressions that depend on concepts like what is or is not a character that would compose a word (represented as “ \w ” in regex syntax) cause problems when the locale is unknown or if the encoding is not known for certain.

Regular expressions can be tested for matching using the sequence == and for non-matching using the sequence != . For example:

rcpt-to ==
 "^goober@dev\\.null\\....$" (matching)

rcpt-to != "^goober@dev\\.null\\....$" (non-matching)

Unless otherwise noted, regular expressions are case-sensitive. Thus, if your regular expression is searching for foo , it does not match the pattern FOO or even Foo .

This example shows two filters that do the same thing, but the first one takes much more CPU. The second filter uses a regular expression that is more efficient.

attachment-filter: if ((recv-listener == "Inbound") AND ((((((((((((((((((((((((((((((((((((((((((((((attachment-filename ==

"\\.386$") OR (attachment-filename == "\\.exe$")) OR (attachment-filename == "\\.ad$")) OR 
(attachment-filename == "\\.ade$")) OR (attachment-filename == "\\.adp$")) OR 
(attachment-filename == "\\.asp$")) OR (attachment-filename == "\\.bas$")) OR 
(attachment-filename == "\\.bat$")) OR (attachment-filename == "\\.chm$")) OR 
(attachment-filename == "\\.cmd$")) OR (attachment-filename == "\\.com$")) OR 
(attachment-filename == "\\.cpl$")) OR (attachment-filename == "\\.crt$")) OR 
(attachment-filename == "\\.exe$")) OR (attachment-filename == "\\.hlp$")) OR 
(attachment-filename == "\\.hta$")) OR (attachment-filename == "\\.inf$")) OR 
(attachment-filename == "\\.ins$")) OR (attachment- filename == "\\.isp$")) OR 
(attachment-filename == "\\.js$")) OR (attachment-filename == "\\.jse$")) OR 
(attachment- filename == "\\.lnk$")) OR (attachment-filename == "\\.mdb$")) OR 
(attachment-filename == "\\.mde$")) OR (attachment-filename == "\\.msc$")) OR 
(attachment-filename == "\\.msi$")) OR (attachment-filename == "\\.msp$")) OR 
(attachment-filename == "\\.mst$")) OR (attachment-filename == "\\.pcd$")) OR 
(attachment-filename == "\\.pif$")) OR (attachment-filename == "\\.reg$")) OR 
(attachment-filename == "\\.scr$")) OR (attachment-filename == "\\.sct$")) OR 
(attachment-filename == "\\.shb$")) OR (attachment-filename == "\\.shs$")) OR 
(attachment-filename == "\\.url$")) OR (attachment-filename == "\\.vb$")) OR 
(attachment-filename == "\\.vbe$")) OR (attachment-filename == "\\.vbs$")) OR 
(attachment-filename == "\\.vss$")) OR (attachment-filename == "\\.vst$")) OR 
(attachment-filename == "\\.vsw$")) OR (attachment-filename == "\\.ws$")) OR 
(attachment-filename == "\\.wsc$")) OR (attachment-filename == "\\.wsf$")) OR 
(attachment-filename == "\\.wsh$"))) { bounce(); }

In this instance, AsyncOS will have to start the regular expression engine 30 times, once for each attachment type and the recv-listener.

Instead, write the filter to look like this:

attachment-filter: if (recv-listener == "Inbound") AND (attachment-filename == "\\.
(386|exe|ad|ade|adp|asp|bas|bat|chm|cmd|com|cpl|crt|exe|hlp|hta|inf|ins|isp|js|jse|l
nk|mdb|mde|msc|msi|msp|mst|pcd|pif|reg|scr|sct|shb|shs|
url|vb|vbe|vbs|vss|vst|vsw|ws|wsc|wsf|wsh)$") {

The regular expression engine only has to start twice and the filter is arguably easier to maintain as you do not have to worry about adding “()”, spelling errors. In contrast to the above, this should show a decrease in CPU overhead.

Depending on how a PDF is generated, it may contain no spaces or line breaks. When this occurs, the scanning engine attempts to insert logical spaces and line breaks based on the location of the words on the page. For example, when a word is constructed using multiple fonts or font sizes, the PDF code is rendered in a way that makes it difficult for the scanning engine to determine word and line breaks. When you attempt to match a regular expression against a PDF file constructed in this way, the scanning engine may return unexpected results.

For example, you enter a word in a PowerPoint document that uses different fonts and different font sizes for each letter in the word. When a scanning engine reads a PDF generated from this application, it inserts logical spaces and line breaks. Because of the construction of the PDF, it may interpret the word “callout” as “call out” or “c a l lout.” Attempting to match either of these renderings against the regular expression, “callout,” would result in no matches.

When you use a smart identifier in a filter rule, enter the smart-identifier keyword in quotes within a filter rule that scans the body or attachment file, as in the example below:

ID_Credit_Cards:

if(body-contains("*credit")){

notify("legaldept@example.com");

}
.

You can also use smart identifiers in content filters and as a part of content dictionaries.

Note	You cannot combine a smart identifier key word with a normal regular expression or another key word. For example the pattern *credit|*ssn would not be valid.

Note

To minimize on false positives using the *SSN smart identifier, it may be helpful to use the *ssn smart identifier along with other filter criteria. One example filter that can be used is the “only-body-contains” filter condition. This will only evaluate the expression to be true if the search string is present in all of the message body mime parts. For example, you could create the following filter:

SSN-nohtml: if only-body-contains(“*ssn”) { duplicate-quarantine(“Policy”);}

The true rule matches all messages. For example, the following rule changes the IP interface to external for all messages it tests.

externalFilter:

   if (true)

   {

        alt-src-host('external');

   }

The valid rule returns false if the message contains unparsable/invalid MIME parts and true otherwise. For example, the following rule drops all unparsable messages it tests.

not-valid-mime:

if not valid

{

drop();

}

The subject rule selects those messages where the value of the subject header matches the given regular expression.

For example, the following filter discards all messages with subjects that start with the phrase Make Money...

not-valid-mime:

if not valid

{

drop();

}

You can specify non-ASCII characters to search for in the value of the header.

When working with headers, remember that the current value of the header includes changes made during processing (such as with filter actions that add, remove, or modify message headings). See Message Header Rules and Evaluation for more information.

The following filter returns true if the headers are empty or if the headers are missing from the message:

EmptySubject_To_filter:

if (header('Subject') != ".") OR

(header('To') != ".") {

drop();

}

Note	This filter returns true for empty Subject and To headers, but it also returns true for missing headers. If the message does not contain the specified headers, the filter still returns true.

The rcpt-to rule selects those messages where any Envelope Recipient matches the given regular expression. For example, the following filter drops all messages sent with an email address containing the string “scarface.”

Note	The regular expression for the rcpt-to rule is case insensitive .

scarfaceFilter:

if (rcpt-to == 'scarface')

{

drop();

}

Note	The rcpt-to rule is message-based. If a message has multiple recipients, only one recipient has to match the rule for the specified action to affect the message to all recipients.

The rcpt-to-group rule selects those messages where any Envelope Recipient is found to be a member of the LDAP group given. For example, the following filter drops all messages sent with an email address within the LDAP group “ExpiredAccounts.”

expiredFilter:

if (rcpt-to-group == 'ExpiredAccounts')

{

drop();

}

Note	The rcpt-to-group rule is message-based. If a message has multiple recipients, only one recipient has to match the rule for the specified action to affect the message to all recipients.

The mail-from rule selects those messages where the Envelope Sender matches the given regular expression. For example, the following filter immediately delivers any message sent by admin@yourdomain.com .

Note	The regular expression for the mail-from rule is case insensitive . Note that the period character is escaped in the following example.

kremFilter:

if (mail-from == '^admin@yourdomain\\.com$')

{

skip-filters();

}

The mail-from-group rule selects those messages where the Envelope Sender is found to be in an LDAP group given on the right side of the operator (or, in the case of inequality, where the sender’s email address is not in the given LDAP group). For example, the following filter immediately delivers any message sent by someone whose email address is in the LDAP group “KnownSenders.”

SenderLDAPGroupFilter:

if (mail-from-group == 'KnownSenders')

{

skip-filters();

}

The sendergroup message filter selects a message based on which sender group was matched in a listener's Host Access Table (HAT). This rule uses '==' (for matching) or '!=' (for not matching) to test for matching a given regular expression (the right side of the expression). For example, the following message filter rule evaluates to true if the sender group of the message matches the regular expression Internal, and, if so, sends the message to an alternate mail host.

senderGroupFilter:

if (sendergroup == "Internal")

{

alt-mailhost("[172.17.0.1]");

}

Body size refers to the size of the message, including both headers and attachments. The body-size rule selects those messages where the body size compares as directed to a given number. For example, the following filter bounces any message where the body size is greater than 5 megabytes.

BigFilter:

if (body-size > 5M)

{

bounce();

}

The body-size can be compared in the following ways:

body-size < 10M

body-size <= 10M

body-size > 10M

body-size >= 10M

body-size == 10M

body-size != 10M

As a convenience, the size measurement may be specified with a suffix:

10b

13k

5M

40G

The remote-ip rule tests to see if the IP address of the host that sent that message matches a certain pattern. The IP address can be either Internet Protocol version 4 (IPv4) or Internet Protocol version 6 (IPv6). The IP address pattern is specified using the allowed hosts notation described in “Sender Group Syntax”, except for the SBO , SBRS , dnslist notations and the special keyword ALL .

The allowed hosts notation can only identify sequences and numeric ranges of IP addresses (not hostnames). For example, the following filter bounces any message not injected from IP addresses of form 10.1.1. x where X is 50 , 51 , 52 , 53 , 54 , or 55 .

notMineFilter:

if (remote-ip != '10.1.1.50-55')

{

bounce();

}

The recv-listener rule selects those messages received on the named listener. The listener name must be the nickname of one of the listeners currently configured on the system. For example, the following filter immediately delivers any message arriving from the listener named expedite .

expediteFilter:

if (recv-listener == 'expedite')

{

skip-filters();

}

The recv-int rule selects those messages received via the named interface. The interface name must be the nickname of one of the interfaces currently configured for the system. For example, the following filter bounces any message arriving from the interface named outside .

outsideFilter:

if (recv-int == 'outside')

{

bounce();

}

The date rule checks the current time and date against a time and date you specify. The date rule is compares against a string containing a timestamp of the format MM/DD/YYYY hh:mm:ss . This is useful to specify actions to be performed before or after certain times in US format. (Note that there may be an issue if you are searching messages with non-US date formats.) the following filter bounces all messages from campaign1@yourdomain.com that are injected after 1:00pm on July 28th, 2003:

TimeOutFilter:

if ((date > '07/28/2003 13:00:00') and (mail-from ==

'campaign1@yourdomain\\.com'))

{

bounce();

}

Note	Do not confuse the date rule with the $Date message filter action variable.

The header() rule checks the message headers for a specific header, which must be specified quoted in parentheses (“header name ”). This rule may be compared to a regular expression, much like the subject rule, or may be used without any comparison, in which case it will be “true” if the header is found in the message, and “false” if it is not found. For example, the following example checks to see if the header X-Sample is found, and if its value contains the string “ sample text ”. If a match is made, the message is bounced.

FooHeaderFilter:

if (header('X-Sample') == 'sample text')

{

bounce();

}

You can specify non-ASCII characters to search for in the value of the header.

The following example demonstrates the header rule without a comparison. In this case, if the header X-DeleteMe is found, it is removed from the message.

DeleteMeHeaderFilter:

if header('X-DeleteMe')

{

strip-header('X-DeleteMe');

}

When working with headers, remember that the current value of the header includes changes made during processing (such as with filter actions that add, remove, or modify message headings). See Message Header Rules and Evaluation for more information.

The random rule generates a random number from zero to N-1, where N is the integer value supplied in parenthesis after the rule. Like the header() rule, this rule may be used in a comparison, or may be used alone in a “unary” form. The rule evaluates to true in the unary form if the random number generated is non-zero. For example, both of the following filters are effectively equal, choosing Virtual Gateway address A half the time, and Virtual Gateway address B the other half of the time:

load_balance_a:

if (random(10) < 5) 
{

alt-src-host('interface_a');
} 

else 

{

alt-src-host('interface_b');

}

load_balance_b:

if (random(2)) 

{

alt-src-host('interface_a');

} 

else 

{

alt-src-host('interface_b');

}

The rcpt-count rule compares the number of recipients of a message against an integer value, in a similar way to the body-size rule. This can be useful for preventing users from sending email to large numbers of recipients at once, or for ensuring that such large mailing campaigns go out over a certain Virtual Gateway address. The following example sends any email with more than 100 recipients over a specific Virtual Gateway address:

large_list_filter:

if (rcpt-count > 100) {

alt-src-host('mass_mailing_interface');

}

The addr-count() message filter rule takes one or more header strings, counts the number of recipients in each line and reports the cumulative number of recipients. This filter differs from the rcpt-count filter rule in that it operates on the message body headers instead of the envelope recipients. The following example shows the filter rule used to replace a long list of recipients with the alias, “undisclosed-recipients”:

large_list_filter:


if (rcpt-count > 100) {

alt-src-host('mass_mailing_interface');

}

The body-contains() rule scans the incoming email and all its attachments for a particular pattern defined by its parameter. This includes delivery-status parts and associated attachments. The body-contains() rule does not perform multi-line matching. The scanning logic can be modified on the Scan Behavior page or using the scanconfig command in the CLI to define which MIME types should or should not be scanned. You can also specify a minimum number of matches that the scanning engine must find in order for the scan to evaluate to true.

By default, the system scans all attachments except for those with a MIME type of video/* , audio/* , image/* . The system scans archive attachments — .zip , .bzip , .compress , .tar , or .gzip attachments containing multiple files. You can set the number of “nested” archived attachments to scan (for example, a .zip contained within a .zip ).

For more information, see Configuring Scan Behavior.

When AsyncOS performs body scanning, it scans the body text and attachments for the regular expression. You can assign a minimum threshold value for the expression, and if the scanning engine encounters the regular expression the minimum number of times, the expression evaluates to true .

AsyncOS evaluates the different MIME parts of the message, and it scans any MIME part that is textual. AsyncOS identifies the text parts if the MIME type specifies text in the first part. AsyncOS determines the encoding based on the encoding specified in the message, and it converts the text to Unicode. It then searches for the regular expression in Unicode space. If no encoding is specified in the message, AsyncOS uses the encoding you specify on the Scan Behavior page or using the scanconfig command.

For more information about how AsyncOS evaluates MIME parts when scanning messages, see Message Bodies vs. Message Attachments.

If the MIME part is not textual, AsyncOS extract files from a .zip or .tar archive or decompresses compressed files. After extracting the data, a scanning engine identifies the encoding for the file and returns the data from the file in Unicode. AsyncOS then searches for the regular expression in Unicode space.

The following example searches the body text and attachment for the phrase “Company Confidential.” The example specifies a minimum threshold of two instances, so if the scanning engine finds two or more instances of the phrase, it bounces any matching messages, and notifies the legal department of the attempt:

ConfidentialFilter:

if (body-contains('Company Confidential',2)) {

notify ('legaldept@example.domain');

bounce();

}

To scan only the body of the message, use only-body-contains :

disclaimer:

if (not only-body-contains('[dD]isclaimer',1) ) {

notify('hresource@example.com');

}

The encrypted rule examines the contents of a message for encrypted data. It does not attempt to decode the encrypted data, but merely examines the contents of the message for the existence of encrypted data. This can be useful for preventing users from sending encrypted email.

Note	The encrypted rule can only detect encrypted data in the content of messages. It does not detect encrypted attachments.

The encrypted rule is similar to the true rule in that it takes no parameters and cannot be compared. This rule returns true if encrypted data is found and false if no encrypted data is found. Because this function requires the message to be scanned, it uses the scanning settings you define on the Scan Behavior page or using the scanconfig command. For more information about configuring these options, see Configuring Scan Behavior.

The following filter checks all email sent through the listener, and if a message contains encrypted data, the message is blind-carbon-copied to the legal department and then bounced:

prevent_encrypted_data:

if (encrypted) {

bcc ('legaldept@example.domain');

bounce();

}

The attachment-type rule checks the MIME types of each attachment in a message to see if it matches the given pattern. The pattern must be of the same form used in the Scan Behavior page or the scanconfig command, as described in Configuring Scan Behavior, and so may have either side of the slash ( / ) replaced by an asterisk as a wildcard. If the message contains an attachment that matches this specified MIME type, this rule returns “true.”

Because this function requires the message to be scanned, it obeys all of the options described in Configuring Scan Behavior.

See Attachment Scanning for more information on message filter rules you can use to manipulate attachments to messages.

The following filter checks all email sent through the listener, and if a message contains an attachment with a MIME type of video/* , the message is bounced:

bounce_video_clips:

if (attachment-type == 'video/*') {

bounce();

}

The attachment-filename rule checks the filenames of each attachment in a message to see if it matches the given regular expression. This comparison is case-sensitive. The comparison is, however sensitive to whitespace so if the filename has encoded whitespace at the end, the filter will skip the attachment. If one of the message’s attachments matches the filename, this rule returns “true.”

Please note the following points:

• Each attachment’s filename is captured from the MIME headers. The filename in the MIME header may contain trailing spaces.
• If an attachment is an archive, the appliance will harvest the filenames from inside the archive, and apply scan configuration rules (see Configuring Scan Behavior) accordingly.
  • If the attachment is a single compressed file (despite the file extension), it is not considered an archive and the filename of the compressed file is not harvested. This means that the file is not processed by the attachment-filename rule. An example of this type of file is an executable file (.exe) compressed with gzip .
  • For attachments consisting of a single compressed file, such as foo.exe.gz, use regular expression to search for specific file types within compressed files. See Attachment Filenames and Single Compressed Files within Archive Files.

See Attachment Scanning for more information on message filter rules you can use to manipulate attachments to messages.

The following filter checks all email sent through the listener, and if a message contains an attachment with a filename *.mp3 , the message is bounced:

block_mp3s:

if (attachment-filename == '(?i)\\.mp3$') {

bounce();

}

The dnslist() rule queries a public DNS List server that uses the DNSBL method (sometimes called “ip4r lookups”) of querying. The IP address of the incoming connection is reversed (so an IP of 1.2.3.4 becomes 4.3.2.1) and then added as a prefix to the server name in the parenthesis (a period to separate the two is added if the server name does not start with one). A DNS query is made, and the system is returned with either a DNS failure response (indicating the connection's IP address was not found in the server's list) or an IP address (indicating that the address was found). The IP address returned is usually of the form 127.0.0. x where x can be almost any number from 0 to 255 (IP address ranges are not allowed). Some servers actually return different numbers based on the reason for the listing, while others return the same result for all matches.

Like the header() rule, dnslist() can be used in either a unary or binary comparison. By itself, it simply evaluates to true if a response is received and false if no response is received (for example, if the DNS server is unreachable).

The following filter immediately delivers a message if the sender has been bonded with the Cisco Bonded Sender information services program:

allowedlist_bondedsender:

if (dnslist('query.bondedsender.org')) {

skip-filters();

}

Optionally, you can compare the result to a string using the equality ( == ) or inequality ( != ) expressions.

The following filter drops a message that results in a “ 127.0.0.2 ” response from the server. If the response is anything else, the rule returns “false” and the filter is ignored.

blockedlist:

if (dnslist('dnsbl.example.domain') == '127.0.0.2') {

drop();

}

The reputation rule checks the SenderBase Reputation Score against another value. All the comparison operators are allowed, such as > , == , <=, and so forth. If the message does not have a SenderBase Reputation Score at all (because one was never checked for it, or because the system failed to get a response from the SenderBase Reputation Service query server), any comparison against a reputation fails (the number will not be greater than, less than, equal to, or not equal to any value). You can check for a SBRS score of “none” using the no-reputation rule described below. The following example adjusts the “Subject:” line of a message to be prefixed by “ *** BadRep *** ” if the reputation score returned from the SenderBase Reputation Service is below a threshold of -7.5..

note_bad_reps:

if (reputation < -7.5) {
strip-header ('Subject');
insert-header ('Subject', '*** BadRep $Reputation *** $Subject');
}

For more information, see the “Sender Reputation Filtering” chapter. See also Bypass Anti-Spam System Action

Values for the SenderBase Reputation rule are -10 through 10, but the value NONE may also be returned. To check specifically for the value NONE , use the no-reputation rule.

none_rep:

if (no-reputation) {

strip-header ('Subject');

insert-header ('Subject', '*** Reputation = NONE *** $Subject');

}

The dictionary-match(< dictonary_name >) rule evaluates to true if the message body contains any of the regular expressions or terms in the content dictionary named “dictonary_name .” If the dictionary does not exist, the rule evaluates to false . For more information on defining dictionaries (including their case sensitivity and word boundary settings), see the “Text Resources” chapter.

The following filter blind carbon copies the administrator when the Cisco scans a message that contains any words within the dictionary named “secret_words.”

copy_codenames:

if (dictionary-match ('secret_words')) {

bcc('administrator@example.com');

}

The following example sends the message to the Policy quarantine if the message body contains any words within the dictionary named “secret_words.” Unlike the only-body-contains condition, the body-dictionary-match condition does not require that all the content parts individually match the dictionary. The scores of each content part (taking into account multipart/alternative parts) are added together.

quarantine_data_loss_prevention:

if (body-dictionary-match ('secret_words'))

{

quarantine('Policy');

}

In the following filter, a subject that matches a term in the specified dictionary is quarantined:

quarantine_policy_subject:

if (subject-dictionary-match ('gTest'))

{

quarantine('Policy');

}

This example matches an email address in the “to” header and blind copies an administrator:

headerTest:

if (header-dictionary-match ('competitorsList', 'to'))

{

bcc('administrator@example.com');

}

The attachment-dictionary-match(<dictonary_name>) rule works like the dictionary-match rule above, except that it looks for matches in the attachment.

The following filter sends the message to the Policy quarantine if the message attachment contains any words found within the dictionary named “secret_words.”

quarantine_codenames_attachment:

if (attachment-dictionary-match ('secret_words'))

{

quarantine('Policy');

}

The header-dictionary-match(<dictonary_name>, <header>) rule works like the dictionary-match rule above, except that it looks for matches in the header specified in <header >. The header name is case insensitive, so, for example, “subject” and “Subject” both work.

The following filter sends the message to the Policy quarantine if the message’s “cc” header contains any words found within the dictionary named “ex_employees.”

quarantine_codenames_attachment:

if (header-dictionary-match ('ex_employees', 'cc'))

{

quarantine('Policy');

}

You can use wild cards within the dictionary terms. You do not have to escape the period in email addresses.

When you receive SPF/SIDF verified mail, you may want to take different actions depending on the results of the SPF/SIDF verification. The spf-status rule checks against different SPF verification results. For more information, see Verification Results.

Note	If you have configured an SPF verification message filter rule without an SPF identity and if a message contains different SPF identities with different verdicts, the rule is triggered if one of the verdicts in the message matches the rule.

You can check against the SPF/SIDF verification results using the following syntax:

if (spf-status == "Pass")

If you want a single condition to check against multiple status verdicts, you can use the following syntax:

if (spf-status == "PermError, TempError")

You can also check the verification results against the HELO, MAIL FROM, and PRA identities using the following syntax:

if (spf-status("pra") == "Fail")

The following example shows the spf-status filter in use:

skip-spam-check-for-verified-senders:

if (sendergroup == "TRUSTED" and spf-status == "Pass"){

skip-spamcheck();

}

quarantine-spf-failed-mail:

if (spf-status("pra") == "Fail") {

if (spf-status("mailfrom") == "Fail"){

# completely malicious mail

quarantine("Policy");

} else {

if(spf-status("mailfrom") == "SoftFail") {

# malicious mail, but tempting

quarantine("Policy");

}

}

} else {

if(spf-status("pra") == "SoftFail"){

if (spf-status("mailfrom") == "Fail"

or spf-status("mailfrom") == "SoftFail"){

# malicious mail, but tempting

quarantine("Policy");

}

}

}

stamp-mail-with-spf-verification-error:

if (spf-status("pra") == "PermError, TempError"


or spf-status("mailfrom") == "PermError, TempError"

or spf-status("helo") == "PermError, TempError"){

# permanent error - stamp message subject

strip-header("Subject");

insert-header("Subject", "[POTENTIAL PHISHING] $Subject"); }

.

The following example shows an spf-passed rule used to quarantine emails that are not marked as spf-passed:

quarantine-spf-unauthorized-mail:

if (not spf-passed) {

quarantine("Policy");

}

Note

Unlike the spf-status rule, the spf-passed rule reduces the SPF/SIDF verification values to a simple Boolean. The following verification results are treated as not passed in the spf-passed rule: None, Neutral, Softfail, TempError, PermError, and Fail. To perform actions on messages based on more granular results, use the spf-status rule.

The S/MIME Gateway Message rule checks if a message is S/MIME signed, encrypted, or signed and encrypted. The following message filter checks if the message is an S/MIME message and quarantines it if the verification or decryption using S/MIME fails.

quarantine_smime_messages:
if (smime-gateway-message and not smime-gateway-verified) {
quarantine("Policy"); 
}

For more information, see S/MIME Security Services.

The S/MIME Gateway Message Verified rule checks if a message is successfully verified, decrypted, or decrypted and verified. The following message filter checks if the message is an S/MIME message and quarantines it if the verification or decryption using S/MIME fails.

quarantine_smime_messages:
if (smime-gateway-message and not smime-gateway-verified) {
quarantine("Policy"); 
}

For more information, see S/MIME Security Services

The workqueue-count rule checks the workqueue-count against a specified value. All the comparison operators are allowed, such as > , == , <=, and so forth.

The following filter checks the workqueue count, and skips spam check if the queue is greater than the specified number.

wqfull:

if (workqueue-count > 1000) {

skip-spamcheck();

}

For more information on SPF/SIDF, see Overview of SPF and SIDF Verification.

If your appliance uses SMTP authentication to send messages, the smtp-auth-id-matches (<target> [, <sieve-char>] )rule can check a message’s headers and Envelope Sender against the sender’s SMTP authenticated user ID to identify outgoing messages with spoofed headers. This filter allows the system to quarantine or block potentially spoofed messages.

The smtp-auth-id-matches rule compares the SMTP authenticated ID against the following targets:

The filter performs matches loosely. It is not case-sensitive. If the optional sieve-char parameter is supplied, the last portion of an address that follows the specified character will be ignored for the purposes of comparison. For example, if the + character is included as a parameter, the filter ignores the portion of the address joe+folder@example.com that follows the + character. If the address was joe+smith+folder@example.com , only the +folder portion is ignored. If the SMTP authenticated user ID string is a simple username and not a fully-qualified e-mail address, only the username portion of the target will be examined to determine a match. The domain must be verified in a separate rule.

Also, you can use the $SMTPAuthID variable to insert the STMP authenticated user ID into headers.

The following table shows examples of comparisons between the SMTP authenticated ID and email addresses and whether they would match using the smtp-auth-id-matches filter rule:

The following filter checks all messages created during an authenticated SMTP session to verify that the addresses in the From header and the Envelope Sender match the SMTP authenticated user ID. If the addresses and the ID match, the filter verifies the domain. If they do not match, the appliance quarantines the message.

Msg_Authentication:

if (smtp-auth-id-matches("*Any"))

{

# Always include the original authentication credentials in a

# special header.

insert-header("X-Auth-ID","$SMTPAuthID");

if (smtp-auth-id-matches("*FromAddress", "+") and

smtp-auth-id-matches("*EnvelopeFrom", "+"))

{

# Username matches. Verify the domain

if header('from') != "(?i)@(?:example\\.com|alternate\\.com)" or

mail-from != "(?i)@(?:example\\.com|alternate\\.com)"

{

# User has specified a domain which cannot be authenticated

quarantine("forged");

}

} else {

# User claims to be an completely different user

quarantine("forged");

}

}

The signed rule checks messages for a signature. The rule returns a boolean value to indicate if the message is signed or not. This rule evaluates whether the signature is encoded according to ASN.1 DER encoding rules and that it conforms to the CMS SignedData Type structure (RFC 3852, Section 5.1.). It does not aim to validate whether the signature matches the content, nor does it check the validity of the certificate.

The following example shows a signed rule used to insert headers into a signed message:

signedcheck: if signed { insert-header("X-Signed", "True"); }

The following example shows a signed rule used to drop attachments from unsigned messages from a certain sender group:

Signed: if ((sendergroup == "NOTTRUSTED") AND NOT signed) {

html-convert();

if (attachment_size > 0)

{

drop_attachments("");

}

}

The signed-certificate rule selects those S/MIME messages where the X.509 certificate issuer or message signer matches the given regular expression. This rule only supports X.509 certificates.

The rule’s syntax is signed-certificate (<field> [<operator> <regular expression>]) , where:

• <field> is either the quoted string “issuer” or “signer” ,
• <operator> is either == or != ,
• and <regular expression> is the value for matching the “issuer” or “signer.”

If the message is signed using multiple signatures, the rule returns true if any of the issuers or signers match the regular expression. The short form of this rule, signed-certificate(“issuer”) and signed-certificate(“signer”) , returns true if the S/MIME message contains an issuer or signer.

The Header Repeats rule evaluates to true if at a given point in time, a specified number of messages:

• With same subject are detected in the last one hour.
• From same envelope sender are detected in the last one hour.

You can use this rule to detect high volume emails. For example, political campaigns through certain websites may send out emails to organizations in high volumes. Anti-spam engines treat such emails as clean, and do not stop the delivery of these emails.

The syntax of this rule is header-repeats (<target>, <threshold> [, <direction>]) , where:

• <target> is subject or mail-from . AsyncOS counts the repetition of values of the target.
• <threshold> is the number of messages with identical values for a given target, received in the last one hour, beyond which the rule evaluates to true.
• <direction> is incoming , outgoing , or both. If direction is not specified in this rule, incoming or outgoing messages are counted for rule evaluation.

Every time when a Header Repeats rule evaluates to true , a System Alert is sent. SeeSystem Alerts.

Note	If the header field includes comma or semi-colon separated values, the rule considers the complete string for tracking. This rule ignores messages with empty subject header.

The Header Repeats rule maintains a moving sum of messages with up to one minute’s precision. As a result, after the set threshold has reached, there can be a delay of one minute before this rule is triggered.

Use a URL reputation rule to define message actions based on the reputation score of any URL in the message. For important details, see Filtering by URL Reputation or URL Category: Conditions and Rules in Protecting Against Malicious or Undesirable URLs

For these rules:

• msg_filter_name : is the name of this message filter.
• allowedlist is the name of a defined URL list (via the urllistconfig command.) Specifying an allowed list is optional.

Use URL categories to define message actions based on the category of URLs in the message. For important details, see Filtering by URL Reputation or URL Category: Conditions and Rules in Protecting Against Malicious or Undesirable URLs.

Filter syntax when using a url-category rule is:

<msg_filter_name>: if url-category ([‘<category-name1>’,’<category-name2>’,..., ‘<category-name3>’],’<url_allowed_list>’,'<include_attachments>','<include_message_body_subject>')

<action>

Where:

• msg_filter_name is the name of this message filter.
• action is any message filter action.
• category-name is the URL category. Separate multiple categories with commas. To obtain correct category names, look at a URL Category condition or action in a Content Filter. For descriptions and examples of the categories, see About URL Categories.
• url_allowed_list is the name of a defined URL list (via the urllistconfig command.)
• include_attachments to scan for URLs in message attachments. A value of '1' indicates that URL scanning for message attachments is enabled and a value of '0' indicates that URL scanning for message attachments is not enabled.

• include_message_body_subject to scan for URLs in the message body and subject. A value of '1' indicates that URL scanning for the message body and subject is enabled and a value of '0' indicates that URL scanning for the message body and subjects is not enabled.

The Corrupt Attachment rule evaluates to true if a message contains corrupt attachment. A corrupt attachment is an attachment that the scanning engine cannot scan and identified as corrupt.

You may want to take different message actions based on the message language. For example, you may want to:

• Add a disclaimer in Russian to the messages that are in Russian
• Drop the messages whose language could not be determined

Use the message-language rule to take message actions depending on the language of the message subject and body.

Note	This rule will not check for the language in attachments and headers.

You can use the Macro Detection rule to detect macro-enabled attachments in messages for the specified file types.

Note	If an archive or embedded file contains macros, the parent file is dropped from the message.

You may want to detect fraudulent messages with forged sender address (From: header) and perform actions on such messages.

Use the forged-email-detection rule to detect such messages. While configuring this rule, you must specify a content dictionary and the threshold value (1 through 100) for considering a message as potentially forged.

The forged-email-detection rule compares the From: header with the users in the content dictionary. During this process, depending on the similarity, the appliance assigns similarity score to each of the users in the dictionary. The following are some examples:

• If the From: header is <j0hn.sim0ns@example.com> and the content dictionary contains a user ‘John Simons,’ the appliance assigns a similarity score of 82 to the user.
• If the From: header is <john.simons@diff-example.com> and the content dictionary contains a user ‘John Simons,’ the appliance assigns a similarity score of 100 to the user.

The higher the similarity score, the higher the probability that the message is forged. If the similarity score is greater than or equal to the specified threshold value, the filter action is triggered.

For more information, see Forged Email Detection.

<filter_name>: if (forged-email-detection(“<content_dictionary>”, threshold)) {<action>;}

FED_CF: if (forged-email-detection("Execs", 70)) { fed("from", ""); }

You can use the duplicate_boundaries rule to detect messages that contain duplicate MIME boundaries.

Note	Attachment-based rules (for example, attachment-contains ) or actions (for example, drop-attachments-where-contains ) will not work on malformed messages (with duplicate MIME boundaries).

<filter_name>: if (duplicate_boundaries){<action>;}

DuplicateBoundaries: if (duplicate_boundaries) { quarantine("Policy"); }

You can use the malformed-header rule to detect messages that contain malformed MIME headers.

<filter_name>: if (malformed-header){<action>;}

quarantine_malformed_headers: if (malformed-header)
{
quarantine("Policy");
}

You can use the Geolocation rule to handle incoming messages from particular countries that you select.

<msg_filter_name>: if (geolocation-rule (['country_name-1', 'country_name-2',...
,’country_name-n'])) {<action>}

Quarantine_Incoming_Messages_from_Country1_and_Country2: if (geolocation-rule
(['Country1', 'Country2'])) {quarantine("Policy");}

As an example, use the following message filter rule syntax to detect malicious domains in messages using the ETF engine, and take appropriate actions on such messages.

Syntax:

quarantine_msg_based_on_ETF: if (domain-external-threat-feeds (['etf_source1'],
 ['mail-from', 'from'], <'domain_exception_list'>)) { quarantine("Policy"); }

Where

• ‘domain-external-threat-feeds' is the Domain reputation message filter rule.

• ‘etf_source1' is the ETF source(s) used to detect malicious domain(s) in the header(s) of a message.

• ‘mail-from','from' are the required header(s) used to check for the reputation of the domain.

• 'domain_exception_list' is the name of a domain exception list. If a domain exception list is not present it is displayed as "".

Example

In the following example, if the domain in the ‘Errors To:’ custom header is detected as malicious by the ETF engine, the message is quarantined.

Quaranting_Messages_with_Malicious_Domains: if domain-external-threat-feeds 
(['threat_feed_source'], ['Errors-To'], "")) {quarantine("Policy");}

You can use the Domain Reputation rule to filter messages based on SDR, and take appropriate actions on such messages:

• Sender Domain Verdict

• Sender Domain Age

• Sender Domain Unscannable

You can specify a particular file type (“exe” files for example) or common groups of attachments in the attachment-filetype and drop-attachments-by-filetype rules . AsyncOS divides the attachments into the groups listed in the following table.

If you create a message filter that uses the != operator to match a message that does not contain an attachment with a specific file type, the filter will not perform any action on the message if there is at least one attachment with the file type you want to filter out. For example, the following filter drops any message with an attachment that is not an .exe file type:

exe_check: if (attachment-filetype != "exe") {

drop();

}

If a message has multiple attachments, the appliance does not drop the message if at least one of the attachments is an .exe file, even if the other attachments not .exe files.

The system supports the expansion of action variables that contain ISO-2022 style character codings (the style of encoding used in header values) and also supports international text in the notification. These will be merged together to generate a notification that will then be sent as a UTF-8, quoted printable message.

The skip-filters action ensures that the message skips any further processing from message filters and continues through the email pipeline. The message that incurs the skip-filters action will be subject to anti-spam scanning and anti-virus scanning, if it is available on the appliance . The skip-filters action is the default final action for message filters.

The following filter notifies customercare@example.com and then immediately delivers any message addressed to boss@admin .

bossFilter:

if(rcpt-to == 'boss@admin$')

{

notify('customercare@example.com');

skip-filters();

}

The drop action discards a message without any delivery. The message is not returned to the sender, not sent to the intended recipient, nor processed further in any way.

The following filter first notifies george@whitehouse.gov and then discards any message where the subject begins with SPAM .

spamFilter:

if(subject == '^SPAM.*')

{

notify('george@whitehouse.gov');

drop();

}

The bounce action sends the message back to the sender (Envelope Sender) without further processing.

The following filter returns (bounces) any message from an email address that ends in @yahoo\\.com .

yahooFilter:

if(mail-from == '@yahoo\\.com$')

{

bounce();

}

The encrypt action uses the configured encryption profile to deliver encrypted messages to email recipients.

The following filter encrypts messages if they contain the term [encrypt] in the subject:

Encrypt_Filter:

if ( subject == '\\[encrypt\\]' )

{

encrypt('My_Encryption_Profile');

}

Note	You must have a Cisco Encryption Appliance in your network or a hosted key service configured to use this filter action. You must also have configured an encryption profile to use this filter action.

The smime-gateway-deferred action performs an S/MIME signing or encryption of the message using the specified sending profile during the delivery. This means that the message continues to the next stage of processing, and when all processing is complete, the message is signed or encrypted and delivered.

The following filter performs an S/MIME encryption on all the outgoing messages from a particular sender during the delivery:

smime-deferred:if(mail-from == "user@example.com"){smime-gateway-deferred("smime-encrypt");}

The smime-gateway action performs an S/MIME signing or encryption using the specified sending profile and delivers the message, skipping any further processing.

The following filter performs an S/MIME signing on all the outgoing messages from a particular sender and delivers them immediately:

smime-deliver-now:if(mail-from == "user@example.com"){smime-gateway("smime-sign");}

The notify and notify-copy actions send an email summary of the message to the specified email address. The notify-copy action also sends a copy of the original message, similar to the bcc-scan action. The notification summary contains:

• The contents of the Envelope Sender and Envelope Recipient ( MAIL FROM and RCPT TO ) directives from the mail transfer protocol conversation for the message.
• The message headers of the message.
• The name of the message filter that matched the message.

You can specify the recipient, subject line, from address, and notification template. the following filter selects messages with sizes larger than 4 megabytes, sends a notification email of each matching message to admin@example.com , and finally discards the message:

bigFilter:

if(body-size >= 4M)

{

notify('admin@example.com');

drop();

}

Or

bigFilterCopy:

if(body-size >= 4M)

{

notify-copy('admin@example.com');

drop();

}

The Envelope Recipient parameter may be any valid email address (for example, admin@example.com in the example above), or alternatively, may be the action variable $EnvelopeRecipients (see Action Variables), which specifies all Envelope Recipients of the message:

bigFilter:

if(body-size >= 4M)

{

notify('$EnvelopeRecipients');

drop();

}

The notify action also supports up to three additional, optional arguments that allow you to specify the subject header, the Envelope Sender, and a pre-defined text resource to use for the notification message. These parameters must appear in order, so a subject must be provided if the Envelope Sender is to be set or a notification template specified.

The subject parameter may contain action variables (see Action Variables) that will be replaced with data from the original message. By default, the subject is set to Message Notification .

The Envelope Sender parameter may be any valid email address, or alternatively, may be the action variable $EnvelopeFrom , which will set the return path of the message to the same as the original message

The notification template parameter is the name of an existing notification template. For more information, see Notifications.

This example extends the previous one, but changes the subject to look like [bigFilter] Message too large , sets the return path to be the original sender, and uses the “message.too.large” template:

bigFilter:

if (body-size >= 4M)

{

notify('admin@example.com', '[$FilterName] Message too large',

'$EnvelopeFrom', 'message.too.large');

drop();

}

You can also use the $MatchedContent action variable to notify senders or administrators that a content filter was triggered. The $MatchedContent action variable displays the content that triggered the filter. For example, the following filter sends a notification to an administrator if the email contains ABA account information.

ABA_filter:

if (body-contains ('*aba')){

notify('admin@example.com','[$MatchedContent]Account Information Displayed');

}

The bcc action sends an anonymous copy of the message to a specified recipient. This is sometimes referred to as message replication. Because no mention of the copy is made in the original message and the anonymous copy will never successfully bounce back to the recipient, the original sender and recipients of the message will not necessarily know that the copy was sent.

The following filter sends a blind carbon copy to mom@home.org for each message addressed to sue from johnny :

momFilter:

if ((mail-from == '^johnny$') and (rcpt-to == '^sue$'))

{

bcc('mom@home.org');

}

The bcc action also supports up to three additional, optional arguments that allow you to specify the subject header and Envelope Sender to use on the copied message, as well as an alt-mailhost. These parameters must appear in order, so a subject must be provided if the Envelope Sender is to be set.

The subject parameter may contain action variables (see Action Variables) that will be replaced with data from the original message. By default, this is set to the subject of the original message (the equivalent of $Subject ).

The Envelope Sender parameter may be any valid email address, or alternatively, may be the action variable $EnvelopeFrom , which will set the return path of the message to the same as the original message.

This example expands the previous one by setting the subject to be [Bcc] <original subject> , and the return path set to badbounce@home.org :

momFilter:

if ((mail-from == '^johnny$') and (rcpt-to == '^sue$'))

{

bcc('mom@home.org', '[Bcc] $Subject', 'badbounce@home.org');

}

The alt-mailhost is the fourth parameter:

momFilterAltM:

if ((mail-from == '^johnny$') and (rcpt-to == '^sue$'))

{

bcc('mom@home.org', '[Bcc] $Subject', '$EnvelopeFrom',

'momaltmailserver.example.com');

}

Caution

The Bcc() , notify() , and bounce() filter actions can allow viruses through your network. The blind carbon copy filter action creates a new message which is a full copy of the original message. The notify filter action creates a new message that contains the headers of the original message. While it is rare, headers can contain viruses. The bounce filter action creates a new message which contains the first 10k of the original message. In all three cases, the new message will not be processed by anti-virus or anti-spam scanning.

To send to multiple hosts, you can call the bcc() action multiple times:

multiplealthosts:

if (recv-listener == "IncomingMail")

{

insert-header('X-ORIGINAL-IP', '$remote_ip');

bcc ('$EnvelopeRecipients', '$Subject', '$EnvelopeFrom', '10.2.3.4');

bcc ('$EnvelopeRecipients', '$Subject', '$EnvelopeFrom', '10.2.3.5');

bcc ('$EnvelopeRecipients', '$Subject', '$EnvelopeFrom', '10.2.3.6');

}

The quarantine(‘quarantine_name’) action flags a message for inclusion into a queue called a quarantine. For more information about quarantines, see the “Quarantines” chapter. The duplicate-quarantine ( ‘quarantine_name’) action immediately places a copy of the message into the specified quarantine and the original message continues through the email pipeline. The quarantine name is case sensitive.

When flagged for quarantine, the message continues through the rest of the email pipeline. When the message reaches the end of the pipeline, if the message has been flagged for one or more quarantines then it enters those queues. Otherwise, it is delivered. Note that if the message does not reach the end of the pipeline, it is not placed in a quarantine.

Accordingly, if a message filter contains a quarantine() action followed by a bounce() or drop() action, the message will not enter the quarantine, since the final action prevents the message from reaching the end of the pipeline. The same is true if a message filter includes a quarantine action, but the message is later dropped by anti-spam or anti-virus scanning, or a content filter. The skip-filters() action causes the message to skip any remaining message filters, but content filters may still apply. For example, if a message filter flags a message for quarantine and also includes the skip-filters() action, the message skips all remaining message filters and will be quarantined, unless another action in the email pipeline causes the message to be dropped.

In the following example, the message is sent to the Policy quarantine if the message contains any words within the dictionary named “secret_word.”

quarantine_codenames:

if (dictionary-match ('secret_words'))

{

quarantine('Policy');

}

In the following example, suppose a company has an official policy to drop all .mp3 file attachments. If an inbound message has a .mp3 attachment, the attachment is stripped and the remaining message (original body and remaining attachments) is sent to the original recipient. Another copy of the original message with all attachments will be quarantined (sent to the Policy quarantine). If it is necessary to receive the blocked attachment(s), the original recipient would then request that the message be released from the quarantine.

strip_all_mp3s:

if (attachment-filename == '(?i)\\.mp3$') {

duplicate-quarantine('Policy');

drop-attachments-by-name('(?i)\\.mp3$');

}

The alt-rcpt-to action changes all recipients of the message to the specified recipient upon delivery.

The following filter sends all messages with an Envelope Recipient address that contain .freelist.com and changes all recipients for the message to system-lists@myhost.com :

freelistFilter:

if(rcpt-to == '\\.freelist\\.com$')

{

alt-rcpt-to('system-lists@myhost.com');

}

The alt-mailhost action changes the IP address for all recipients of the selected message to the numeric IP address or hostname given.

Note	The alt-mailhost action prevents a message classified as spam by an anti-spam scanning engine from being quarantined. The alt-mailhost action overrides the quarantine action and sends it to the specified mail host.

The following filter redirects recipient addresses to the host example.com for all messages.

localRedirectFilter:

if(true)

{

alt-mailhost('example.com');

}

Thus, a message directed to joe@anywhere.com is delivered to the mailhost at example.com with the Envelope To address joe@anywhere.com . Note that any additional routing information specified by the smtproutes command still affects the routing of the message. (See Routing Email for Local Domains.)

Note	The alt-mailhost action does not support specifying a port number. To do this, add an SMTP route instead.

The following filter redirects all messages to 192.168.12.5 :

local2Filter:

if(true)

{

alt-mailhost('192.168.12.5');

}

The alt-src-host action changes the source host for the message to the source specified. The source host consists of the IP interface or group of IP interfaces that the messages should be delivered from. If a group of IP interfaces is selected, the system round-robins through all of the IP interfaces within the group as the source interface when delivering email. In essence, this allows multiple Virtual Gateway addresses to be created on a single appliance . For more information, see Configuring Mail Gateways for all Hosted Domains Using Virtual Gateway™ Technology.

The IP interface may only be changed to an IP interface or interface group currently configured in the system. the following filter creates a Virtual Gateway using the outbound (delivery) IP interface outbound2 for all messages received from a remote host with the IP address 1.2.3.4 .

externalFilter:

if(remote-ip == '1.2.3.4')

{

alt-src-host('outbound2');

}

The following filter uses the IP interface group Group1 for all messages received from a remote host with the IP address 1.2.3.4 .

groupFilter:

if(remote-ip == '1.2.3.4')

{

alt-src-host('Group1');

}

The archive action saves a copy of the original message, including all message headers and recipients into an mbox-format file on the appliance. The action takes a parameter that is the name of the log file in which to save the message. The system automatically creates a log subscription with the specified filename when you create the filter, or you can also specify an existing filter log file. After the filter and the filter log file are created, the filter log options may then be edited with the filters -> logconfig subcommand.

Note	The logconfig command is a subcommand of filters . See Using the CLI to Manage Message Filters for a full description of how to use this subcommand.

The mbox format is a standard UNIX mailbox format, and there are many utilities available to make viewing the messages easier. Most UNIX systems allow you to type “ mail -f mbox.filename ” to view the files. The mbox format is in plain text, so you can use a simple text editor to view the contents of the messages.

In the following example, a copy of the message is saved to a log named joesmith if the Envelope Sender matches joesmith@yourdomain.com :

logJoeSmithFilter:

if(mail-from == '^joesmith@yourdomain\\.com$')

{

archive('joesmith');

}

The strip-header action examines the message for a particular header and removes those lines from the message before delivering it. When there are multiple headers, all instances of the header are removed (for example, the “Received:” header.)

In the following example, all messages have the header X-DeleteMe removed before transmission:

stripXDeleteMeFilter:

if (true)

{

strip-header('X-DeleteMe');

}

When working with headers, remember that the current value of the header includes changes made during processing (such as with filter actions that add, remove, or modify message headings). See Message Header Rules and Evaluation for more information.

The insert-header action inserts a new header into a message. AsyncOS does not verify the compliance to standards of the header you insert; you are responsible for ensuring that the resulting message complies with Internet standards for email.

The following example inserts a header named X-Company with the value set to My Company Name if the header is not already found in the message:

addXCompanyFilter:

if (not header('X-Company'))

{

insert-header('X-Company', 'My Company Name');

}

The insert-header() action allows the use of non-ASCII characters in the text of the header, while restricting the header name to be ASCII (to comply with standards). The transport encoding will be quoted-printable to maximize the readability.

Note

The strip-headers and insert-header actions can be used in combination to rewrite any message headers in the original message. In some case, it is valid to have multiple instances of the same header (for example, Received: ) where in other cases, multiple instances of the same header could confuse a MUA (for example, multiple Subject: headers.)

When working with headers, remember that the current value of the header includes changes made during processing (such as with filter actions that add, remove, or modify message headings). See Message Header Rules and Evaluation for more information.

The edit-header-text action allows you to rewrite specified header text using the regular expression substitution function. The filter matches the regular expression within the header and replaces it with a regular expression you specify.

For example, an email contains the following subject header:

Subject: SCAN Marketing Messages

The following filter removes the “SCAN” text, and leaves the text, “Marketing Messages”, in the header:

Remove_SCAN: if true

{

edit-header-text (‘Subject’, ‘^SCAN\\s*’,’’);

}

After the filter processes the message, it returns the following header:

Subject: Marketing Messages

The edit-body-text() message filter is similar to the Edit-Header-Text() filter, but it operates across the body of the message instead of one of the headers.

The edit-body-text() message filter uses the following syntax where the first parameter is the regular expression to search for and the second parameter is the replacement text:

Example: if true {

edit-body-text("parameter 1","parameter 2");

}

The edit-body-text() message filter only works on the message body parts. For more information about whether a given MIME part is considered a message “body” or a message “attachment”, see Message Bodies vs. Message Attachments.

The following example shows a URL removed from a message and replaced with the text, ‘URL REMOVED’:

URL_Replaced: if true {

edit-body-text("(?i)(?:https?|ftp)://[^\\s\">]+", "URL REMOVED");

}

The following example shows a social security number removed from the body of a message and replaced with the text, “XXX-XX-XXXX’:

ssn: if true {

edit-body-text("(?!000)(?:[0-6]\\d{2}|7(?:[0-6]\\d|7[012]))([
-]?)(?!00)\\d\\d\\1(?!0000)\\d{4}",

"XXX-XX-XXXX");

}

Note	You cannot use smart identifiers with the edit-body-text() filter at this time.

While RFC 2822 defines a text format for email messages, there are extensions (such as MIME) to provide the transport of other content within an RFC 2822 message. AsyncOS can now use the html-convert() message filter to convert HTML to plain text using the following syntax:

Convert_HTML_Filter:

if (true)

{

html-convert();

}

The Cisco message filters make a determination on whether a given MIME part is considered a message “body” or a message “attachment”. The html-convert() filter only works on the message body parts. For more information about message bodies and attachments, see Message Bodies vs. Message Attachments.

Depending on the format, the html-convert() filter uses different methods to strip the HTML from within the documents.

If the message is plain text (text/plain), the message passes through the filter unchanged. If the message is a simple HTML message (text/html), all the HTML tags are stripped out of the message and the resulting body replaces the HTML message. The lines are not reformatted, and the HTML is not rendered in plain text. If the structure is MIME (with a multipart/alternative structure) and it contains both a text/plain part and text/html part with the same content, the filter removes the text/html part of the message and leaves the text/plain part of the message. For all other MIME types (such as multipart/mixed), all HTML body parts are stripped of their tags and reinserted into the message.

When encountered in a message filter, the html-convert() filter action only tags the message to be processed but does not immediately make a change to the message structure. The changes to the message only take effect after all processing is complete. This allows the other filter actions to process the original message body prior to modification.

The bounce-profile action assigns a previously-configured bounce profile to the message. (See Directing Bounced Email.) If the message is undeliverable, the bounce options configured via the bounce profile are used. Using this feature overrides the bounce profile assigned to the message from the listener’s configuration (if one is assigned).

The following filter example assigns the bounce profile “fastbounce” to all email sent with the header X-Bounce-Profile: fastbounce :

fastbounce:

if (header ('X-Bounce-Profile') == 'fastbounce') {

bounce-profile ('fastbounce');

}

The skip-spamcheck action instructs the system to allow the message to bypass any content-based anti-spam filtering configured on the system. This action does nothing to the message if no content-based anti-spam filtering is configured, or if the message was never flagged to be scanned for spam in the first place.

The following example allows messages that have a high SenderBase Reputation Score to bypass the content-based anti-spam filtering feature:

allowed_list_on_reputation:

if (reputation > 7.5)

{

skip-spamcheck();

}

If you do not want to apply graymail actions on certain messages, you can bypass them using the following message filter actions:

The following example specifies that messages received on the listener “private_listener” must bypass graymail actions on social network emails.

internal_mail_is_safe:

if (recv-listener == 'private_listener')

{

skip-socialcheck();

}

The skip-viruscheck action instructs the system to allow the message to bypass any virus protection system configured on the system. This action does nothing to the message if there is no anti-virus system configured, or if the message was never flagged to be scanned for viruses in the first place.

The following example specifies that messages received on the listener “private_listener” should bypass the anti-spam and the anti-virus systems.

internal_mail_is_safe:

if (recv-listener == 'private_listener')

{

skip-spamcheck();

skip-viruscheck();

}

The skip-ampcheck action instructs the system to allow message to bypass File Reputation Filtering and File Analysis configured on the system. This action does nothing to the message if File Reputation Filtering and File Analysis is not configured, or if the message was never flagged to be scanned for File Reputation Filtering and File Analysis in the first place.

The following example specifies that messages with PDF attachments should bypass File Reputation Filtering and File Analysis.

skip_amp_scan:
if (attachment-filetype == 'pdf') 
{
skip-ampcheck();
}

The skip-vofcheck action instructs the system to allow the message to bypass the Outbreak Filters scanning. This action does nothing to the message if Outbreak Filters scanning is not enabled.

The following example specifies that messages received on the listener “private_listener” should bypass Outbreak Filter scanning.

internal_mail_is_safe:

if (recv-listener == 'private_listener') Outbreak Filters

{

skip-vofcheck();

}

The tag-message action inserts a custom term into an outgoing message to use with DLP policy filtering. You can configure a DLP policy to limit scanning to messages with the message tag. The message tag is not visible to recipients. The tag name can contain any combination of characters from the set [a-zA-Z0-9_-.] .

For information on configuring a DLP policy to filter messages, see the “Data Loss Prevention” chapter.

The following example inserts a message tag into a message with “[Encrypt]” in the subject. You can then create a DLP policy that will encrypt messages with this message tag before delivering them if Cisco Email Encryption is available:

Tag_Message:

if (subject == '^\\[Encrypt\\]')

{

tag-message('Encrypt-And-Deliver');

}

The log-entry action inserts customized text into the Text Mail logs at the INFO level. The text can include action variables. You can use this action to insert useful text for debugging purposes and information on why a message filter performed a certain action. The log entry also appears in message tracking.

The following example inserts a log entry explaining that message was bounced because it possibly contained confidential company information:

CompanyConfidential:

if (body-contains('Company Confidential'))

{

log-entry('Message may have contained confidential information.');

bounce();

}

Use the reputation score of URLs in messages to modify the URLs or their behavior. For important details and examples, see Modifying URLs in Messages: Using URL Reputation and URL Category Actions in Filters in Protecting Against Malicious or Undesirable URLs

No rule is needed with these actions.

In URL Reputation actions:

• msg_filter_name : is the name of this message filter.
• min_score and max_score are the minimum and maximum scores in the range for which the action should apply. The applicable range includes the values that you specify.

Minimum and maximum scores must be between -10.0 and 10.0 .

• To specify an action when the reputation service does not provide a score, use the corresponding "no-reputation" version of the action, as shown in the following subsections.
• allowedlist is the name of a defined URL list (via the urllistconfig command.) Specifying an allowed list is optional.
• In place of Preserve_signed , enter 0 or 1:
  • 1 - Apply this action to unsigned messages only
  • 0 - Apply this action to all messages

If you do not specify a preserve_signed value, the action is applied to unsigned messages only.

Use the categories of URLs in messages to modify the URLs or their behavior. For important details, see Modifying URLs in Messages: Using URL Reputation and URL Category Actions in Filters in Protecting Against Malicious or Undesirable URLs

No rule is needed with these actions.

In all URL Category actions:

• msg_filter_name : is the name of the message filter.
• category-name is the URL category. Separate multiple categories with commas. To obtain correct category names, look at a URL Category condition or action in a Content Filter. For descriptions and examples of the categories, see About URL Categories.
• url_allowed_list is the name of a defined URL list (via the urllistconfig command.)
• unsigned-only : Enter 0 or 1.
  • 1 - Apply this action to unsigned messages only
  • 0 - Apply this action to all messages

The No Operation action performs a no-op, or no operation. You can use this action in a message filter if you do not want to use any of the other actions such as Notify, Quarantine, or Drop. For example, to understand the behavior of a new message filter that you created, you can use the No Operation action. After the message filter is operational, you can monitor the behavior of the new message filter using the Message Filters report page, and fine-tune the filter to match your requirements.

The following example shows how to use No Operation action in a message filter.

new_filter_test: if header-repeats ('subject', X, 'incoming') {no-op();}

Strips the From: header from the forged message and replaces it with the Envelope Sender.

The following message filter compares the From: header in the message with the terms in dictionary and if the matching score of a term in the content dictionary is greater than or equal to 70, the message filter strips the From: header and replaces it with the Envelope Sender.

FED_CF: if (forged-email-detection("Execs", 70)) { fed("from", ""); }

In these examples, AsyncOS inserts headers when the attachments contain specified content.

In the following example, all of the attachments on the message are scanned for a keyword. If the keyword is present in all of the attachments, a custom X-Header is inserted:

attach_disclaim:

if (every-attachment-contains('[dD]isclaimer') ) {

insert-header("X-Example-Approval", "AttachOK");

}

In the following example, the attachment is scanned for a pattern in the binary data. The filter uses the attachment-binary-contains filter rule to search for a pattern that indicates that the PDF document is encrypted. If the pattern is present in the binary data, a custom header is inserted:

match_PDF_Encrypt:

if (attachment-filetype == 'pdf' AND

attachment-binary-contains('/Encrypt')){

strip-header (‘Subject’);

insert-header (‘Subject’, ‘[Encrypted] $Subject’);

}

In the following example, the “executable” group of attachments ( .exe , .dll , and .scr ) is stripped from messages and text is added to the message, listing the filenames of the dropped files (using the $dropped_filename action variable). Note that the drop-attachments-by-filetype action examines attachments and strips them based on the fingerprint of the file, and not just the three-letter filename extension. Note also that you can specify a single file type (“mpeg”) or you can refer to all of the members of the file type (“Media”):

strip_all_exes: if (true) {

drop-attachments-by-filetype ('Executable', “Removed attachment:

$dropped_filename”);

}

In the following example, the same “executable” group of attachments ( .exe , .dll , and .scr ) are stripped from messages whose Envelope Sender is not within the domain example.com .

strip_inbound_exes: if (mail-from != "@example\\.com$") {

drop-attachments-by-filetype ('Executable');

}

In the following example, a specific member of a file type (“wmf”) as well as a the same “executable” group of attachments ( .exe , .dll , and .scr ) are stripped from messages whose Envelope Sender is not within the domain example.com .

strip_inbound_exes_and_wmf: if (mail-from != "@example\\.com$") {

drop-attachments-by-filetype ('Executable');

drop-attachments-by-filetype ('x-wmf');

}

In the following example, the “executable” pre-defined group of attachments is extended to include more attachment names. (Note that this action will not examine the attachments’ file type.)

strip_all_dangerous: if (true) {

drop-attachments-by-filetype ('Executable');

drop-attachments-by-name('(?i)\\.(cmd|pif|bat)$');

}

The drop-attachments-by-name action supports non-ASCII characters.

Note	The drop-attachments-by-name action matches the regular expression against the filename captured from the MIME header. The filename captured from the MIME header may contain trailing spaces.

In the following example, a message is dropped if the attachment is not an .exe executable file type. However, the filter will not perform any action on the message if there is at least one attachment with the file type you want to filter out. For example, the following filter drops any message with an attachment that is not an .exe file type:

exe_check: if (attachment-filetype != "exe") {

drop();

}

If a message has multiple attachments, the appliance does not drop the message if at least one of the attachments is an .exe file, even if the other attachments not .exe files.

This drop-attachments-where-dictionary-match action strips attachments based on matches to dictionary terms. If the terms in the MIME parts considered to be an attachment match a dictionary term (and the user-defined threshold is met), the attachment is stripped from the email. The following example shows attachment drops if words in the “secret_words” dictionary are detected in the attachment. Note that the threshold for the matches is set to one:

Data_Loss_Prevention: if (true) {

drop-attachments-where-dictionary-match("secret_words", 1);

}

The attachment-protected filter tests whether any attachment in the message is password protected. You might use this filter on incoming mail to ensure that the attachments are scannable. According to this definition, a zip file containing one encrypted member along with unencrypted members will be considered protected. Similarly, PDF file that has no open password will not be considered protected, even though it may restrict copying or printing with a password. The following example shows protected attachments sent to a policy quarantine:

quarantine_protected:

if attachment-protected

{

quarantine("Policy");

}

The attachment-unprotected filter tests whether any attachment in the message is not password protected. This message filter complements the attachment-protected filter. You might use this filter on outgoing mail to detect outgoing mail that is unprotected. The following example shows AsyncOS detecting unprotected attachments on an outgoing listener and quarantining the messages:

quarantine_unprotected:

if attachment-unprotected

{

quarantine("Policy");

}

set [seqnum|filtname|range] active|inactive

Sets the filters identified to have the given state. Legal states are:

• active: Set the state of the selected filters to be active.
• inactive: Set the state of the selected filters to be inactive.

The following conditions can cause errors:

• No filter with a given filtname .
• No filter with a given sequence number.

Note

A filter which is inactive may also be noted in its syntax; the colon after the label (name of the filter) is changed to an exclamation point ( ! ). A filter entered manually from the CLI, or imported, that contains this syntax, will automatically be marked inactive. For example, mailfrompm! instead of mailfrompm: is displayed.

This filter sends notification based on whether the subject contains specific words:

search_for_sensitive_content:


if (Subject == "(?i)plaintiff|lawsuit|judge" ) {


notify ("admin@company.com");


}

This filter scans and blind copies messages that are sent to competitors. Note that you could use a dictionary and the header-dictionary-match() rule to specify a more flexible list of competitors (see Dictionary Rules):

competitorFilter:

if (rcpt-to == '@competitor1.com|@competitor2.com') {

bcc-scan('legal@example.com');

}

Use this filter to block email from a specific address:

block_harrasing_user:

if (mail-from == "ex-employee@hotmail\\.com") {

notify ("admin@company.com");

drop ();

}

Log and drop only the messages that have matching filetypes:

drop_attachments:

if (mail-from != "user@example.com") AND (attachment-filename ==

'(?i)\\.(asp|bas|bat|cmd|cpl|exe|hta|ins|isp|js)$')

{

archive("Drop_Attachments");

insert-header("X-Filter", "Dropped by: $FilterName MID: $MID");

drop-attachments-by-name("\\.(asp|bas|bat|cmd|cpl|exe|hta|ins|isp|js)$");

}

Find messages with very large “To” headers.

Use the archive() line for verification of proper action, with drop() enabled or disabled for extra safety:

toTooBig:

if(header('To') == "^.{500,}") {

archive('tooTooBigdropped');

drop();

}

Identify blank “From” headers,

This filter can alleviate various forms of blank “from” addresses:

blank_mail_from_stop:

if (recv-listener == "InboundMail" AND header("From") == "^$|<\\s*>") {

drop ();

}

If you also want to drop messages with a blank envelope from, use this filter:

blank_mail_from_stop:

if (recv-listener == "InboundMail" AND (mail-from == "^$|<\\s*>" OR header ("From") ==
"^$|<\\s*>"))

{

drop ();
}

SenderBase Reputation filter:

note_bad_reps:
if (reputation < -2) {
strip-header ('Subject');

insert-header ('Subject', '***BadRep $Reputation *** $Subject');
}

Alter the (SenderBase Reputation Score) SBRS threshold for certain domains:

mod_ipr:
if ( (rcpt-count == 1) AND (rcpt-to == "@domain\\.com$") AND (reputation < -2) ) {
drop ();
}

This filter specifies a range of size for the body of the message, and looks for an attachment that matches the regular expression (this matches files named “readme.zip”, “readme.exe”, “attach.exe”, and so forth.):

filename_filter:
if ((body-size >= 9k) AND (body-size <= 20k)) {
if (body-contains ("(?i)(readme|attach|information)\\.(zip|exe)$")) {
drop ();

}

}

Remember to log the headers (see the “Logging” chapter) so they appear in the mail log:

Check_ipr:

if (true) {

insert-header('X-ipr', '$Reputation');

}

Show which mail flow policy accepted the connection:

Policy_Tracker:

if (true) {

insert-header ('X-HAT', 'Sender Group $Group, Policy $Policy applied.');

}

Bounce all outbound email messages with more than 50 recipients from more than two unique domains:

bounce_high_rcpt_count:

if ( (rcpt-count > 49) AND (rcpt-to != "@example\\.com$") ) {

bounce-profile ("too_many_rcpt_bounce"); bounce ();

}

Segment traffic using virtual gateways. Assuming you have two Interfaces on the system, 'public1' and 'public2', and the default delivery interface is 'public1'. This would force all of your outbound traffic over the second interface; since bounces and other similar types of mail do not go through filters, they will be delivered from public1:

virtual_gateways:

if (recv-listener == "OutboundMail") {

alt-src-host ("public2");

}

Use the same listener for delivery and receiving. This filter will allow you to send any messages received on the public listener “listener1” out the interface “listener1” (you will have to set up a unique filter for each public listener configured):

same_listener:

if (recv-inj == 'listener1') {

alt-src-host('listener1');

}

Make the filter work on a single listener. For example, specify a specific listener for message filter processing instead of being performed system wide.

textfilter-new:

if (recv-inj == 'inbound' and body-contains("some spammy message")) {

alt-rcpt-to ("spam.quarantine@spam.example.com");

}

Drop email with a spoofed domain (pretending to be from an internal address; works with a single listener). IP addresses below represent fictional domain for mycompany.com :

DomainSpoofed:

if (mail-from == "mycompany\\.com$") {

if ((remote-ip != "1.2.") AND (remote-ip != "3.4.")) {

drop();

}

}

As above, but works with multiple listeners:

domain_spoof:

if ((recv-listener == "Inbound") and (mail-from == "@mycompany\\.com")) {

archive('domain_spoof');

drop ();

}

Summary: Anti domain spoof filter:

reject_domain_spoof:

if (recv-listener == "MailListener") {

insert-header("X-Group", "$Group");

if ((mail-from == "@test\\.mycompany\\.com") AND (header("X-Group") != "RELAYLIST")) {

notify("me@here.com");

drop();

strip-header("X-Group");

}

This filter is used to detect, stop, and determine what is causing, a mail loop. This filter can help determine a configuration issue on the Exchange server or elsewhere.

External_Loop_Count:

if (header("X-ExtLoop1")) {


if (header("X-ExtLoopCount2")) {

if (header("X-ExtLoopCount3")) {

if (header("X-ExtLoopCount4")) {

if (header("X-ExtLoopCount5")) {

if (header("X-ExtLoopCount6")) {

if (header("X-ExtLoopCount7")) {

if (header("X-ExtLoopCount8")) {

if (header("X-ExtLoopCount9")) {

notify ('joe@example.com');

drop();

}

else {insert-header("X-ExtLoopCount9", "from
$RemoteIP");}}

else {insert-header("X-ExtLoopCount8", "from $RemoteIP");}}

else {insert-header("X-ExtLoopCount7", "from $RemoteIP");}}

else {insert-header("X-ExtLoopCount6", "from $RemoteIP");}}

else {insert-header("X-ExtLoopCount5", "from $RemoteIP");}}

else {insert-header("X-ExtLoopCount4", "from $RemoteIP");}}

else {insert-header("X-ExtLoopCount3", "from $RemoteIP");}}

else {insert-header("X-ExtLoopCount2", "from $RemoteIP");}}

else {insert-header("X-ExtLoop1", "1"); 

}

Note	By default, AsyncOS automatically detects mail loops and will drop messages after 100 loops.