--------------------------------------------------------------------------------
-                                                                              -
-                             POP3 Virus Scanner                               -
-                                     0.4                                      -
-                              by Folke Ashberg                                -
-                             <folke@ashberg.de>                               -
-                                                                              -
--------------------------------------------------------------------------------

This is a full-transparent proxy-server for POP3-Clients, and as i know it's the
first! Not for caching, but for virus scanning. Or scan what you want. It can
only be used with Linux 2.4 iptables netfilter.

LICENCE / Copyright:

  POP3VScan was written by Folke Ashberg

  (C) 2002 by Folke Ashberg
  
  Contact:
      eMail:
         folke@ashberg.de
      Adresse:
         Birkenstr. 9
	 85567 Grafing
	 Germany
  
  POP3VScan is copylefted with the 'General Public Licence v2' (GPL).
  See file 'LICENCE'.

  POP3VScan uses ripMIME from P.L.Daniels, which is licenced with the
  'ripMIME LICENSE'. See file 'ripmime/LICENSE'.

How it works / Overview:

  You have to set up a port redirection in the linux-netfilter (iptables) so
  that all connections from e.g. inside your office to any POP3 server outside
  in the world will not leave your router, but come a local port, on which
  POP3VScan listens. POP3VScan receives from the linux kernel the original
  destination (the POP3 server outside in the world) and will connect to them.
  
  All data we receive from the client will be sent to the server, and vice
  versa. With a little enhancement: we parse the neccessary parts of the POP3
  protocol and when an email is sent from the server, we store it into a file,
  invoke a virusscanner and send it if it is good, or we just replace it with a
  virus notification. It should be possible to use all scanners using the
  scannertype=basic. Also POP3VScan provides scannertype=avpd for high-speed
  scanning using 'Kaspersky Anti-Virus for Linux', every C programmer can easily
  adept other scan-daemons (trophie, sophie, antivir, ...).
  
  Neither the client nor the server has to be configured, none of them will take
  notice that there's a mailscanner (except the client when he gets a virus
  notification or if he looks into the header, and the server gets our ip as
  source).

--------------------------------------------------------------------------------

                      Configuration/Compillation: 

--------------------------------------------------------------------------------

Kernel:
  
  The following kernel-parameters have to be enabled to get POP3VScan to work.
  If you have no clue about kernel-compiling then here good news: all linux
  distributions i know support what we need (but you need Kernel 2.4.x !).
  
    -CONFIG_NETFILTER=y
    -CONFIG_IP_NF_IPTABLES=[y/m]
    -CONFIG_IP_NF_TARGET_REDIRECT=[y/m]


Compillation: 
  
  If you have a binary distribution you can jump to the next section, or copy
  the below listed files to /usr/sbin and /etc/ if it is no rpm. To all other
  people i can say that we need absolute no very special libraries, only the
  common libpcre (RegularExpressions).
  Then run as user
     $ make
     and as root (su root)
     # make install
     
  The only binary will be copied to /usr/sbin/pop3vscan , pop3vscan.conf and
  pop3vscan.mail into /etc/ .


Preparing / Configuration:

  We need a user under which POP3VScan runs. We call it mail and create it
  with this command (if it shouldn't exist)
    # useradd -d /tmp -s /bin/false -g nogroup mail
  Create the directory /var/spool/pop3vscan
    # mkdir -p /var/spool/pop3vscan
  chown it to our brandnew user
    # chown mail /var/spool/pop3vscan
  and set a restrict permission
    # chmod 700 /var/spool/pop3vscan
    
  Change /etc/pop3vscan.mail if you wish (that's the template which is sent
  instead of a virus). Do not use any special character (like german-umlauts
  ) und don't forget the leading dot at the end of the file.


  For configuration (especially configuring to a virusscanner) read
  /etc/pop3vscan.conf , the file is a mixture between configfile and
  documentation. In most cases you need to set/change only scannertype, scanner,
  demime, viruscode and virusregexp.
 
 
IP-Tables / Port redirecting:
  
  A rule like

# iptables -t nat -A PREROUTING -p tcp -i eth0 --dport pop3 \
#	-j REDIRECT --to 8110

  is enough. Change eth0 to your device for the inbound connections (your office
  or home network). Btw: That rule also redirects pop3 connections to a local
  pop3 server.


Startup:

  Call pop3vscan (without any parameters, it will move into background) and see
  what will be shown in /var/log/messages (or /var/log/daemon) when you fetch
  your mails. Also you can send a testmail with a virus. Therefore every
  mailscanner should know the eicar.com testvirus (which will not demage your
  system). You can get eicar.com from http://www.eicar.com/


RC System / Bootup:

  To configure the system that POP3VScan will be started at boot-time you can
  look into the stuff/ directory. If you have luck ther is a file called
  pop3vscan.rc.<distribution-name>-install matching your distribution. Change
  into the stuff directory and run as root that script; otherwise you have to do
  it yourself.
  

--------------------------------------------------------------------------------
  
Special-Configuration

  If you also need to scan pop3-traffic requested from localhost to net, then
  you have to ensure that the requests POP3VScan makes to POP3 servers are not
  redirected to himself (that would generaye a terrible never ending loop!!).
  What you can do is to use the experimental match-owner netfilter module,
  therefore it is possible that you need to recompile your kernel. Then you need
  to insert a netfilter rule which allows the user mail (or whatever you have
  choosen) outgoing traffic to port 110 (pop3), any other users will be
  redirected.

# iptables -t nat -A OUTPUT  -p tcp --dport pop3 -m owner --uid-owner <UID> \
#   -j ACCEPT
  and the redirection:
# iptables -t nat -A OUTPUT  -p tcp --dport pop3 -j REDIRECT --to 8110
 
  change <UID> to the userid of the user pop3vscan runs.


--------------------------------------------------------------------------------


			    Happy scanning!!!


--------------------------------------------------------------------------------

$Id: README,v 1.24 2002/06/11 23:58:10 folke Exp $

vim:set tw=80:
