+----------------------------------------------------------------------+
| PIX Logging Architecture v1.01: Installation and Configuration Guide |
+------------------------------+-------------------+-------------------+
| kristof.philipsen@ubizen.com | Sun, Oct 12, 2003 |  version #1.01/1  |  
+------------------------------+-------------------+-------------------+

+--------------------------------------------------+
| Table of Contents                                |
+--------------------------------------------------+
| 1. Introduction                                  |
| 2. Deployment Options                            |
|    2.1 PLA Infrastructure Layout                 |
|    2.2 PLA Centralized Deployment                |
|    2.3 PLA Distributed Deployment                |
| 3. Installation                                  |
|    3.1 Installation Requirements                 |
|    3.2 Installing Parsing Scripts                |
|    3.3 Installing Web-based Frontend             |
| 4. Configuration                                 |
|    3.1 Configuring PIX Firewall                  |
|    3.2 Configuring Syslog                        |
|    3.3 Configuring MySQL Database                |
|    3.4 Configuring Parsing Script                |
|    3.5 Configuring Web-based Frontend            |
| 5. Additional Information                        |
+--------------------------------------------------+

====================================================
====================================================


1. INTRODUCTION

   The PIX Logging Architecture [PLA] provides a centralized method for correlating and
   displaying logs generated by Cisco PIX Firewalls. Cisco PIX supports logging to a
   syslog host. PLA uses this feature in order to parse these logs, based on their type
   (traffic or ids) and then push them into a MySQL database. A web-based frontend queries
   the MySQL database for the entries and then displays them according to the various 
   options available in the PLA web-based frontend.
 
   The web-based frontend supports the following features:

     * PIX Traffic Log Entries
     * PIX IDS Log Entries
     * PIX Traffic & IDS Log Statistics
     * PIX Traffic & IDS Log Search
     * Event Management (Incident Reporting)
     * PIX Traffic/IDS Log Details
     * Whois and IP Lookup

   More information about the web-based frontend will soon be made available on the PLA website,
   located at http://packet.sequenced.org/projects/pla/ 

   
2. DEPLOYMENT OPTIONS

   2.1 PLA INFRASTRUCTURE LAYOUT

       As previously mentioned, the PLA Infrastructure parses logs sent by a Cisco PIX Firewall, and then pushes
       them to a MySQL database. The parsing is done on the system defined as the syslog host for the Cisco PIX
       Firewall, the parsing script then uses the Perl DBI module to enter the logging information into the 
       MySQL database.

       Two deployment infrastructures can be considered:

       - Centralized Deployment: all PLA components are located on the same system.
       - Distributed Deployment: various PLA components are located on different systems.

   2.2 PLA CENTRALIZED DEPLOYMENT

       When using the PLA Centralized Deployment option, all PLA components are located on the same systems. This
       deployment could be used for various reasons, such as shortage of machines, centralized management policy.
       The following components are centralized on a single component:
           - syslog
           - MySQL database
           - Apache Web Server
           - PLA Parsing Script
           - PLA Web-based Frontend

       The PLA Centralized Deployment architecture looks as follows:

       +---+   syslog    +------------------------+
       |PIX| ----------> | PLA Centralized System |
       +---+             +------------------------+
                         | (1) Parse Syslog       |
                         | (2) Populate Database  |
                         | (3) Provide Web-based  |
                         |     frontend           |
                         +------------------------+

   2.3 PLA DISTRIBUTED DEPLOYMENT

       When using the PLA Distributed Deployment option, each PLA component or a group of PLA components are located
       on various systems. 

       The PLA Distributed Deployment architecture looks as follows:

       +---+   syslog    +------------------------+               +------------------------+
       |PIX| ----------> | PLA Distributed System |               | PLA Distributed System |
       +---+             | Logging Host           |               | DB + Web Frontend      |
                         +------------------------+  Perl::DBI    +------------------------+
                         | (1) Parse Syslog       | ----------->  | (2) Populate Database  |
                         +------------------------+               | (3) Provide Web-based  |
                                                                  |     frontend           |
                                                                  +------------------------+


3. INSTALLATION
 
   3.1 INSTALLATION REQUIREMENTS

       The PLA Infrastructure requires certain components to be installed in order to function properly. The following
       components must be installed:

       * Perl (version >= 5.6.0)
         --> Perl is used to run the scripts associated with PLA.
       * Perl Modules
         --> Perl::DBI (version >= 1.20)
         --> Perl::CGI (version >= 1.19)
       * MySQL Database (version >= 3.23.42)
       * Apache (or your preferred) Web Server 

       The PLA scripts are written in Perl, and should therefore work on any system supporting Perl. I'm personnally
       running this infrastructure on Linux, and I've had no problems so far. If you run this on any other platforms,
       i.e. ActivePerl on Windows or so, please send me an email (kristof.philipsen@ubizen.com) so I can add your
       platform to the compatibility list.

   3.2 INSTALLING PARSING SCRIPTS

       The parsing script is located in the "scripts/parsing/" directory of the PLA Software Package. This script must
       be installed on the system which received the system logs (syslog) and is used to identify which log entries
       should be pushed to the database, this script requires both Perl and Perl::DBI. Personally, I've put this script
       in an "/etc/pix/" directory, which I've created on the system receiving the syslog messages from the Cisco PIX.
       The parsing script is called "pix_log_mysql". This script also requires a specific syslog configuration, which
       is shown in the Configuration section of this document. The script basically uses Regular Expressions to match
       for conditions within syslog messages, and then pushes the necessary parameters to the MySQL database using the
       Perl::DBI Module.
 
   3.3 INSTALLING WEB-BASED FRONTEND

       The web-based frontend is a collection of Perl/CGI scripts located in the "scripts/frontend/" directory of the
       PLA software package. These scripts query the MySQL database for information and entries pertaining to the 
       Cisco PIX logs. These scripts should be copied to a scripts executable directory on your web server. For example
       the "/cgi-bin/" directory on many web servers. The web-based frontend consists of the following scripts:

	- about 			-> Information about PLA
        - conf.pl			-> PLA General Configuration File
        - pix_event_create		-> Create an Event (Incident)
        - pix_event_create_process	-> Process the creation of an event
        - pix_event_edit 		-> Edit an Event (Incident)
        - pix_event_edit_process	-> Process the editing of an event
        - pix_event_id_add		-> Add a PIX Log entry to an event
        - pix_event_id_process		-> Process the addition of a PIX Log entry to an event
        - pix_event_management		-> Event Management
        - pix_event_view		-> View Event Details
        - pix_ids_id			-> View PIX IDS Log Details
        - pix_ids_logs			-> List PIX IDS Logs
        - pix_search_logs		-> Search PIX Traffic and IDS Logs
        - pix_search_result_ids		-> Results of PIX Traffic Logs Search
        - pix_search_result_traffic	-> Results of PIX IDS Logs Search
        - pix_stats			-> PIX Traffic and IDS Statistics
        - pix_traffic_id		-> View PIX Traffic Log Details
        - pix_traffic_logs		-> List PIX Traffic Logs
        - src-whois			-> Perform a whois of a given IP
        - subs.pl			-> PLA subroutines


4. CONFIGURATION

   4.1 CONFIGURING CISCO PIX FIREWALL

       In order to get a Cisco PIX Firewall to be compatible with the PIX Logging Architecture, several configuration
       statements will have to be added on the Cisco PIX Firewall:

       A. Configuring System Logging
 
          pix(config)# logging on
          pix(config)# logging timestamp
          pix(config)# logging trap informational
          pix(config)# logging facility <logging facility>
          pix(config)# logging host inside <logging host>

          -> the "logging facility" defines where systems messages will be logged on the system host, I've set it to
             "22", which corresponds to logging facility local6 on a UNIX Syslog System. 
             For more information about setting up PIX System Logging and Logging Facilities, refer to the following URL:
             http://www.cisco.com/en/US/products/hw/vpndevc/ps2030/products_tech_note09186a0080094030.shtml

          -> the "logging host inside" statement defines where to send the syslog messages, this should be the IP address
             of the system running the PLA Parsing Script.

       B. Configuring IDS Logging

          pix(config)# ip audit name info info action alarm
          pix(config)# ip audit name attack attack action alarm drop reset
          pix(config)# ip audit interface outside info
          pix(config)# ip audit interface outside attack
          pix(config)# ip audit info action alarm
          pix(config)# ip audit attack action drop

          -> this configuration enables the PIX to match IDS signatures and perform a drop action on them. In the above
             configuration, the interface is named "outside"; In your infrastructure, this interface may have another name.

   4.2 CONFIGURING SYSLOG
            
       The syslog host will receive the alerts sent by the Cisco PIX Firewall(s). 
       
       First of all, the syslog daemon will need to be configured to listen for syslog messages from other hosts, in our case 
       the Cisco PIX Firewall(s) on port 514/udp, this can be done by starting the syslogd in the following manner: 
       "syslogd -m 0 -r" -> the "-r" option specified remote listening. 

       Secondly, Syslog will need to be configured to redirect system log messages received from the Cisco PIX Firewall(s) to
       a separate file (I'm using "/var/log/pix-mysql.log"). In order to do this you'll have to reconfigure /etc/syslog.conf
       by adding the following line:

          "local6.*                                                /var/log/pix-mysql.log"

       The "local6.*" facility is used here because I chose "logging facility 22" on the Cisco PIX Firewall, therefore this 
       may need to be changed if you're using a different logging facility. 

       The "/var/log/pix-mysql.log" file may also be different in your configuration, but do note that you will need to define
       this file as a variable($pix_log_file) in the PLA parsing script. 

   4.3 CONFIGURING MYSQL

       Since MySQL (the database) is the primary component empowering the PLA infrastructure, it needs to definately be configured
       properly.  

       First of all, the PIX logging database needs to be created. A template for this database is located in the "scripts/" 
       directory of the PLA Package and is called pix_database.sql. This file can easily be imported into the MySQL database 
       as follows:

           root@mysql-host# cd <PLA-Package-Directory/scripts
           root@mysql-host# mysql < pix_database.sql

       Secondly, a user must be created that is allowed full access only to the "pix" database. This user will be used both
       by the PLA Parsing script to push data into the database, and by the PLA Web-based Frontend to retrieve information
       from the database. The user can be created in the following manner:
 
           root@mysql-host# mysql -u root mysql
           mysql> GRANT ALL PRIVILEGES ON pix.* TO <user>@*.* IDENTIFIED BY '<password>';

       Remember to write down the user and password, you'll need to use these as variables in the PLA scripts.

   4.4 CONFIGURING PLA PARSING SCRIPT
  
       The PLA Parsing script, located on the syslog host, will need to be configured with several parameters before PLA
       can be configured. 

       A. Configure Variables

          Several variables will need to be configured in the "pix_log_mysql" (PLA Parsing) script:

          $mysql_db_host = "<mysql_logging_host>";     # Host running MySQL Database
          $mysql_db_port = "<mysql_logging_port>";     # Port on which MySQL is running (usually: 3306)
          $mysql_db_user = "<mysql_logging_user>";     # Username you configured in the MySQL database
          $mysql_db_pass = "<mysql_logging_pass>";     # Password you configured in the MySQL database
          $pix_log_file  = "<mysql_logging_file";      # PIX Logging file you configured in /etc/syslog.conf

       B. Configure Script Execution

          The PLA Parsing script should be executed at regularly, in order to have as close to a real-time logging
          as possible. I'm executing the script for "crontab", and I've got the execution interval set to 5 minutes.
          The following crontab entry allows my script to be executed every 5 minutes:

          "*/5 * * * * /etc/pix/pix_log_mysql"

   4.5 CONFIGURING WEB-BASED FRONTEND

       First of all, make sure the scripts in the "scripts/frontend/" directory of the PLA Package are copied to a 
       directory configured to execute Perl/CGI scripts.

       Secondly, several variables need to be configured to allow the frontend to connect to the MySQL database.
       These variables can be found in the "conf.pl", which is also located within this directory:

          $mysql_db_host = "<mysql_logging_host>";     # Host running MySQL Database
          $mysql_db_port = "<mysql_logging_port>";     # Port on which MySQL is running (usually: 3306)
          $mysql_db_user = "<mysql_logging_user>";     # Username you configured in the MySQL database
          $mysql_db_pass = "<mysql_logging_pass>";     # Password you configured in the MySQL database


5. ADDITIONAL INFORMATION

   Sometime soon I'll be putting some more documents of the PIX Logging Architecture project online. These documents
   mainly concern the Web-based Frontend, since I haven't had much time to work on this. But they'll be coming!!
   
   Keep checking for updates on: http://packet.sequenced.org/projects/pla/

   Any questions? --> email: kristof.philipsen@ubizen.com



