--------------------------------------------------------------------------------
-                                 P3Scan 1.0                                   -
-                               by Jack S. Lai                                 -
-                           <laitcg at cox dot net>                            -
--------------------------------------------------------------------------------
-                                  README                                      -
--------------------------------------------------------------------------------

p3scan is a fully transparent proxy scanning server for POP3 clients. It runs on
a Linux box with iptables (for port redirection).It implements a centralized
POP3 email scanning point, transparently inspecting messages fetched by internal
network hosts from servers "in the wild" (the Internet) for viruses, worms,
trojans, spam and potentially dangerous attachments. Since HTML email can be
used by spammers to validate the recipient address (via Web Bugs) p3scan
also provide HTML stripping.

p3scan can help you in protecting your "Other OS" LAN especially if used
synergically with a firewall and other proxy servers.

LICENSE / Copyright:

   This project is maintained by Jack S. Lai <laitcg at cox dot net>.

   P3Scan is a derived work of POP3VScan as written by Folke Ashberg
   <folke at ashberg dot de>.

   It's intent is to provide a follow on program to POP3-Virusscan-Proxy 0.4

   It is based upon his program but provides numerous changes to include
   scanning pop3 mail for spam, hardening the program, addaption to todays
   email environment, and many other changes.

   The initial release of p3scan includes patches made and submitted to the
   original project but were never incorporated.

   I want to thank Folke Ashberg here for his wonderful program.
   His program is located at: http://pop3vscan.sourceforge.net/

   (C) 2003 by Jack S. Lai

   Contact:
      email: laitcg@cox.net

   P3Scan is copylefted with the 'General Public License v2' (GPL).
   See file 'LICENSE'.

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

How it works / Overview:

   You have to set up a port redirection with 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 to a local port, on which P3Scan listens.
   P3Scan 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 necessary parts of the POP3
   protocol and when an email is sent from the server, we store it into a file,
   invoke our scanning, and send it along if it is good, or we replace it with
   a virus notification and optionally delete the infected message.

   It should be possible to use all scanners using the scannertype=basic.

   Also, P3Scan 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 mail scanner (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/Compilation:

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

Requirements:

   iptables	- Normally installed by default on major Linux Distributions.
      http://www.netfilter.org
   libpcre - Normally installed by default on major Linux Distributions.
      http://www.pcre.org
   An Anti-Virus program
      P3Scan is known to work with:
         Kaspersky Anti-Virus for Linux (AVPD)
            http://www.kaspersky.com/
         Trophie Anti-Virus Daemon
            http://www.vanja.com/tools/trophie/
         FRISK F-Prot Antivirus
            http://www.f-prot.com/
         Any other virus scanner that can output it's report to the console
         (stout) so that it can be captured with "2>&1".
   Mail::SpamAssassin (optional) - http://www.spamassassin.org
   renattach (optional) - http://www.pc-tools.net/unix/renattach/

Kernel:

   The following kernel-parameters have to be enabled to get P3Scan to work.
   If you have no clue about kernel-compiling, then here is some good news:
   A lot of Linux Distributions support what we need by default with kernels
   2.4.x or greater. However, if your distribution does not have it, please
   read your system documentation on how to add it to your kernel.

      -CONFIG_NETFILTER=y
      -CONFIG_IP_NF_IPTABLES=[y/m]
      -CONFIG_IP_NF_TARGET_REDIRECT=[y/m]

Compilation:

   Change to the directory where you untar'ed the program and as user:
      $ make
   and as root (su root)
      # make install

   The only binary will be copied to /usr/sbin/p3scan.

   Make install will also copy p3scan.conf and p3scan.mail into /etc/p3scan
   while creating directories /etc/p3scan, /var/run/p3scan, /var/spool/p3vscan,
   /var/spool/p3vscan/children, and /var/spool/p3scannotify.

   After this, you must prepare your configuration file as described below.

Preparing / Manual Configuration:

   If you decide not to use "make install" (for example, you don't want gcc on
   your firewall machine where p3scan is going to run). Please ensure the
   following directories are created and that they are owned and
   readable/writable by only the user "mail" (default).

   As root, create the following directories as follows:
      # mkdir /etc/p3scan
      # mkdir /var/run/p3scan
      # mkdir -p /var/spool/p3scan/children
      # mkdir -p /var/spool/p3scannotify

   Make them "owned" by the user "mail" (default):
      # chown mail.mail /etc/p3scan
      # chown mail.mail /var/run/p3scan
      # chown mail.mail /var/spool/p3scan
      # chown mail.mail /var/spool/p3scan/children
      # chown mail.mail /var/spool/p3scannotify

   Then make them read/write by only our user:
      # chmod 700 /etc/p3scan
      # chmod 700 /var/run/p3scan
      # chmod 700 /var/spool/p3scan
      # chmod 700 /var/spool/p3scan/children
      # chmod 700 /var/spool/p3scannotify

   If you don't have the user "mail" and do not know how to create this user,
   please see your operating systems documentation on how to create a user.

   Change /etc/p3scan/p3scan.mail if you wish (that's the template which is
   sent instead of a virus). Do not use any special character (like
   German-umlauts ) and don't forget the leading dot at the end of the file.

Configuration:

   The configuration file defaults to /etc/p3scan/p3scan.conf

   This file is a mixture of configuration data and documentation and MUST be
   modified to work correctly upon initial installation. You must specify
   AT LEAST how to call your anti-virus program and how to extract the virus
   name (if one is found).

   Currently, the default configuration is as follows (see p3scan.conf for more
   info):

   The PID file is stored in: pidfile = /var/run/p3scan/p3scan.pid
   The maximum simultaneous scans is: maxchilds = 10
   We listen to any address: ip = 0.0.0.0
   We listen only on: port = 8110
   We run as: user = mail
   We create notification mails in: notifydir = /var/spool/p3scannotify before
      sending.
   We default to storing infected messages in: virusdir = /var/spool/p3scan
   We do not check remaining disk space before scanning mail.
      "bytesfree" is not set
   We DO NOT have an Anti-Virus program selected, scanner return code, nor
      regular expression on how to extract a virus name.
      scannertype=basic
      "scanner" is not set
      "viruscode" is not set
      "virusregexp" is not set
   We keep infected mail.
      "justdelete" is not set.
   We demime the message or separate attachments from the original mail before
      scanning.
      "demime" is set
   We DO NOT check for "Spam".
      "spamcheck" is not set
   We DO NOT parse HTML code.
      "overwrite" is not set
   We report all program steps to syslog less debug info.
      "quiet" is not set.

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).

   Also, "pop3" must be defined in your "services" file. Normally /etc/services
   If it is not defined, enter the definition you have for 110/tcp. IE: pop-3

   This rule redirects pop3 connections to a local port (like a pop3 server).

