PEP: Tests
For support call:     778-410-2454

PEP: Tests


PEP rules have the following format:

     ACTION [if] HEADERS COMPARISON VALUE [P1] [P2]

This could be read "perform ACTION if the result of comparing HEADERS to VALUE is true". The word "if" is optional and does nothing except make rules easier to read.

A rule compares one or more headers against a value, and if the result is true, the action is performed. If the result is false, the rule is skipped.

The HEADERS part of the rule lists one or more message headers to test. If you have more than one header they must be separated with a comma. No spaces are allowed in the header list.

If there are multiple occurances of the same header (eg: there are usually several Received: headers), only the first one in the message is tested unless you include a '*' wildcard. So to test the first Received: header you would just refer to "received", but if you want to test all the Received: headers you would refer to "received*".

Examples:

delete if from contains "hotmail.com"
delete if from,return-path,reply-to contains "hotmail.com"
delete if received* contains "hotmail.com"

Note that you must not include a colon (:) when refering to headers.

The headers are followed by a comparison operator and then the value to compare the headers against. Now we'll list each of the possible comparison operators and describe how they work.

IS
This test is true if any of the headers equal the test value. Case is NOT significant (ie: "you@islandnet.com" and "YOU@ISLANDNET.COM" are considered to be equal).

Example:

delete if to is "friend@public.com"

The opposite of is would be the is not test, which is true if none of the headers equal the test value.

Example:

delete if subject is not "web order"

CONTAINS
This test is true if any of the headers contain the test value. Case is NOT significant.

Example:

delete if from,return-path,received* contains "hotmail.com"

The opposite of contains would be the does not contain test, which is true if none of the headers contain the test value.

Example:

delete if to,cc,bcc does not contain "you@islandnet.com"

MATCHES
This test is similar to IS but the test value may contain the '*', '#', and '?' wildcards. Case is NOT significant. If no wildcards are present in the value, this test functions exactly like the IS test.

The '*' (asterisk) wildcard matches zero or more characters of any type (letters, numbers, punctuation, etc.) For example:

  • The value "*" matches everything.
  • The value "*@hotmail.com" matches any hotmail address.

The '#' (hash mark) wildcard is like the asterisk, except it only matches the digits 0 through 9. For example:

  • The value "#" matches any number.
  • The value "#@hotmail.com" matches all numeric hotmail address.
  • The value "*@#.com" matches any address at any numeric .com domain name.

The '?' (question mark) matches any single character. For example:

  • The value "???" matches anything that is exactly three characters long.
  • The value "*@*.??" matches any address that ends with a two character top level domain.

Example:

delete if senderaddress matches "*@#.com"

The opposite of matches would be the does not match test, which is true if none of the headers match the test value.

Example:

delete if to does not match "*@islandnet.com"

IPMATCHES (advanced)
This test is true if any of the headers are an IP address that is in the specified net block.

A net block can take three forms:

  • aaa.bbb.ccc.ddd is a single IP address.
  • aaa.bbb.ccc.ddd/mm is a network with CIDR style netmask.
  • aaa.bbb.ccc.ddd/www.xxx.yyy.zzz is a network with an old style netmask.

This example keeps messages that come from an IP address that is within one of Islandnet's net blocks:

keep if ip ipmatches 199.175.107/24

REGEX (advanced)
This test is true if any of the headers match the regular expression in the test value provided.

Regular expressions are a pattern matching mechanism similar to wildcards except they are far more powerful (and far more complex). In fact they are complex enough that we won't really document them here. There are many web sites out there that explain how regular expressions work.

NOTE: Regular expressions use the backslash to escape special characters. For example, to match a single character in a regular expression you use a dot, but to match a literal dot you need to escape it like this: \. However PEP itself uses the backslash to escape characters, so you must double up any backslashes that you use in your regular expressions. To match a literal dot in a PEP rule you'd use this: \\.

This example deletes messages that contain an URL with an IP address instead of a domain name (note the doubled up backslashes). It matches "http://" followed by 1 to 3 digits followed by a literal dot, then 1-3 more digits and another dot, and so on:

delete if body regex "http://[0-9]{1,3}\\.[0-9]{1,3}\\.[0-9]{1,3}\\.[0-9]{1,3}"

The opposite of regex would be the does not regex test, which is true if none of the headers match the test value.

Example:

delete if to does not regex "(bob|robert|rob)@yourdomainislandnet.com"

PEP utilizes the PCRE (Perl Compatible Regular Expressions) library by Philip Hazel.

BEGINS
This test is true if any of the headers begin with the test value. Case is NOT significant.

Example:

delete if subject begins "ADV:"

The opposite of begins would be the does not begin test, which is true if none of the headers begin with the test value.

Example:

delete if subject does not begin "re:"

< (less than)
This test is true if one of the headers is numerically less than the test value. A non-numeric header has a value of zero.

Example:

keep if tocount < 20

> (greater than)
This test is true if one of the headers is numerically greater than the test value. A non-numeric header has a value of zero.

Example:

delete if sascore > 99

IS IN
This test is a little different. The test value is actually the name of a file and each header is tested to see if it matches any line in that file. The file must be a plain text file with a single value per line.

This example performs a wildcard comparison (just like the MATCHES test) against each line in the file "spammers" and deletes the message if a match is found.

delete if from is in "spammers"

Here's a sample "spammers" file:

#@hotmail.com
*@#.com
bob@aol.com

The example rule above combined with the sample spammers file is functionally equivalent to this set of rules:

delete if from matches "#@hotmail.com"
delete if from matches "*@#.com"
delete if from matches "bob@aol.com"

If you have a large number of values you want to check headers against, using an IS IN test makes managing them easier.

The opposite of is in would be the is not in test, which is true if none of the headers match a line in the named file.

Example:

delete if senderaddress is not in "friends"

The default test is a wildcard pattern match, which means that the lines in the file may contain wildcard characters. You can change the type of test that is performed by adding keywords like this:

  • is in wildcard is the same as is in. The lines in the file may contain wildcard characters.
  • is in literal does a simple comparison where wildcard characters are treated literally and have no special function.
  • is in iplist does an ipmatch comparison, so the file is assumed to contain a list of IP addresses and/or networks.
  • is in regex does a regex comparison where each line in the file is treated as a regular expression.

Examples:

delete if senderaddress is in wildcard "spammers"
delete if subject is in literal "spamsubjects"
delete if ip is in iplist "spamnetworks"