Using SnortSnarf (updated: 6 April 2001)
================

This document is intended as introductory reading about SnortSnarf and
cohesive documentation about using its advanced features.  See README for
information about installation.  See the top of SnortSnarf.pl and the
utilities for information about particular command line arguments.  See
README.nmap2html for how to use nmap2html and README.SISR on how to use
SnortSnarf Incident Storage and Reporting.


Basic Usage
-----------
SnortSnarf is run over one or more output files from Snort and these are
converted into web pages.  The source files are given at the end of on the
command line when snortsnarf.pl is run.  The following formats are accepted:

+ Snort alerts files (either standard or -A fast type)
+ syslog files containing some Snort entries
+ spp_portscan files

You can mix and match these formats as you see fit.  Alerts from Spade can be
included.

This generates an integrated set of HTML files in a certain directory
(snfout.<file1> unless -d is used).  You want to view these pages with a web
browser, starting with index.html.  The directory should be visible by a web
server using "http://" if you want to use the annotation feature (described
below), SISR or text4sel.  Otherwise you can use "file://".

The rest is pretty intuitive; the links take you around the pages generated
from the log and to a few external sites for more information.  Take a look
around.

The background of alerts is colored (unless you use -color=no).  This feature
is intended to make the long listings of alerts easier to parse.  The color
will stay the same from one alert to the next until one of the following
changes:  the Snort message (signature), the source IP, or the destination IP.


Log file linking
----------------
As an option, you may have SnortSnarf generate links to Snort log files.  The
links will appear next to displayed alerts that have corresponding entries in
the log files (or at least they are expected to).  We find this feature saves
alot of time in trying to find out the content of a packet that generated an
alert, being able to just click on the link to the log entry and have the log
file appear in the browser.

In order to use this, your log directory must be visible to your web browser. 
This means either having it be part of what your web server provides or
available via your file system.  Also, your log files and directories must
have appropriate permissions to be viewed by your browser.   You might use the
fix_perms.pl utility that is included in this distribution to do this.

Give snortsnarf.pl the -ldir <URL> option to enable this linking, where <URL>
is the URL to the base directory for your log files.  Since Snort bases its
decision on where to log alerts to on what your home network is, you must tell
SnortSnarf this via the -homenet network option.  The default is that you
have no home network.

Note that links will only be created for alerts in standard snort format.  "-A
fast" alerts and syslog entries do not provide enough information to figure
out the name of the log file that the alert will be in (specifically the
protocol is not given).  Portscan files have no corresponding log.


Rule inclusion and reference links
----------------------------------
If snortsnarf.pl is given the -rulesfile option, then it will search through
your Snort rule files to find rules with a given signature.  These rules are
then shown on the page for alerts with that signature.  The idea here is to
allow you to easily see what caused the alerts to be generated.  There is a
bonus if you have a "pass" rule related to an "alert" rule and the signature
is the same (such as would be the case if you modified the text for an alert
rule to disable it for certain cases).  The pass rules will be displayed as
well.

In addition, SnortSnarf will search these rules for reference information
about the alerts in your source file.  If any references are found and URLs
are available, links are provided on the signature index page (the start
page)) and signature pages.  In addition, if the alert signature contains
the text IDSxxx, this is assumed to an arachNIDS reference number.

The argument with the -rulesfile is your starting rule file (e.g.,
snort.lib).  Files included by this rule file (and their rule files) are
parsed as well.  The rules found for signature are displayed in the order
that they are found in the file (following includes immediately).

To support the relocation of rules files (perhaps you make a copy of the rules
you used on a given day), the -rulesdir option is provided.  Its argument is a
directory in which all rule files are to be found, even if a different
directory is found in a file off of the command line.


Annotations
-----------
Your may tell SnortSnarf to produce pages that are integrated with a specified
annotation database by using the -db <annfile.xml> option, where <annfile.xml>
is the full path to your annotation database file.  An annotation database is
a file external to Snort and SnortSnarf that holds your knowledge about a
particular IP address or Snort message.  You may have an arbitrary number of
notes about any IP address or message.

With this feature on, you will find a link to view and edit annotations for a
snort message on the page for that message and to view and edit annotations
for an IP address on the pages for that IP address (both when it is a source
and a destination).  These links will show you the current annotations (if
any) and give you the option to add a new annotation.  After you submit a new
annotation, you will be shown the updated annotations.

The annotation database is not read when SnortSnarf.pl is run.  Rather a
couple CGI scripts included with the distribution take care of this
dynamically.  Put these in a directory where the will be executed by your
server as CGI scripts.  You will need to give the -cgi URL option unless your
CGI directory can be reached from your generated pages by "/cgi-bin/".

Your annotation database file needs to be writable by the server when it is
executing the scripts.  In fact, since the database is backed up before it is
updated, the directory also needs to be writable by the server.  We recommend
creating a special directory with the appropriate access permissions to hold
your annotation database(s) using the setup_anns_dir.pl utility included in
this distribution.  To create just an "empty" annotations database file, you
can make a copy of new-annotation-base.xml in the top level of the
distribution.

There is no way at present to edit or delete annotations in the database using
online methods.  You can use an XML editor to do this or just a plain text
editor.  The format should be straightforward.

The annotation feature requires the XML::Parser Perl module, available from
CPAN:
    http://www.perl.com/CPAN-local/modules/by-module/XML/
and the CGI.pm module included with the Perl distribution.


Contributions
-------------
We welcome your complaints, kudos, and especially improvements and bugfixes.  
We wish for this to be a useful as possible, so your feedback and assistance
is important.  You may reach us at hoagland@SiliconDefense.com.

Thank you and happy SnortSnarfing!

-- Jim Hoagland (hoagland@SiliconDefense.com)
   Stuart Staniford-Chen (stuart@SiliconDefense.com)


