avcheck(1)

NAME
avcheck - antivirus daemon client for mail system

SYNOPSYS
avcheck options -- recipient...

DESCRIPTION
avcheck reads a mail message from standard input, saves it to a temporary file, and then asks the running antivirus daemon to check this file for viruses. If no viruses are found, avcheck optionally reinjects message back into mail system for further delivery. If the antivirus software claims that message contains some virus-infected file or such, avcheck will call another program to handle this message and take appropriate actions. In case of any error (except of incorrect usage/options), avcheck will exit with EX_TEMPFAIL exit code, so that further "delivery" attempt will be attempted again later, thus allowing to correct that error. Typically, avcheck is used as a part of mail subsystem to scan mail messages before further delivery. The "idea" behind this simple program is as follows: Mail messages are received by a mail system, queued, and then passed to avcheck for inspection. If a message passes the antivirus check, then it will be routed using normal MTA mechanisms, either by reinjecting (requeuing) back into that same mail subsystem (or other a subsystem on another host etc), or by continuing without reinjecting. Or, if the antivirus software detects a virus, control will be passed to an administrator-defined handler that will send virus-alert messages to administrator, sender or recipients, places the message into quarantine folder for further examination etc. Note that avcheck is not a virusscanner, but antivirus client: it can't work without a supported antivirus daemon. The antivirus daemon should be able to handle MIME structure, attachtments, archives and so on, since avcheck itself doesn't contain any code for these tasks.

OPTIONS

-f from (required)
    specify envelope from (sender) address of a mail message

-s avtype[:avsocket] (required)
    specifies antivirus daemon product to use and a path for it's control socket. Currently, only antivirus products from the following vendors are supported:
      AVP, www.kaspersky-labs.com
      DrWeb, www.sald.com
    avsocket may be a pathname to Unix-domain socket, or host:port for a TCP connection. In latter case, host part may be omitted and defaults to 127.0.0.1. avsocket may be omitted, default is antivirus-dependant.

-d tmpdir (required)
    specify a temporary directory where the message will be stored for inspection by the antivirus daemon. Do NOT use /tmp, /var/tmp and other public-accessable directory here, but create one especially dedicated for mail antivirus scanning, and give it appropriate, restrictive permissions. If tmpdir contains "/./" component, e.g. /var/avscan/./tmp, then avcheck assumes that antivirus daemon is chrooted in /var/avscan, and filename will be translated accordingly before being sent to antivirus daemon.

-t timeout
    set timeout in secounds to wait for answer from the antivirus daemon. If the answer will not be available after this time, avcheck will exit with EX_TEMPFAIL error code. By default, avcheck will not restrict time it waits for an answer.

-n  do not reinject good message back into mail subsystem (by default, avcheck will do so).

-g okcode
    exit with okcode (default 0) when no viruses found. Useful with conjunction with -n and an MTA which will continue normal delivery when AV inspector returns this exit code.

-S sendmail
    specifies path to sendmail-compatible program that will be used for message re-injection (unless -n option given). May be a pathname (starting with slash character), or host:port to use (subset of) SMTP. Default is 127.0.0.1:smtp, i.e. avcheck will attempt to talk SMTP with localhost using the standard smtp port. In case of SMTP (host:port form), either host or port part may be omitted and defaults to 127.0.0.1 and 25). Note that avcheck's SMTP implementation does not permit multiline responses from SMTP server, and the ESMTP protocol is not supported. When given a path to local program, this program should be compatible with sendmail(1). In particular, -f option (specifying envelope from address) should be supported, and this program is expected to send a mail message given on standard input to a list of recipients specified in command line. In order to specify additional arguments for this external program (for Sendmail, it may be useful to specify -ppoto option, for example), -S option may be repeated with all needed arguments, or one can specify multiword value for -S option. For example, to specify
      /usr/sbin/sendmail -p AVSCAN
    as a sendmail program, one may use either
      avcheck -S "/usr/sbin/sendmail -p AVSCAN"
    or
      avcheck -S /usr/sbin/sendmail -S -p -S AVSCAN
    or
      avcheck -S /usr/sbin/sendmail -S "-p AVSCAN"
    and so on. When using Sendmail-compatible program, do not forget to specify -i option for it (use avcheck -S /usr/sbin/sendmail -S -i), to stop sendmail from treating a line consisting of one dot character (.) as end of a message. Note that the flow path used for further delivery as specified by this -S option should not include avcheck again, or else the mail will loop. The mail system should assume that mails injected by this method are already safe from an antivirus point of view.

-h hdr
    Prepend the
      X-AV-Checked: <time> hdr
    header line to every email message passed virus check and reinjected back into the mail system (via the path specified by -S option). It is common to use a local hostname as a value for hdr. Note that this option has no effect when used with -c or -n options or when avcheck encounters an infected message.

