summaryrefslogtreecommitdiffstats
path: root/pigeonhole/doc/extensions/spamtest-virustest.txt
diff options
context:
space:
mode:
Diffstat (limited to 'pigeonhole/doc/extensions/spamtest-virustest.txt')
-rw-r--r--pigeonhole/doc/extensions/spamtest-virustest.txt140
1 files changed, 140 insertions, 0 deletions
diff --git a/pigeonhole/doc/extensions/spamtest-virustest.txt b/pigeonhole/doc/extensions/spamtest-virustest.txt
new file mode 100644
index 0000000..2ac8ad4
--- /dev/null
+++ b/pigeonhole/doc/extensions/spamtest-virustest.txt
@@ -0,0 +1,140 @@
+Spamtest and Virustest Extensions
+
+Relevant Specifications
+=======================
+
+ RFC5235 - doc/rfc/spamvirustest.rfc5235.txt
+
+Description
+===========
+
+Using the spamtest and virustest extensions (RFC 5235), the Sieve language
+provides a uniform and standardized command interface for evaluating spam and
+virus tests performed on the message. Users no longer need to know what headers
+need to be checked and how the scanner's verdict is represented in the header
+field value. They only need to know how to use the spamtest (spamtestplus) and
+virustest extensions. This also gives GUI-based Sieve editors the means to
+provide a portable and easy to install interface for spam and virus filter
+configuration. The burden of specifying which headers need to be checked and how
+the scanner output is represented falls onto the Sieve administrator.
+
+Configuration
+=============
+
+The spamtest, spamtestplus and virustest extensions are not enabled by default
+and thus need to be enabled explicitly using the sieve_extensions setting.
+
+The following settings need to be configured for using the spamtest and
+spamtestplus extensions. The virustest extension has identical configuration
+settings, but with a `sieve_virustest_' prefix instead of a `sieve_spamtest_'
+prefix:
+
+sieve_spamtest_status_type = "score" / "strlen" / "text"
+ This specifies the type of status result that the spam/virus scanner produces.
+ This can either be a numeric score ("score"), a string of identical characters
+ ("strlen"), e.g. '*******', or a textual description, e.g. `Spam'
+ or `Not Spam'.
+
+sieve_spamtest_status_header = <header-field> [ ":" <regexp> ]
+ This specifies the header field that contains the result information of the
+ spam scanner and it may express the syntax of the content of the header. If no
+ matching header is found in the message, the spamtest command will match
+ against "0".
+
+ This is a structured setting. The first part specifies the header field name.
+ Optionally, an extended POSIX regular expression follows the header field
+ name, separated by a colon. Any whitespace directly following the colon is not
+ part of the regular expression. If the regular expression is omitted, any
+ header content is accepted and the full header value is used. When a regular
+ expression is used, it must specify one match value (inside brackets) that
+ yields the desired spam scanner result. If the header does not match the
+ regular expression or if no value match is found, the spamtest will match
+ against "0".
+
+sieve_spamtest_max_value =
+ This statically specifies the maximum value a numeric spam score can have.
+
+sieve_spamtest_max_header = <header-field> [ ":" <regexp> ]
+ Some spam scanners include the maximum score value in one of their status
+ headers. Using this setting, this maximum can be extracted from the message
+ itself instead of specifying the maximum manually using the setting
+ `sieve_spamtest_max_value' explained above. The syntax is identical to the
+ `sieve_spamtext_status_header' setting.
+
+sieve_spamtest_text_valueX =
+ When the `sieve_spamtest_status_type' setting is set to "text", these settings
+ specify that the spamtest command will match against "X" when the specified
+ string is equal to the text (extracted) from the status header. For spamtest,
+ values of X between 0 and 10 are recognized, while virustest only uses values
+ between 0 and 5.
+
+Examples
+========
+
+This section shows several configuration examples. Each example shows a specimen
+of valid virus/spam test headers that the given configuration will work on.
+
+Example 1
+---------
+
+Spam header: `X-Spam-Score: No, score=-3.2'
+
+plugin {
+ sieve_extensions = +spamtest +spamtestplus
+
+ sieve_spamtest_status_type = score
+ sieve_spamtest_status_header = \
+ X-Spam-Score: [[:alnum:]]+, score=(-?[[:digit:]]+\.[[:digit:]])
+ sieve_spamtest_max_value = 5.0
+}
+
+Example 2
+---------
+
+Spam header: `X-Spam-Status: Yes'
+
+plugin {
+ sieve_extensions = +spamtest +spamtestplus
+
+ sieve_spamtest_status_type = text
+ sieve_spamtest_status_header = X-Spam-Status
+ sieve_spamtest_text_value1 = No
+ sieve_spamtest_text_value10 = Yes
+}
+
+Example 3
+---------
+
+Spam header: `X-Spam-Score: sssssss'
+
+plugin {
+ sieve_extensions = +spamtest +spamtestplus
+
+ sieve_spamtest_status_header = X-Spam-Score
+ sieve_spamtest_status_type = strlen
+ sieve_spamtest_max_value = 5
+}
+
+Example 4
+---------
+
+Spam header: `X-Spam-Score: status=3.2 required=5.0'
+Virus header: `X-Virus-Scan: Found to be clean.'
+
+plugin {
+ sieve_extensions = +spamtest +spamtestplus +virustest
+
+ sieve_spamtest_status_type = score
+ sieve_spamtest_status_header = \
+ X-Spam-Score: score=(-?[[:digit:]]+\.[[:digit:]]).*
+ sieve_spamtest_max_header = \
+ X-Spam-Score: score=-?[[:digit:]]+\.[[:digit:]] required=([[:digit:]]+\.[[:digit:]])
+
+ sieve_virustest_status_type = text
+ sieve_virustest_status_header = X-Virus-Scan: Found to be (.+)\.
+ sieve_virustest_text_value1 = clean
+ sieve_virustest_text_value5 = infected
+}
+
+
+