Installing avfilter

The avfilter code is not packaged. The installation is cumbersome and oriented toward the code logic rather easing installation. Instructions are as terse as possible at the beginning, postponng discussion to the later sections in this page.

Get the software, unpack and install some

Make a new directory and download both the Sophos anti-virus and SAVI development kit. Install the anti-virus.

1. Click HERE for Sophos Unix download page,
2. find the right piece of software, request a password for evaluation,
3. download some xxx.tar.Z file,
4. unpack it, e. g. with zcat xxx.tar.Z | tar xvf - it will unpack in a new subdirectory sav-install,
5. Install the anti-virus. You may want to look at the options by
   sav-install/install.sh -h
   unless you need the InterCheck daemon, use option -ni, e. g.
   sav-install/install.sh -v -ni -nidc
   that will install the sweep utility and libsavi.so.2. Chances are the shared object is not installed in the right directory and the easiest solution may be to make a symbolic link to it, e. g.
   libname=`ls -l /usr/local/lib/libsavi.so.2 | awk '{print $11;}'`
ln -n -s /usr/local/lib/$libname /lib/libsavi.so.2
6. Click HERE for Sophos SAVI Developer ToolKit download page and download the savidtk.tar.Z,
7. Unpacking it yields the new subdirectories cprog, docs, and sav_if
8. Downlad avfilter.tar.gz from this server.
9. Make a new subdirectory and unpack, e. g.,
   mkdir avfilter
cd avfilter
gtar -xvzf ../avfilter.tar.gz

Compile the software, and test some

You may want to make sure you can run sweep correctly. If you have some virus samples, keep them at hands; in the following we assume they are in subdirectoy test. Next, you should get the same results with savidemo.

1. sweep ../test/virussample
2. compile savidemo; if your compiler doesn't like the -R option or if you placed a symbolic link from the default directory to the Sophos shared object, you may need/want to change CFLAGS from Sophos' makefile, e. g.
   cd ../cprog
vi makefile
make
3. ./savidemo ../test/virussample

Now recap the directories you used to install Courier. There is a main source directory usually named something like courier-0.vv.m. The base directory for installing filters was specified when configuring Courier with the --libexecdir option, and the one for configuring filters was specified with the --sysconfdir option; you should have a filters subdirectory inside both of these two. So you may find them like