-i infected-program
    specify a pathname for an external program (typically, a shell-like script will be used here) to handle infected mail messages. Default is `infected' in the same directory as avcheck itself, i.e. if apcheck called as /some/where/avcheck, it will attempt to execute /some/where/infected to handle infected mail. This external program will be called with 3 fixed arguments: the full pathname where the infected message has been stored temporary (in a directory specified with -d option below), it is up to this handler to delete this file; the message from the antivirus daemon (may be multiline or empty if none available), and the envelope from (sender) address as specified with -f argument). Next arguments will be recipient address(es) as given to avcheck itself. Environment variables for this program will be set as follows:

    PATH
        will hold standard "/bin:/usr/bin" value.

    SENDMAIL
        will point to a program with arguments sutable to inject a mail message into the mail subsystem that will not be a subject for an antivirus check (as specified with -S option for avcheck). In case when argument for -S option specifies a TCP socket, SENDMAIL will hold "/path/to/avcheck -c -S host:port" (see -c option below).

    This program/script should perform all the required work, as local administrator decides. Examples of such a shell script are provided in the avcheck distribution.

-w waitfile
    Instructs avcheck not to attempt to contact with the antivirus daemon and not to perform any actions but to immediately exit with the EX_TEMPFAIL exit code if specified waitfile is present. If it is not present, avcheck will operate as usual. This may be useful to safely restart antivirus daemon without worrying about mails not being scanned etc while the daemon starts up and initializes. The idea behind this is to create waitfile before reloading/restarting the daemon (e.g. when there is a need to reload it's antivirus bases), wait for some time so that all current in-progress checking operations will complete, then actually reload/restart a daemon, and after the reload completes successefully to remove waitfile. All mails that need to be checked during this time will be deferred by a mail system and retried later. Note that avcheck will always exit with EX_TEMPFAIL in case of any error (e.g. when connection to antivirus daemon can't be established or a daemon returned some unexpected response).

-c  This is a special option that turns on the special "mail injection client" mode. If this option is given, avcheck will read a mail message from standard input and inject it into mail system as specifier by -S option. Only -f (from) option and list of recipients are required; all other options are ignored. Note that avcheck will not contact the antivirus daemon in this mode, it will only submit mail without checking it for viruses. This mode of operation can be used inside the `infected' script to submit message(s) (see -S option). When sendmail given in -S option specifies a TCP socket, avcheck sets the $SENDMAIL environment variable to be
      /path/to/avcheck -c -Ssendmail
    where sendmail is the argument given to -S option, so that the script can submit mail using the same SMTP protocol as avcheck itself.

USAGE
Many mail transfer agents exists, and every one needs it's own section here. For now, please read various README files in the avcheck distribution.

SECURITY
In order to operate safely and securely, the "antivirus checking subsystem" should be configured properly. Most important parts are filesystem and process permissions. Many antivirus software available today runs as root user by default -- this is a very bad idea and clearly violates the "principle of least privilege". This simplifies access to any user's file from the antivirus daemon (in order to check a file for viruses, the daemon needs read permissions for that file), but opens a great risk to crack a system (in case of bugs in the antivirus software, inaccurate settings and so on). Unfortunately, many antiviruses today, while being good at their primary task (detecting viruses), are inaccurate from security/stability point of view. To use antivirus in mail system, I recommend to set up two user accounts on a system that will be dedicated for virusscanning of mail (and nothing else!). One account (be it avdaemon for example) is for antivirus daemon, and another (avclient) is for antivirus client (like avcheck). Place them both in one (again, dedicated for this purposes) group (named e.g. avgroup), and set up a temporary directory owned and fully accessible by avclient user, executable by avgroup, and not accessible by anyone else. If the antivirus daemon uses Unix-domain socket for control connection (like AVP does or DrWeb may be configured to do), then place it to a directory owned by avdaemon and accessible by avgroup group (for avclient user) only. This way:

•   the mail system will not harm the antivirus daemon, since it has no permissions to do so;

•   the antivirus daemon will not be able to access/crash mailsystem, and message(s) stored in that temporary directory will be safe as no one else will be able to read/modify them

•   the antivirus daemon will not be able to modify them as well (but can read them in order to check for viruses).

Configure mail system in such a way so that it will call avcheck as avclient user, grouop avgroup. For extra care, antivirus daemon may be run chrooted (avcheck supports this, see -d option). To simplify running the antivirus daemon chrooted and as non-privileged user, there is a program in the avcheck distribution, called uchroot. It is similar to the standard unix chroot(1) utility, but has two additional options: -u, to switch to given userid before running specified program, and -d, to chdir to non-root directory inside the chroot jail.

AUTHOR
This program written by Michael Tokarev <mjt@corpit.ru>, with many contributions, ideas and testing by Ralf Hildebrandt <Ralf_Hildebrandt@web.de>.

LICENSE
This program is a public domain code. Do with it anything you like.