<?xml version="1.0" encoding="UTF-8" standalone="no"?> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><style xmlns="" type="text/css"> div.added { background-color: #ffff99; } div.deleted { text-decoration: line-through; background-color: #FF7F7F; } div.changed { background-color: #99ff99; } div.off { } span.added { background-color: #ffff99; } span.deleted { text-decoration: line-through; background-color: #FF7F7F; } span.changed { background-color: #99ff99; } span.off { } pre.literallayout { background-color: #E8E8D0; padding-left: 0.5cm; padding-top: 5px; padding-bottom: 5px; } div[class=changed] pre.literallayout { background-color: #99ff99; padding-left: 0.5cm; padding-top: 5px; padding-bottom: 5px; } div.literallayout { background-color: #E8E8D0; padding-left: 0.5cm; padding-top: 5px; padding-bottom: 5px; } div[class=changed] div.literallayout { background-color: #99ff99; padding-left: 0.5cm; padding-top: 5px; padding-bottom: 5px; } </style><title>41. Content scanning at ACL time</title><meta name="generator" content="DocBook XSL Stylesheets V1.72.0" /><link rel="start" href="index.html" title="Specification of the Exim Mail Transfer Agent" /><link rel="up" href="index.html" title="Specification of the Exim Mail Transfer Agent" /><link rel="prev" href="ch40.html" title="40. Access control lists" /><link rel="next" href="ch42.html" title="42. Adding a local scan function to Exim" /></head><body><div class="navheader"> <table width="100%" summary="Navigation header"><tr><td width="20%" align="left"><a accesskey="p" href="ch40.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="ch42.html">Next</a></td></tr></table></div> <div class="chapter" lang="en" xml:lang="en"> <div class="titlepage"> <div> <div> <h2 class="title"><a href="index.html#toc0358" id="CHAPexiscan">41. Content scanning at ACL time</a></h2></div> </div> </div> <p> <a id="IIDcosca" class="indexterm"></a> The extension of Exim to include content scanning at ACL time, formerly known as “<span class="quote">exiscan</span>”, was originally implemented as a patch by Tom Kistner. The code was integrated into the main source for Exim release 4.50, and Tom continues to maintain it. Most of the wording of this chapter is taken from Tom’s specification. </p> <p> It is also possible to scan the content of messages at other times. The <em class="function">local_scan()</em> function (see chapter <a href="ch42.html" title="42. Adding a local scan function to Exim">42</a>) allows for content scanning after all the ACLs have run. A transport filter can be used to scan messages at delivery time (see the <span><strong class="option">transport_filter</strong></span> option, described in chapter <a href="ch24.html" title="24. Generic options for transports">24</a>). </p> <p> If you want to include the ACL-time content-scanning features when you compile Exim, you need to arrange for WITH_CONTENT_SCAN to be defined in your <em class="filename">Local/Makefile</em>. When you do that, the Exim binary is built with: </p> <div class="itemizedlist"> <ul type="disc"><li><p> Two additional ACLs (<span><strong class="option">acl_smtp_mime</strong></span> and <span><strong class="option">acl_not_smtp_mime</strong></span>) that are run for all MIME parts for SMTP and non-SMTP messages, respectively. </p> </li><li><p> Additional ACL conditions and modifiers: <span><strong class="option">decode</strong></span>, <span><strong class="option">malware</strong></span>, <span><strong class="option">mime_regex</strong></span>, <span><strong class="option">regex</strong></span>, and <span><strong class="option">spam</strong></span>. These can be used in the ACL that is run at the end of message reception (the <span><strong class="option">acl_smtp_data</strong></span> ACL). </p> </li><li><p> An additional control feature (“<span class="quote">no_mbox_unspool</span>”) that saves spooled copies of messages, or parts of messages, for debugging purposes. </p> </li><li><p> Additional expansion variables that are set in the new ACL and by the new conditions. </p> </li><li><p> Two new main configuration options: <span><strong class="option">av_scanner</strong></span> and <span><strong class="option">spamd_address</strong></span>. </p> </li></ul></div> <p> There is another content-scanning configuration option for <em class="filename">Local/Makefile</em>, called WITH_OLD_DEMIME. If this is set, the old, deprecated <span><strong class="option">demime</strong></span> ACL condition is compiled, in addition to all the other content-scanning features. </p> <p> Content-scanning is continually evolving, and new features are still being added. While such features are still unstable and liable to incompatible changes, they are made available in Exim by setting options whose names begin EXPERIMENTAL_ in <em class="filename">Local/Makefile</em>. Such features are not documented in this manual. You can find out about them by reading the file called <em class="filename">doc/experimental.txt</em>. </p> <p> All the content-scanning facilities work on a MBOX copy of the message that is temporarily created in a file called: </p> <div class="literallayout"> <<span class="emphasis"><em>spool_directory</em></span>><code class="literal">/scan/</code><<span class="emphasis"><em>message_id</em></span>>/<<span class="emphasis"><em>message_id</em></span>><code class="literal">.eml</code><br /> </div> <p> The <em class="filename">.eml</em> extension is a friendly hint to virus scanners that they can expect an MBOX-like structure inside that file. The file is created when the first content scanning facility is called. Subsequent calls to content scanning conditions open the same file again. The directory is recursively removed when the <span><strong class="option">acl_smtp_data</strong></span> ACL has finished running, unless </p> <pre class="literallayout">control = no_mbox_unspool </pre><p> has been encountered. When the MIME ACL decodes files, they are put into the same directory by default. </p> <div class="section" lang="en" xml:lang="en"> <div class="titlepage"> <div> <div> <h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="index.html#toc0359" id="SECTscanvirus">41.1 Scanning for viruses</a></h3></div> </div> </div> <p> <a id="id634489" class="indexterm"></a> <a id="id634500" class="indexterm"></a> <a id="id634514" class="indexterm"></a> The <span><strong class="option">malware</strong></span> ACL condition lets you connect virus scanner software to Exim. It supports a “<span class="quote">generic</span>” interface to scanners called via the shell, and specialized interfaces for “<span class="quote">daemon</span>” type virus scanners, which are resident in memory and thus are much faster. </p> <p> <a id="id634550" class="indexterm"></a> You can set the <span><strong class="option">av_scanner</strong></span> option in first part of the Exim configuration file to specify which scanner to use, together with any additional options that are needed. The basic syntax is as follows: </p> <div class="literallayout"> <code class="literal">av_scanner = <</code><span class="emphasis"><em>scanner-type</em></span><code class="literal">>:<</code><span class="emphasis"><em>option1</em></span><code class="literal">>:<</code><span class="emphasis"><em>option2</em></span><code class="literal">>:[...]</code><br /> </div> <p> If you do not set <span><strong class="option">av_scanner</strong></span>, it defaults to </p> <pre class="literallayout">av_scanner = sophie:/var/run/sophie </pre><p> If the value of <span><strong class="option">av_scanner</strong></span> starts with dollar character, it is expanded before use. The following scanner types are supported in this release: </p> <div class="variablelist"> <dl><dt><span class="term"><span><strong class="option">aveserver</strong></span></span></dt><dd><p> <a id="id634642" class="indexterm"></a> This is the scanner daemon of Kaspersky Version 5. You can get a trial version at <span class="bold"><strong><a href="http://www.kaspersky.com" target="_top">http://www.kaspersky.com</a></strong></span>. This scanner type takes one option, which is the path to the daemon’s UNIX socket. The default is shown in this example: </p> <pre class="literallayout">av_scanner = aveserver:/var/run/aveserver </pre></dd><dt><span class="term"><span><strong class="option">clamd</strong></span></span></dt><dd><p> <a id="id634693" class="indexterm"></a> This daemon-type scanner is GPL and free. You can get it at <span class="bold"><strong><a href="http://www.clamav.net/" target="_top">http://www.clamav.net/</a></strong></span>. Some older versions of clamd do not seem to unpack MIME containers, so it used to be recommended to unpack MIME attachments in the MIME ACL. This no longer believed to be necessary. One option is required: either the path and name of a UNIX socket file, or a hostname or IP number, and a port, separated by space, as in the second of these examples: </p> <pre class="literallayout">av_scanner = clamd:/opt/clamd/socket av_scanner = clamd:192.168.2.100 1234 </pre><p> If the option is unset, the default is <em class="filename">/tmp/clamd</em>. Thanks to David Saez for contributing the code for this scanner. </p> </dd><dt><span class="term"><span><strong class="option">cmdline</strong></span></span></dt><dd><p> <a id="id634755" class="indexterm"></a> This is the keyword for the generic command line scanner interface. It can be used to attach virus scanners that are invoked from the shell. This scanner type takes 3 mandatory options: </p> <div class="orderedlist"> <ol type="1"><li><p> The full path and name of the scanner binary, with all command line options, and a placeholder (<code class="literal">%s</code>) for the directory to scan. </p> </li><li><p> A regular expression to match against the STDOUT and STDERR output of the virus scanner. If the expression matches, a virus was found. You must make absolutely sure that this expression matches on “<span class="quote">virus found</span>”. This is called the “<span class="quote">trigger</span>” expression. </p> </li><li><p> Another regular expression, containing exactly one pair of parentheses, to match the name of the virus found in the scanners output. This is called the “<span class="quote">name</span>” expression. </p> </li></ol></div> <p> For example, Sophos Sweep reports a virus on a line like this: </p> <pre class="literallayout">Virus 'W32/Magistr-B' found in file ./those.bat </pre><p> For the trigger expression, we can match the phrase “<span class="quote">found in file</span>”. For the name expression, we want to extract the W32/Magistr-B string, so we can match for the single quotes left and right of it. Altogether, this makes the configuration setting: </p> <pre class="literallayout">av_scanner = cmdline:\ /path/to/sweep -ss -all -rec -archive %s:\ found in file:'(.+)' </pre></dd><dt><span class="term"><span><strong class="option">drweb</strong></span></span></dt><dd><p> <a id="id634874" class="indexterm"></a> The DrWeb daemon scanner (<span class="bold"><strong><a href="http://www.sald.com/" target="_top">http://www.sald.com/</a></strong></span>) interface takes one argument, either a full path to a UNIX socket, or an IP address and port separated by white space, as in these examples: </p> <pre class="literallayout">av_scanner = drweb:/var/run/drwebd.sock av_scanner = drweb:192.168.2.20 31337 </pre><p> If you omit the argument, the default path <em class="filename">/usr/local/drweb/run/drwebd.sock</em> is used. Thanks to Alex Miller for contributing the code for this scanner. </p> </dd><dt><span class="term"><span><strong class="option">fsecure</strong></span></span></dt><dd><p> <a id="id634934" class="indexterm"></a> The F-Secure daemon scanner (<span class="bold"><strong><a href="http://www.f-secure.com" target="_top">http://www.f-secure.com</a></strong></span>) takes one argument which is the path to a UNIX socket. For example: </p> <pre class="literallayout">av_scanner = fsecure:/path/to/.fsav </pre><p> If no argument is given, the default is <em class="filename">/var/run/.fsav</em>. Thanks to Johan Thelmen for contributing the code for this scanner. </p> </dd><dt><span class="term"><span><strong class="option">kavdaemon</strong></span></span></dt><dd><p> <a id="id634992" class="indexterm"></a> This is the scanner daemon of Kaspersky Version 4. This version of the Kaspersky scanner is outdated. Please upgrade (see <span><strong class="option">aveserver</strong></span> above). This scanner type takes one option, which is the path to the daemon’s UNIX socket. For example: </p> <pre class="literallayout">av_scanner = kavdaemon:/opt/AVP/AvpCtl </pre><p> The default path is <em class="filename">/var/run/AvpCtl</em>. </p> </dd><dt><span class="term"><span><strong class="option">mksd</strong></span></span></dt><dd><p> <a id="id635046" class="indexterm"></a> This is a daemon type scanner that is aimed mainly at Polish users, though some parts of documentation are now available in English. You can get it at <span class="bold"><strong><a href="http://linux.mks.com.pl/" target="_top">http://linux.mks.com.pl/</a></strong></span>. The only option for this scanner type is the maximum number of processes used simultaneously to scan the attachments, provided that the demime facility is employed and also provided that mksd has been run with at least the same number of child processes. For example: </p> <pre class="literallayout">av_scanner = mksd:2 </pre><p> You can safely omit this option (the default value is 1). </p> </dd><dt><span class="term"><span><strong class="option">sophie</strong></span></span></dt><dd><p> <a id="id635102" class="indexterm"></a> Sophie is a daemon that uses Sophos’ <span><strong class="option">libsavi</strong></span> library to scan for viruses. You can get Sophie at <span class="bold"><strong><a href="http://www.clanfield.info/sophie/" target="_top">http://www.clanfield.info/sophie/</a></strong></span>. The only option for this scanner type is the path to the UNIX socket that Sophie uses for client communication. For example: </p> <pre class="literallayout">av_scanner = sophie:/tmp/sophie </pre><p> The default path is <em class="filename">/var/run/sophie</em>, so if you are using this, you can omit the option. </p> </dd></dl></div> <p> When <span><strong class="option">av_scanner</strong></span> is correctly set, you can use the <span><strong class="option">malware</strong></span> condition in the DATA ACL. <span class="bold"><strong>Note</strong></span>: You cannot use the <span><strong class="option">malware</strong></span> condition in the MIME ACL. </p> <p> The <span><strong class="option">av_scanner</strong></span> option is expanded each time <span><strong class="option">malware</strong></span> is called. This makes it possible to use different scanners. See further below for an example. The <span><strong class="option">malware</strong></span> condition caches its results, so when you use it multiple times for the same message, the actual scanning process is only carried out once. However, using expandable items in <span><strong class="option">av_scanner</strong></span> disables this caching, in which case each use of the <span><strong class="option">malware</strong></span> condition causes a new scan of the message. </p> <p> The <span><strong class="option">malware</strong></span> condition takes a right-hand argument that is expanded before use. It can then be one of </p> <div class="itemizedlist"> <ul type="disc"><li><p> “<span class="quote">true</span>”, “<span class="quote">*</span>”, or “<span class="quote">1</span>”, in which case the message is scanned for viruses. The condition succeeds if a virus was found, and fail otherwise. This is the recommended usage. </p> </li><li><p> “<span class="quote">false</span>” or “<span class="quote">0</span>” or an empty string, in which case no scanning is done and the condition fails immediately. </p> </li><li><p> A regular expression, in which case the message is scanned for viruses. The condition succeeds if a virus is found and its name matches the regular expression. This allows you to take special actions on certain types of virus. </p> </li></ul></div> <p> You can append <code class="literal">/defer_ok</code> to the <span><strong class="option">malware</strong></span> condition to accept messages even if there is a problem with the virus scanner. Otherwise, such a problem causes the ACL to defer. </p> <p> <a id="id635280" class="indexterm"></a> When a virus is found, the condition sets up an expansion variable called <em class="varname">$malware_name</em> that contains the name of the virus. You can use it in a <span><strong class="option">message</strong></span> modifier that specifies the error returned to the sender, and/or in logging data. </p> <p> If your virus scanner cannot unpack MIME and TNEF containers itself, you should use the <span><strong class="option">demime</strong></span> condition (see section <a href="ch41.html#SECTdemimecond" title="41.6 The demime condition">41.6</a>) before the <span><strong class="option">malware</strong></span> condition. </p> <p> Here is a very simple scanning example: </p> <pre class="literallayout">deny message = This message contains malware ($malware_name) demime = * malware = * </pre><p> The next example accepts messages when there is a problem with the scanner: </p> <pre class="literallayout">deny message = This message contains malware ($malware_name) demime = * malware = */defer_ok </pre><p> The next example shows how to use an ACL variable to scan with both sophie and aveserver. It assumes you have set: </p> <pre class="literallayout">av_scanner = $acl_m0 </pre><p> in the main Exim configuration. </p> <pre class="literallayout">deny message = This message contains malware ($malware_name) set acl_m0 = sophie malware = * deny message = This message contains malware ($malware_name) set acl_m0 = aveserver malware = * </pre></div> <div class="section" lang="en" xml:lang="en"> <div class="titlepage"> <div> <div> <h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="index.html#toc0360" id="SECTscanspamass">41.2 Scanning with SpamAssassin</a></h3></div> </div> </div> <p> <a id="id635390" class="indexterm"></a> <a id="id635404" class="indexterm"></a> <a id="id635415" class="indexterm"></a> The <span><strong class="option">spam</strong></span> ACL condition calls SpamAssassin’s <span><strong class="option">spamd</strong></span> daemon to get a spam score and a report for the message. You can get SpamAssassin at <span class="bold"><strong><a href="http://www.spamassassin.org" target="_top">http://www.spamassassin.org</a></strong></span>, or, if you have a working Perl installation, you can use CPAN by running: </p> <pre class="literallayout">perl -MCPAN -e 'install Mail::SpamAssassin' </pre><p> SpamAssassin has its own set of configuration files. Please review its documentation to see how you can tweak it. The default installation should work nicely, however. </p> <p> <a id="id635465" class="indexterm"></a> After having installed and configured SpamAssassin, start the <span><strong class="option">spamd</strong></span> daemon. By default, it listens on 127.0.0.1, TCP port 783. If you use another host or port for <span><strong class="option">spamd</strong></span>, you must set the <span><strong class="option">spamd_address</strong></span> option in the global part of the Exim configuration as follows (example): </p> <pre class="literallayout">spamd_address = 192.168.99.45 387 </pre><p> You do not need to set this option if you use the default. As of version 2.60, <span><strong class="option">spamd</strong></span> also supports communication over UNIX sockets. If you want to use these, supply <span><strong class="option">spamd_address</strong></span> with an absolute file name instead of a address/port pair: </p> <pre class="literallayout">spamd_address = /var/run/spamd_socket </pre><p> You can have multiple <span><strong class="option">spamd</strong></span> servers to improve scalability. These can reside on other hardware reachable over the network. To specify multiple <span><strong class="option">spamd</strong></span> servers, put multiple address/port pairs in the <span><strong class="option">spamd_address</strong></span> option, separated with colons: </p> <pre class="literallayout">spamd_address = 192.168.2.10 783 : \ 192.168.2.11 783 : \ 192.168.2.12 783 </pre><p> Up to 32 <span><strong class="option">spamd</strong></span> servers are supported. The servers are queried in a random fashion. When a server fails to respond to the connection attempt, all other servers are tried until one succeeds. If no server responds, the <span><strong class="option">spam</strong></span> condition defers. </p> <p> <span class="bold"><strong>Warning</strong></span>: It is not possible to use the UNIX socket connection method with multiple <span><strong class="option">spamd</strong></span> servers. </p> </div> <div class="section" lang="en" xml:lang="en"> <div class="titlepage"> <div> <div> <h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="index.html#toc0361" id="SECID206">41.3 Calling SpamAssassin from an Exim ACL</a></h3></div> </div> </div> <p> Here is a simple example of the use of the <span><strong class="option">spam</strong></span> condition in a DATA ACL: </p> <pre class="literallayout">deny message = This message was classified as SPAM spam = joe </pre><p> The right-hand side of the <span><strong class="option">spam</strong></span> condition specifies a name. This is relevant if you have set up multiple SpamAssassin profiles. If you do not want to scan using a specific profile, but rather use the SpamAssassin system-wide default profile, you can scan for an unknown name, or simply use “<span class="quote">nobody</span>”. However, you must put something on the right-hand side. </p> <p> The name allows you to use per-domain or per-user antispam profiles in principle, but this is not straightforward in practice, because a message may have multiple recipients, not necessarily all in the same domain. Because the <span><strong class="option">spam</strong></span> condition has to be called from a DATA ACL in order to be able to read the contents of the message, the variables <em class="varname">$local_part</em> and <em class="varname">$domain</em> are not set. </p> <p> The right-hand side of the <span><strong class="option">spam</strong></span> condition is expanded before being used, so you can put lookups or conditions there. When the right-hand side evaluates to “<span class="quote">0</span>” or “<span class="quote">false</span>”, no scanning is done and the condition fails immediately. </p> <p> Scanning with SpamAssassin uses a lot of resources. If you scan every message, large ones may cause significant performance degradation. As most spam messages are quite small, it is recommended that you do not scan the big ones. For example: </p> <pre class="literallayout">deny message = This message was classified as SPAM condition = ${if < {$message_size}{10K}} spam = nobody </pre><p> The <span><strong class="option">spam</strong></span> condition returns true if the threshold specified in the user’s SpamAssassin profile has been matched or exceeded. If you want to use the <span><strong class="option">spam</strong></span> condition for its side effects (see the variables below), you can make it always return “<span class="quote">true</span>” by appending <code class="literal">:true</code> to the username. </p> <p> <a id="id635712" class="indexterm"></a> When the <span><strong class="option">spam</strong></span> condition is run, it sets up a number of expansion variables. With the exception of <em class="varname">$spam_score_int</em>, these are usable only within ACLs; their values are not retained with the message and so cannot be used at delivery time. </p> <div class="variablelist"> <dl><dt><span class="term"><em class="varname">$spam_score</em></span></dt><dd><p> The spam score of the message, for example “<span class="quote">3.4</span>” or “<span class="quote">30.5</span>”. This is useful for inclusion in log or reject messages. </p> </dd><dt><span class="term"><em class="varname">$spam_score_int</em></span></dt><dd><p> The spam score of the message, multiplied by ten, as an integer value. For example “<span class="quote">34</span>” or “<span class="quote">305</span>”. This is useful for numeric comparisons in conditions. This variable is special; its value is saved with the message, and written to Exim’s spool file. This means that it can be used during the whole life of the message on your Exim system, in particular, in routers or transports during the later delivery phase. </p> </dd><dt><span class="term"><em class="varname">$spam_bar</em></span></dt><dd><p> A string consisting of a number of “<span class="quote">+</span>” or “<span class="quote">-</span>” characters, representing the integer part of the spam score value. A spam score of 4.4 would have a <em class="varname">$spam_bar</em> value of “<span class="quote">++++</span>”. This is useful for inclusion in warning headers, since MUAs can match on such strings. </p> </dd><dt><span class="term"><em class="varname">$spam_report</em></span></dt><dd><p> A multiline text table, containing the full SpamAssassin report for the message. Useful for inclusion in headers or reject messages. </p> </dd></dl></div> <p> The <span><strong class="option">spam</strong></span> condition caches its results. If you call it again with the same user name, it does not scan again, but rather returns the same values as before. </p> <p> The <span><strong class="option">spam</strong></span> condition returns DEFER if there is any error while running the message through SpamAssassin. If you want to treat DEFER as FAIL (to pass on to the next ACL statement block), append <code class="literal">/defer_ok</code> to the right-hand side of the spam condition, like this: </p> <pre class="literallayout">deny message = This message was classified as SPAM spam = joe/defer_ok </pre><p> This causes messages to be accepted even if there is a problem with <span><strong class="option">spamd</strong></span>. </p> <p> Here is a longer, commented example of the use of the <span><strong class="option">spam</strong></span> condition: </p> <pre class="literallayout"># put headers in all messages (no matter if spam or not) warn spam = nobody:true add_header = X-Spam-Score: $spam_score ($spam_bar) add_header = X-Spam-Report: $spam_report # add second subject line with *SPAM* marker when message # is over threshold warn spam = nobody add_header = Subject: *SPAM* $h_Subject: # reject spam at high scores (> 12) deny message = This message scored $spam_score spam points. spam = nobody:true condition = ${if >{$spam_score_int}{120}{1}{0}} </pre></div> <div class="section" lang="en" xml:lang="en"> <div class="titlepage"> <div> <div> <h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="index.html#toc0362" id="SECTscanmimepart">41.4 Scanning MIME parts</a></h3></div> </div> </div> <p> <a id="id635901" class="indexterm"></a> <a id="id635915" class="indexterm"></a> <a id="id635926" class="indexterm"></a> <a id="id635938" class="indexterm"></a> The <span><strong class="option">acl_smtp_mime</strong></span> global option specifies an ACL that is called once for each MIME part of an SMTP message, including multipart types, in the sequence of their position in the message. Similarly, the <span><strong class="option">acl_not_smtp_mime</strong></span> option specifies an ACL that is used for the MIME parts of non-SMTP messages. These options may both refer to the same ACL if you want the same processing in both cases. </p> <p> These ACLs are called (possibly many times) just before the <span><strong class="option">acl_smtp_data</strong></span> ACL in the case of an SMTP message, or just before the <span><strong class="option">acl_not_smtp</strong></span> ACL in the case of a non-SMTP message. However, a MIME ACL is called only if the message contains a <span xmlns="" class="changed"><span xmlns="http://www.w3.org/1999/xhtml"><span class="emphasis"><em>Content-Type:</em></span></span></span> header line. When a call to a MIME ACL does not yield “<span class="quote">accept</span>”, ACL processing is aborted and the appropriate result code is sent to the client. In the case of an SMTP message, the <span><strong class="option">acl_smtp_data</strong></span> ACL is not called when this happens. </p> <p> You cannot use the <span><strong class="option">malware</strong></span> or <span><strong class="option">spam</strong></span> conditions in a MIME ACL; these can only be used in the DATA or non-SMTP ACLs. However, you can use the <span><strong class="option">regex</strong></span> condition to match against the raw MIME part. You can also use the <span><strong class="option">mime_regex</strong></span> condition to match against the decoded MIME part (see section <a href="ch41.html#SECTscanregex" title="41.5 Scanning with regular expressions">41.5</a>). </p> <p> At the start of a MIME ACL, a number of variables are set from the header information for the relevant MIME part. These are described below. The contents of the MIME part are not by default decoded into a disk file except for MIME parts whose content-type is “<span class="quote">message/rfc822</span>”. If you want to decode a MIME part into a disk file, you can use the <span><strong class="option">decode</strong></span> condition. The general syntax is: </p> <div class="literallayout"> <code class="literal">decode = [/</code><<span class="emphasis"><em>path</em></span>><code class="literal">/]</code><<span class="emphasis"><em>filename</em></span>><br /> </div> <p> The right hand side is expanded before use. After expansion, the value can be: </p> <div class="orderedlist"> <ol type="1"><li><p> “<span class="quote">0</span>” or “<span class="quote">false</span>”, in which case no decoding is done. </p> </li><li><p> The string “<span class="quote">default</span>”. In that case, the file is put in the temporary “<span class="quote">default</span>” directory <<span class="emphasis"><em>spool_directory</em></span>><em class="filename">/scan/</em><<span class="emphasis"><em>message_id</em></span>><em class="filename">/</em> with a sequential file name consisting of the message id and a sequence number. The full path and name is available in <em class="varname">$mime_decoded_filename</em> after decoding. </p> </li><li><p> A full path name starting with a slash. If the full name is an existing directory, it is used as a replacement for the default directory. The filename is then sequentially assigned. If the path does not exist, it is used as the full path and file name. </p> </li><li><p> If the string does not start with a slash, it is used as the filename, and the default path is then used. </p> </li></ol></div> <p> The <span><strong class="option">decode</strong></span> condition normally succeeds. It is only false for syntax errors or unusual circumstances such as memory shortages. You can easily decode a file with its original, proposed filename using </p> <pre class="literallayout">decode = $mime_filename </pre><p> However, you should keep in mind that <em class="varname">$mime_filename</em> might contain anything. If you place files outside of the default path, they are not automatically unlinked. </p> <p> For RFC822 attachments (these are messages attached to messages, with a content-type of “<span class="quote">message/rfc822</span>”), the ACL is called again in the same manner as for the primary message, only that the <em class="varname">$mime_is_rfc822</em> expansion variable is set (see below). Attached messages are always decoded to disk before being checked, and the files are unlinked once the check is done. </p> <p> The MIME ACL supports the <span><strong class="option">regex</strong></span> and <span><strong class="option">mime_regex</strong></span> conditions. These can be used to match regular expressions against raw and decoded MIME parts, respectively. They are described in section <a href="ch41.html#SECTscanregex" title="41.5 Scanning with regular expressions">41.5</a>. </p> <p> <a id="id636219" class="indexterm"></a> The following list describes all expansion variables that are available in the MIME ACL: </p> <div class="variablelist"> <dl><dt><span class="term"><em class="varname">$mime_boundary</em></span></dt><dd><p> If the current part is a multipart (see <em class="varname">$mime_is_multipart</em>) below, it should have a boundary string, which is stored in this variable. If the current part has no boundary parameter in the <span class="emphasis"><em>Content-Type:</em></span> header, this variable contains the empty string. </p> </dd><dt><span class="term"><em class="varname">$mime_charset</em></span></dt><dd><p> This variable contains the character set identifier, if one was found in the <span class="emphasis"><em>Content-Type:</em></span> header. Examples for charset identifiers are: </p> <pre class="literallayout">us-ascii gb2312 (Chinese) iso-8859-1 </pre><p> Please note that this value is not normalized, so you should do matches case-insensitively. </p> </dd><dt><span class="term"><em class="varname">$mime_content_description</em></span></dt><dd><p> This variable contains the normalized content of the <span class="emphasis"><em>Content-Description:</em></span> header. It can contain a human-readable description of the parts content. Some implementations repeat the filename for attachments here, but they are usually only used for display purposes. </p> </dd><dt><span class="term"><em class="varname">$mime_content_disposition</em></span></dt><dd><p> This variable contains the normalized content of the <span class="emphasis"><em>Content-Disposition:</em></span> header. You can expect strings like “<span class="quote">attachment</span>” or “<span class="quote">inline</span>” here. </p> </dd><dt><span class="term"><em class="varname">$mime_content_id</em></span></dt><dd><p> This variable contains the normalized content of the <span class="emphasis"><em>Content-ID:</em></span> header. This is a unique ID that can be used to reference a part from another part. </p> </dd><dt><span class="term"><em class="varname">$mime_content_size</em></span></dt><dd><p> This variable is set only after the <span><strong class="option">decode</strong></span> modifier (see above) has been successfully run. It contains the size of the decoded part in kilobytes. The size is always rounded up to full kilobytes, so only a completely empty part has a <em class="varname">$mime_content_size</em> of zero. </p> </dd><dt><span class="term"><em class="varname">$mime_content_transfer_encoding</em></span></dt><dd><p> This variable contains the normalized content of the <span class="emphasis"><em>Content-transfer-encoding:</em></span> header. This is a symbolic name for an encoding type. Typical values are “<span class="quote">base64</span>” and “<span class="quote">quoted-printable</span>”. </p> </dd><dt><span class="term"><em class="varname">$mime_content_type</em></span></dt><dd><p> If the MIME part has a <span class="emphasis"><em>Content-Type:</em></span> header, this variable contains its value, lowercased, and without any options (like “<span class="quote">name</span>” or “<span class="quote">charset</span>”). Here are some examples of popular MIME types, as they may appear in this variable: </p> <pre class="literallayout">text/plain text/html application/octet-stream image/jpeg audio/midi </pre><p> If the MIME part has no <span class="emphasis"><em>Content-Type:</em></span> header, this variable contains the empty string. </p> </dd><dt><span class="term"><em class="varname">$mime_decoded_filename</em></span></dt><dd><p> This variable is set only after the <span><strong class="option">decode</strong></span> modifier (see above) has been successfully run. It contains the full path and file name of the file containing the decoded data. </p> </dd></dl></div> <p> <a id="id636482" class="indexterm"></a> </p> <div class="variablelist"> <dl><dt><span class="term"><em class="varname">$mime_filename</em></span></dt><dd><p> This is perhaps the most important of the MIME variables. It contains a proposed filename for an attachment, if one was found in either the <span class="emphasis"><em>Content-Type:</em></span> or <span class="emphasis"><em>Content-Disposition:</em></span> headers. The filename will be RFC2047 decoded, but no additional sanity checks are done. If no filename was found, this variable contains the empty string. </p> </dd><dt><span class="term"><em class="varname">$mime_is_coverletter</em></span></dt><dd><p> This variable attempts to differentiate the “<span class="quote">cover letter</span>” of an e-mail from attached data. It can be used to clamp down on flashy or unnecessarily encoded content in the cover letter, while not restricting attachments at all. </p> <p> The variable contains 1 (true) for a MIME part believed to be part of the cover letter, and 0 (false) for an attachment. At present, the algorithm is as follows: </p> <div class="orderedlist"> <ol type="1"><li><p> The outermost MIME part of a message is always a cover letter. </p> </li><li><p> If a multipart/alternative or multipart/related MIME part is a cover letter, so are all MIME subparts within that multipart. </p> </li><li><p> If any other multipart is a cover letter, the first subpart is a cover letter, and the rest are attachments. </p> </li><li><p> All parts contained within an attachment multipart are attachments. </p> </li></ol></div> <p> As an example, the following will ban “<span class="quote">HTML mail</span>” (including that sent with alternative plain text), while allowing HTML files to be attached. HTML coverletter mail attached to non-HMTL coverletter mail will also be allowed: </p> <pre class="literallayout">deny message = HTML mail is not accepted here !condition = $mime_is_rfc822 condition = $mime_is_coverletter condition = ${if eq{$mime_content_type}{text/html}{1}{0}} </pre></dd><dt><span class="term"><em class="varname">$mime_is_multipart</em></span></dt><dd><p> This variable has the value 1 (true) when the current part has the main type “<span class="quote">multipart</span>”, for example “<span class="quote">multipart/alternative</span>” or “<span class="quote">multipart/mixed</span>”. Since multipart entities only serve as containers for other parts, you may not want to carry out specific actions on them. </p> </dd><dt><span class="term"><em class="varname">$mime_is_rfc822</em></span></dt><dd><p> This variable has the value 1 (true) if the current part is not a part of the checked message itself, but part of an attached message. Attached message decoding is fully recursive. </p> </dd><dt><span class="term"><em class="varname">$mime_part_count</em></span></dt><dd><p> This variable is a counter that is raised for each processed MIME part. It starts at zero for the very first part (which is usually a multipart). The counter is per-message, so it is reset when processing RFC822 attachments (see <em class="varname">$mime_is_rfc822</em>). The counter stays set after <span><strong class="option">acl_smtp_mime</strong></span> is complete, so you can use it in the DATA ACL to determine the number of MIME parts of a message. For non-MIME messages, this variable contains the value -1. </p> </dd></dl></div> </div> <div class="section" lang="en" xml:lang="en"> <div class="titlepage"> <div> <div> <h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="index.html#toc0363" id="SECTscanregex">41.5 Scanning with regular expressions</a></h3></div> </div> </div> <p> <a id="id636697" class="indexterm"></a> <a id="id636712" class="indexterm"></a> You can specify your own custom regular expression matches on the full body of the message, or on individual MIME parts. </p> <p> The <span><strong class="option">regex</strong></span> condition takes one or more regular expressions as arguments and matches them against the full message (when called in the DATA ACL) or a raw MIME part (when called in the MIME ACL). The <span><strong class="option">regex</strong></span> condition matches linewise, with a maximum line length of 32K characters. That means you cannot have multiline matches with the <span><strong class="option">regex</strong></span> condition. </p> <p> The <span><strong class="option">mime_regex</strong></span> condition can be called only in the MIME ACL. It matches up to 32K of decoded content (the whole content at once, not linewise). If the part has not been decoded with the <span><strong class="option">decode</strong></span> modifier earlier in the ACL, it is decoded automatically when <span><strong class="option">mime_regex</strong></span> is executed (using default path and filename values). If the decoded data is larger than 32K, only the first 32K characters are checked. </p> <p> The regular expressions are passed as a colon-separated list. To include a literal colon, you must double it. Since the whole right-hand side string is expanded before being used, you must also escape dollar signs and backslashes with more backslashes, or use the <code class="literal">\N</code> facility to disable expansion. Here is a simple example that contains two regular expressions: </p> <pre class="literallayout">deny message = contains blacklisted regex ($regex_match_string) regex = [Mm]ortgage : URGENT BUSINESS PROPOSAL </pre><p> The conditions returns true if any one of the regular expressions matches. The <em class="varname">$regex_match_string</em> expansion variable is then set up and contains the matching regular expression. </p> <p> <span class="bold"><strong>Warning</strong></span>: With large messages, these conditions can be fairly CPU-intensive. </p> </div> <div class="section" lang="en" xml:lang="en"> <div class="titlepage"> <div> <div> <h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="index.html#toc0364" id="SECTdemimecond">41.6 The demime condition</a></h3></div> </div> </div> <p> <a id="id636828" class="indexterm"></a> <a id="id636842" class="indexterm"></a> The <span><strong class="option">demime</strong></span> ACL condition provides MIME unpacking, sanity checking and file extension blocking. It is usable only in the DATA and non-SMTP ACLs. The <span><strong class="option">demime</strong></span> condition uses a simpler interface to MIME decoding than the MIME ACL functionality, but provides no additional facilities. Please note that this condition is deprecated and kept only for backward compatibility. You must set the WITH_OLD_DEMIME option in <em class="filename">Local/Makefile</em> at build time to be able to use the <span><strong class="option">demime</strong></span> condition. </p> <p> The <span><strong class="option">demime</strong></span> condition unpacks MIME containers in the message. It detects errors in MIME containers and can match file extensions found in the message against a list. Using this facility produces files containing the unpacked MIME parts of the message in the temporary scan directory. If you do antivirus scanning, it is recommended that you use the <span><strong class="option">demime</strong></span> condition before the antivirus (<span><strong class="option">malware</strong></span>) condition. </p> <p> On the right-hand side of the <span><strong class="option">demime</strong></span> condition you can pass a colon-separated list of file extensions that it should match against. For example: </p> <pre class="literallayout">deny message = Found blacklisted file attachment demime = vbs:com:bat:pif:prf:lnk </pre><p> If one of the file extensions is found, the condition is true, otherwise it is false. If there is a temporary error while demimeing (for example, “<span class="quote">disk full</span>”), the condition defers, and the message is temporarily rejected (unless the condition is on a <span><strong class="option">warn</strong></span> verb). </p> <p> The right-hand side is expanded before being treated as a list, so you can have conditions and lookups there. If it expands to an empty string, “<span class="quote">false</span>”, or zero (“<span class="quote">0</span>”), no demimeing is done and the condition is false. </p> <p> The <span><strong class="option">demime</strong></span> condition set the following variables: </p> <div class="variablelist"> <dl><dt><span class="term"><em class="varname">$demime_errorlevel</em></span></dt><dd><p> <a id="id636967" class="indexterm"></a> When an error is detected in a MIME container, this variable contains the severity of the error, as an integer number. The higher the value, the more severe the error (the current maximum value is 3). If this variable is unset or zero, no error occurred. </p> </dd><dt><span class="term"><em class="varname">$demime_reason</em></span></dt><dd><p> <a id="id636997" class="indexterm"></a> When <em class="varname">$demime_errorlevel</em> is greater than zero, this variable contains a human-readable text string describing the MIME error that occurred. </p> </dd></dl></div> <div class="variablelist"> <dl><dt><span class="term"><em class="varname">$found_extension</em></span></dt><dd><p> <a id="id637032" class="indexterm"></a> When the <span><strong class="option">demime</strong></span> condition is true, this variable contains the file extension it found. </p> </dd></dl></div> <p> Both <em class="varname">$demime_errorlevel</em> and <em class="varname">$demime_reason</em> are set by the first call of the <span><strong class="option">demime</strong></span> condition, and are not changed on subsequent calls. </p> <p> If you do not want to check for file extensions, but rather use the <span><strong class="option">demime</strong></span> condition for unpacking or error checking purposes, pass “<span class="quote">*</span>” as the right-hand side value. Here is a more elaborate example of how to use this facility: </p> <pre class="literallayout"># Reject messages with serious MIME container errors deny message = Found MIME error ($demime_reason). demime = * condition = ${if >{$demime_errorlevel}{2}{1}{0}} # Reject known virus spreading file extensions. # Accepting these is pretty much braindead. deny message = contains $found_extension file (blacklisted). demime = com:vbs:bat:pif:scr # Freeze .exe and .doc files. Postmaster can # examine them and eventually thaw them. deny log_message = Another $found_extension file. demime = exe:doc control = freeze </pre><p> <a id="id637094" class="indexterm"></a> </p> </div> </div> <div class="navfooter"> <table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch40.html">Prev</a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="ch42.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div> </body></html>