This page is out of date! Please see http://k9.io for newer information!


Sagan HOWTO

Compiling and installing Sagan.

We've tried to make Sagan as simple and easy to use as possible. For the most part, compiling and installation is done your typical Unix way. That is, the old "./configure && make && make install". However, you'll probably want to read about Sagan dependencies to get the best functionality to fit your needs. Currently, there is only one required dependency to get the basic functionality of Sagan up and running. It is.....

PCRE (http://www.pcre.org) - libpcre

This will get the very basics of the Sagan engine up and running. Using only this dependency, you will not be able to store events into an SQL database or have the ability to e-mail them. PCRE gives Sagan the ability to use ' regular expressions', which is a Sagan requirement. If you're running this on a local workstation, this might be sufficient for your needs. If you require logging and correlation, continue reading and I'll go into enabling the necessary libraries after the required dependencies are covered.

Installation of PCRE (REQUIRED)

PCRE can be installed from source, or you might be able to use your distribution's package manager to install it. If you'll be building PCRE from source, go to the PCRE web site and follow the installation instructions there. For these instructions to work, you'll need to be "root" on the system that you're installing Sagan on.

On Gentoo based Linux systems, you can install PCRE by typing:

emerge -va libpcre

Ubuntu users can install PCRE by typing:

apt-get install libpcre3-dev libpcre3

FreeBSD (and BSD users in general) can install PCRE by typing:

cd /usr/ports/devel/pcre
make && make install

Once PCRE has been installed, you can build Sagan with the bare basic functionality. This means that Sagan will generate 'alert' logs (/var/log/sagan/alert) and be able to call external functions to deal with them via the "output external:" Sagan configuration option. You will not be able to log and/or correlate to an SQL database or e-mail out alerts. The basic functionality might be fine if you intend to run Sagan on a local workstation (for example, a non-centralized log environment). If this basic functionality fits your needs, you can skip forward to the configuration portion of this document.

Intallation of liblognorm (OPTIONAL, BUT SUGGESTED)

"liblognorm" allows Sagan to gather useful information from events. While it's not required by Sagan, it's highly suggested. "liblognorm" works in conjunction with the Sagan engine to gather data for better correlation of events. For more information on how compile and install liblognorm, please see the LibLogNorm page. This page contains all the information you need to install and configure liblognorm It's actually quiet easy to compile and install. Also depending on your system, there might be a package already built. For example, Debian packages for liblognorm are available.

For more information see the LibLogNorm page.

Installation of libesmtp (OPTIONAL)

If you need Sagan to e-mail alerts, then you'll want this functionality. Sagan uses libesmtp for this purpose. To install it from source, see the libesmtp web site for instruction on how to do so.

If you're a Gentoo user, you can type:

emerge -av libesmtp

If you're a Ubuntu user, you can type:

apt-get install libesmtp-dev

FreeBSD users can type:

cd /usr/ports/mail/libesmtp
make && make install

This will give Sagan the ability to e-mail alerts in the "sagan.conf" configuration option "output email:".

Installation of libdnet librarys (OPTIONAL)

If you want Sagan to log events to a Unified2 output format, you'll want this. Libdnet basically allows Sagan to "build" event "packets" so they can be stored to a Unified2 format. External processes, like Barnyard2 can be used to read in the Sagan Unified2 output.

Gentoo users can type:

emerge -av libdnet

Ubuntu users can type:

apt-get install libdumbnet1 libdumbnet-dev

(Read the warning below)

*Warning to Ubuntu users* - Ubuntu uses the Debian packet of Libdnet which is known as "libdumbnet". During out tests, we found this version of the library didn't function as we'd expect and led to more problems. On Ubuntu, it might be better to download the libdnet source code from http://libdnet.sourceforge.net/ and compile/install them manually.

FreeBSD users can type:

cd /usr/ports/net/libdnet
make && make install 

Compiling and installing Sagan

Once the required dependency and the optional dependencies have been installed, Sagan is pretty straightforward to compile. At the command line, type:

./configure && make && make install

By default, Sagan installs into the /usr/local/bin directory and configuration files go into the /usr/local/etc directory. If this is not desired, type:

./configure --help

Tweak the ./configure to fit your particular needs. By default, Sagan attempts to configure with all dependencies enabled. For example, let's say you don't want MySQL support, and you get this following message during the ./configure:

------- MySQL Support is enabled -------
checking for mysql/mysql.h... (cached) no
checking for main in -lmysqlclient_r... no
configure: error: The MySQL library libmysqlclient_r is missing!
        If you're not interested in MySQL support use the --disable-mysql flag. 

Follow the directions. That is, re-run ./configure with the "--disable-mysql" flag. For example:

./configure --disable-mysql

If you do need MySQL support and you're getting a similar error message, it means that the Sagan configuration process is having problems locating the necessary libraries to compile with that option. This means that either the optional libraries are not installed or they are installed in such a way that the configuration process cannot find them. Resolve this, and then re-run the ./configure.

If you're a BSD user, you might need to do the following, assuming you're using the 'bash' shell:

If you are a FreeBSD or OpenBSD user, you might need to do the following. In most cases, the required libraries get installed in the /usr/local/lib and include files into the /usr/local/include directory. If you are getting an error in BSD stating the libraries and/or include files can't be found and you are sure they've been installed, try the following. This assumes you're using the 'bash' shell.

LDFLAGS=-L/usr/local/lib CFLAGS=-I/usr/local/include ./configure

Once the configuration process has run to your satisfaction, build Sagan by issuing the following commands:

make && make install

This will compile Sagan and install it on the system. You'll need to do this command as "root" for a global system install.

After compilation and installation is completed, you'll need to create a Sagan user. In order for Sagan to process syslog/event messages, it must be started as 'root'. This is done so Sagan can access possible 'root' level information (for example, FIFO's or named pipes). Once this process is completed, Sagan drops its 'root' privileges and becomes the 'sagan' user. This is done for security reasons.

