8.4 Using exiscan

One of Exim's most powerful and flexible features is its ACL system. Each ACL is a set of rules or tests that Exim performs when receiving a message; for example, an ACL is available for each stage of the SMTP transaction (start of connection, after HELO, after MAIL FROM, etc.). Rules are evaluated in order until one matches, and the associated action is then performed. Actions can include allowing the transaction to proceed, deferring the transaction, rejecting the transaction, ignoring the transaction, adding warning headers to the message, or dropping the connection altogether. If no rule matches, the ACL rejects the corresponding portion of the SMTP transaction.

exiscan is a set of patches for Exim that introduces the ability to invoke SpamAssassin in the acl_smtp_data ACL that Exim consults after the DATA step of an SMTP transaction. You can download exiscan from http://duncanthrax.net/exiscan-acl/; many precompiled versions of Exim (e.g., in Linux distributions) have the patch already applied. exiscan's new ACL actions also include blocking MIME attachments, virus-checking, and checking headers against regular expressions.

8.4.1 Installing exiscan

If you're not using a version of Exim that has exiscan already compiled in, you should download the exiscan patch file and apply it to your Exim source code with the GNU patch program. Example 8-7 shows the patch process, assuming that both the Exim source code and the patch are in /usr/local/src . Stop and restart Exim after you install the patched version.

Example 8-7. Patching the Exim source code with exiscan

 $  cd /usr/local/src/exim-4.30  $  patch -p1 -s < ../exiscan-acl-4.30-14.patch  $  rm -rf build-*  $  make  ...Compilation messages... $  su  Password:    XXXXXXXX    #  make install  

The rm -rf build-* command removes any old Exim build directories that may be present and forces Exim's Makefile to recreate them and repopulate them with symbolic links to source code files. This is important, because exiscan adds new source code files that would otherwise not have links in the build directory.

8.4.2 Writing acl_smtp_data

exiscan extends Exim's ACL language by adding a new rule, spam , that makes a connection to spamd to request a message check on behalf of a specified user and returns true if the message would exceed the user 's SpamAssassin spam threshold. Example 8-8 shows a simple acl_smtp_data that uses the spam condition to add an X-Spam-Flag: YES header to spam messages.

Example 8-8. Adding an X-Spam-Flag header with exiscan

 acl_smtp_data:   warn  message = X-Spam-Flag: YES         spam = nobody 

In this ACL, the condition spam = nobody invokes spamc as the user nobody . If the message's spam score exceeds nobody 's threshold, Exim takes the warn action, adding the X-Spam-Flag header. Similarly, the following ACL rule will generate a second Subject header with a spam tag for spam messages.

 warn  message = Subject: *SPAM* $h_Subject       spam = nobody 

ACLs can add headers but cannot remove them or modify them in situ . To replace the Subject header with a tagged version, you must add a new header through the ACL (e.g., X-Spam-Subject ) and direct Exim's system filter to replace the message subject with the new header if it's present. An example of how to do this is included with the exiscan documentation.

The spam condition also sets several useful Exim variables as a side effect:

$spam_bar

If SpamAssassin gives a message a positive spam score, exiscan sets this variable to a string of plus (+) characters, with one plus for each point of spam score, up to 50. If SpamAssassin gives a message a negative spam score, exiscan sets this variable to a string of minus characters (-), with one minus for each negative point of spam score. If SpamAssassin gives a message a zero spam score, exiscan sets this variable to a slash (/) character.

$spam_report

The full SpamAssassin report on a message.

$spam_score

The score assigned to a message by SpamAssassin.

$spam_score_int

The score assigned to a message by SpamAssassin multiplied by 10. exiscan stores this variable in the message's spool file, so Exim can use this value in later processing (e.g., in routers) to handle high-scoring messages differently than low-scoring messages.

These variables can be used with warn or deny actions to implement several kinds of spam policies. Example 8-9, adapted from the exiscan documentation, shows how you can direct Exim to add an X-Spam-Score header for all messages, to add an X-Spam-Report header for spam, and to reject a message completely if the spam score is higher than 12.

Example 8-9. Spam policies with exiscan

 warn  message = X-Spam-Report: $spam_report       spam = nobody warn  message = X-Spam-Score: $spam_score ($spam_bar)       spam = nobody:true deny   message = This message scored $spam_score spam points.        spam = nobody        condition = ${if >{$spam_score_int}{120}{1}{0}} 

The first rule performs spam-checking and adds the X-Spam-Report header if a message exceeds the spam threshold. exiscan caches the spam-checking results, so future calls to the spam condition for this message will not actually recheck the message. The second rule uses the :true option, which causes the condition to be evaluated as true regardless of the results of the spam check. Accordingly, Exim will add an X-Spam-Score header to all messages. Finally, Exim executes the deny action (refusing the message with the given text added to the SMTP rejection response) if the $spam_score_int is greater than 120 (which corresponds to a SpamAssassin score greater than 12.0).

8.4.3 Using Per-User Preferences

Because exiscan checks messages for spam just once ‚ at message receipt after the SMTP DATA command ‚ it's difficult to use SpamAssassin's per-user preference files. Messages may have multiple recipients, some of whom are not local, and exiscan will not be able to determine whose preferences should be used.

You can continue to use per-user preferences with exiscan in two ways, but each comes at a performance cost.

• You can ensure that each email message will have only a single recipient by writing an ACL for the SMTP RCPT TO phase that defers all recipients except the first one. The sending MTA will retry delivery to the deferred recipients but may not do so immediately. As a result, some copies of messages with multiple recipients may be significantly delayed. The exiscan documentation includes an example of how to do this.

• You can use exiscan to perform initial spam-checking and refuse messages with high scores, and then use the router/transport approach described earlier to reinvoke SpamAssassin on the remaining messages for local recipients. This approach results in an extra spamd connection for each message with a local recipient but might be worthwhile if exiscan can refuse enough very obvious spam sent to multiple recipients.