# $Id: INSTALL,v 1.23 2008/03/21 17:36:12 bamm Exp $ #

NOTE: If you are upgrading from an older version of 
Sguil to version 0.7.0, please use the UPGRADE document
as your guide.
 
Sguil should be installed in the following order:

Step 1: Install mysql and create the sguil database.
Step 2: Install the GUI server (sguild).
Step 3: Install the GUI client (sguil.tk).
Step 4: Install the sensor.

NOTE: Everything can be installed on a single system,
or the different services can be split up between 
different systems. For instance, snort and barnyard
can be installed on one sytem (the sensor), the GUI
server on another system, the database on yet another
system, and the client could be run on a number of
different systems. The configuration is flexible and
the number of systems required depends on the
resources needed. Large networks will benefit by
splitting the different processes up on different
sytems, while a home user should easily be able to
run everything on a single system.
 
######################################################
#Step 1: Install mysql and create the sguil database.#
######################################################

Install mysql (http:www.mysql.com) per its installation
instructions. 

########## Security Note ##########
Some operating systems install mysql-server with a 
'root' admin account and NO passwd. Use the below steps
to correct this oversight.

    shell> mysql -u root mysql
    mysql> UPDATE user SET Password=PASSWORD('dbpasswd')
           WHERE user='root';
    mysql> FLUSH PRIVILEGES;

It is also recommended that you create a 'sguil' user in
mysql and use that account for your sguil installation.

    shell> mysql -u root -p mysql
    Enter password:
    mysql> GRANT ALL PRIVILEGES ON sguildb.*
           TO sguil@localhost IDENTIFIED BY 'sguilpasswd';
    mysql> FLUSH PRIVILEGES;
######## End Security Note ########
  
You can either create the DB structure using the 
below methods now, or skip to 'Installing sguild',
section where it will prompt to create the DB structure
for you on init.

NOTE: It's highly recommended that you set your time-
zone (TZ) to GMT prior to starting mysqld. This can
often be done inside your mysqld init script.

If you want to create the sguild database prior to starting
sguild for the first time then use these instructions:
  Bamm@syn# mysql -u sguil -p -e "CREATE DATABASE sguildb"
Build the required tables:
  Bamm@syn# mysql -u sguil -p -D sguildb < ./server/sql_scripts/create_sguildb.sql
  *NOTE: Verify all is well with: mysql -u root -p -e "show tables". As of Sguil 
         version 0.6.0, you will no longer see event, tcphdr, udphdr, icmphdr,
         data, and sancp tables after a fresh install. They will be created by
         sguild as data comes in from sensor_agent.

##########################################
#Step 2: Install the GUI server (sguild).#
##########################################
Sguild is a tcl script and I would recommend using tcl-8.3
or better. I haven't had time to test lesser versions but
they may work. 

*NOTE: Sguild DOES NOT require root privileges to run. We
recommend you create a 'sguil' user and run sguild under
that account.

1) Create the directory /etc/sguild. I recommend using this
directory for storing all the sguild config files. Copy
sguild.users, sguild.conf, sguild.queries, sguild.access,
and autocat.conf to the /etc/sguild directory.

2) Make sure tcl is installed along with the extended (tclx)
libs (http://tclx.sourceforge.net). Tclx is a common tcl
extensions and packages can be found as a package/port for
most OSes/distros.  To test that tclx is installed:
  tcl> package require Tclx
  tcl>
Any errors indicate that tclx was NOT install or was installed
incorrectly.

BUG NOTE: Some systems may require a symlink be made from 
/usr/lib/libtclx.so to /usr/lib/libtclx8.3.so.

3) Sguild requires mysqltcl support and it can
be downloaded from http://www.xdobry.de/mysqltcl/. Once
installed, test that it can be loaded by invoking the tcl
interpreter (ie /usr/bin/tcl or /usr/local/bin/tclsh8.3)
and adding the package:
  tcl> package require mysqltcl
  tcl>
If you receive no errors than all is good.

(NOTE: On OpenBSD you may need to add the line:
  load /usr/local/lib/libmysqltcl.so.0.0
prior to the line:
  package require mysqltcl
in order for the tcl/tk interpreter to find the package.)

4) Sguild now REQUIRES openssl. Please see the file
OPENSSL.readme for configuration instructions.

5) On startup sguild will attempt to use the tcl interpreter
(tclsh) from your PATH. You may need to create a link from
tclsh8.3 (or similar) to tclsh in the appropriate directory.
(i.e. `ln -s /usr/local/bin/tclsh8.3 /usr/local/bin/tclsh)

6) Configure options within sguild.conf. Pay particular attention
to the PATH you define for sguild to look for snort rules.  In the
future, rules will be localized in the DB, for now each rule file
must be kept on the sguild server based on the hostname. Don't
forget to copy these rule files over after installing the sensor.
As of version 0.4.1, the xscript functions were moved into sguild.

7) Add users to sguild.users file by running `sguild -adduser <username>`
If you want your users/passwd file to be somewhere other than
/etc/sguild/sguild.users or ./sguild.users, then use the
 -u <path> switch. You can delete users using `sguild -deluser <username>`
Again, specify the path of sguild.users if it is in a non
default location.

8) By default the sguild.access file allows any sensor and client
to connect to sguild. Update this file if you want to add access
lists.

9) Other configuration files are included with instructions on
their use in the file itself. These include sguild.email, 
sguild.reports, sguild.conf, autocat.conf, and sguild.queries.

10) Now it is time to start sguild. The command `sguild --help`
will generate a short list of available switches. If you have
placed your config files in a default location (/etc/sguild or
./) then you shouldn't need to specify any paths. Command line
switches like -D (run as a daemon) override the sguild.conf. 
If a database has not been created yet, you will be prompted 
to create it at this point:

    shell> ./sguild
    Error: mysqluse/db server: Unknown database 'sguildb'
    The database sguildb does not exist. Create it ([y]/n)?:
    Path to create_sguildb.sql [./sql_scripts/create_sguildb.sql]:
    Creating the DB sguildb...Okay.
    Creating the structure for sguildb: ...Done
    <snip>
    Sguild Initialized

At this point, sguild is ready to receive connections from sensor
agents and sguil.tk clients.


############################################
#Step 3: Install the GUI client (sguil.tk).#
############################################
Sguil.tk is a tcl/tk script. It requires tcl/tk 8.3 (I haven't tested
lesser versions, they may work), tclx 8.3 (I have heard that
some distros package tclx with the standard tcl libs), incr tcl (itcl)
3.2 (including the iwidgets 2.2 set - see http://www.tcltk.com/iwidgets/
for more info), and the tcllib extension (http://tcllib.sf.net). The
client - sguil.tk - also runs under win32 using the ActiveState tcl
libraries (http://www.activestate.com/Products/ActiveTcl/). Tcl/tk
version 8.5 is NOT supported at this time.

On startup, sguil.tk reads the options in sguil.conf. If a path to
the sguil.conf file is not provided, it will look in the users home
directory and then the current directory by default. To specify the
location for the sguil.conf, start sguil.tk like so:
  shell> ./sguil.tk -- -c <path>/sguil.conf
Explanations for the different options are within the default conf file.

Along with the config file, sguil.tk will also read $HOME/.sguilrc for
font information if it exists. Anytime you change the default font in
sguil.tk, it will write your new preferences to .sguilrc.

NOTE: Until a sensor has been installed and reported its first event,
there will be no sensors to select for monitoring. It is okay to 
start sguil.tk this way anyway, just to make sure sguil.tk and 
sguild can communicate, but remember to restart the client once the
sensor(s) have been configured and are reporting events to sguild.


#############################
#Step 4: Install the sensor.#
#############################
A. Begin by installing snort -

  NOTE: In order to provide better support for sensors monitoring 
  multiple interfaces, we now use default logging directory of
  $LOG_DIR/$SENSOR_NAME (ie /snort_data/sensor1, /snort_data/sensor2,
  etc). This allows us to run multiple snort, barnyard, and
  sensor_agent.tcl instances without munging data together.

  Two patches for snort were once included in Sguil releases. Those
  patches have been depriciated by the use of SANCP and sf_portscan.
  
  First, download the source for snort from http://www.snort.org/dl.
  During the configure, make sure you enable snort statistics via the
  option --enable-perfprofiling. Please read the documentation for
  Snort for adding other options you may need. Sguil does NOT require
  mysql to be enabled for Snort.
 
    If you want to have access to snort statistics from Sguil, enable the perfmonitor
    preprocessor.
    EXAMPLE:
      preprocessor perfmonitor: time 300 file /snort_data/<sensorname>/snort.stats pktcnt 10000

     Enable unified logging with this line:
       output log_unified: filename snort.log_unified, limit 128

       NOTE: The default example shipped with snort uses the filename 
       prefix "snort.log". The pcap (binary) output mechanism also uses
       this naming convention. If pcap files are inadvertantly created with
       the same prefix as unified are, it can cause spool readers like
       Barnyard to crash.

  Make sure all the config files for snort are copied to the appropriate
  directory (ie /etc/snort) and create the appropriate log dirs if you are
  using the sguil patches.
    Bamm@syn# ls /etc/snort/
    gen-msg.map snort.conf classification.config reference.config sid-msg.map
   
  Finally, start snort (best to run snort as a non-root user too. we use -m 122
  so barnyard can read the unfied_log files without root privs.):
    Bamm@syn# snort -u sguil -g sguil -l /snort_data/<sensorname> -c /etc/snort/snort.conf -U -A none -m 122 -i <interface>

  *NOTE: I use a seperate partition /snort_data to do all my logging.
         The -U is to keep all times in GMT (if you don't do this then
         your session data and realtime/pcap data can have different
         times, basically b0rking things.)

B. Start log_packets.sh

The script log_packets.sh is used to log the binary data. It is located 
in the sguil/sensor directory and should be ran on the sensor.  log_packets.sh
runs snort in 'packet logger' mode. Edit the configurations, start the script
(./log_packets.sh start), and then add an entry to the crontab to restart
the script every hour (you can change the interval based on your requirements):
  # Crontab example
  00 0-23/1 * * * /usr/local/bin/log_packets.sh restart

NOTE: By default, log_packets.sh is set up to have snort log EVERY packet on
the network. A bpf filter example is included in the script. Use bpf to tune
the amount of logging based on the available drive space. It is highly
recommended to create a seperate partion for logging data to. The sensor agent
reports currect disk stats to sguild, but the user is responsible for 
deleting/archiving old data at this time.

c. Now install Barnyard -

  Instructions for patching barnyard-0.2.0 to work with sguil-0.7.0 are 
  in the sensor/barnyard_mods/README file of this src. Once you have
  patched and compiled barnyard according to those instructions, continue
  with the configuration below.

  Edit the barnyard.conf and add the following lines to enable the sguil plugin:
    config hostname: <yoursensorname>
    output sguil

  Start Barnyard:
    sguil@syn: /usr/local/bin/barnyard -c /etc/snort/barnyard.conf \
    -d /snort_data/<sensorname> -g /etc/snort/gen-msg.map -s /etc/snort/sid-msg.map \
    -f snort.log_unified -w /etc/snort/waldo.file

B. Next install and start the various agent scripts from the ./sensor directory.
The configuration files for each agent (i.e. snort_agent.conf, pcap_agent.conf, etc)
contain comments in them to help you configure them properly.  You can define the 
location of each config file with the -c switch. By default the agents will look 
in /etc and the current working directory if the -c switch is not specified. On 
startup the agents will attempt to use the tcl interpreter (tclsh) from your PATH. 
You may need to create a link from tclsh8.3 (or similar) to tclsh in the appropriate
directory.  (i.e.`ln -s /usr/local/bin/tclsh8.3 /usr/local/bin/tclsh). A brief 
description of each sensor agent is below.

snort_agent.tcl:   The snort agent creates a socket on localhost and accepts connections
                   from barnyard over it. Barnyard sends realtime alerts from snort via
                   this communication path. The snort agent also tails the snort stats 
                   file and forwards the lines up to sguild.

pcap_agent.tcl:    The pcap agent connects to sguild and waits for raw data requests from
                   it. I uses tcpdump to parse pcap files based on a filter and sends
                   the binary files to sguild.

sancp_agent.tcl:   The sancp agent monitors the specified directory for SANCP stats files.
                   When available, it copies those files up to sguild. Sguild writes those
                   files to a new directory and a loader process comes by and LOADs them
                   into the Mysql database.

 pads_agent.tcl:   The pads agent is still considered alpha. It listens to a FIFO and reads
                   data written by PADS (http://passive.sourceforge.net/). New assets are
                   forwarded to sguild. Sguild processes the information and determines 
                   whether an alert for either a new or changed asset should be created.
                   Please see the PADS.readme for more information.

example_agent.tcl: Sguil now supports a simple interface for new agent types. Example 
                   agent documents how one might go about creating an agent to provide
                   alerts from other sources (OSSEC, syslog, etc). More documention
                   will be provided later. If you have any questions about the example
                   agent and how you can create your own agent, please use the sguil-devel
                   mailing list or join #snort-gui on irc.freenode.net. 

############
#   DONE!  #
############

Please read the USAGE for information about using the Sguil client (sguil.tk)

Bammkkkk

