Analysis Console for Incident Databases (ACID) v0.9.6

by Roman Danyliw <rdd@cert.org>, <roman@danyliw.com>

This plugin was developed at the CERT Coordination Center as a part 
of the AIRCERT project.

See http://www.cert.org/kb/acid for the most up to date 
information and documentation about this application.

Mirrored: 
http://acidlab.sourceforge.net
http://www.andrew.cmu.edu/~rdanyliw/snort/
(usually contains the latest beta code)

-------------------------------------------------------------------------------
** Copyright (C) 2000 Carnegie Mellon University
**
** Author: Roman Danyliw <rdd@cert.org>, <roman@danyliw.com>
**
** 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
========

ACID is a PHP-based analysis engine to search and process a database of 
security incidents generated by the security-related software such as the 
NIDS Snort.  The features currently include:

 - Search interface for finding alerts matching practically any criteria.
   This includes arrival time, sensor, signature time, source/destination 
   address/port, flags, payload, etc.  These queries can be 
   made arbitrarily complex to satisfy almost any parameters.

 - Alert Groups: allow for a logical grouping of alerts on which 
   analysis can be done.  It a quick way to combine multiple searches or
   to associate a comment with an alert or group of alerts 

 - Alert purging: allows for the deletion of alerts from the database.  
   This functionality is ideal for removing known false-positives.

 - Statistics:
    - Snapshot statistics to assess current network state 
    - Aggregate statistics on a per sensor, IP, or alert basis 
    - Graphing alert arrival over time 

 - All features are provided in real-time 

II. PREREQUISITES
=================

 - MySQL 3.23+ or PostgreSQL 7.1+ as the database used by Snort to store the 
   alert information.

 - PHP 4.0.4+ enabled Apache web server.
     = PHP must be compiled with MySQL or PostgresSQL support 
       (--with-mysql or --with-postgresql)
     = PHP must also be compiled with the BCMath library enabled
       (--enable-bcmath)
     = If graphing functionality is desired, GD support must
       also be compiled (--with-gd), and for native whois query
       support socket functionality must be enabled (--enable-sockets) 
  
 - Snort v1.7. Upgrading to this newer version
   of the database plugin has significant logging advantages.  See Jed's 
   documentation in README.database of the Snort source code.

 - ADODB v0.93+.  This database abstraction library can be found at
   http://php.weblogs.com/adodb

 - Web browser capable of supporting cookies.

 - (optional) For graphing functionality
      = GD 1.8.*: This is the underlying image library used by PHPlot
        http://www.boutell.com/gd/
      = PHPlot v4.4.6+: This PHP graphing library can be found at 
        http://www.phplot.com

III. INSTALLATION
=================

 0. At this point it is assumed that PHP is working and that Snort is 
    successfully logging to a database.

    If not, check the following sites for configuration help:
      = Apache: www.apache.org
      = PHP: www.php.net
      = Snort: www.snort.org
      = Snort DB-plugin: www.incident.org/snortdb (documentation)

 1. Install the underlying software libraries:
      = Uncompress and install ADODB into a directory viewable/served
        by PHP.  Specifically remember to configure the $ADODB_DIR
        in adodb.inc.php
      = Uncompress and install PHPlot into a directory viewable/server 
        by PHP.

 2. Copy the ACID distribution into a directory viewable/served by 
    the PHP server.

      e.g.  % cp acid.0.9.5.tar.gz /home/httpd/html

 3. Extract and uncompress the ACID distribution.

       eg.  % tar xvfz acid.0.9.5.tar.gz 

 4. Change into the newly created ACID directory

       % cd acid

 5. Open the acid_main.php page in a browser.  If the
    any database changes are required, ACID will prompt
    for action.  Adding index support (if not already
    present) is highly recommended.  If a setup page does not
    open automatically, open 'acid_db_setup.php'. 

    Note: in order to make changes to the database, the database
    account used by ACID (configured in acid_conf.php) must have
    at a minimum these privileges: INSERT, UPDATE, SELECT, DELETE. 
  
IV. CONFIGURATION
=================

 6. The file 'acid_conf.php' controls the configuration of ACID.  

    This file is PHP code which will be included in each ACID page 
    request.  Since 'acid.conf' is PHP, it is imperative that the opening 
    '<?php' and closing '?>' tags not be removed from the file. 
    Furthermore as a PHP file, all conventions of the PHP language (i.e. 
    comments) apply.

    The general format of each configuration entry is:

       $<variable name> = <value>;
   
    The only variables which need to be changed from their default 
    configuration is the database connection information.  These variables
    are as follows

       = $DBlib_path     : full path to the ADODB install
       = $DBtype         : type of the database used ("mysql", "postgres")

       = $alert_dbname   : database name where the alerts are stored 
       = $alert_host     : host where the database is stored
       = $alert_port     : port where the database is stored
       = $alert_user     : username into the database
       = $alert_password : password for the username

       = $ChartLib_path  : full path to the PHPlot install

    Much of this information can be extracted from the Snort database plugin
    configuration.

    NOTE on PostgreSQL: Due to the user shadowing scheme of authentication, 
    remember that the user running the webserver will need to be given access 
    to the database!

  6. Read the security notes about deploying ACID.


V. SECURITY
===========

  - ACID is currently _beta_.  No real work has been done in validating
    any input.  Therefore, exercise extreme caution in deploying this
    application to a public area.

  - The Snort database passwords configured in ACID are only as secure
    as any other PHP "code".
