Benjamin Smee - strerror@disciplina.net
1.01
The point of this HOWTO is to take someone through the process of getting SGUIL up and running on a Gentoo machine. I will also endeavour to explain a little bit about the workings of SGUIL itself but if you are really interested in SGUIL then I recommend going to their site and reading the documentation.
SGUIL can be thought of as a management console for snort, it enables you to do a number of things including the following key features:
Automatic alert categorization
Event correlation
TCP Stream examination, including replays and dumping said stream into Ethereal
and many more check out this post for a nice overview
SGUIL is made up of 3 key components:
Sensor - The sensor runs snort, sancp, barnyard, the sguil sensor agent and a script to log packets. The sensors role is to gather the information that the server will process and act on. This information is placed into a database for storage and reference by barnyard. The log packets script actually stores the relevant tcp streams from all traffic, which means that it can use up a lot of space (as much space as traffic you push around) so its important to make sure that you crontab the script to restart regularly so that it will automatically clean out older files and keep disk usage at a defined level. Its also important with the sensor that you put it on a partition of its own in case it fills up the partition.
Server - The server runs the sguild process that acts as a "GUI" server for the SGUIL client.
Client - The client is a GUI interface to the SGUIL server. It allows you to perform all the functionality that SGUIL offers, mostly from right clicks on different columns that are displayed.
For best performance and scalability it is recommended that you run the sensor and server on separate machines but in the interests of getting something up and running this HOWTO will assume that the sensor and server will be installed on the same machine. The aim of this HOWTO is for the user to have a working SGUIL installation up and running and accessible by the client.
There are no requirements beyond the installation of the relevant packages. That said, it is HIGHLY recommend that you mount /var/lib/sguil on its OWN partition and NOT on the same mount point as /var. As I have just put all the SGUIL components into portage so all that has to be done is to put the relevant ebuilds into /etc/portage/packages.keywords. The following should do it:
echo -e "net-analyzer/sguil-server ~x86\nnet-analyzer/sguil-client ~x86\nnet-analyzer/sguil-sensor ~x86\nnet-analyzer/oinkmaster ~x86\nnet-analyzer/snort ~x86\nnet-analyzer/sancp ~x86\nnet-analyzer/barnyard ~x86" >> /etc/portage/package.keywords
Now we just emerge the packages (portage will pull in our dependencies) with:
emerge sguil-client sguil-server sguil-sensor
Once everything has been emerged then all we need to do is make sure the configuration files accurately reflect our desired setup. It should be fairly easy with everything on one box as that is what the ebuild was written to configure, however, you should note that if you were installing different components on different machines that there is a little more conf file editing.
Start off by editing /etc/snort/snort.conf and changing the line "var HOME_NET any" to reflect your home network eg "var HOME_NET 10.0.0.0/24". While snort in portage now comes with the basic community rules, I recommend you take the time to register at the snort site so that you can get the rules that are updated more frequently. There is no cost to this, just a little effort. Once you have registered you should modify your /etc/oinkmaster.conf to reflect your rules. In my case the only line I needed to add was:
url = http://www.snort.org/pub-bin/oinkmaster.cgi/
Once this is done, you should do the following commands as root:
# touch /etc/snort/rules/local.rules
# mkdir /etc/snort/rules-backup
# chown -R sguil:sguil /etc/snort/rules*
# sudo -u sguil oinkmaster.pl -o /etc/snort/rules/ -b /etc/snort/rules-backup
At this point you should see oinkmaster updating your rules for you. I personally add the following line to /etc/crontab:
30 4 * * * sguil oinkmaster.pl -o /etc/snort/rules/ -b /etc/snort/rules-backup 2>&1 | logger -t oinkmaster
Now we have the latest rules and have a basic snort configuration (check /etc/conf.d/snort to make sure the interface is correct) we can start up snort with:
/etc/init.d/snort start
Next edit /etc/conf.d/sancp and make sure the interface is correct and then /etc/sancp/sancp.conf and define the HOME_NET variable like we did with the snort.conf. Once that is done you should start up sancp by:
/etc/init.d/sancp start
At this point we should create the mysql database that we are going to use for storing all of the SGUIL information. The following is how I did it:
mysql -u root -p
mysql> GRANT ALL PRIVILEGES ON sguildb.* TO sguil@localhost IDENTIFIED BY 'secret' WITH GRANT OPTION;
mysql> GRANT INSERT,SELECT on sguildb.* to sguil@localhost;
mysql> GRANT file on *.* to sguil@localhost;
mysql> flush privileges;
Then from the command line:
gunzip /usr/share/doc/sguil-server-0.6.0p1/create_sguildb.sql.gz
mysql -u sguil -p -D sguildb < /usr/share/doc/sguil-server-0.6.0p1/create_sguildb.sql
We now have setup the database with the right permissions and can continue.
Next we need to edit /etc/sguil/sguild.conf. Here we need to add modify the db password. Have a look around this file and modify it to suit your system / desires it is fairly well commented so it should all be clear, but all that you NEED to modify to get it working is the dbpassword. Now we need to add a user so that we can connect to sguild with our client. We do this by the following command:
sguild -c /etc/sguil/sguild.conf -u /etc/sguil/sguild.users -adduser USERNAME
We have to specify the full config and user files as by default it looks for it in /etc/sguild not /etc/sguil. Once that is done then you can start sguild with:
/etc/init.d/sguild start
The next step is to edit /etc/snort/barnyard.conf. In previous versions of sguil we needed to uncomment the last two lines and modify them as required, this is no longer the case with sguil 0.6.0p1, instead we need to ensure that we have a hostname defined (this should be done automatically by the ebuild for you) and then we simply append:
output sguil
We are almost done! At this point we have snort running with the latest rules logging infomation using sancp that barnyard is periodically parsing and dumping into our sguild database. Sguild is running and accepting the updates from the db. Now we need to connect the sensor itself into sguild. By default all we need to do is just start the daemon, but it is worth looking around in /etc/sguil/sensor_agent.conf just to familiarize yourself with what options are in there before doing so. We start it like the others with:
/etc/init.d/sensor_agent start
Due to changes in sguil, we should now start barnyard AFTER sensor_agent so:
/etc/init.d/barnyard start
At this point we have a working SGUIL installation. The only thing that is missing is the ability to replay the full tcp stream of attacks and dump streams into Ethereal, there is a small problem with getting this powerful ability and that is disk space! In order to be able to manipulate the tcp stream of the attacks SGUIL has to store the entire tcp stream, this means that it will record EVERY bit of traffic that it sees, on a busy network this can mean a lot of traffic. Due to the nature of recording all the traffic it sees the space requirements are by definition infinite but, alas, no one that I know yet has infinite storage. To get around this Bamm wrote a script called log_packets.sh. I have modified this script for Gentoo and this is what we need to configure to get this final bit of functionality. This is also why mounting /var/lib/sguil on a separate partition is listed in the requirements. Edit the /etc/conf.d/log_packets file and adjust it to your requirements. It is well commented and should be clear what each option does. Again check to make sure that the interface is the correct one. Once that is done you should start log_packets via:
/etc/init.d/log_packets start
Please note, that due to the way snort starts up you MUST stop BOTH log_packets and snort before trying to restart snort. Snort detects the log_packets instance running and refuses to start otherwise. In other words ensure that you always start log_packets AFTER snort. It is important to let the script automatically manage the disk space, it does this via a restart so I recommend crontabbing the script to restart every 10 mins or so. The line I have in /etc/crontab is:
* * * * * root /etc/init.d/log_packets restart >/dev/null 2>&1
Configuration is now complete, you should be able to start the SGUIL client via:
sguil.tk
and log into the server. For reference you can configure the settings of the SGUIL client by editting /etc/sguil/sguil.conf and define things like your browser and the default SGUIL server to connect to. For further information about the actual use of SGUIL please read the documentation at the sguil site.
Don't forget that you can set all of these services to start at boot time via:
rc-update add service_name default
While in theory sguils components can be started up in almost any order, due to the fact that if they can't get / do what they need to they sleep and try again at regular intervals, in reality this tends to cause problems. For a while I thought about changing the init scripts for all of the relevant services, but aside from being cumbersome due to the possibility of the services running without sguil, it also seemed unneccesary as there are times when you do want to start things in an unusual order (normally when testing). Instead I have this note here as a suggested order to start up the relevant services for sguil.
sancp
snort
sguild
sensor_agent
barnyard
log_packets
sancp
snort
sensor_agent
barnyard