Malicious Attack Livid Termination Filter daemon (maltfilter) v0.20.1
=====================================================================
Programmed by Matti 'ccr' Hämäläinen <ccr@tnsp.org>
(C) Copyright 2009 Tecnic Software productions (TNSP)

Distributed under the modified ("3-clause") BSD license. Please see
included file COPYING for more information.


Homepage: http://www.tnsp.org/maltfilter.php


About
=====
Maltfilter is daemon script written in Perl, which continuously scans various
system logfiles including auth.log, Apache style common logformat and error
logs, etc. for signs of malicious connections, break-in (login bruteforcing,
etc.) and exploitation attempts. The originating IP addresses of these
connections can be then acted upon in following ways, each being optional:

 * Insertion (and eventual deletion or "weeding") of Netfilter rules.
 * Submitting entry to DroneBL DNSBL service.
 * Gather "evidence" about certain PHP XSS exploit attempts into
   specified directory. These evidence files include the attempted
   exploit code (if found) and hosts which have tried to make your
   server run it.

Additionally Maltfilter can generate status reports (either continuously
in daemon mode, or in run-once report mode), in plaintext and HTML
formats.


Requirements:

 - Perl 5.8 or later
 - Date::Parse (libtimedate-perl)
 - Net::IP (libnet-ip-perl)
 - Net::DNS (libnet-dns-perl)
 - LWP::UserAgent (libwww-perl)


Memory requirement considerations
=================================
Because Maltfilter is written in Perl, it (or rather the Perl interpreter
it is running under) tends not to free any allocated memory. This is NOT
a memory leak per se, but a feature of Perl's memory allocator. Currently
allocated memory is simply reused for other structures when needed,
thus making the VIRT consumption periodically rise.

However, there may be some situations (none that I have experienced myself
as of yet, but as usual anything is possible) where Maltfilter's memory
consumption rises to unbearable level. In high-volume servers it may be
useful to periodically restart (as in complete restart, not reload via HUP)
the daemon to free the memory.

It is also helpful to change the FILTER_MAX_AGE and GLOBAL_MAX_AGE
configuration settings to smaller values, so that amount of data held
in memory at once is smaller.


Manual installation
===================
1) Copy maltfilter script to /usr/sbin and set permissions

   $ cp maltfilter /usr/sbin/maltfilter
   $ chmod 755 /usr/sbin/maltfilter
   $ chown root:root /usr/sbin/maltfilter

2) Copy example configuration under /etc (you may not want to have the
   configuration readable to regular users, so below example sets mode
   0600 to it.)

   $ cp example.conf /etc/maltfilter.conf
   $ chmod 600 /etc/maltfilter.conf
   $ chown root:root /etc/maltfilter.conf

3) Additionally you can set up the provided Debian style init script
   for starting Maltfilter at boot.  You may need to edit the script,
   if you didn't install the configuration and maltfilter script to
   paths described above.

   $ cp example.init /etc/init.d/maltfilter
   $ chmod 755 /etc/init.d/maltfilter
   $ chown root:root /etc/init.d/maltfilter

   After that you should run rcconf(8) or chkconfig(8) or similar SysV
   runlevel configuration utility to enable the script on desired
   runlevels.

4) You will also most likely want to set up Maltfilter to be SIGHUP'd/
   restarted when logfiles are rotated via logrotate (because Maltfilter
   does not automatically notice if logfiles are switched while it is
   running).

   There are several ways this can be done, most of which are distribution
   specific. If you are using Debian-based distribution or something close
   enough, you can try following:

   a) Use the included 'logrotate.example' logrotate script. This may not
      as reliable method as below, however, but it is somewhat easier and
      much more maintainable.

      $ cp logrotate.example /etc/logrotate.d/maltfilter
      $ chmod 644 /etc/logrotate.d/maltfilter
      $ chown root:root /etc/logrotate.d/maltfilter

   b) Alternatively you can edit /etc/logrotate.conf or relevant file(s)
      under /etc/logrotate.d/ and add reloading or restarting maltfilter
      in the script's postrotate section.

      For example, if you are using Debian with rsyslog, there should be
      /etc/logrotate.d/rsyslog, which takes care of rotating most system
      logs, such as auth.log. Add following line in postrotate section:

      invoke-rc.d maltfilter reload > /dev/null


Configuration and usage
=======================
See example.conf for documentation about settings. After editing your
configuration, you should do a preliminary test run via report mode to
see if most settings are sane.

$ maltfilter -f /etc/maltfilter.conf

After that, you can start maltfilter either via the init script
(recommended) or through commandline:

$ maltfilter /var/run/maltfilter.pid /etc/maltfilter.conf

If you want to use the init script, you need to edit your init runlevel
settings to enable it, for example in Debian/Ubuntu you can use rcconf(8)
or chkconfig(8).


Reports
=======
Automatic report generation can be enabled from configuration.
You can also run "full" report generation via the "-f" option, in this
special mode, no automatic weeding is performed, resulting in
more data being shown. In report mode Maltfilter will only parse files
once, generate reports (if enabled) and quit.