Analysis Console for Incident Databases (ACID) v0.9.6

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

This application 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/

CVS     :  cvs.acidlab.sourceforge.net

-------------------------------------------------------------------------------
** Copyright (C) 2000, 2001 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 Analysis Console for Intrusion Databases (ACID) 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

ACID 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)
     - Cisco PIX
     - 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 2000
      Version:      8.00.194+
      Description:  Commercial RDBMS
      Reason:       Back-end database
      Homepage:     http://www.microsoft.com/sql/default.asp

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

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

   -  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+
    Description:  Web scripting language
    Reason:       Implementation language of ACID
    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:      1.2+
    Description:  PHP database abstraction library
    Reason:       PHP provides no clean database API
    Homepage:     http://php.weblogs.com/adodb/

 o  Package:      PHPlot
    Version:      4.4.6+
    Description:  PHP chart library
    Reason:       Set of PHP classes over GD to generate charts
    Homepage:     http://www.phplot.com
    Type:         optional

 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

 o Any web browser capable of supporting cookies


III. INSTALLATION
_____________________________________

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

1.  [OPTIONAL] Prior to deploying ACID, successful logging of alerts from 
    the sensor (be it Snort, logsnorter, etc.) to the database should be confirmed.
    ACID 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 ACID.  The minimum permissions for each relation (table) 
    are listed in Table 1.

     Table 1: Required database permissions on tables used by ACID
 
                           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    |
     +------------------++--------+--------+--------+--------+
     | 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 ACID (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).

    [MySQL and PostgreSQL] : GRANT select ON schema TO acid_user 

    (Gives the SELECT privilege to the 'schema' table to user 'acid_user') 

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-apache 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 ACID.  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 1.2+.  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 adodb112.tgz /home/httpd/html
      $ cd /home/httpd/html
      $ tar xvfz adodb112.tgz
      $ cd ..

7.  Uncompress and install PHPlot 4.4.6+.  Again, this installation should
    involve only copying the files into a directory viewable by the web
    server and PHP.

    [UNIX]
      $ cp phplot-4.4.6.tar.gz /home/httpd/html
      $ cd /home/httpd/html
      $ tar xvfz phplot-4.4.6.tar.gz
      $ cd ..

8.  [OPTIONAL] Confirm that GD support has been properly configured in
    PHP by opening a browser and attempting to view the PHPlot diagnostics page
    examples/test_setup.php (the full URL will depend on where PHPlot was
    installed; e.g. http://mywebserver/phplot/examples/test_setup.php).  If
    PHP has been configured correctly, at least one chart graphic should be
    seen on this page.  Otherwise, PHP has not been configured correctly with
    GD support.

9.  Uncompress and install ACID by copying and expanding it to a directory 
    viewable by the web server and PHP.

    [UNIX]
      $ cp acid-0.9.6.tar.gz /home/httpd/html
      $ cd /home/httpd/html
      $ tar xvfz acid-0.9.6.tar.gz
      $ cd acid

10. 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)'
  
  
IV. CONFIGURATION
_____________________________________

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

    Note: 'acid_conf.php' is PHP code which will be included in each 
          ACID 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
          'acid_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 ACID to function properly.  Aside from this minimal 
    configuration, there are a number of other settings which can be tweaked.
    Please see http://acidlab.sourceforge.net/acid_params.html 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 $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_dbname   : archive/backup database name 
       o $archive_host     : archive database server
       o $archive_port     : 
       o $archive_user     : "root";
       o $archive_password : "mypassword";

       [OPTIONAL for chart support]
  
       o $ChartLib_path     : full path to the PHPlot install
                              (Note: do not include a trailing '\' character)

       o $chart_file_format : graphic format to use for generated charts
                              ("png", "jpeg", "gif").  The selected format should
                              have displayed correctly with the PHPlot diagnostic 
                              page (see Step 8)

       [OPTIONAL for Snort portscan pre-processor support]

       o $portscan_file  : full path to a Snort portscan log file

12. Open the acid_main.php page in a browser.  If the any database changes 
    are required, ACID will prompt for action.  

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

      | The underlying database appears to be incomplete/invalid.
      |
      | The database version is valid, but the ACID 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
    (acid_db_setup.php).  This next page will facilitate the creation of
    the necessary tables.  Click on the "Create ACID AG" buttons as seen
    below.

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

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

13. Read the security notes about deploying ACID.


V. SECURITY
_____________________________________

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

  o Run ACID 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 no authentication or access control mechanisms in ACID.
    However, both can be provided by tweaking the underlying components.  Use
    native web server authenticate techniques to identify users connecting 
    to the ACID 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 ACID.  For example, the ability to delete alerts can be easily controlled
    by granting or revoking the DELETE SQL privilege from the ACID database
    user.  Thus, by create two separate users each set in two different instances
    of ACID, a read-only and a full-access configuration can be established.

  o While the primary interface of ACID 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 
    ACID files by users who have local accounts to the web server.

  o ACID is currently _beta_!  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 ACID 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.

