Basic Analysis and Security Engine (BASE) v1.4.5 (lilias)
  
By Kevin Johnson <kjohnson@secureideas.net , http://www.secureideas.net>
    and the BASE Development Team
Portions by Roman Danyliw <rdd@cert.org>, <roman@danyliw.com>

Project Website: http://base.secureideas.net
Sourceforge Site: http://sourceforge.net/projects/secureideas

CVS     :  cvs.sourceforge.net

-------------------------------------------------------------------------------
** Copyright (C) 2004 Kevin Johnson
** Portions Copyright (C) 2000, 2001, 2002 Carnegie Mellon University
**
** This program is free software; you can redistribute it and/or modify
** it under the terms of the GNU General Public License as published by
** the Free Software Foundation; either version 2 of the License, or
** (at your option) any later version.
**
** This program is distributed in the hope that it will be useful,
** but WITHOUT ANY WARRANTY; without even the implied warranty of
** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
** GNU General Public License for more details.
**
** You should have received a copy of the GNU General Public License
** along with this program; if not, write to the Free Software
** Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
-------------------------------------------------------------------------------

I. ABOUT
_____________________________________

The Basic Analysis and Security Engine (BASE) is a PHP-based analysis 
engine to search and process a database of security events generated by 
various IDSes, firewalls, and network monitoring tools.  The features currently 
include:

 o Query-builder and search interface for finding alerts matching
   on alert meta information (e.g. signature, detection time) as well as
   the underlying network evidence (e.g. source/destination address, ports,
   payload, or flags).

 o Packet viewer (decoder) will graphically display the layer-3 and
   layer-4 packet information of logged alerts

 o Alert management by providing constructs to logically group alerts 
   to create incidents (alert groups), deleting the handled alerts or 
   false positives, exporting to email for collaboration, or archiving of 
   alerts to transfer them between alert databases.

 o Chart and statistic generation based on time, sensor, signature, protocol, 
   IP address, TCP/UDP ports, or classification

BASE has the ability to analyze a wide variety of events which are 
post-processed into its database.  Tools exist for the following formats:
  
  o using Snort (www.snort.org)
     - Snort alerts
     - tcpdump binary logs

  o using logsnorter (www.snort.org/downloads/logsnorter-0.2.tar.gz)
     - ipchains
     - iptables
     - ipfw


II. PREREQUISITES
_____________________________________

 o A database in which to store the event information (exactly one of):

   -  Package:      MySQL
      Version:      3.23.x+
      Description:  Open Source RDBMS
      Reason:       Back-end database
      Homepage:     http://www.mysql.com/

   -  Package:      PostgreSQL
      Version:      7.1+
      Description:  Open Source RDBMS
      Reason:       Back-end database
      Homepage:     http://www.postgresql.org/

   -  Package:      Microsoft SQL Server
      Version:      8.00.194+
      Description:  Commercial RDBMS
      Reason:       Back-end database
      Homepage:     http://www.microsoft.com/sql/default.asp

   -  Package:	    Oracle Database Server
      Version:      9.0+
      Description:  Commercial RDBMS
      Reason:       Back-end database
      Homepage:     http://www.oracle.com

 o A mechanism by which to log raw information into the database (any of):

   -  Package:      Snort
      Version:      2.2+
      Description:  Network Intrusion Detection System
      Reason:       Detects security events
      Homepage:     http://www.snort.org/

   -  Package:      logsnorter
      Version:      0.2+
      Description:  PERL script which parses firewall logs
      Reason:       Detects security events
      Homepage:     http://www.snort.org/downloads/logsnorter-0.2.tar.gz

   - any home-grown script that understands the underlying DB format

 o  Package:      PHP
    Version:      4.0.4+ (5.0+ recommended)
    Description:  Web scripting language
    Reason:       Implementation language of BASE
    Homepage:     http://www.php.net/
                  (Windows builds) http://www.php4win.com/builds/latest-build.php

 o A web server (any of):
 
   -  Package:      Apache Server
      Version:      1.3.*+
      Description:  HTTP server
      Reason:       Web server for PHP 
      Homepage:     http://www.apache.org/
 
   - PHP supports a number of other web servers (e.g. Netscape, Roxen, IIS); 
     any of these should also be compatible (although untested).  

 o  Package:      ADODB
    Version:      4.9+
    Description:  PHP database abstraction library
    Reason:       PHP provides no clean database API
    Homepage:     http://adodb.sourceforge.net/

 o  Package:      GD
    Version:      1.8.*
    Description:  Image manipulation library
    Reason:       Raw JPEG/PNG/GIF support for creating charts
    Homepage:     http://www.boutell.com/gd/
    Type:         optional

    The following are GD dependencies:

      o  Package:      libpng
         Description:  PNG library
         Reason:       PNG format support for GD
         Homepage:     http://www.libpng.org/pub/png/

      o  Package:      libjpeg-6b
         Description:  JPEG library
         Reason:       JPEG format support for GD
         Homepage:     http://www.ijg.org/

      o  Package:      zlib
         Version:      1.8.*
         Description:  compression library
         Reason:       Compression support for GD
         Homepage:     http://www.gzip.org/zlib/

 o Any web browser capable of supporting cookies


