# $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 ` If you want your users/passwd file to be somewhere other than /etc/sguild/sguild.users or ./sguild.users, then use the -u switch. You can delete users using `sguild -deluser ` 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 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 /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//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/ -c /etc/snort/snort.conf -U -A none -m 122 -i *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: output sguil Start Barnyard: sguil@syn: /usr/local/bin/barnyard -c /etc/snort/barnyard.conf \ -d /snort_data/ -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