--- Version 3.05 --- Introduction REMEMBER: YOU NEED Sophos library/package in order to use Sophie! Sophie is a daemon which uses 'libsavi' library from Sophos anti virus vendor ( http://www.sophos.com ). On startup, Sophie initializes SAPI (Sophos Anti-Virus Interface), loads virus patterns into memory, opens local UNIX domain socket, and waits for someone to connect and instructs it which path to scan. Since it is loaded in RAM, scanning is very fast. Of course, speed of scanning also depends on SAVI settings and size of the file. Some of Sophie (V3) features: * Configuration file (sophie.cfg) for Sophie options. * Configuration file (sophie.savi) for SAVI options. * Usage of SAVI callbacks. This allows Sophie to have control over the scanning process at all times. It can be used to detect malicious archives (42.zip, for example), check if the remote socket is still connected during the scan, or simply to limit scanning parameters. * Can receive files (to be scanned) over the network. * I am useless when it comes to marketing... help! ;) --- Requirements You must have libsavi installed on your system, and virus patterns. You will also probably need some application that will be able to send request(s) to Sophie, and do something with the result. Sample applications are included with Sophie (sample_apps/ subdir). Sophie V3 has been compiled/tested on: Linux (kernel 2.4.20, RedHat 7.3) with gcc 2.96 and 3.2.2 HP-UX 10.20 Solaris 8/9 (Sparc/x86) FreeBSD (various) Engines/virus patterns tested: engine v2.14 / patterns (IDE) v3.67 --- Installation Version 3 of Sophie has only two configurable options: --with-savilib=[path] --enable-net All the other options are configurable via configuration file. After configure script has finished, type: make --- Configuration Sophie uses 2 configuration files. One if for Sophie itself (sophie.cfg), and another one is for SAVI options (sophie.savi). Sample configuration files can be found in etc/ subdirectory of Sophie distribution. Have a good look at them before you setup Sophie, please. * sophie.cfg Configuration file contains short explanations for most of the options. Some of the options (when modified) will take effect after Sophie has been reloaded (-HUP), while some others will require full Sophie restart. Each option clearly states which action is required in order for changes to take effect. One of the most interesting features (which has to be used with great care) is implementation of callbacks, which allow Sophie to perform action while scan is in progress. Refer to the next chapter in order to get more details on this feature. Sophie does need a configuration file in order to run, and good place to keep configuration file is at /etc/sophie.cfg. Sophie will also check /usr/local/etc/sophie.cfg and ./sophie.cfg for configuration files, before it gives up. If you wish to use configuration file at some other path, use -C command line option. * sophie.savi SAVI options are set in this configuration file. SAVI3 offers 'group options', which allow user to turn on options belonging to a 'group' (executables, compressed files, etc.) with one call. Each individual SAVI option (in configuration file) has a short description, as taken from SAVI SDK. It is critical that admin reads the descriptions and decides which options are needed for his system. Turning on too many options can cause scans to take longer, but not turning enough options can cause viruses to get by. --- Callbacks and remote socket check Sophie can be set to use SAVI callbacks. Basically, during scanning process, function (CISaviNotify_OkToContinue() in sophie_notify.c) gets called continuously, which allows Sophie to perform some action depending on the certain parameters. There are 3 parameters for which limits can be set (sophie.cfg). In CISaviNotify_OkToContinue() 3 variables are declared (as static, so that they get increased for each 'activity'), and each time one of SAVI 'activities' occurs (look below for SOPHOS_ACTVTY_* descriptions) counters get incremented. These are the names from sophie.cfg configuration file, along with SAVI3 SDK descriptions: limit_classif (related to SOPHOS_ACTVTY_CLASSIF) "This activity code indicates that the virus scanner is attempting to match the contents of the file with virus patterns. In this situation, the Extent parameter represents the number of thousands of loops around the central pattern-matching loop." Current default is set to 10, since I am still trying to fully understand what this means :) 10 seems to work just fine for now :) limit_nextfile (related to SOPHOS_ACTVTY_NEXTFILE) "The virus scanner has found another subfile inside an archive-type parent. The Extent parameter represents the number of files encountered in the parent archive. It should be noted that if excessive subfiles are encountered within an archive parent, the only appropriate return value to abort processing is SOPHOS_SAVI_CBCK_STOP." Current default is set to 10000. From what I've seen so far, the counter gets increased for each new file found inside the archive. In other words, if ZIP archive contains 5000 other ZIP archives and each of them contain a file, that'll make counter get to 10000. This is useful for files like 42.zip which creates a loop. Now, if someone sends you a packed backup of their whole filesystem in a mail, Sophie will definitelly abort the scan after 10000 files, and return error. It's up to you to tweak the limits. limit_decompr (related to SOPHOS_ACTVTY_DECOMPR) "The virus scanner is decompressing the contents of a compressed archive. The Extent parameter represents the number of kilobytes decompressed from the current compressed stream." This can also be useful to prevent loops, like what happens in 42.zip file. You can uncomment a printf() in CISaviNotify_OkToContinue() and recompile Sophie - it will display the values of each variable, for each run, so you can get a better picture of what's going on. Another feature (or bug, we'll see how it works for others :) is that each time CISaviNotify_OkToContinue(), there is a piece of code which performs a VERY DODGY check to see if the remote socket (client) is still connected. Problem is that there is no 100% reliable way to find this out, except trying to actually write to a remote sock and check the responses. However, after playing a bit with select(), I found that one can try to read() from a socket (for which select() claims can be read), and see if the response is 0. During my testing, in 100% of cases it worked, and select() returned 'can read' at the moment socket got disconnected. I have no idea on how many platforms this can/will work. To test it, compile scan_file (from sample_apps/sock), ask Sophie to scan some tarball and interrupt scan_file as after second or two (or wait as long as you wish and try to interrupt it). What you should see is: (sophie output...) WARNING : write() to remote end of the socket failed! [Broken pipe] NOTICE : write() failed because: Remote socket disconnected. --- Problems/Bugs You might get a message like this on startup: ld.so.1: ./sophie: fatal: libsavi.so.2: open failed: No such file or directory Make sure libsavi.so is in LD_LIBRARY_PATH. Additionaly, it seems that you might need to create a symbolic link for libsavi.so in order to make configure script work ok - some people have reported problems with configure script not recognizing the library, even if it was in /usr/lib. To fix this, go to the directory where libsavi library is, and type: # ln -s libsavi.so.3 libsavi.so (re-run ldconfig, if needed) --- Usage To get brief help, use: ./sophie -h To specify path to the configuration file use -C switch: ./sophie -C /etc/sophie.cfg To see version of SAVI engine and patterns, use: ./sophie -v To see current SAVI configuration, use: ./sophie -c To check Sophie and scan a *file* (not a directory) on a local hard disk, use: ./sophie -f To check Sophie and scan a *directory* on a local hard disk, use: ./sophie -s To send Sophie into background, use: ./sophie -D Sophie will reload patterns/configuration if it receives HUP signal. eicar.com test file is also available, to make testing easier. NOTE: eicar.com is created during compilation proces (from Makefile) --- Sample applications You can find some sample applications (C and Perl) in 'sample_apps' directory. --- Availability Releases of Sophie are (should be) available at: http://www.vanja.com/tools/ --- Author Comments/patches send to: vanja@pobox.com --- License This program is released under the GPL license