III. INSTALLATION
_____________________________________

The following is a step-by-step list of installing BASE.  

1.  [OPTIONAL] Prior to deploying BASE, successful logging of alerts from 
    the sensor (be it Snort, logsnorter, etc.) to the database should be confirmed.
    BASE can only manage alerts stored in the database.  Consult the 
    appropriate documentation for database logging configuration specifics.

     o Snort -- README.database included in the source distribution or
                at http://www.snort.org/documentation.html

     o logsnorter -- README included in distribution

    In order to confirm successful logging, use the command-line database
    clients (or a graphical front-end tool) to execute the following
    SQL queries:

     [for MySQL]

       $ echo "SELECT count(*) FROM event" | mysql snort_db -u root -p

       (Note: the connection parameters used with mysql may vary with your
              configuration. In this case, the mysql client will connect to
              the 'snort_db' database as the 'root' user prompting for a 
              password)

       This command should return output similar to the following.

        count(*)
        1

     [for PostgreSQL]

       $ echo "SELECT count(*) FROM event" | psql -d snort_db -U root -W

       (Note: the connection parameters used with psql may vary with your
              configuration. In this case, the PostgreSQL client will connect to
              the 'snort_db' database as the 'root' user prompting for a 
              password)

       This command should return output similar to the following.

        count
       -------
       (1 rows)

    In this example, both the MySQL and PostgreSQL database contained 1 alert.  
    If no alerts are found in the database (i.e. a 0 is returned), then (obviously) 
    nothing has been successfully logged.

