--- 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 <path_to_infected_or_some_other_file>
    
    To check Sophie and scan a *directory* on a local hard disk, use:

    ./sophie -s <path_to_directory_you_wish_to_scan>

    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
