Read Me

SoftlabsAV
Simple and efficient virus protection at the incoming mail server. 

	http://softlabsav.softlabs.net/

                                 Manual
                                 ======

Version 0.9.5
Release date: 2009-05-26

________
Contents

 1. About this software

 2. How it works

 3. Virus types

 4. Requirements

 5. Installation

   1. Place the SoftlabsAV files into its installation directory
   2. Modify or add procmail's main run commands file
   3. Plug SoftlabsAV into procmail

 6. Logging of found viruses

 7. The 'clamscan.cron' cronjob shell script

 8. License

 9. Credits

10. History of version changes (ChangeLog)

11. Feedback

______________________
1. About this software

 SoftlabsAV is a generic anti-virus filter for incoming mail servers on 
 Unix. It is driven by the widely used "procmail" Mail Delivery Agent (MDA). 
 In addition, it plugs to the ClamAV anti-virus scanner (clamscan) and 
 scans for viruses, phishings and possible phishings. 

 SoftlabsAV has been designed with security, efficiency and simplicity in 
 mind. It is free and open source. 

_______________
2. How it works

 A set of procmail recipes isolates mails with an attached potential virus 
 into a quarantine directory. Directly infectious attachments as well as 
 packed viruses (UU encoded or inside a Zip or Rar archive, including 
 encrypted ones) will all be detected. Both "Base64" and "Quoted-Printable" 
 Transfer-Encodings are supported. Encoded file names are also supported. 

 Suspicious attachments will be classified and extracted into directories 
 representing its virus type. ClamAV's clamscan will then scan the 
 attachment to prove if it is in fact a virus. In addition, potential 
 malicious mails that do not necessarily have an attachment (such as HTML 
 mails) will also be scanned (as raw mbox file). Per default, ClamAV will 
 scan each entire mail as mbox file if it could not identify a virus within 
 an attachment or if no potential malicious content has been unveiled. 

 Once ClamAV has been proven a mail to be infected, the mail will be 
 removed, along with its extracted attachment (if it contained one). That 
 behaviour can be changed through a configuration file if preferred. 

 The name of each found virus will be logged, beside other useful data. 
 Results will be written into a handy viruses log file, within the mail's 
 header (by adding a 'X-Virus-Filter' header field) and into procmail's log 
 file. 

______________
3. Virus types

 7 virus main types are distinguished: 
 EXE, UUE, ZIP, EZIP, RAR, ERAR and MBOX types. 

 + EXE types: Directly attached infectious files (mainly Executables, but may 
     also include non-executable malicious files such as JPEG images)

 + UUE types: Infectious files packed inside UU encoded attachments

 + ZIP types: Infectious files inside attached Zip archives 

 + EZIP types: Infectious files inside encrypted (password protected) Zip 
     archives

 + RAR types: Infectious files inside attached Rar archives 

 + ERAR types: Infectious files inside encrypted (password protected) Rar 
     archives

 + MBOX types: Mails that have been scanned by ClamAV as entire mbox file. 
     Include phishings and possible phishings. 

 A potential infectious EXE type file will be detected if it has a "bad 
 extension" (checked case-insensitively). Currently, there are the following 
 bad extensions set per default: bat, chm, cmd, com, cpl, exe, hta, pif, scr, 
 vbe, vbs and jpg (including jpeg). If necessary, the list of bad extensions 
 can be extended easily in the configuration file. 

 The main virus types are divided into sub-types, each representing either 
 one of those bad extensions or being a special case: 
 
 If an extracted ZIP or RAR archive cannot be opened by its unpacker program, 
 it is considered as broken and represents the virus type "ZIP.Broken" or 
 "RAR.Broken", respectively. Similar, if an extracted potential UU encoded 
 attachment has been found not to be valid UU encoded, it represents the 
 virus type "UUE.Broken". 

 MBOX types include HTML mails (representing the "MBOX.Html" virus type) 
 and - unless turned off in the configuration file - Non-HTML mails 
 (representing the "MBOX.SCAN_ALL" virus type). 

 Thus, there are possible virus types of 
 EXE.bat, EXE.chm, ..., EXE.exe, ..., EXE.jpg, UUE.bat, ..., UUE.Broken, 
 ZIP.bat, ..., ZIP.Broken, ..., MBOX.Html, MBOX.SCAN_ALL and so on. 

 Per default, each quarantined mailbox folder is a separate file in mbox 
 format. The file's named follows the scheme 'ID_TYPE.EXT.virus'. ID is 
 the mail's ID (for details see section 6 below), TYPE is one of the 7 main 
 virus types mentioned above and EXT is the extension corresponding to the
 sub-type mentioned above. An example for a possible file name is 
 "20070901-183928.525212_EXE.bat.virus". 

 If the quarantined mailbox folders have been configured to be in maildir 
 format, they are directories following the scheme '.ID_TYPE_EXT_virus', 
 where the dot within the ID has been replaced by an underline. 