2.  Confirm that the proper database permissions have been set for the database
    and tables used by BASE.  The minimum permissions for each relation (table) 
    are listed in Table 1.

     Table 1: Required database permissions on tables used by BASE
 
                           SELECT   INSERT   UPDATE   DELETE
     +=======================================================+
     | acid_ag          ||   X    |   X    |        |   X    |
     +------------------++--------+--------+--------+--------+
     | acid_ag_alert    ||   X    |   X    |        |   X    |
     +------------------++--------+--------+--------+--------+
     | acid_event       ||   X    |   X    |   X    |   X    |
     +------------------++--------+--------+--------+--------+
     | acid_ip_cache    ||   X    |   X    |   X    |   X    |
     +------------------++--------+--------+--------+--------+
     | base_roles       ||   X    |   X    |   X    |   X    |
     +------------------++--------+--------+--------+--------+
     | base_users       ||   X    |   X    |   X    |   X    |
     +------------------++--------+--------+--------+--------+
     | data             ||   X    |   X    |        |   X    |
     +------------------++--------+--------+--------+--------+
     | detail           ||   X    |        |        |        |
     +------------------++--------+--------+--------+--------+
     | encoding         ||   X    |        |        |        |
     +------------------++--------+--------+--------+--------+
     | event            ||   X    |   X    |        |   X    |
     +------------------++--------+--------+--------+--------+
     | icmphdr          ||   X    |   X    |        |   X    |
     +------------------++--------+--------+--------+--------+
     | iphdr            ||   X    |   X    |        |   X    |
     +------------------++--------+--------+--------+--------+
     | opt              ||   X    |   X    |        |   X    |
     +------------------++--------+--------+--------+--------+
     | reference        ||   X    |   X    |   X    |   X    |
     +------------------++--------+--------+--------+--------+
     | reference_system ||   X    |   X    |   X    |   X    |
     +------------------++--------+--------+--------+--------+
     | schema           ||   X    |        |        |        |
     +------------------++--------+--------+--------+--------+
     | sensor           ||   X    |        |        |   X    |
     +------------------++--------+--------+--------+--------+
     | sig_class        ||   X    |   X    |   X    |   X    |
     +------------------++--------+--------+--------+--------+
     | sig_reference    ||   X    |   X    |   X    |   X    |
     +------------------++--------+--------+--------+--------+
     | signature        ||   X    |   X    |   X    |   X    |
     +------------------++--------+--------+--------+--------+
     | tcphdr           ||   X    |   X    |        |   X    |
     +------------------++--------+--------+--------+--------+
     | udphdr           ||   X    |   X    |        |   X    |
     +=======================================================+

     Table 2: Required database permissions on sequences 
              used by BASE (PostgreSQL and MS SQL only)

                                          SELECT   INSERT   UPDATE   DELETE
     +======================================================================+
     | acid_ag_ag_id_seq               ||   X    |        |   X    |        |
     +---------------------------------++--------+--------+--------+--------+
     | reference_ref_id_seq            ||   X    |        |   X    |        |    
     +---------------------------------++--------+--------+--------+--------+
     | reference_sys_ref_system_id_seq ||   X    |        |   X    |        |
     +---------------------------------++--------+--------+--------+--------+
     | sensor_sid_seq                  ||   X    |        |   X    |        |
     +---------------------------------++--------+--------+--------+--------+
     | sig_class_sig_class_id_seq      ||   X    |        |   X    |        |
     +---------------------------------++--------+--------+--------+--------+
     | signature_sig_id_seq            ||   X    |        |   X    |        |
     +======================================================================+
     
    The following SQL statement is an example of assigning permissions to
    database entities (tables).

    [PostgreSQL] : GRANT select ON schema TO base_user 
    [MySQL]:       GRANT select ON `schema` TO base_user

    (Gives the SELECT privilege to the 'schema' table to user 'base_user')
    (With MySQL "schema" has become a reserved word. 
     Therefore the backticks.) 

3.  Install Apache, PHP (and GD).  There are many configuration options whose 
    specifics are best addressed by the appropriate package's documentation.  
    Here are several suggestion.

    o The PHP build that is used must have support for
        - either MySQL, PostgreSQL, or MS SQL
        - GD
        - socket functionality.  
     
      The following is an example of the necessary options to the ./configure 
      script when building from source.

       ./configure [your config options] --with-mysql --with-gd --enable-sockets

       (MySQL support)

       ./configure [your config options] --with-pgsql --with-gd --enable-sockets

       (PostgreSQL support)

      In the case where building PHP from source is undesirable or inconvenient
      (e.g. Windows) binary distributions can be used.  However, most do not
      provide some of the required functionality (e.g. GD or PostgreSQL support).  
      To add this functionality, PHP dynamic module loading (extensions) can be used.
      Examine the following PHP document for the installation of extensions 
      under Windows, http://www.php.net/manual/en/install-windows.php.   

    o PHP will execute more efficiently if run as an Apache module
      (--with-apxs in the ./configure script).  However, it is possible to
      run PHP as a CGI application and under different web servers. It should
      be noted that these configurations are untested. 

4.  Edit the PHP configuration file, php.ini, and make the following changes: 

    [All OSes]
 
    o Set the 'display_errors' variable to 'off' (display_errors = off) for
      production deployments of BASE.  This setting will prevent debugging
      messages from being included inline to the HTML.  If it is desired to
      to have some debugging messages sent inline, then it is recommended  
      to at least set the 'error_reporting' variable to 'E_ALL & ~E_NOTICE'
      (error_reporting = E_ALL & ~E_NOTICE).

    [Windows]

    o For PostgreSQL support, uncomment the following line:

       extension=php_pgsql.dll

     For MSSQL support, uncomment the following line:

       extension=php_mssql.dll

     (For MySQL support, nothing special needs to get done)

    o Set the 'SMTP' variable to refer to your SMTP server.
    
    o Set the 'session.save_path' variable to a temporary directory writable
      by the web server (e.g. c:\temp).

    [UNIX]

    o Set the 'sendmail_path' variable to the full path to your mail transfer
      agent (MTA) such as sendmail.

5.  Start the web server.

6.  Uncompress and install ADODB 4.9+.  This process should be as simple as
    copying the files into a directory viewable by the web server and
    PHP.  In the case of Apache, any child directory of 'DocumentRoot'
    set in httpd.conf.

    [UNIX]
      $ cp adodb494.tgz /home/httpd/html
      $ cd /home/httpd/html
      $ tar xvfz adodb494.tgz
      $ cd ..

7.  If you do not have PEAR::Image_Graph installed follow the below instructions

    [UNIX]
      $ pear install Image_Color
      $ pear install Log
      $ pear install Numbers_Roman
      $ pear install Numbers_Words
      $ pear install http://download.pear.php.net/package/Image_Graph-0.7.2.tgz
      $ pear install Mail_Mime


8.  Verify that cookie support in the browser is enabled.  

    [Netscape 4.*]

     o Choose 'Edit->Preferences' from the menu bar
     o Click on the 'Advanced' tree item and select either "Accept all cookies" 
       or "Only accept cookies from the same server as the page being viewed" 
       from the cookie options.

    [Mozilla 0.9.3]

     o Choose 'Edit->Preferences' from the menu bar 
     o Click on the "Privacy and Security->Security" tree item and select either 
       "Enable all cookies" or "Enable cookies for originating web site only" 
       from the cookie options.
    
    [IE 5.*]
 
     o Choose 'Tools->Internet Options' from the menu bar
     o Click on the 'Security' tab
     o Choose the appropriate web content zone
     o In the 'Security Settings' window, find and choose 'enable' (or 'prompt') 
       for the options 'Allow cookies that are stored on your computer' and 
       'Allow per-session cookies (not stored)'

9.  (Optional) Install signatures into BASE install
    
     o Create a directory named signature/ in the BASE install directory
     o Copy any signature txt file you would like into that directory 
  
  
IV. CONFIGURATION
_____________________________________

9. The file base_conf.php.dist needs to be copied to base_conf.php.  This
    will enable you to edit the configuration while retaining the original
    settings in case you have problems.
    The file 'base_conf.php' controls the configuration of BASE.  

    Note: 'base_conf.php' is PHP code which will be included in each 
          BASE page request.  As such, it is imperative that the opening 
          '<?php' and closing '?>' tags not be removed from the file. Likewise,
          no extra lines can be found before or after these '<?php' '?>'
          delimiters.
 
          All conventions of the PHP language (e.g. comments) apply to the
          'base_conf.php' file.  For example, the comment characters are
          either a '//' or '/* ... */'.

             // comment #1

             /* multi-line comment #1
                multi-line comment #2 
              */

    The general format of each configuration entry is:

       $<variable name> = <value>;

    Variable names are case sensitive.

   
    The following options will need to be set with site specific information in
    order for BASE to function properly.  Aside from this minimal 
    configuration, there are a number of other settings which can be tweaked.
    Please see http://sourceforge.net/projects/secureideas for an 
    exhaustive list.

       o $DBlib_path     : full path to the ADODB installation
                           (Note: do not include a trailing '\' character)

       o $DBtype         : type of the database used ("mysql", "postgres", "mssql")
       o $Use_Auth_System: Set this to 1 if you would like to use the user authentication
                            system.  Remember add a user before setting it to 1!
       o $BASE_urlpath   : This needs to be set to the root URI of your site.
                            example: /~kjohnson/base

       o $alert_dbname   : alert database name 
       o $alert_host     : alert database server
       o $alert_port     : port where the database is stored
       o $alert_user     : username for the alert database
       o $alert_password : password for the username

       [OPTIONAL for alert archiving support]

       o $archive_exists   : Set to 1
       o $archive_dbname   : archive/backup database name 
       o $archive_host     : archive database server
       o $archive_port     : 
       o $archive_user     : "root";
       o $archive_password : "mypassword";

10. Open the base_main.php page in a browser.  If the any database changes 
    are required, BASE will prompt for action.  

    For new databases, several BASE specific tables will need to be created.  
    When running BASE for the first time, an error message will appear:

      | The underlying database appears to be incomplete/invalid.
      |
      | The database version is valid, but the BASE DB structure is not present. 
      | Use the _Setup page_ to configure and optimize the DB.

    Click on the "Setup page" link to be brought to the DB configuration page
    (base_db_setup.php).  This next page will facilitate the creation of
    the necessary tables.  Click on the "Create BASE AG" buttons as seen
    below.

      | BASE tables  Adds tables to extend the Snort DB to   [Create BASE AG] 
      |             support the BASE functionality

    After the tables are created, BASE will return status indicating success.

11. Read the security notes about deploying BASE.


V. SECURITY
_____________________________________

As with any software, an appropriate deployment strategy must be employed.  
The following are some recommendations and notes about the security of BASE.

  o Run BASE only on encrypted connections for many of the queries could return
    potentially sensitive information.  The use of HTTPS (SSL/TLS) is highly
    recommended (mod_ssl -- http://www.modssl.org  provides this functionality for 
    Apache).

  o There is currently a simple authentication mechanism in BASE.
    However, both can be provided by tweaking the underlying components.  Use
    native web server authenticate techniques to identify users connecting 
    to the BASE pages (e.g. basic or digest HTTP authentication or X.509 certificates 
    with mod_ssl).

    Authorization can also be provided through per-file or per-directory access
    control methods specific to the web server (e.g. through .htaccess files in 
    Apache).  Furthermore, the specific actions which can be performed on 
    the individuals alerts in the database can be controlled to a certain degree
    through the privileges assigned to the underlying database user configured
    in BASE.  For example, the ability to delete alerts can be easily controlled
    by granting or revoking the DELETE SQL privilege from the BASE database
    user.  Thus, by create two separate users each set in two different instances
    of BASE, a read-only and a full-access configuration can be established.

  o While the primary interface of BASE is through a web browser, proper file
    permissions still need to be set on the local file system.  These permissions
    will protect against potential unauthorized viewing or modification of 
    BASE files by users who have local accounts to the web server.

  o BASE is currently _beta_!  Currently no real work has been done in validating any input.  
    This means that the code may allow arbitrary access to the underlying database.
    Exercise extreme caution in deploying this application in a public area.

  o The alert (and archive) database passwords configured in BASE are stored in
    clear-text in the file system.  Their security is contingent on the settings
    of the local file system permissions.  Furthermore, these passwords are 
    hard-coded in the application and are only as secure as any other PHP "code" from
    being exposed in unparsed form.  Improper configurations of the web server can 
    result in the exposure of these passwords if unparsed PHP files are returned.