4. find / -type d -name filters -print
   (this way you'll also get filters subdirectory that live in the source tree and in the --localstatedir (var) tree)
5. cd ../avfilter
6. cp linux-makefile makefile
7. vi makefile
8. in vi, locate COURIERSRC and substitute the path to your source tree,
9. locate COURIERINS and substitute the path to the libexec base dir,
10. locate the chown command and substitute courier's userid and groupid,
11. you may need/want to review the xCFLAGS settings before saving makefile.

The makefile builds tavfilter and a couple of other tst* test utilities. Non-debug objects have a -nd suffix. DCFLAGS are for debug versions and OCFLAGS are for optimized versions. You want to make sure the filter runs perfectly clean before enabling it, so that stuff may be handy. To build the debug stuff run

12. make

You'll get a number of warnings about unused parameters and defined but not used functions, don't panic, it's ok. However, if you get different warnings or errors, most probably there's some porting to be done. If you are not into programming, it may be better to give up at this step. If you have better ideas, please feel free to write me about them or just do how you feel is cool.

Test the software, and adjust run-time configuration

You need a virus sample wrapped as an e-mail attachment in order to test avfilter. If you don't have one, you can build one by acting as in the following session with the tstmime utility.

./tstmime
1> wrap
wrap
0 from mime_wrap [1/1 time(s) in 0ms]
2> s downr
s downr
1 from mime_seek [1/1 time(s) in 0ms]
3> attach ../test/virussample
attach ../test/virussample
0 from mime_attach_binary [1/1 time(s) in 0ms]
4> hcont application/x-virussample
hcont application/x-virussample
0 from mime_set_content_type [1/1 time(s) in 0ms]
5> s top
s top
0 from mime_seek [1/1 time(s) in 0ms]
6> encode base64
encode base64
mime_ok_7bit from mime_commit_encoding [1/1 time(s) in 0ms]
7> write ../test/mailvirussample 1 0
write ../test/mailvirussample 1 0
0 from mime_write [1/1 time(s) in 20ms]
8> +
+
00: _3_ 0 multipart/mixed ("multipart/mixed") enc=7bit <=====CUR
    last node multipart
    ---3r5ESDA---(part_1)---A
    01: _1_ 1 application/octetstream ("application/x-virussample") enc=base64 act=binary fpw:
handle 5
        last alt
        offset=0 length=145906
8> x
x

Using that, you can run tavfilter to check it gets the virus. CAUTION: make sure you use the -t switch as a first argument in tavfilter, otherwise it will think it is being loaded by Courier.

./tavfilter -t ../test/mailvirussample

The test version is more verbose and obtains file names from the command line, but it then forks just like the regular version. If you want to use gdb on it you should set the DEBUG_AVFILTER environment variable and then attach gdb to a running process when prompted.

Find a line in tavfilter output that says "cannot read /some-path/filters/avfilter.conf." That's the filter configuration directory and there's a couple of files you should place there:

1. avfilter-mode should contain just the word all, as mentioned in Courier documentation about dupfilter-mode and perlfilter-mode, e. g.,
   echo all > /some-path/filters/avfilter-mode
2. avfilter.conf should contain run-time directives, e. g.
   cp avfilter.conf /some-path/filters/avfilter.conf
3. Set proper ownership and permissions, e. g.
   chown courier:courier /some-path/filters/avfilter*
chmod u=rw,go= /some-path/filters/avfilter*

There are three kind of things inside avfilter.conf that you may change to suit your needs (please find syntax as comment in the file):

• Verbosity and directory options. The directories used are for creating temporary files (attachments extracted from mail and passed to the scan engine), for saving missed files (response was 4xx) and virus files (5xx).
• Scan error response. Unexpected return codes from Sophos are printed in the logs by a running avfilter or on terminal by tavfilter -t , in the example only the two cases I actually encountered are listed. That way you override the generic cannot scan content error message that is returned to the SMTP client otherwise. It is also possible to configure avfilter to accept attachments that result in a given scan_error by omitting the message text
• Sophos features listed in the SAVI documentation and/or mentioned by savidemo. These are set when initialising the interface, e. g. at load time.

Please run tests until you are completely satisfied.

Install the filter, and upgrade the database

You have to reinstall the filter whenever the SAVI interface changes. If you buy a Sophos licence, they are going to send you a new CD every month and an e-mail message every time they discover a new virus. A new CD doesn't necessarily mean anything is changed for the include files in ../sav_if and/or in the shared object, but you should check.

1. make release to compile and link avfilter
2. courierfilter stop if you are already running it; if you are running some other filter that you don't want to stop, use filterctl stop avfilter instead. Please refer to Courier documentation.
3. make install to copy the executable code where it belongs, and
4. courierfilter start to restart filtering. You should use filterctl start avfilter on the first time or if you used filterctl in step 2.

Most of times the interface didn't change but you get a new virus database or a new set of ide's. People at Sophos release a new ide for each new virus they find. Sometime they upgrade an ide without changing its name, hence ides may become obsolete. Please refer to documentation at Sophos's.

On a monthly schedule, Sophos compiles all ide's into a vdl-x.nn.dat that is symbolically linked from vdl.dat. When you install the new database, it will also adjust the link, but you have to manually delete old ide's and replace them with the new ones. To cope with this activity I made a downloads directory under the Sophos directory and placed a couple of shell scripts in it: check_ide.sh and wgs.sh. They are unpacked in the avfilter subdirectory, but you should move and edit them appropriately. They both use wget.

Use check_ide.sh, without parameters, whenever you want to check the list of ide's you've got. Use ./wgs.sh filename.ide ... for unconditionally downloading ide file(s) from Sophos. Then move any ide you have retrieved to the parent directory where they belong, make them world readable and re-load avfilter using steps 2 and 4 above. Check how the number of viruses increases in avfilter logs and/or running sweep.

Problems and ToDo's

Restarting avfilter

Using courierfilter stop/courierfilter start on every upgrade is not elegant. There is some code to catch a HUP signal, but currently it doesn't cause SAVI to reload the virus database.

MIME parser

The mime parser that comes with avfilter is not completely RFC-compliant. Users must watch out for possible MIME parsing errors and the parser be amended when it is the case. (That's why there is an option to save viruses/missed.) Currently there are two cases that don't work:

1. Missing close boundary. Badtrans-b virii most of times miss the last two dashes, so the message is blocked but not properly recognized.

2. message/partial. This MIME type is currently not recognized at all. If it were recognize I still wouldn't know how to deal with it, since it could contain a part of a virus not recognizable until joined with the other part(s) of the message.

Having a MIME parser that is not integrated with the engine is not perfectly safe. A MIME entity is a kind of file archive. Hence, one may send viruses wrapped in a MIME file wrapped in a zip archive attached to an e-mail message. However, MIME is not considered a popular file archiver that a scanner should dive in, see, e. g. condition (P) of Test Conformance Text at Hamburg's University's Virus Test Center.

What to do when a virus is found

Some users may prefer to receive viruses rather than lose e-mail. This should be handled through local filter vs. global filter interactions but I haven't figured it out yet. Also, it would be nice to modify the mail file in order to make clear that a virus was found, to disinfect Word Macro Viruses, etcetera.

Currently, the safest thing to do is to stop any virus or scan error. However, this implies it is not possible to send corrupted MSWord .docs, corrupted .zips nor even multivolume archives: since one cannot scan them they may contain viruses.

What about SysV-style signals?

I'm duplicating that bit of code because modifying it is of no interest for Courier. (I submitted a proposal for reusing the lf_accept Courier library function on Jan 2002.)

Virus for the Mac

Even if Sophos has a Mac version of SAVI and MacVirus databases, one cannot enable scanning for the Mac. Sophos support wrote on 4 November 2001:

At present the Unix versions of SAV do not support scanning for Mac viruses. This is basically because there is no consistent way across the various flavours of Unix to represent the two separate forks of a Mac file on an essentially single-streamed file system. There are a number of different software products that provide file services to Mac clients and they each use their own way to handle this.

We are looking into a way to enable this support for Mac files that arrive through a gateway in BinHex (HQX) format and so this option may well be enabled in Unix versions soon.

The option should be set in avfilter.conf when it will work.

Have fun!