_______________
4. Requirements

 SoftlabsAV will run on all Unix like operating systems, such as GNU/Linux, 
 Mac OS X, FreeBSD, Solaris. In this description examples may be given 
 especially for Red Hat (RH) / Fedora based Linux systems, such as 
 RH Enterprise Linux 5 (RHEL5) or CentOS 5, referred here as 
 "Red Hat Linux based" platforms. 

 The following programs must be available:

 + procmail and formail

   The 'procmail' version must be at least 3.20, however, the latest 
   version (3.22) is recommended. It has been released back in 2001, 
   so there should really be no reason to still use an even older 
   version. The version number will be returned by executing 

	procmail LOG='"$PROCMAIL_VERSION"' /dev/null < /dev/null; echo

   and should be "3.22" in the best case. If you try to run SoftlabsAV 
   with an older procmail version than 3.20, it will not do anything 
   except delivering all mails unfiltered and quitting. However, the 
   reason of quitting will be written into the log file. 

   'formail' is part of the "procmail" package, so it should be available 
   as well. Executing 

	formail -v 2>&1 | sed q

   should return "formail v3.22 2001/09/10" 
   if you have the latest procmail package installed. 

 + ClamAV

   The 'clamscan' component of ClamAV (Clam AntiVirus) in version 0.95 or higher 
   is required. On RHEL5 with the "rpmforge-release" package installed (see above), 
   you can install the "clamav" package using 

	yum --enablerepo rpmforge install clamav

   Executing 

	clamscan --stdout -V | sed -e 's/.*\/ //' -e 's/\/.*//'

   should return something like "ClamAV 0.95.1" (when using the latest version, 
   as of release time of SoftlabsAV 0.9.5). 

   For other Unix systems, visit ClamAV's website at 

	http://www.clamav.net/

   The 'freshclam' component should be configured to check for new virus 
   signature databases hourly (24 checks per day). 

   NOTE: If there is no supported 'clamscan' version available on your system, 
   all mails will be delivered, including possible infected ones! The warning 
   "[ClamAV ERROR!]" will be prepended to each mail's subject and a message 
   will be added to the "X-Virus-Filter" header. In addition, error messages 
   will be written into both the procmail log file and SoftlabsAV's own viruses 
   log file. 

   If you cannot yet run ClamAV 0.95 or higher, you could use SoftlabsAV 0.9.3 
   instead, which supports the ClamAV versions 0.91 up to 0.94.2. 

 + mimencode

   'mimencode' originally was part of the "metamail" package, which is no 
   more available for many current operating systems. However, the 
   "xemacs" (or "xemacs-common") package, which is actively maintained and 
   available for many operating systems, contains mimencode as a binary called 
   'mmencode'. The installation of the "xemacs" package on a current Fedora 
   system should work using 

	yum install xemacs

   or on RHEL5 with Scott A. Hughes' "sahughes" repo configured using 

	yum --enablerepo sahughes install xemacs

   In recent Red Hat Linux based systems, the 'mmencode' binary is part of the 
   "xemacs-common" package: 

	rpm -ql xemacs-common | grep mmencode

   Symlink the resulting file to 'mimencode' into a directory available via 
   PATH: 

	ln -s /usr/lib/xemacs-21.5-b27/i686-redhat-linux/mmencode /usr/bin/mimencode

   As a simple test, executing 

	echo OK | mimencode | mimencode -u

   should return "OK". 

 + UnZip

   The 'unzip' program is required to support Zip archives. Executing 

	unzip -Z | sed -e '1!d' -e 's/ o.*//'

   should return "ZipInfo 2.42" if you have the latest UnZip version 
   (5.52 as of release time of SoftlabsAV 0.9.5) installed. 

   The "unzip" package is usually pre-installed on most Unix systems. More 
   information may be available on that project's homepage at 

	http://www.info-zip.org/UnZip.html

   NOTE: If 'unzip' does not exist on your system (or its execution fails), 
   all mails with an attached Zip archive will not be fully processed by 
   SoftlabsAV! In that case, the warning "[Possible VIRUS!]" will be 
   prepended to the mail's subject and the "X-Virus-Filter" header will include 
	"WARNING: Executing of 'unzip' failed - Attached ZIP archive may contain a virus!". 
   The attachment will be considerd as a "ZIP.Broken" virus type and could still 
   be detected by ClamAV. 

 + UnRar

   The 'unrar' program is required to support Rar archives. On RHEL5 with the 
   "rpmforge-release" package installed (see http://dag.wieers.com/rpm/FAQ.php), 
   you can install the "unrar" package using 

	yum --enablerepo rpmforge install unrar

   Executing 

	unrar | sed -e '2!d' -e 's/ f.*//'

   should return something like "UNRAR 3.80 beta 2" if you have a current 
   "unrar" package installed. 

   A list of some available Unix ports may be available at 

	http://www.rarlab.com/rar_add.htm

   NOTE: If 'unrar' does not exist on your system (or its execution fails), 
   all mails with an attached Rar archive will not be fully processed by 
   SoftlabsAV! In that case, the warning "[Possible VIRUS!]" will be 
   prepended to the mail's subject and the "X-Virus-Filter" header will include 
	"WARNING: Executing of 'unrar' failed - Attached RAR archive may contain a virus!". 
   The attachment will be considerd as a "RAR.Broken" virus type and could still 
   be detected by ClamAV. 

 + sed, date, test, file, ls, mkdir, mv, rm, id

   These utilities are part of every Unix system. If they are not available 
   on your system, you probably are on the wrong platform.

_______________
5. Installation

 Although installing SoftlabsAV is very easy, it is intended to be done only by 
 experienced Unix SysAdmins because the person who does the installation must 
 login as root. 

 First ensure that all requirements are satisfied (see chapter 4 above). The 
 installation is basically a three-step procedure: 

 5.1 Place the SoftlabsAV files into its installation directory
 --------------------------------------------------------------

 First, unpack the distributed BZip2 compressed Tar archive by executing 

	tar -xjf SoftlabsAV-<VERSION>.tar.bz2

 directly on the target Unix system. '<VERSION>' has to be replaced by the 
 package's real version number. 

 It is recommended to use the same file and directory structure as given 
 here. 

 SoftlabsAV's installation directory resides within the '/etc/procmailrcs' 
 directory. So check if that directory exists on your target system and 
 create it if it doesn't. Then copy the entire 'SoftlabsAV' directory found 
 in this package into the server machine's '/etc/procmailrcs' directory, 
 recursively. The files' permissions should be fine as they are within the 
 distributed archive: 0644 for files and 0755 for directories. 

 Finally, you should have the following file structure on the server machine:

 + etc                   (the server's '/etc' directory)
   |
   + procmailrcs
     |
     + SoftlabsAV        SoftlabsAV installation directory
       |
       + inc             SoftlabsAV include files' ('av_*.inc') directory
       | | 
       | | av__ver.inc
       | | 
       | | av_b64.inc
       | | 
       | | av_bq.inc
       | | 
       | | av_bq-multi.inc
       | |
       | | av_broken.inc
       | | 
       | | av_cat.inc
       | | 
       | | av_clamcheck.inc
       | | 
       | | av_clamscan.inc
       | | 
       | | av_const.inc
       | | 
       | | av_decode.inc
       | | 
       | | av_exe.inc
       | | 
       | | av_ext.inc
       | | 
       | | av_formail.inc
       | | 
       | | av_html.inc
       | | 
       | | av_lc.inc
       | | 
       | | av_log.inc
       | | 
       | | av_length.inc
       | | 
       | | av_match.inc
       | | 
       | | av_mbox.inc
       | | 
       | | av_mid.inc
       | | 
       | | av_mkdir.inc
       | | 
       | | av_print.inc
       | | 
       | | av_qpr.inc
       | | 
       | | av_rar.inc
       | | 
       | | av_rm.inc
       | | 
       | | av_snr.inc
       | |
       | | av_split.inc
       | |
       | | av_uue.inc
       | |
       | | av_v320.inc
       | |
       | | av_zip.inc
       |
       | antivirus.conf  SoftlabsAV configuration file
       |                 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
       | antivirus.rc    SoftlabsAV main Run Commands file

 None of these files except the configuration file should be modified!!! 
 If you want to transfer some of these files directly (unpacked) from or to 
 another computer, only do so using FTP's binary mode, to ensure keeping 
 their Unix-style line endings. 

 Take a look inside the configuration file, to see if you want to modify 
 some settings. 

 5.2 Modify or add procmail's main run commands file
 ---------------------------------------------------

 The SoftlabsAV main Run Commands file 
 ('/etc/procmailrcs/SoftlabsAV/antivirus.rc') 
 is intended to be called by the main (global) procmail Run Commands file, 
 '/etc/procmailrc'. This package also ships this file. If there does not yet 
 reside one on your server machine, use the shipped one; otherwise, be sure 
 to copy the marked essential parts of the shipped etc/procmailrc file into 
 your own one! 

 The shipped procmailrc file is divided into three sections:

   1. Built-in Environment variables
   2. Definitions of used constants. Do not change!
   3. SoftlabsAV specific section

 The interface between procmailrc and Softlabs AntiVirus is the last setting 
 in section 3 of the procmailrc file: 

   INCLUDERC = '/etc/procmailrcs/SoftlabsAV/antivirus.rc'

 which is commented out per default. Leave it commented out until you have 
 tested the antivirus filter for a while to work fine for you, as explained 
 below. 

 5.3 Plug SoftlabsAV into procmail
 ---------------------------------

 After you have finished the two installation steps above, test if it has 
 been successful. For this purpose, first plug SoftlabsAV into procmail 
 *only for you as user* and check procmail's verbose log for a while. 
 To do so, be sure that a user specific procmail run commands file 
 exists in the home directory for you as a normal user (*not* as root). 
 That file's location must be '~/.procmailrc'. Add the follwing entries
 into it:

   VERBOSE = 'on'
   INCLUDERC = '/etc/procmailrcs/SoftlabsAV/antivirus.rc'

 After some EXE and ZIP viruses have been sent to your account, check your 
 procmail log file and the viruses log file (see below) for any errors. If 
 you find one, try to fix it, of course. You may come across an error due to 
 unsufficient file permissions, for example. Also, you should (almost) never 
 see a log entry like 

   Executing "test -r /var/spool/mail/adam_TRASH/viruses/EXE/file.exe"

 that contains spaces within the string after 'Executing '. There should 
 be commas instead of that spaces, like this: 

   Executing "/usr/bin/test,-r,/var/spool/mail/adam_TRASH/viruses/EXE/file.exe"

 SoftlabsAV has been developed with much care to avoid any possible 
 overhead *and* being robust and secure. 

 You should also have observed that a "viruses" directory has been created 
 under the av_TRASHDIR, containing at least one sub directory. 

 Finally, after everything went fine for a while (it is recommended to test 
 it for at least one day), go ahead and enable Softlabs AntiVirus for all users 
 (except for those defined in av_DISABLE_USERS of the configuration file). 
 To do so, uncomment the INCLUDERC line of the main procmailrc file, as mentioned 
 in chapter 5.2 above. 

___________________________
6. Logging of found viruses

 When a mail has been considered to contain a VIRUS, PHISHING or 
 Possible PHISHING, or when the clamscan virus scanner exited with 
 an error, information about the scanned file will be logged 
 into a viruses log file. Its location can be specified by the 
 'av_VIRUSES_LOGFILE' configuration setting - the default file name is 
 "viruses.log". This log file is designed to be both clearly human 
 readable and easily machine readable. Each line consists of 8 TAB 
 separated fields (columns). These fields are: 

 (1) The mail's ID. This is an unique number created by SoftlabsAV, that 
     will be increased for each processed mail. It always begins with the 
     mail's processing date and time with an accurancy of to the second, in 
     the format "YYYYMMDD-hhmmss". Then, it is followd by a dot and either 
     6-digits microseconds (if supported by the OS), or 5-digits Process-ID. 

 (2) The user the mail should have been sent to. Depending on the 
     av_LOG_USER configuration setting, this can either be the user's name
     or its numerical user ID, or left empty. 

 (3) Virus type (one of the those classified in chapter 3 above). 
     For easier reading by humans, this filed is aligned to always place 
     the dot at the same position. 

 (4) Result of the clamscan virus scanner, including the virus name (if one 
     was found). In addition, the version of ClamAV and its daily virus 
     database is given.
     Examples: 
       VIRUS FOUND: PUA.Scanner.Angryscan (ClamAV 0.95.1/9350)
       PHISHING FOUND: Phishing.Heuristics.Email.SpoofedDomain (both scan methods) (ClamAV 0.95.1/9350)
       Possible PHISHING FOUND: Phishing.Heuristics.Email.SpoofedDomain (ClamAV 0.95.1/9350)

 (5) The file size of the attachment or the MBOX file, respectively (in bytes). 
     This filed is also right aligned and thus may be prefixed by (1 to 3) 
     space characters. 

 (6) The original attachment's file name, enclosed within double quotes 
     (since the file name may contain several spaces). In case of a 
     MBOX type, "(no attachment)" will be printed.

 (7) The file type description of the attachment or the MBOX file, 
     respectively (may contain several words). 

 (8) The MIME type of the mail's part containg the potential infected 
     attachment. In case of a MBOX type, the entire mail's MIME type 
     will be printed.

 Here are some examples of lines found in a viruses log file 
 (resorted by detected virus type): 

 EXE virus types:
 ---------------
20080417-165704.039273	504	 EXE.exe	VIRUS FOUND: Trojan.Downloader-31055 (ClamAV 0.91.2/6813)	  11776	"photo.exe"	MS Windows PE 32-bit Intel 80386 GUI executable not relocatable	application/octet-stream

 UUE virus types:
 ---------------
20060224-105944.794936	500	 UUE.scr	VIRUS FOUND: Worm.VB-9 (ClamAV 0.88/1301)	 134053	"Video_part.mim"	uuencoded or xxencoded text	application/x-msdownload

 ZIP virus types:
 ---------------
20080510-142216.763827	502	 ZIP.scr	VIRUS FOUND: Trojan.Dropper-6823 (ClamAV 0.91.2/7083)	  38162	"ssaver.zip"	Zip archive data	application/zip

 EZIP virus types:
 ----------------
20081008-001116.955372	500	EZIP.exe	VIRUS FOUND: Trojan.Downloader-zippwd-5 (ClamAV 0.94/8393)	  76313	"bill9.zip"	Zip archive data	application/zip

 RAR virus types:
 ---------------
20080623-192404.661805	500	 RAR.exe	VIRUS FOUND: PUA.Packed.NPack-2 (ClamAV 0.91.2/7545)	  66243	"Rechnung.rar"	RAR archive data	application/rar

 ERAR virus types:
 ----------------
20051202-044115.549329	500	ERAR.chm	VIRUS FOUND: Trojan.Spy.Goldun.A-rarpwd (ClamAV 0.87.1/1200)	  19723	"clients.rar"	RAR archive data	APPLICATION/OCTET-STREAM

 MBOX virus types:
 ----------------
20090525-182216.960009	507	MBOX.Html	PHISHING FOUND: Phishing.Heuristics.Email.SpoofedDomain (both scan methods) (ClamAV 0.95.1/9390)	   8308	"(no attachment)"	ASCII mail text	text/html
20080906-003904.184343	504	MBOX.Html	Possible PHISHING FOUND: Phishing.Heuristics.Email.HexURL (ClamAV 0.91.2/8170)	   6000	"(no attachment)"	ASCII mail text	text/html
20080713-210924.969030	504	MBOX.SCAN_ALL	VIRUS FOUND: Email.PornTeaser (ClamAV 0.91.2/7705)	  60080	"(no attachment)"	ASCII mail text	(Non-HTML)
20080805-052613.971207	504	MBOX.SCAN_ALL	VIRUS FOUND: Email.Phishing.DblDom-92 (ClamAV 0.91.2/7941)	   2099	"(no attachment)"	ASCII mail text	(Non-HTML)

 In addition, an entry will be written into procmail's log file, containing 
 the virus main type (as described in chapter 3 above), the MIME type, 
 the attached file name (in archived attachments, along with the 
 file name inside the archive) and ClamAV's result. 

___________________________________________
7. The 'clamscan.cron' cronjob shell script

 This package also includes a 'sh' shell script that scans the entire file 
 system for viruses with ClamAV's clamscan. It is intended to be run 
 automatically once a day, as a cronjob. Per default, the result will be 
 emailed to the system's root once the scan has finished. It does the same 
 version check on clamscan as SoftlabsAV itself, ensuring to have the 
 required minimum version installed and calling clamscan with the 
 appropriate options, depending on its version. 

 Copy the 'clamscan.cron' file found in the 'etc/cron.daily' directory of 
 this package into the server machine's '/etc/cron.daily' directory and 
 test-run it. You may want to look into it and edit some settings within 
 its configuration section. 

 You can also use this script without having the SoftlabsAV procmail 
 filter installed, for an automatic daily full scan. In that case, uncomment 
 the configuration line 

   SCANDIR_FIRST=''

__________
8. License

 Copyright (C) 2004-2009 Robert Allerstorfer

    This program is free software: you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program.  If not, see <http://www.gnu.org/licenses/>.

 A copy of the GNU General Public License (GPL), version 3 (29 June 2007) 
 in plain text format is included in this package as "gpl-3.0.txt" 
 (taken from http://www.gnu.org/licenses/gpl-3.0.txt). The GPL should also 
 be available online at

	http://www.gnu.org/licenses/gpl.html

__________
9. Credits

 Thanks go out to (in alphabetical order):

 + Tomasz Kojm for his great ClamAV open source anti-virus scanner 
   (http://www.clamav.net/)

 + James Lick - the author of "clamassassin" (http://drivel.com/clamassassin/) 

 + Nancy McGough for her "Procmail Quick Start" tutorial, available at 
	http://www.ii.com/internet/robots/procmail/qs/
   which was the place where I got my feet wet in starting with procmail 

 + Ruud H.G. van Tol for his continued useful suggestions and his fabulous 
   "just procmail" collection, published at 
	http://www.xs4all.nl/~rvtol/procmail/

 + everybody who gave constructive feedback to the project 

_________________________________________
10. History of version changes (ChangeLog)

 Please refer to the file "history.txt".

____________
11. Feedback

 If you have constructive suggestions or found a bug, join the open-source
 community and share your opinions. Your contribution may propably become 
 part of this project. Please feel free to post feedback of any flavour into 
 the project's open discussion forum at 

	http://sourceforge.net/forum/forum.php?forum_id=360141

 You can find this link, along with all other useful informations regarding 
 SoftlabsAV, at the official project homepage 

	http://softlabsav.sourceforge.net/