# $Id: INSTALL,v 1.21 2006/02/10 18:10:10 bamm Exp $ #

NOTE: If you are upgrading from an older version of 
guil to version 0.6.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'
           WITH GRANT OPTION;
    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: If you choose to let sguild
create the DB for you, then you still need to use 'GRANT'
to give privledges for each sensor to INSERT,SELECT in
the database.

NOTE-2: 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"
Make sure each sensor has INSERT and SELECT privledges:
  Bamm@syn# mysql -u sguil -p -e "GRANT INSERT,SELECT on sguildb.* to <user>@<sensorip>"
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.
  +-------------------+
  | Tables_in_sguildb |
  +-------------------+
  | history           |
  | portscan          |
  | sensor            |
  | sessions          |
  | status            |
  | user_info         |
  | version           |
  +-------------------+

##########################################
#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. If you plan
on using OpenSSL between the servers and client, don't forget
to read the README.openssl file in the docs 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) 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)

5) 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.

6) 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.

7) 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.

8) 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.

9) 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 -o (enable OpenSSL) and -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/).

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 are included in the the sguil tarball. These 
  patches are NOT required for sguil to function. Instead, they are 
  used to provide more data to analyst that he/she can view from the
  sguil console. The two patches include one for spp_stream4 and 
  another for spp_portscan. The patch for spp_stream4 allows you to
  configure snort to write session data in a pipe delimiated text
  file for easy loading by sensor_agent.tcl into the DB. The 
  spp_stream4 patch can still be used, but sancp is recommended. The 
  patch for spp_portscan adds a configuration option to write portscan
  data to a pipe deliminated file, again for easy loading into the
  DB. The spp_portscan patch also facilitates the logging of portscan
  events to log_unified as well as establishes a 'priority' of 5 to
  those alerts.
 
  
  First, download the source for snort from http://www.snort.org/dl.
  Untar the package. If you wish to utilize the sguil patches,
  change to the preprocessors directory and make a
  back up of the portscan and stream4 preprocessor:
    Bamm@syn# cd src/preprocessors
    Bamm@syn# cp spp_portscan.c spp_portscan.c.bak
    Bamm@syn# cp spp_stream4.c spp_stream4.c.bak
  Then copy the patch files from the sguil source tree to the snort
  source tree and patch the preprocessors:
    Bamm@syn# cp <sguil-src>/sensors/snort_mods/2_1/spp_portscan_sguil.patch .
    Bamm@syn# cp <sguil-src>/sensors/snort_mods/2_1/spp_stream4.patch .
    Bamm@syn# patch spp_portscan.c < spp_portscan_sguil.patch
    Bamm@syn# patch spp_stream4.c < spp_stream4_sguil.patch
  
  Now, compile and install snort as normal. You do NOT need to enable
  mysql when compiling snort as barnyard will handle that function.

  Next, configure snort to use the new portscan and stream4 preprocessors
  and the log_unified output plugin:

    Format for the portscan mod is:
      preprocessor portscan: $HOME_NET <ports> <secs> <logdir> <sensorname>
        <logdir> must exists and will be read by portscan_loader.tcl
    EXAMPLE:
      preprocessor portscan: $HOME_NET 4 3 /snort_data/<sensorname>/portscans syn

    Format for the stream4 (keepstats) mod is:
      keepstats db <log path>
    EXAMPLE:
      preprocessor stream4: detect_scans, disable_evasion_alerts, keepstats db /snort_data/<sensorname>/ssn_logs
    
    Enable unified logging with this line:
      output log_unified: filename snort.log, limit 128

    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

  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
    Bamm@syn# ls /snort_data/<sensorname>/
    portscans  ssn_logs
   
  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.6.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 -w /etc/snort/waldo.file

B. Next install and start the sensor_agent.tcl from the ./sensor directory.
The configuration file sensor_agent.conf should be configured appropriately.
You can define the location of the config file with the -c switch. By default
sensor_agent.tcl will look in /etc and the current working directory if the -c
switch is not specified. On startup sensor_agent.tcl 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). The sensor agent forwards
portscan, session, and sancp files to sguild for loading to the DB. It also is
the main communications link between the sensor and sguild as well as 
receives alerts from barnyard and passes them up to sguild for insertion.

############
#   DONE!  #
############
Read the USAGE for information about using sguil.tk.

Bammkkkk