The 'sagan' user does not need a shell. If you plan on using Sagan with the libesmtp (E-mail) output plug in, the Sagan user will need a valid, user writeable home directory.

If you're a CentOS user and having some difficulty installing Sagan, check the CentOS page.

Syslog-ng configuration.

In order for Sagan to be able to process and analyze syslog events, Syslog-ng or Rsyslog must be configured first. Sagan can run in a couple of different 'modes', which means that it's likely Sagan is compatible with other 'syslog' daemons. If you successfully get Sagan to work with other syslog daemons side from Syslog-NG or Rsyslog, please let us know.

If you plan for Sagan to out put alert information to a Snort database, it is important to disable DNS lookups. If this is not done, Sagan won't be able to put the correct information into the Snort tables. This means that any change or correlating events will be nullified. While this will directly affect the Snort output plug in for Sagan, it's not as important for other output plug ins, but it is advised to disable DNS lookups anyway. The start of a typical 'syslog-ng.conf' would look something like this in the 'options' section:

options {
       chain_hostnames(off);
       long_hostnames(off);
       use_dns(no);         # Most important!
       sync(0);
       stats(43200);
};

The most important option is use_dns(no). That's it for the 'options', we can now on to the output methods.

Sagan currently handles incoming events one of two ways:

  • FIFO (First In/First Out), also known as a 'named pipe'. Syslog-ng sends events as they are received to the named pipe. In this mode, Sagan 'reads' the named pipe. By default, Sagan opens the named pipe /var/run/sagan.fifo. The means that Syslog-ng must write /var/run/sagan.fifo.
  • For a Sagan/FIFO based system, using the syslog-ng destination method, you'll first need to run the following command as 'root'. This will create the FIFO for Sagan to read and Syslog-ng to write to. Simply type:

    mkfifo /var/run/sagan.fifo
    
    In your syslog-ng.conf file, you'll create a destination like the one below. For a full basic example syslog-ng.conf file with FIFO support, see the example syslog-ng-fifo.txt

    destination sagan {
          pipe("/var/run/sagan.fifo"
          template("$SOURCEIP|$FACILITY|$PRIORITY|$LEVEL|$TAG|$YEAR-$MONTH-$DAY|$HOUR:$MIN:$SEC|$PROGRAM| $MSG\n") template-escape(no)); 
          };
    

    ( Note the space between the last field. - ie '| $MG')

    Rsyslog configuration

    If you'd prefer to use Rsyslog (http://www.rsyslog.com) rather than Syslog-ng, that's not a problem.

    # The standard "input" template Sagan uses.  Basically the message 'format' Sagan understands.  The template is _one_ line.
    
    $template sagan,"%fromhost-ip%|%syslogfacility-text%|%syslogpriority-text%|%syslogseverity-text%|%syslogtag%|%timegenerated:1:10:date-rfc3339%|
    %timegenerated:12:19:date-rfc3339%|%programname%|%msg%\n"  
    
    # The FIFO/named pipe location.  This is what Sagan will read. 
    
    *.*     |/var/run/sagan.fifo;sagan
    

    Once this has been added, we'll need to create the Sagan FIFO. You can do this, by typing as "root":

    # mkfifo /var/run/sagan.fifo
    # chown sagan:sagan /var/run/sagan.fifo    # Sagan needs to be able to read the FIFO!
    

    At this point, you can restart Rsyslog. To test that output is going to the FIFO, you can simply type "cat /var/run/sagan.fifo". You should see syslog messages formatted for Sagan usage. Note, the 'cat /var/run/sagan.fifo will not work if Sagan is already running and reading the FIFO!

    Sagan configuration file.

    Below is the standard Sagan configuration file, 'sagan.conf'. This file is fairly explanatory. Depending on your systems configuration, stored in the /usr/local/etc/sagan.conf.

    #  ,-._,-.    Sagan configuration file [http://sagan.softwink.com]
    #  \/)"(\/    By Champ Clark III & The Softwink Team: http://www.softwink.com
    #   (_o_)     Copyright (C) 2009-2011 Softwink, Inc., et al.
    #   /   \/)   
    #  (|| ||)    
    #   oo-oo     
    
    
    ##############################################################################
    # Standard _required_ Sagan options!
    ##############################################################################
    
    # Sagan can read log entries via a FIFO (First In,  First Out) or via 
    # 'standard input' (stdin).   If this option is _present_,  then Sagan assumes
    # log entries will come in via a FIFO.  If this option is _not_ present,  then
    # Sagan will 'assume' log entries will come in via stdin.   
    #
    # When Sagan takes input from stdin,  syslog-ng calls this via the 'program' 
    # mode/call. 
    #
    # [optional] - Depending on system configuration.
    
    var FIFO /var/run/sagan.fifo
    
    # This variable contains the path of the Sagan rule sets.  It is required.
    
    var RULE_PATH /usr/local/etc/sagan-rules
    
    # Where Sagan should store it's lock file. 
    
    var LOCKFILE /var/run/sagan/sagan.pid
    
    # This is for storage of Sagan runtime information.
    
    var SAGANLOG /var/log/sagan/sagan.log
    
    # Where Sagan should store alerts,  in a text file format. 
    
    var ALERTLOG /var/log/sagan/alert
    
    # This is the IP address _of_ the Sagan system.   These options are used
    # if Sagan is unable to determine a TCP/IP network address and/or port.
    #
    # [Required]
    
    sagan_host 192.168.0.1
    sagan_port 514
    
    # If logging to a Snort/Prelude database,  and the rule set specifies the
    # protocol a "any",  this is the protocol we default to.  This is only
    # needed if you are # logging to a Snort/Prelude database. 
    #
    # [Defaults to 17 [UDP],  which is what normal 'syslog' traffic is.  If you
    # want TCP to be the desired effect,  change this option to "6". 
    
    ; sagan_proto 17
    
    # Disable DNS warnings.  Sagan will warn every time it has to do a DNS lookup
    # when attempting to normalize a log entry.  You typically don't want to
    # do DNS lookups with the log analysis.  More information can be found at:
    # https://wiki.softwink.com/bin/view/Main/SaganDNS.  If it's not possible
    # to gather the true TCP/IP address information,  you can supress these 
    # warnings here.
    
    ; disable_dns_warnings 1
    
    ##############################################################################
    # Snort database specific configurations                                     
    ##############################################################################
    
    # Sagan "sensor" configuration.  If you plan on running Sagan and storing data
    # to a Snort database,  these options are required.   This information gets 
    # logged to the Snort database's "sensor" table to differentiate  between Snort
    # IDS/IPS data and log data.   We don't really have an "interface", so we create
    # one known as "syslog",  or what ever you'd like to call it.
    #
    # [Required if logging to a Snort database]
    
    ; sagan_hostname sagan
    ; sagan_interface syslog
    ; sagan_filter none
    ; sagan_detail 1
    
    # If you plan on logging to a Snort database,  this is where you tell Sagan 
    # where to log to.   The options should be pretty clear.  Currently Sagan 
    # supports MySQL and PostgreSQL.  The "maxdb_threads" is the maximum number of
    # threads that can be created.  This defaults to 50.
    #
    # [Required if logging to a Snort database]
    
    ; maxdb_threads 50
    ; output database: log, mysql, user=sagan password=secret dbname=snort_db host=192.168.0.1
    ; output database: log, postgresql, user=sagan password=secret dbname=snort_db host=192.168.0.1
    
    ##############################################################################
    # External program/system calls configurations specifics
    ##############################################################################
    
    # This option calls an external program when an event is triggered by a rule.
    # Sagan basically makes a thread and calls the execl() system call.
    # Data is supplied to the program being called via standard in (stdin). 
    # Data can be sent in a "parsable" or "alert" format.   "parsable" will be
    # probably easier for your external program to parse. 
    #
    # The "max_ext_threads" limits the amount of threads that can be created, 
    # which defaults to 50.
    
    ; max_ext_threads 50
    ; output external: /home/champ/stdout parsable
    
    ##############################################################################
    # libesmtp (SMTP/E-mail) specific configuration options
    ##############################################################################
    
    # If you'd like Sagan to e-mail triggered events to you,  then you'll want
    # to configure the below.
    
    # The max number of threads that can be spawned for SMTP.  This defaults to 
    # 50. 
    
    ; max_email_threads 50
    
    # If min_email_priority is set,  then Sagan will _only_ e-mail events equal to
    # or less than this priority event.  If left commented out or set to 0, 
    # Sagan will e-mail _all_ events.  This option does _not_ over ride rules
    # with the "email:" option set! 
    
    ; min_email_priority 5
    
    # This is where alerts will be sent if a rule _does not_ have a "email:"
    # option.  If a rule does have "email:" option,  then the rules e-mail address
    # will over ride this option.  If this option is not set,  then only
    # rules with the "email:" option will be sent. 
    
    ; send-to sagan-alerts@example.com
    
    # SMTP Server information.  This tells Sagan "who" to send e-mail as and where 
    # the SMTP server to relay is.  This must be set if the "send-to" option
    # set,  or you have rules with the "email:" option!
    
    ; output email: smtpserver=192.168.0.1:25 from=sagan-alert@example.com
    
    ##############################################################################
    # Prelude (IDMEF) output plug in
    ##############################################################################
    
    # This lets Sagan output to the Prelude security framework.  This allows 
    # Sagan events to be viewed in the Prelude "Prewikka" console.  The Prelude
    # framework is useful in corelating events from multiple sources.   Prelude
    # uses fhe Intrusion Detection Message Exchange Format (IDMEF) format,  which
    # also might be useful. 
    #
    # more information,  please see: http://www.prelude-technologies.com
    
    ; max_prelude_threads 50
    ; output prelude: profile=sagan
    
    ##############################################################################
    # Unified2 output plug in 
    ##############################################################################
    
    # This lets Sagan log the Snort's 'Unified2' output format.  This allows 
    # events generated by Sagan to be read and queued for external programs 
    # like Barnyard2 (http://www.securixlive.com/barnyard2/).  Barnyard2 can 
    # the record events in various formats (Prelude,  alert_fast,  log_ascii, 
    # log_tcpdump,  Sguil,  MySQL,  PostgreSQL, ODBC, MS-SQL and Oracle). 
    
    ; output unified2: filename sagan.u2, limit 128, nostamp
    ; output unified2: filename sagan.u2, limit 128
    
    ##############################################################################
    # Sagan syslog "Sniffier" mode.  (PLOG). Promiscuous syslog injector
    ##############################################################################
    
    # This lets Sagan "listen" on a network interface via pcap/bpf and "suck"
    # up UDP syslog messages.  When it "finds" a syslog message within a packet,
    # it injects it into /dev/log.  Basically,  it 'sniffs' syslog messages and
    # injects them to your syslog daemon (for archival purposes) and Sagan
    # (for analysis).  Good for environments you can't reconfigure syslog
    # services.   For more information,  see src/sagan-plog.c.
    
    # Network interface to "sniff" traffic on.
    ; plog_interface eth0
    
    # Syslog "port" to listen on...
    ; plog_port 514
    
    # Where to inject "found" messages to.
    ; plog_logdev /dev/log
    
    ##############################################################################
    # Sagan rule sets! Arrgh Villains! Sagan neither takes nor gives mercy!
    ##############################################################################
    
    # This should be enabled!  "classifications.config" allows correlation between
    # a short name (for example,  "attempted-admin") and a priority level 
    # (for example, "1").  "reference.config" gives your various places to learn
    # more information pertaining to an alert. 
    
    include $RULE_PATH/classification.config
    include $RULE_PATH/reference.config
    
    #############################################################################
    # Sagan normalization 'rule base'. (liblognorm)
    #############################################################################
    
    # These "rules" are for the liblognorm library.  These are use to further 
    # "normalize" (extract useful information out of) log messages.  These rules
    # are loaded in a dynamic method.  That is,  rather than load all these 
    # at run time,  they are loaded 'as needed' by the Sagan rule sets.  These
    # get triggered by the 'normalize:' flag within a Sagan rule. 
    
    normalize: cisco, $RULE_PATH/normalize/cisco.rulebase
    normalize: openssh, $RULE_PATH/normalize/openssh.rulebase
    normalize: smtp, $RULE_PATH/normalize/smtp.rulebase
    normalize: dns, $RULE_PATH/normalize/dns.rulebase
    normalize: imap, $RULE_PATH/normalize/imap.rulebase
    
    # These are the specific rule sets of events which are of interest and require
    # notification.  Tailor these to your specific needs and check from time to 
    # time for new rule sets that might be of benefit.
    
    include $RULE_PATH/apache.rules
    include $RULE_PATH/arp.rules
    include $RULE_PATH/asterisk.rules
    include $RULE_PATH/attack.rules
    include $RULE_PATH/bash.rules
    include $RULE_PATH/bind.rules
    include $RULE_PATH/bro-ids.rules
    include $RULE_PATH/cisco-ios.rules
    include $RULE_PATH/cisco-pixasa.rules
    include $RULE_PATH/courier.rules
    include $RULE_PATH/dovecot.rules
    include $RULE_PATH/ftpd.rules
    include $RULE_PATH/grsec.rules
    include $RULE_PATH/hordeimp.rules
    include $RULE_PATH/imapd.rules
    include $RULE_PATH/ipop3d.rules
    include $RULE_PATH/juniper.rules
    include $RULE_PATH/knockd.rules
    include $RULE_PATH/milter.rules
    include $RULE_PATH/mysql.rules
    include $RULE_PATH/nginx.rules
    include $RULE_PATH/ntp.rules
    include $RULE_PATH/openssh.rules
    include $RULE_PATH/ossec.rules
    include $RULE_PATH/php.rules
    include $RULE_PATH/postfix.rules
    include $RULE_PATH/postgresql.rules
    include $RULE_PATH/pptp.rules
    include $RULE_PATH/proftpd.rules
    include $RULE_PATH/pure-ftpd.rules
    include $RULE_PATH/racoon.rules 
    include $RULE_PATH/roundcube.rules
    include $RULE_PATH/rsync.rules
    include $RULE_PATH/samba.rules 
    include $RULE_PATH/sendmail.rules
    include $RULE_PATH/snort.rules
    include $RULE_PATH/solaris.rules
    include $RULE_PATH/squid.rules 
    include $RULE_PATH/su.rules
    include $RULE_PATH/syslog.rules
    include $RULE_PATH/tcp.rules 
    include $RULE_PATH/telnet.rules
    include $RULE_PATH/tripwire.rules
    include $RULE_PATH/vmpop3d.rules
    include $RULE_PATH/vmware.rules
    include $RULE_PATH/vpopmail.rules
    include $RULE_PATH/vsftpd.rules
    include $RULE_PATH/windows.rules
    include $RULE_PATH/wordpress.rules
    include $RULE_PATH/xinetd.rules
    include $RULE_PATH/zeus.rules
    

    Configuration with Unified2 output support.

    If Sagan is compiled with libdnet support, then it can write events to a Unified2 format. Unified2 is commonly used with Sourcefire's "Snort" Intrusion Detection (IDS/IPS) engine to decouple the Snort IDS/IPS engine from the output module. Think of it this way; If Snort has to constantly monitor a high speed Internet connection for potentially hostile traffic, then you do not want the engine to have to deal with inserting into a SQL database. Any CPU time given to the task of logging takes away from Snort's ability to monitor for hostile events.

    Sagan uses Unified2 the same way. This allows a third process to log events, like Barnyard2, and lets Sagan concentrate on the detection of malicious events.

  • output unified2: filename sagan.u2, limit 128

    This informs Sagan that you want to use the Unified2 output plug in. The file that will be created, containing our Unified2 output, will be called "sagan.u2" and will include time stamp information. This means the file created will be named "sagan.u2.{current utime}". For example, "sagan.u2.1300224609". The location of the file is determined by the sagan.conf file and the "SAGANLOGPATH" (variable). This typically defaults to "/var/log/sagan". If you do not with utime to be associated with the Sagan Unified2 output file, append a "nostamp" at the end.

    The "limit 128" indicate that Unified2 output files should never exceed 128 megabytes of data. When that limit is reached or exceeded, Sagan generates a new Unified2 output spool/file with a new utime. Basically, the file will be rotated at this value.

    If you're using Barnyard2, you might want to read over the Barnyard2HowTo.

    Configuration with the Prelude security framework.

    Sagan can support the Prelude security framework, if built with the proper support. For more information about the Prelude security framework, check out the Prelude website

    Configuration of Sagan to use a Prelude back end is very similar to how Snort can be configured with Prelude (suprise, eh!). This means that it's likely many configuration manuals and "HOWTO's" for Snort & Prelude can most likely be used with Sagan & Prelude.

  • max_prelude_threads 50
  • output prelude: profile=sagan

    Configuration with Snort database support.

    Using Sagan with the Snort database output plug in is probably one of the most interesting ways to use Sagan. If you use Sourcefire's Snort with a MySQL or PostgreSQL database, Sagan will log triggered events to that same database using a seperate sensor ID. This way, you can correlate, when applicable, IDS/IPS triggered events (packet level) with syslog/event log events with Sagan. This section of documentation covers the required Sagan configurations that will get you up and running. This information is based off of the example configuration file in the "Sagan configuration file" section.

  • sagan_hostname sagan
  • sagan_interface syslog
  • sagan_filter none
  • sagan_detail 1

    These configuration options are required if you plan on logging output to a Snort database. These options are used for Sagan to identify and store information as its own separate sensor ID within a Snort database. In the sensor table of your Snort database, Sagan stores its existence as a "sensor". For example, the current schema for the sensor table is as follows:

    +-----------+------------------+------+-----+---------+----------------+
    | Field     | Type             | Null | Key | Default | Extra          |
    +-----------+------------------+------+-----+---------+----------------+
    | sid       | int(10) unsigned | NO   | PRI | NULL    | auto_increment | 
    | hostname  | text             | YES  |     | NULL    |                | 
    | interface | text             | YES  |     | NULL    |                | 
    | filter    | text             | YES  |     | NULL    |                | 
    | detail    | tinyint(4)       | YES  |     | NULL    |                | 
    | encoding  | tinyint(4)       | YES  |     | NULL    |                | 
    | last_cid  | int(10) unsigned | NO   |     | NULL    |                | 
    +-----------+------------------+------+-----+---------+----------------+
    

    For the sake of an example, let's say we're running a Snort IDS/IPS sensor as sid number 1. Sagan might become sid number 2. Like Snort, when Sagan starts for the first time, it automatically allocates a sensor entry in the sensor table. No user intervention is necessary. Our example senor table might look like this:

    +-----+--------------+-----------+--------+--------+----------+----------+
    | sid | hostname     | interface | filter | detail | encoding | last_cid |
    +-----+--------------+-----------+--------+--------+----------+----------+
    |   1 | snort-ids    | eth1      | NULL   |      1 |        0 |      918 |
    |   2 | sagan        | syslog    | none   |      1 |        0 |       0  |
    +-----+--------------+-----------+--------+--------+----------+----------+
    

    Note: The 'interface' with Snort is typically the physical interface that Snort will be listening on. This does not apply to Sagan, so assign the "interface" something unique.

  • sagan_proto 17

    This is the protocol Sagan will default to if a protocol cannot be determined. The default is 17, which is UDP, since standard syslog messages are sent by UDP. Other values are, 1 = ICMP, 6 TCP and 17 = UDP. In many events, Sagan can determine the protocol via the rule set. For example, if a rule set specifies that Secure Shell (SSH) traffic is TCP and happens on port 22, Sagan will log it that way. However, there are some instances where messages do not relate to a protocol; for example, if a message is received that an application has crashed, or a hard drive is out of space. These are standard syslog (UDP) messages on port 514, unless you specify otherwise. To alter the default port, you'll need to change:

  • sagan_port 514

    These are only used in the event the protocol and/or port cannot be determined by Sagan.

  • maxdb_threads 50

    This option is the maximum number of threads that can be spawned by Sagan to insert events into the Snort database. Sagan defaults to 50, but you'll likely want to tweak this for your site. The value largely depends on how many entries will be inserted into the database at any given time. If set too low, you'll run out of Snort database threads and "drop" events, which is not good. If set too high, there is a chance you'll run out of resources. It's better to set this value too high than too low. Just keep in mind your available system resources.

  • output database: log, mysql, user=sagan password=secret dbname=snort_db host=192.168.0.1
  • output database: log, postgresql, user=sagan password=secret dbname=snort_db host=192.168.0.1

    This configuration file should look familar to Snort users. This tells Sagan how and where to log data into the database.

    Note: Currently, Sagan only supports the 'log' format. There is no 'alert' format.

  • Configuration with libesmtp support (E-mail support).

    What good would Sagan be without the ability to send events triggered via e-mail? If Sagan is compiled with libesmtp, it can do just that; e-mail you when 'bad things' happen. The configuration is simple and looks like this:

  • min_email_priority 5
  • max_email_threads 50

    The maximum number of threads can be used to send e-mail. The default value is 20. The minimum priority a alert must be before it is e-mailed out. For example, if you want to be e-mailed on priority 1 and 2 events, you'd set this to "2". If events over 2 happen, they'll be logged and stored, but not e-mailed to you. Comment this field out or set to "0" if you want all event to be e-mailed to you.

  • output email: to=sagan-alerts@example.com smtpserver=192.168.0.1:25 from=sagan@example.com

    This should be pretty simple to understand. We're basically setting 'where' the SMTP server is and the port (192.168.0.1:25) and 'who' it goes to (sagan-alert@example.com) and 'who' it should appear 'from' (sagan@example.com).

    Configuration with external program support.

    This option calls a external program when an event is triggered by a rule set. Let's assume you want something to happen to triggered events that Sagan doesn't support. This could be just about anything. This option allows you to call a program of your choosing, in whatever language you want, and process the event as you see fit. The options for externally called threads are:

  • max_ext_threads 50

    Defaults to 50, but you'll likely want to do testing with your external routine to find what works for your environment.

  • output external: /usr/local/bin/yourprogram parsable

    '/usr/local/bin/yourprogram' is what external program you'd like Sagan to call. The final option can be 'parsable' or 'alert'. Using 'alert' results in output similar to a Snort output format. Below is an example:

    [**] [5000075] [SSH] Authentication success [**]
    [Classification: successful-user] [Priority: 3]
    2010-04-28 12:46:10 10.222.0.55:38559 -> 10.222.0.1:22 auth info
    

    Below is an example of 'parsable' output:

    ID:5000075
    Message:[SSH] Authentication success
    Classification:successful-user
    Priority:3
    Date:2010-04-28
    Time:12:46:10
    Source:10.222.0.55
    Source Port:38559
    Destination:10.222.0.1
    Destination Port:22
    Facility:auth
    Syslog Priority:info
    Syslog message: sshd[9091]: Accepted keyboard-interactive/pam for exampleuser from 10.222.0.55 port 38559 ssh2 
    

    Alert information is passed to your external program via standard in (stdin).

    Making the 'sagan' user.

    Once everything is compiled and installed, you'll need to make a user name on your system for Sagan to run as. This is done for security reasons, so Sagan doesn't have to run with 'root' privileges. The 'sagan' user name will need a home directory owned by 'sagan' for temporary files created by libesmtp.

    After creating a 'sagan' user name on your system, you'll need to create a log directory for Sagan to store information to. This will be the place that Sagan stores it's 'Snort like' alert file and the sagan.log. The 'alert' file has all alerts that have been triggered. The 'sagan.log' file has Sagan run time information, and is some times useful in debugging problems. To create these, simply type

    mkdir /var/log/sagan
    mkdir /var/run/sagan
    chown -R sagan /var/log/sagan
    chown -R sagan /var/run/sagan
    

    Installation of Sagan rules.

    Once you have Sagan configured to your specifications, you'll need to download the latest rule set. These can be found at http://sagan.softwink.com/rules. You can manually install them, or use Oinkmaster or Pulledpork to automated this process.

  • Topic revision: r19 - 2014-03-28 - ChampClark
     
    This site is powered by the TWiki collaboration platform Powered by PerlCopyright © 2008-2014 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
    Ideas, requests, problems regarding TWiki? Send feedback