Mail::SpamAssassin

   The spam checking capability of p3scan has only been tested using
   Mail::SpamAssassin v2.6

   If you will be scanning for spam using SpamAssassin, you need to install the
   program according to the documentation found at http://www.spamassassin.org

   The easiest (as fastest) interface to Mail::SpamAssassin is through it's
   daemon program "spamd" using "spamc".

   You can start spamd as follows before running p3scan:
   spamd -L -d
   This will not invoke DNS and other network tests (speeds up scanning) and
   will daemonize the program.

renattach:

   Is used to rename attachments and is totally configurable.

   Renattach must be compiled, installed, and configured before enabling this
   feature. See the renattach documentation INSTALL and README for further
   information.

HTML Parsing:

   The HTML parsing function will remove all HTML data between "<" and ">" on
   a single line. It will also ensure removal of "src" and "href" including
   multiple tag lines, but convert <br> to a new line and <p> to two newlines.

Startup:

   Call p3scan (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 test mail with a virus. Therefore every
   mail scanner should know the eicar.com test virus (which will not damage
   your system). You can get eicar.com from http://www.eicar.com

   If you think too much information is being sent to your system logs, you
   can enable the "quiet" option. This will inhibit "normal" messages.

   If P3Scan is started by root, it will change it's user to "mail" (default)
   after it finishes it's initial startup.

   If you are using Mail::SpamAssassin, start spamd BEFORE running p3scan.

RC System / Boot up:

   You can add p3scan to your normal default startup file. For example, in
   Slackware place p3scan as follows:

   # echo "/usr/sbin/p3scan" >> /etc/rc.d/rc.local

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

Special-Configuration

Outbound Scanning

  If you also need to scan pop3-traffic requested from localhost to net, then
  you have to ensure that the requests P3Scan makes to POP3 servers are not
  redirected to himself (that would generate 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
  chosen) 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 p3scan runs.

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

                                    Enjoy!

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