Autobuse
--------

http://www.picante.com/~gtaylor/download/
Copyright (c) 1998 by Grant Taylor <gtaylor+autobuse@picante.com>
$Id: README,v 1.7 1999/02/02 18:32:31 gtaylor Exp $

Autobuse, such as it is, is free software distributed under the GNU
license.  See the file COPYING in this distribution for license
information.

Autobuse is a little script I wrote to identify probes and the like in
logfiles and automatically report them via email.  This is, in a way,
the opposite of logcheck, in that autobuse tries to identify known
badness and deal with it automatically, while logcheck tries to
identify known goodness and leave you with the rest.

Autobuse is not a substitute for proper vigilance; it is merely an
effort to automatically handle the fallout from script kiddies.

Autobuse normally runs as a daemon, periodically parsing new lines in
various logfiles, sending a nice summary email to wherever when it
finds something that it knows is bad.  For an example of such an
email, see the file sample.report in this directory.

Autobuse is, at the moment, tied to Linux:

 - It uses tie with the BD_File module that includes compiled code
   interfacing to the Berkeley database library.  You could change
   this to use the implementation Perl includes instead.

 - It pipes stuff to /bin/mail to send mail.  You could just speak at
   an SMTP server instead; CPAN includes code for this.

 - It contains few modules useful on other platforms: just an Apache
   one.  NukeNabber, WinGate, Tcpd, and other modules would be
   straightforward to write. 

... so making this go on FreeBSD, Solaris, or Windows is just a simple
matter of programming.


Installing
----------

Note: Autobuse is incompatible with "promiscuous mode" as set by ie
tcpdump.  Running the two together on a repeated (aka hubbed) ethernet
interface will result in no end of confusion when Autobuse reports
about packets going to and fro between other machines.

Before running autobuse, you must configure it by editing one or
perhaps two files:

In autobuse itself, you must set the proper values for the following:

 - The path to your Perl interpreter, usually /usr/bin/perl,
   /usr/local/bin/perl, or somesuch.

 - The path to the autobuse installation (in the BEGIN block).  You
   can skip this and just run autobuse from the install directory.

 - The hostname and interface name of your public network interface.

 - A list of domain names to ignore.  Connections from these hosts to
   otherwise taboo services will not be reported.  IPs and names are
   looked up in a TCP-wrappers-like paranoid way.

 - A filename for autobuse to store state information in.  This state
   is merely the last file position for each logfile; the file must be
   in a directory writable to the user you run autobuse as.

 - A list of logfiles to monitor.  Each Autobuse plugin module knows
   what kind of logfile it can parse, so you specify a type for each
   logfile, too.

 - A mailing command.  Reports are piped into this program.

 - A polling frequency in minutes.  Don't set it too small or you
   might be flooded with emails.

 - A reporting threshold.  For each host with events, there must be at
   least the threshold number of events or it will not be reported.
   This threshold can also be set with the -l command-line option.

 - Which modules to use.  This can usually be left alone, since only
   modules appropriate for each logfile are run, but if you don't want
   reports from a certain module which you have configured a logfile
   for you can comment it out.   

 - In Common.pm, you can adjust some of the known exploit data.
   There is a list of bad URLs like "phf", and a three dimensional
   array of protocols, port numbers, and exploit descriptions.

Autobuse must be run with read permission for all the logfiles you
told it to read.  I run it as root, but you may be less adventurous.
To actually run it, just run "./autobuse &".  It should produce no
output on stdout/err unless something is wrong.  If there is a
permissions problem, it should complain immediately.

There is also a test mode, which just parses your logfiles and spits
out a sample message on stdout with everything it found.  You can use
this to check the configuration before you start sending out emails.
This is the -t option.

If you also run logcheck, you can use the example rules in the file
logcheck.violations.ignore to filter out everything that autobuse
reports automatically.  


Autobuse modules
----------------

There are various modules available for autobuse.  Included in this
distributions are:

LinuxIpFw: This module handles kernel messages from the v2.0 ipfw code
           and the v2.2 ipchains code.  Note that each rule entered
           with ipfwadm or ipchians must have the "log" flag turned on
           or packets for the reule will not be reported.

Apache: This module handles apache logfiles.  It looks for the most
        common exploits as listed in Common.pm.


Writing modules
---------------

Autobuse can be extended to handle new types of log information.  The
basic design of the thing is to feed each logfile entry into each
module that claims it can handle lines from the current type of
logfile, and to report whatever the modules says to report.

Modules are Perl objects which inherit from Autobuse::Plugin.  They
have:

 - a method new which takes whatever arguments are necessary and
   returns a blessed hash.    

 - a data value $this->{'logtype'} set to the log type this module can
   handle (ie, "syslog" or "web").  This value should be set in new.

 - a method check_logline which takes one line as an argument and
   returns either 'undef' or an Event object.  See the examples for
   how to construct an Event object.

Modules may use the utility functions in Common.pm:

 - lookup_ip takes an ip address as a #.#.#.# string (or a hostname)
   and returns the hostname

 - lookup_host takes a hostname (or an address as a #.#.#.# string)
   and returns an IP.  Note that I say "an" IP, not "the" IP, as there
   may be multiple IP numbers for a given name.

 - format_ip takes an ip address and returns a string "ipadr (hostname)"

 - paranoid_check_domain takes an ip address and a ref to a list of
   strings, and returns 1 if the address maps to a hostname that ends
   in any ofthe strings.  Note that this works rather poorly in the
   case of multiple IP addresses for a name.

Common data or subroutines that other modules might want to share, but
which is not site-specific, should go in Common.pm