clamassassin 1.2.3 Author: James Lick Website: http://jameslick.com/clamassassin/ Announcement Mailing List: http://lists.jameslick.com/mailman/listinfo/clamassassin-announce Discussion Mailing List: http://lists.jameslick.com/mailman/listinfo/clamassassin-discuss Copyright (c) 2003-2006, James Lick All rights reserved. See LICENSE file for information on your legal rights to this software. clamassassin is a simple script for virus scanning an e-mail message as a filter. If a message is virus infected, the X-Virus-Status header is set to Yes and the X-Virus-Report header is set to the virus(es) found. If the message is fine, it is passed through with X-Virus-Status set to No. If something goes wrong, X-Virus-Status is set to Failed and X-Virus-Report contains a message indicating the problem. This can mean that the script could not create tempfiles, or some internal error occurred in ClamAV. The latter case has been seen on some spam messages with malformed headers when using older versions of ClamAV. An X-Virus-Checker-Version will be added to all messages showing the version of clamassassin and ClamAV which were used, whether clamscan or clamdscan is being used, as well as the version of the virus signature files. The handling of the virus signature files is different for ClamAV 0.80 and higher. Please see the configuration section for more details. If any of the headers clamassassin uses already exist on the incoming message, they will be removed or replaced. This is to avoid your sorting rules from being fooled by bogus headers. Only infected messages or messages which failed to scan will have an X-Virus-Report header. You also have the option of enabling subject rewriting so that the subject is prefixed with a string such as '*****VIRUS*****'. This is useful for users who cannot use folders, cannot sort their email in their mail reader, whose mail reader sorting can't use arbitrary headers such as X-Virus-Status, or for those dangerous individuals who insist none of their mail be discarded or altered. This function is similiar to SpamAssassin's rewrite_subject option. This is off by default but can be set by using the --enable-subject-rewrite option during configuration as documented below. This is intended to act much like spamassassin does. This makes it possible to plug it into a procmail or other filter quite easily. If you've already set up a system to use spamassassin, you can easily use similiar procedures to implement clamassassin. REQUIREMENTS: A unix-like system. ClamAV: http://www.clamav.net/ formail (included in procmail): http://www.procmail.org/ mktemp: http://www.mktemp.org/mktemp/ formail and mktemp are already installed on many systems, but not on some proprietary systems such as Solaris. The following standard unix utilities are also required: rm, cat, echo and sed. It's very rare not to have these on any kind of unix-like system. There are a few compatibility requirements for ClamAV to work with clamassassin 1.2.3. When using the command line scanner clamscan, ClamAV 0.66 or higher is required. When using the client/server scanner clamdscan, ClamAV 0.70 or higher is required. In addition, clamdscan in version 0.75 is not compatible with clamassassin due to a bug in ClamAV. In general, you are highly encouraged to keep ClamAV upgraded to the latest stable version at all times. Older versions are unable to detect some forms of the newer viruses. At the time of this release, 0.87.1 or higher is the recommended version of ClamAV. Check the clamassassin website for details on any compatibility problems with versions newer than this. Future versions of clamassassin will remove support of ClamAV versions older than 0.80. There are no known compatibility problems with any of the other required utilities. If you discover any issues, please let the author know. clamassassin is developed and tested on Solaris 10, but should work on any unix-like system which meet the requirements above. It has been reported to work on various versions of Unix, Linux, and BSD platforms. Please let me know which platforms you successfully run clamasassin on by sending me the output of the 'uname -a' command. clamassassin is Made in Taiwan. QUICK INSTALL GUIDE: Most people will simply need to do: ./configure make install Then setup your procmail rc files as below. If you need to do something more complicated, read on: CONFIGURATION: With version 1.2.0 and later, you must use automatic configuration first. Every effort has been made to ensure that configurable options are available through the automatic configuration process. If for some reason you still need to make changes, run the automatic configuration first, then make your changes in the resulting clamassassin script. Run './configure' which will try to figure out where things are installed based on your path. It will use clamdscan instead of clamscan if it sees /tmp/clamd. Make sure to read the notes below on using clamdscan to make sure your system is configured properly. If you want to force clamdscan to be used, or force it not to be used, you can try the following options to configure: --enable-clamdscan Force clamassassin to use clamdscan even if /tmp/clamd not found. --disable-clamdscan Force clamassassin not to use clamdscan even if /tmp/clamd found. If the configure script doesn't find the preferred location of your system utilities, try checking your shell's path setting. Changing the order of directories in your path may result in the desired location being found. clamassassin uses a temporary directory to store some files during processing. Normally this is the /tmp directory, and in most cases this is the optimal choice. In some cases you may choose to change this for various reasons. To do so, set the TMP environment variable to the directory you wish to use. This directory will need to be writable by whichever user the script is run as. By default, configure will set things to install in /usr/local/bin. If you would like to install elsewhere, use the --prefix or --bindir options to configure. For example, to install in /usr/bin, use one of the following options: --prefix=/usr or --bindir=/usr/bin To enable subject header rewriting use these flags when running configure: --enable-subject-rewrite[=message] When a virus is detected, rewrite Subject: header to be prefixed with *****VIRUS***** or [message] if specified --disable-subject-rewrite Do not do Subject: header rewriting (default) Starting with version 1.2.1, the configure script will detect the ClamAV version and make sure it is compatible with clamassassin. It will require ClamAV 0.66 or higher to use clamscan and 0.70 or higher to use clamdscan. In addition, clamdscan is disabled if version 0.75 is detected. You can disable this version checking if it causes problems, but you are highly encouraged not to: --enable-version-check (default) Checks ClamAV version for compatibility. --disable-version-check Skips checking ClamAV version for compatibility. With ClamAV 0.80 and higher, the version of the signature files is included in the version string. Previously ClamAV did not report the signature versions, so clamassassin had to determine these and add it to the X-Virus-Checker-Version header. The current default for clamassassin is to add the signature version itself for versions of ClamAV 0.80 and earlier. If for some reason the default is incorrect, you can use the following configuration options: --enable-signature-version Turns on signature version reporting (default for ClamAV below 0.80) --disable-signature-version Turns off signature version reporting (default for ClamAV 0.80 and up) Also with ClamAV 0.80 and higher, the version string no longer includes the command being used (clamscan, clamdscan, etc.) in the version string. clamassassin will add this back into the version string if ClamAV 0.80 or higher is detected. If for some reason the default setting is incorrect, you can use the following configuration options: --enable-name-adding Turns on adding of scanner name (default for ClamAV 0.80 and up) --disable-name-adding Turns off adding of scanner name (default for ClamAV below 0.80) If you need more assistance, run './configure --help' for a complete list of options. Please note that not all options are applicable to clamassassin. If the paths detected are incorrect, or you wish to make other changes, you can edit the 'clamassassin' file after running './configure'. I've tried to make everything I could think of configurable using the configure script, so if you have to edit something manually, please send me a suggestion to make that configurable. INSTALLATION: When you are satisfied with the results, run 'make install'. In most cases you will need to run this command as root, or some other priveleged user. PROCMAIL: This script will most commonly be used as a filter in procmail. It is beyond the scope of this document to explain how to setup procmail, so this assumes that you already are familiar with it. To pass your mail through clamassassin, add the following command to your procmail rc file: :0fw | /usr/local/bin/clamassassin If you installed the program elsewhere, change the path. The above will scan the mesage for viruses and add the headers X-Virus-Status and X-Virus-Report as appropriate. Procmail then continues processing the message as normal. Nothing else will happen unless you add additional rules to sort or discard detected viruses. To do this, you might do the following as the next procmail rule: :0: * ^X-Virus-Status: Yes IN.virus This will sort any mail detected as a virus to the "IN.virus" mail folder. If you want to destroy such messages altogether, change IN.virus to /dev/null. I encourage you to test the filter thoroughly before discarding messages. NOTE: DO NOT set up rules to bounce viruses or warning messages back to the sender. Nearly all modern viruses use forged mail headers, meaning the sender noted on the message has nothing to do with it. Sending a warning to them does nothing but annoy an innocent party. I highly recommend inserting the above rules FIRST in your procmail filters. This is to ensure that viruses aren't inadvertently whitelisted later in your sorting rules. Remember, even if a message looks like it comes from a known friend or mailing list, it could be a virus in disguise. I've been running this on my mail for months now and it has never given a false positive on an infected email. ADVANCED PROCMAIL: David Hiebert wrote in to suggest a procmail recipe that only checks MIME messages for viruses. After reminding him that some viruses (Happy99 and MyParty) used uuencoded files to propagate, he added those to his recipe. I highly recommend scanning ALL messages for viruses, as there is no telling whether future viruses will propagate using alternative methods. If you have limited resources, look into using clamdscan first, as this saves tremendous amounts of CPU. If you still need to optimize things further, you may find this recipe useful to cut down on the messages scanned: :0fBHw * ^Content\-(?:Disposition|Transfer-Encoding|Type)\: (?:attachment|base64|multipart) | /usr/local/bin/clamassassin :0fBHw * ^begin [0-9]+ | /usr/local/bin/clamassassin :0: * ^X-Virus-Status: Yes IN.virus Thanks to David for supplying the sample recipe. USING CLAMDSCAN: ClamAV can do virus scanning using a client/server model. This greatly increases the efficiency of scanning messages, as you avoid startup overhead. To use this feature, you must enable clamd to run as a daemon process, then use clamdscan instead of clamscan as your virus scanner. Please see the REQUIREMENTS section for details about which versions of ClamAV support using clamdscan with clamassassin. Here are some other things to check to make sure clamdscan works correctly: 1) Make sure clamd is running 2) Make sure clamd starts on bootup before your mail server does 3) Make sure the ScanMail option is enabled in clamd.conf (or in clamav.conf in older versions of ClamAV) 4) Make sure freshclam.conf is configured to notify the daemon when updates are made. 5) If you use TCP sockets instead of /tmp/clamd as a socket, the automatic configuration may not use clamdscan by default. Try using the --enable-clamdscan flag when running configure. NOTES: Steve Johnson reported a problem where temp files were not deleted on certain debian systems due to some problems with the rm command. Apparently the root cause is a version mismatch between the binutils package and the system shared libraries. Because of limitations in ClamAV, only the first infection found in any message will be reported when using clamdscan. Multiple infections in one message only works properly when using clamscan. This capability also varies depending on the version of ClamAV installed. The virus signature versions are pulled out of the signature files themselves. If you use clamdscan there is a small chance that the versions used by clamd are not the same. Gary Weinfurther reports that his web hoster has restricted the use of /bin/sh, though /bin/bash works. You can manually edit the configure script and the clamassassin script to use /bin/bash instead in this situation. ACKNOWLEDGEMENTS: Since releasing clamassassin, I've received many emails with suggestions. Those that have led to improvements in later versions have been acknowledged where possible in this README or the CHANGELOG file. Thanks also to everyone who wrote in who may not have been mentioned. You all helped make the improvements in this version. PROBLEMS, COMMENTS, ETC: Please send feedback to the author above.