clamassassin 1.2.4

Author: James Lick <james.lick@gmail.com>
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-2007, James Lick
All rights reserved.

See LICENSE file for information on your legal rights to use 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, but is more often due to a ClamAV
misconfiguration.

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.

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 that 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/ Version 0.90 or higher is required.
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.

Starting with clamassassin 1.2.4, the minimum required ClamAV version is
0.90.  In the past clamassassin tried to accommodate older versions of
ClamAV.  However, it is not possible to adequately protect your system when
running old versions of ClamAV, and removing support for obsolete versions
greatly simplifies the clamassassin code.

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.90 or higher is the
recommended version of ClamAV.  Check the clamassassin website for details
on any compatibility problems with versions newer than this.

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.  Currently
clamassassin requires ClamAV 0.90 or higher.  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
not to add the signature version itself.  If for some reason the default is
incorrect, you can use the following configuration options:

  --enable-signature-version
        Turns on signature version reporting
  --disable-signature-version
        Turns off signature version reporting (default)

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 by default.  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)
  --disable-name-adding
        Turns off adding of scanner name

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.  Here are some
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.  Reporting of multiple
infections in one message only works properly when using clamscan.  This
capability also varies depending on the version of ClamAV installed.

In some cases, 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.