.\" $Id: avcheck.1,v 1.4 2002/10/09 22:07:59 mjt Exp $
.\" manpage for avcheck program
.\" Michael Tokarev <mjt@corpit.ru>
.\" Public domain
.TH avcheck 1

.SH NAME
avcheck \- antivirus daemon client for mail system

.SH SYNOPSYS
.B avcheck
.I options
\-\-
.I recipient...

.SH DESCRIPTION

.B 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, \fBavcheck\fR optionally reinjects message
back into mail system for further delivery.  If the
antivirus software claims that message contains
some virus\-infected file or such, \fBavcheck\fR
will call another program to handle this message
and take appropriate actions.  In case of any
error (except of incorrect usage/options), \fBavcheck\fR
will exit with EX_TEMPFAIL exit code, so that further
"delivery" attempt will be attempted again later, thus
allowing to correct that error.

Typically, \fBavcheck\fR 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 \fBavcheck\fR 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 \fBavcheck\fR is \fInot\fR 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 \fBavcheck\fR itself doesn't contain any code
for these tasks.

.SH OPTIONS

.IP "\-f \fIfrom\fR (required)"
specify envelope from (sender) address of a mail message

.IP "\-s \fIavtype\fR[:\fIavsocket\fR] (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:
.nf
  \fBAVP\fR, www.kaspersky\-labs.com
  \fBDrWeb\fR, www.sald.com
.fi
\fIavsocket\fR may be a pathname to Unix\-domain
socket, or \fIhost\fR:\fIport\fR for a TCP connection.
In latter case, host part may be omitted and defaults
to 127.0.0.1.  \fIavsocket\fR may be omitted, default
is antivirus\-dependant.

.IP "\-d \fItmpdir\fR (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 \fItmpdir\fR contains "/./" component, e.g. /var/avscan/./tmp,
then \fBavcheck\fR assumes that antivirus daemon is
chrooted in /var/avscan, and filename will be translated
accordingly before being sent to antivirus daemon.

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

.IP "\-n"
do not reinject good message back into mail subsystem
(by default, \fBavcheck\fR will do so).

.IP "\-g \fIokcode\fR"
exit with \fIokcode\fR (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.

.IP "\-S \fIsendmail\fR"
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 \fIhost\fR:\fIport\fR to use
(subset of) SMTP.  Default is 127.0.0.1:smtp, i.e.
\fBavcheck\fR will attempt to talk SMTP with localhost
using the standard smtp port.

In case of SMTP (\fIhost\fR:\fIport\fR form), either \fIhost\fR
or \fIport\fR part may be omitted and defaults to 127.0.0.1 and
25).  Note that \fBavcheck\fR'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 \fBsendmail\fR(1).  In particular, \fB\-f\fR 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
\-p\fIpoto\fR option, for example), \fB\-S\fR option may be repeated
with all needed arguments, or one can specify multiword value for
\fB\-S\fR option.  For example, to specify
.br
  /usr/sbin/sendmail \-p AVSCAN
.br
as a sendmail program, one may use either
.br
  \fBavcheck\fR \-S "/usr/sbin/sendmail \-p AVSCAN"
.br
or
.br
  \fBavcheck\fR \-S /usr/sbin/sendmail \-S \-p \-S AVSCAN
.br
or
.br
  \fBavcheck\fR \-S /usr/sbin/sendmail \-S "\-p AVSCAN"
.br
and so on.

When using Sendmail\-compatible program, do not forget to specify
\-i option for it (use \fBavcheck\fR \-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 \fBavcheck\fR 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.

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

.IP "\-i \fIinfected\-program\fR"
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 \fBavcheck\fR itself,
i.e. if \fBapcheck\fR called as \fI/some/where/\fBavcheck\fR,
it will attempt to execute \fI/some/where/\fBinfected\fR
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 \fBavcheck\fR itself.

Environment variables for this program will be set as follows:
.RS
.IP \fBPATH\fR
will hold standard "/bin:/usr/bin" value.
.IP \fBSENDMAIL\fR
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 \fBavcheck\fR).  In case when
argument for \-S option specifies a TCP socket, \fBSENDMAIL\fR will
hold "/path/to/\fBavcheck\fR \-c \-S \fIhost\fR:\fIport\fR" (see \-c
option below).

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

.RE

.IP "\fB\-w \fIwaitfile\fR"
Instructs \fBavcheck\fR 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 \fIwaitfile\fR is present.  If it is not present,
\fBavcheck\fR 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 \fIwaitfile\fR 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 \fIwaitfile\fR.  All mails that need to be checked during
this time will be deferred by a mail system and retried later.
Note that \fBavcheck\fR 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).

.IP \fB\-c\fR
This is a special option that turns on the special "mail injection client"
mode.  If this option is given, \fBavcheck\fR will read a mail message from
standard input and inject it into mail system as specifier by \fB\-S\fR
option.  Only \fB\-f\fR (from) option and list of recipients are required;
all other options are ignored.  Note that \fBavcheck\fR will \fInot\fR
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 \fB\-S\fR option).  When \fIsendmail\fR given in
\fB\-S\fR option specifies a TCP socket, \fBavcheck\fR sets the $SENDMAIL
environment variable to be
.br
  \fI/path/to/\fBavcheck \-c \-S\fIsendmail\fR
.br
where \fIsendmail\fR is the argument given to
\fB\-S\fR option, so that the script can submit mail using
the same SMTP protocol as \fBavcheck\fR itself.

.SH USAGE

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

.SH 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 \fIvery bad idea\fR 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 \fIavdaemon\fR for example) is for antivirus
daemon, and another (\fIavclient\fR) is for antivirus client (like
\fBavcheck\fR).  Place them both in one (again, dedicated for this purposes)
group (named e.g. \fIavgroup\fR), 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:

.IP \(bu
the mail system will not harm the antivirus daemon, since it has no permissions
to do so;

.IP \(bu
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

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

.PP

Configure mail system in such a way so that it will call \fBavcheck\fR
as avclient user, grouop avgroup.

For extra care, antivirus daemon may be run chrooted (\fBavcheck\fR supports
this, see \-d option).

To simplify running the antivirus daemon chrooted and as
non\-privileged user, there is a program in the \fBavcheck\fR
distribution, called \fBuchroot\fR.  It is similar to the
standard unix \fBchroot\fR(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.

.SH AUTHOR

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

.SH LICENSE

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