7Network Working Group C. Daboo
8Request for Comments: 5235 January 2008
10Category: Standards Track
13 Sieve Email Filtering: Spamtest and Virustest Extensions
17 This document specifies an Internet standards track protocol for the
18 Internet community, and requests discussion and suggestions for
19 improvements. Please refer to the current edition of the "Internet
20 Official Protocol Standards" (STD 1) for the standardization state
21 and status of this protocol. Distribution of this memo is unlimited.
25 The Sieve email filtering language "spamtest", "spamtestplus", and
26 "virustest" extensions permit users to use simple, portable commands
27 for spam and virus tests on email messages. Each extension provides
28 a new test using matches against numeric "scores". It is the
29 responsibility of the underlying Sieve implementation to do the
30 actual checks that result in proper input to the tests.
34 1. Introduction and Overview .......................................2
35 2. Conventions Used in This Document ...............................2
36 3. Sieve Extensions ................................................3
37 3.1. General Considerations .....................................3
38 3.2. Test spamtest ..............................................3
39 3.2.1. spamtest without :percent Argument ..................4
40 3.2.2. spamtest with :percent Argument .....................5
41 3.3. Test virustest .............................................7
42 4. Security Considerations .........................................9
43 5. IANA Considerations .............................................9
44 5.1. spamtest Registration ......................................9
45 5.2. virustest Registration ....................................10
46 5.3. spamtestplus Registration .................................10
47 6. References .....................................................10
48 6.1. Normative References ......................................10
49 6.2. Informative References ....................................11
50 Appendix A. Acknowledgments .......................................12
51 Appendix B. Important Changes since RFC 3685 ......................12
58Daboo Standards Track [Page 1]
60RFC 5235 Sieve: Spamtest and Virustest Extensions January 2008
631. Introduction and Overview
65 Sieve scripts are frequently being used to do spam and virus
66 filtering either based on implicit script tests (e.g., tests for
67 "black-listed" senders directly encoded in the Sieve script), or via
68 testing messages modified by some external spam or virus checker that
69 handled the message prior to Sieve. The use of third-party spam and
70 virus checker tools poses a problem since each tool has its own way
71 of indicating the result of its checks. These usually take the form
72 of a header added to the message, the content of which indicates the
73 status using some syntax defined by the particular tool. Each user
74 has to then create their own Sieve scripts to match the contents of
75 these headers to do filtering. This requires the script to stay in
76 synchronization with the third-party tool as it gets updated or
77 perhaps replaced with another. Thus, scripts become tied to specific
78 environments and lose portability.
80 The purpose of this document is to introduce two Sieve tests that can
81 be used to implement "generic" tests for spam and viruses in messages
82 processed via Sieve scripts. The spam and virus checks themselves
83 are handled by the underlying Sieve implementation in whatever manner
84 is appropriate, so that the Sieve spam and virus test commands can be
85 used in a portable way.
87 In order to do numeric comparisons against the returned strings,
88 server implementations MUST also support the Sieve relational
89 [RFC5231] extension, in addition to the extensions described here.
90 All examples below assume the relational extension is present.
922. Conventions Used in This Document
94 Conventions for notations are as in [RFC5228] Section 1.1.
96 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
97 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
98 document are to be interpreted as described in [RFC2119].
100 The term "spam" is used in this document to refer to unsolicited or
101 unwanted email messages. This document does not attempt to define
102 what exactly constitutes spam, or how it should be identified, or
103 what actions should be taken when detected.
105 The term "virus" is used in this document to refer to any type of
106 message whose content can cause malicious damage. This document does
107 not attempt to define what exactly constitutes a virus, or how it
108 should be identified, or what actions should be taken when detected.
114Daboo Standards Track [Page 2]
116RFC 5235 Sieve: Spamtest and Virustest Extensions January 2008
1213.1. General Considerations
123 The "spamtest" and "virustest" tests described below evaluate the
124 results of implementation-specific spam and virus checks in a
125 portable way. The implementation may, for example, check for third-
126 party spam tool headers and determine how those map into the way the
127 test commands are used. To do this, the underlying Sieve
128 implementation provides a normalized result string as one of the
129 inputs to each test command. The normalized result string is
130 considered to be the value on the left-hand side of the test, and the
131 comparison values given in the test command are considered to be on
134 The normalized result starts with a digit string, with its numeric
135 value within the range of values used by the specific test,
136 indicating the severity of spam or viruses in a message or whether
137 any tests were done at all. This may optionally be followed by a
138 space (%x20) character and arbitrary text, or in one specific case a
139 single keyword is returned. The numeric value can be compared to
140 specific values using the Sieve relational [RFC5231] extension in
141 conjunction with the "i;ascii-numeric" comparator [RFC4790], which
142 will test for the presence of a numeric value at the start of the
143 string, ignoring any additional text in the string. The optional
144 text can be used to carry implementation-specific details about the
145 tests and descriptive comments about the result. Tests can be done
146 using standard string comparators against this text if it helps to
147 refine behavior; however, this will break portability of the script
148 as the text will likely be specific to a particular implementation.
150 In addition, the Sieve relational [RFC5231] ":count" match type can
151 be used to determine if the underlying implementation actually did a
152 test. If the underlying spam or virus test was done, the ":count" of
153 the normalized result will return the numeric value "1", whilst if
154 the test was not done, or the Sieve implementation could not
155 determine if a test was done or not done, the ":count" value will be
160 Usage: spamtest [":percent"] [COMPARATOR] [MATCH-TYPE]
163 Sieve implementations that implement the "spamtest" test use an
164 identifier of either "spamtest" or "spamtestplus" for use with the
165 capability mechanism.
170Daboo Standards Track [Page 3]
172RFC 5235 Sieve: Spamtest and Virustest Extensions January 2008
175 If the ":percent" argument is not used with any spamtest test, then
176 one or both of "spamtest" or "spamtestplus" capability identifiers
179 If the ":percent" argument is used with any spamtest test, then the
180 "spamtestplus" capability identifier MUST be present. Sieve
181 implementations MUST return an error if the ":percent" argument is
182 used and "spamtestplus" is not specified.
184 In the interests of brevity and clarity, scripts SHOULD NOT specify
185 both "spamtestplus" and "spamtest" capability identifiers together.
187 The "spamtest" test evaluates to true if the normalized spamtest
188 result matches the value. The type of match is specified by the
189 optional match argument, which defaults to ":is" if not specified.
1913.2.1. spamtest without :percent Argument
193 When the ":percent" argument is not present in the "spamtest" test,
194 the normalized result string provided for the left-hand side of the
195 test starts with a numeric value in the range "0" (zero) through
196 "10", with meanings summarized below:
198 +----------+--------------------------------------------------------+
199 | spamtest | interpretation |
201 +----------+--------------------------------------------------------+
202 | 0 | message was not tested for spam, or Sieve could not |
203 | | determine whether any test was done |
205 | 1 | message was tested and is clear of spam |
207 | 2 - 9 | message was tested and may contain spam; a higher |
208 | | number indicates a greater likelihood of spam |
210 | 10 | message was tested and definitely contains spam |
211 +----------+--------------------------------------------------------+
213 The underlying Sieve implementation will map whatever spam check is
214 done into this numeric range, as appropriate.
218 require ["spamtest", "fileinto", "relational", "comparator-
226Daboo Standards Track [Page 4]
228RFC 5235 Sieve: Spamtest and Virustest Extensions January 2008
231 if spamtest :value "eq" :comparator "i;ascii-numeric" "0"
233 fileinto "INBOX.unclassified";
235 elsif spamtest :value "ge" :comparator "i;ascii-numeric" "3"
237 fileinto "INBOX.spam-trap";
240 In this example, any message that has not passed through a spam check
241 tool will be filed into the mailbox "INBOX.unclassified". Any
242 message with a normalized result value greater than or equal to "3"
243 is filed into a mailbox called "INBOX.spam-trap" in the user's
2463.2.2. spamtest with :percent Argument
248 When the ":percent" argument is present in the "spamtest" test, the
249 normalized result string provided for the left-hand side of the test
250 starts with a numeric value in the range "0" (zero) through "100",
251 with meanings summarized below:
253 +----------+-------------------------------------------------------+
254 | spamtest | interpretation |
256 +----------+-------------------------------------------------------+
257 | 0 | message was tested and is clear of spam, or was not |
258 | | tested for spam, or Sieve could not determine whether |
259 | | any test was done |
261 | 1 - 99 | message was tested and may contain spam; a higher |
262 | | percentage indicates a greater likelihood of spam |
264 | 100 | message was tested and definitely contains spam |
265 +----------+-------------------------------------------------------+
267 The underlying Sieve implementation will map whatever spam check is
268 done into the numeric range, as appropriate.
270 To determine whether or not the message was tested for spam, two
273 a. a test with or without the ":percent" argument and ":count" match
274 type, testing for the value "0" as described in Section 3.1.
276 b. a test without the ":percent" argument using the ":value" match
277 type, testing for the normalized result value "0" as described in
282Daboo Standards Track [Page 5]
284RFC 5235 Sieve: Spamtest and Virustest Extensions January 2008
289 require ["spamtestplus", "fileinto", "relational",
290 "comparator-i;ascii-numeric"];
292 if spamtest :value "eq"
293 :comparator "i;ascii-numeric" "0"
295 fileinto "INBOX.unclassified";
297 elsif spamtest :percent :value "eq"
298 :comparator "i;ascii-numeric" "0"
300 fileinto "INBOX.not-spam";
302 elsif spamtest :percent :value "lt"
303 :comparator "i;ascii-numeric" "37"
305 fileinto "INBOX.spam-trap";
312 In this example, any message that has not passed through a spam check
313 tool will be filed into the mailbox "INBOX.unclassified". Any
314 message that is classified as definitely not containing spam
315 (normalized result value "0") will be filed into the mailbox
316 "INBOX.not-spam". Any message with a normalized result value less
317 than "37" is filed into a mailbox called "INBOX.spam-trap" in the
318 user's mailstore. Any other normalized result value will result in
319 the message being discarded.
321 Alternatively, the Sieve relational [RFC5231] ":count" match type can
326 if spamtest :percent :count "eq"
327 :comparator "i;ascii-numeric" "0"
329 fileinto "INBOX.unclassified";
338Daboo Standards Track [Page 6]
340RFC 5235 Sieve: Spamtest and Virustest Extensions January 2008
343 elsif spamtest :percent :value "eq"
344 :comparator "i;ascii-numeric" "0"
346 fileinto "INBOX.not-spam";
348 elsif spamtest :percent :value "lt"
349 :comparator "i;ascii-numeric" "37"
351 fileinto "INBOX.spam-trap";
358 This example will result in exactly the same behavior as the previous
363 Usage: virustest [COMPARATOR] [MATCH-TYPE]
366 Sieve implementations that implement the "virustest" test have an
367 identifier of "virustest" for use with the capability mechanism.
369 The "virustest" test evaluates to true if the normalized result
370 string matches the value. The type of match is specified by the
371 optional match argument, which defaults to ":is" if not specified.
373 The normalized result string provided for the left side of the test
374 starts with a numeric value in the range "0" (zero) through "5", with
375 meanings summarized below:
394Daboo Standards Track [Page 7]
396RFC 5235 Sieve: Spamtest and Virustest Extensions January 2008
399 +-----------+-------------------------------------------------------+
400 | virustest | interpretation |
402 +-----------+-------------------------------------------------------+
403 | 0 | message was not tested for viruses, or Sieve could |
404 | | not determine whether any test was done |
406 | 1 | message was tested and contains no known viruses |
408 | 2 | message was tested and contained a known virus that |
409 | | was replaced with harmless content |
411 | 3 | message was tested and contained a known virus that |
412 | | was "cured" such that it is now harmless |
414 | 4 | message was tested and possibly contains a known |
417 | 5 | message was tested and definitely contains a known |
419 +-----------+-------------------------------------------------------+
421 The underlying Sieve implementation will map whatever virus checks
422 are done into this numeric range, as appropriate. If the message has
423 not been categorized by any virus checking tools, then the virustest
428 require ["virustest", "fileinto", "relational", "comparator-
431 if virustest :value "eq" :comparator "i;ascii-numeric" "0"
433 fileinto "INBOX.unclassified";
435 if virustest :value "eq" :comparator "i;ascii-numeric" "4"
437 fileinto "INBOX.quarantine";
439 elsif virustest :value "eq" :comparator "i;ascii-numeric" "5"
444 In this example, any message that has not passed through a virus
445 check tool will be filed into the mailbox "INBOX.unclassified". Any
446 message with a normalized result value equal to "4" is filed into a
450Daboo Standards Track [Page 8]
452RFC 5235 Sieve: Spamtest and Virustest Extensions January 2008
455 mailbox called "INBOX.quarantine" in the user's mailstore. Any
456 message with a normalized result value equal to "5" is discarded
457 (removed) and not delivered to the user's mailstore.
4594. Security Considerations
461 Sieve implementations SHOULD ensure that "spamtest" and "virustest"
462 tests only report spam and virus test results for messages that
463 actually have gone through a legitimate spam or virus check process.
464 In particular, if such checks rely on the addition and subsequent
465 checking of private header fields, it is the responsibility of the
466 implementation to ensure that such headers cannot be spoofed by the
467 sender or intermediary and thereby prevent the implementation from
468 being tricked into returning the wrong result for the test.
470 Server administrators must ensure that the virus checking tools are
471 kept up to date, to provide reasonable protection for users using the
472 "virustest" test. Users should be made aware of the fact that the
473 "virustest" test does not provide a 100% reliable way to remove all
474 viruses, and they should continue to exercise caution when dealing
475 with messages of unknown content and origin.
477 Beyond that, the "spamtest" and "virustest" extensions do not raise
478 any security considerations that are not present in the base
479 [RFC5228] protocol, and these issues are discussed in [RFC5228].
4815. IANA Considerations
483 The following templates specify the IANA registration of the Sieve
484 extensions specified in this document. The registrations for
485 "spamtest" and "virustest" replace those from [RFC3685]:
4875.1. spamtest Registration
490 Subject: Registration of new Sieve extension
492 Capability name: spamtest
493 Description: Provides a test to check for varying likelihood of
494 an email message being spam.
496 Contact address: The Sieve discussion list <ietf-mta-filters@imc.org>
498 This information has been added to the list of Sieve extensions given
499 on http://www.iana.org/assignments/sieve-extensions.
506Daboo Standards Track [Page 9]
508RFC 5235 Sieve: Spamtest and Virustest Extensions January 2008
5115.2. virustest Registration
514 Subject: Registration of new Sieve extension
516 Capability name: virustest
517 Description: Provides a test to check for varying likelihood of
518 there being malicious content in an email message.
520 Contact address: The Sieve discussion list <ietf-mta-filters@imc.org>
522 This information has been added to the list of Sieve extensions given
523 on http://www.iana.org/assignments/sieve-extensions.
5255.3. spamtestplus Registration
528 Subject: Registration of new Sieve extension
530 Capability name: spamtestplus
531 Description: Provides a test to check for varying likelihood of
532 an email message being spam, possibly using a
535 Contact address: The Sieve discussion list <ietf-mta-filters@imc.org>
537 This information has been added to the list of Sieve extensions given
538 on http://www.iana.org/assignments/sieve-extensions.
5426.1. Normative References
544 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
545 Requirement Levels", BCP 14, RFC 2119, March 1997.
547 [RFC4790] Newman, C., Duerst, M., and A. Gulbrandsen, "Internet
548 Application Protocol Collation Registry", RFC 4790, March
551 [RFC5228] Guenther, P., Ed., and T. Showalter, Ed., "Sieve: An Email
552 Filtering Language", RFC 5228, January 2008.
554 [RFC5231] Segmuller, W. and B. Leiba, "Sieve Email Filtering:
555 Relational Extension", RFC 5231, January 2008.
562Daboo Standards Track [Page 10]
564RFC 5235 Sieve: Spamtest and Virustest Extensions January 2008
5676.2. Informative References
569 [RFC3685] Daboo, C., "SIEVE Email Filtering: Spamtest and VirusTest
570 Extensions", RFC 3685, February 2004.
618Daboo Standards Track [Page 11]
620RFC 5235 Sieve: Spamtest and Virustest Extensions January 2008
623Appendix A. Acknowledgments
625 Thanks to Mark E. Mallett, Tony Hansen, Jutta Degener, Ned Freed,
626 Ashish Gawarikar, Alexey Melnikov, Nigel Swinson, and Aaron Stone for
627 comments and corrections.
629Appendix B. Important Changes since RFC 3685
631 Listed below are some of the major changes from the previous
632 specification [RFC3685], which this one supersedes.
634 1. A ":percent" argument has been added to the "spamtest" test adding
635 a new 0-100 numerical range for test results.
637 2. A "spamtestplus" requires item has been added to indicate the
638 presence of this extension in scripts.
640 3. The "count" match type from [RFC5231] can now be used to determine
641 whether or not a message was tested.
643 4. Clarified that "test not done" also means "Sieve system could not
644 determine if a test was done".
650 EMail: cyrus@daboo.name
674Daboo Standards Track [Page 12]
676RFC 5235 Sieve: Spamtest and Virustest Extensions January 2008
679Full Copyright Statement
681 Copyright (C) The IETF Trust (2008).
683 This document is subject to the rights, licenses and restrictions
684 contained in BCP 78, and except as set forth therein, the authors
685 retain all their rights.
687 This document and the information contained herein are provided on an
688 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
689 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND
690 THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS
691 OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF
692 THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
693 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
697 The IETF takes no position regarding the validity or scope of any
698 Intellectual Property Rights or other rights that might be claimed to
699 pertain to the implementation or use of the technology described in
700 this document or the extent to which any license under such rights
701 might or might not be available; nor does it represent that it has
702 made any independent effort to identify any such rights. Information
703 on the procedures with respect to rights in RFC documents can be
704 found in BCP 78 and BCP 79.
706 Copies of IPR disclosures made to the IETF Secretariat and any
707 assurances of licenses to be made available, or the result of an
708 attempt made to obtain a general license or permission for the use of
709 such proprietary rights by implementers or users of this
710 specification can be obtained from the IETF on-line IPR repository at
711 http://www.ietf.org/ipr.
713 The IETF invites any interested party to bring to its attention any
714 copyrights, patents or patent applications, or other proprietary
715 rights that may cover technology that may be required to implement
716 this standard. Please address the information to the IETF at
730Daboo Standards Track [Page 13]