Application Note: NetIntercept Automatic Operations via syslog
Introduction
NetIntercept operations can be automated via scripts that save and analyze captured traffic, generate reports, and export the results to other systems. Setting up automatic operations to take place at scheduled times, or when NetIntercept receives SNMP traps from another network node is discussed in the NetIntercept User Manual. This application note describes how to configure the NetIntercept system to initiate automatic operations locally or over the net in response to syslog messages.
Some syslog Considerations
The syslog program was originally developed as a simple logging mechanism. Applications use a standard syslog API to send log messages via a central server application, syslogd. Log messages may be saved to shared files on the local server, or transmitted over the network to a central log on another system. By default, log messages are sent over the network using UDP as the transport, with no security whatsoever. The log messages are sent in plain text, and there is no authentication or flow control.
At this time, there are a number of syslog implementations available for various Unix versions and even for Windows. Also, many network appliance vendors offer it as a lightweight alarm and notification system for devices whose capacity and price won't justify the added complexity of SNMP. This document will focus on use of FreeBSD's syslogd (as shipped with the NetIntercept system) to receive and act on alerts in a relatively small-scale network. The various other implementations of and extensions for syslog that provide a more secure protocol or help the operational model scale in larger networks are beyond the scope of this note.
About the syslog.conf Configuration File
The /etc/syslog.conf file is used to enable, disable, or (most often) trigger various kinds of actions in response to log messages. Each line in the file contains a category of event (facility) AND SEVERITY level, followed by a [Tab] and the action to be taken (often shown as a log file that the syslog messages of that facility and severity should be written to). To receive and act upon log messages from a particular device, you will need to find out which facility it is using. You may be able to find this out from the device's documentation.
The facility is one of:
- kern (0)
- user (1)
- mail (2)
- daemon (3)
- auth (4)
- syslog (5)
- lpr (6)
- news (7)
- uucp (8)
- cron (9)
- authpriv (10)
- ftp (11)
- ntp (12)
- security (13)
- console (14)
- local0 - local7 (16-23)
The level is one of:
- emerg -- System is unusable (0)
- alert -- Action must be taken immediately (1)
- crit -- Critical condition (2)
- err -- Error condition (3)
- warning -- Warning condition (4)
- notice -- Normal but significant condition (5)
- info -- Informational messages (6)
- debug -- Debug-level messages (7)
The action can appear in one of five forms:
- An absolute path and filename -- received messages will be appended to this file.
- @hostname -- received messages will be forwarded to
syslogd on the named system.
- A comma-separated list of users -- received messages will be written to these users (if they are logged in).
- An asterisk -- received messages will be written to all users.
- A vertical bar (|) and a command -- received messages will be piped to this command, which is usually run as 'root' and passed to
sh(1) for evaluation.
See man syslogd, man syslog, man syslog.conf, and RFC 3164 for more in-depth information.
The default FreeBSD 6.2 syslog.conf file is shown below. The first uncommented line sends messages from any facility with a level of err (*.err) to /dev/console, along with kernel warnings, authorization notices and mail critical messages. The second sends less urgent events to /var/log/messages. The third line sends messages from security facilities of all levels to /var/log/security, and so forth.
# $FreeBSD: src/etc/syslog.conf,v 1.28 2005/03/12 12:31:16 glebius Exp $
#
# Spaces ARE valid field separators in this file. However,
# other *nix-like systems still insist on using tabs as field
# separators. If you are sharing this file between systems, you
# may want to use only tabs as field separators here.
# Consult the syslog.conf(5) manpage.
*.err;kern.warning;auth.notice;mail.crit /dev/console
*.notice;authpriv.none;kern.debug;lpr.info;mail.crit;news.err /var/log/messages
security.* /var/log/security
auth.info;authpriv.info /var/log/auth.log
mail.info /var/log/maillog
lpr.info /var/log/lpd-errs
ftp.info /var/log/xferlog
cron.* /var/log/cron
*.=debug /var/log/debug.log
*.emerg *
# uncomment this to log all writes to /dev/console to /var/log/console.log
#console.info /var/log/console.log
# uncomment this to enable logging of all log messages to /var/log/all.log
# touch /var/log/all.log and chmod it to mode 600 before it will work
#*.* /var/log/all.log
# uncomment this to enable logging to a remote loghost named loghost
#*.* @loghost
# uncomment these if you're running inn
# news.crit /var/log/news/news.crit
# news.err /var/log/news/news.err
# news.notice /var/log/news/news.notice
!startslip
*.* /var/log/slip.log
!ppp
*.* /var/log/ppp.log
Setting Up Automated Analysis
We will be setting up a simple NetIntercept analyze-and-report script to run whenever an alert is received from the local firewall. If you're not familiar with Unix system administration, there are a number of steps which must be done (as the 'root' user) that involve changing system configuration files. When you are logged in as 'root', be particularly careful when typing commands and editing files.
1. Make syslogd Accept Remote Log Requests
First, you will need to alter your NetIntercept system to allow the firewall to send it UDP syslog messages over the control connection. Log in as 'root', and edit /etc/rc.conf to add the following line (assuming your firewall has an IP address of 192.168.1.1):
syslogd_flags="-n -a 192.168.1.1/32:*"
The -n switch disables DNS lookups. The * allows the firewall to send packets from any UDP port number. The -a switch has a number of other possible arguments, see man syslogd for more information. Note: Even inside a well-secured network, syslog should be used with care, lest a problem on one or more client systems turn into a denial-of-service attack on the log server. For this reason, the default startup mode is syslogd -s, which tells the daemon not to open a network socket.
Save your changes and reboot the NetIntercept system to make them take effect.
2. Create an Automatic Operations Script
The next step is to create a script using NetIntercept's automatic operations primitives that will run in reaction to incoming syslog messages. Here's an example:
#!/bin/sh
#
# This script demonstrates a simple NetIntercept parse to be
# triggered by an incoming message to the system logging daemon,
# syslogd (see 'man syslogd' and 'man syslog.conf'). As provided,
# it waits one minute before preserving a time range which starts
# ten minutes (600 seconds) ago and ends at the current time, analyzes
# the data, creates a database, and runs a Discovery report. This
# example leaves all traffic and results in NetIntercept.
# Specify the time of the alert. This will be used as the name of
# the results database.
#
mydbname=`date +%Y%m%d_%H%M`
mytime=`date +%s`
# Read the text of the syslog message from standard input.
#
read msgmonth msgday msgtime msgip msgtext
# save the syslog message data. The tr call on $text_val removes
# all the quotation marks and replaces them with spaces, to avoid
# SQL insert errors later in the script.
#
date_key='OPS-SYSLOG-MESSAGE-DATE'
date_val=`echo $msgmonth $msgday $msgtime`
ip_key='OPS-SYSLOG-MESSAGE-IP'
ip_val=`echo $msgip`
text_key='OPS-SYSLOG-MESSAGE-TEXT'
text_val=`echo $msgtext | /usr/bin/tr '"' ' '`
# Wait one minute to capture traffic that happen after the alarm.
#
sleep 60
# Immortalize ten minutes's worth of data.
# Note that the $((...)) notation is used to evaluate math in the
# enclosed expression; $(($mydbname-540)) yields whatever is in the
# variable 'mydbname' minus 540. The resulting data is stored into
# a directory named for the time of the alert.
#
/usr/ni/bin/nicmd_immort $(($mytime-540)) $(($mytime+60)) $mydbname
# Sessionize the raw (immortalized) data and parse it into a new
# new database, 'mydbname'. The profile used for this operation is
# the default_profile.
#
/usr/ni/bin/nicmd_parse -p default_profile /ni/immortal/$mydbname $mydbname
# Run the Discovery report, saving it to the default location.
#
/usr/ni/bin/nicmd_report -f html -t discovery -d $mydbname
# Run scandbs to update the per_parse table with syslog message info.
#
/usr/ni/bin/scandbs "insert into per_parse (key_name,value) values('$date_key','$date_val'),\
('$ip_key','$ip_val'),('$text_key','$text_val')" $mydbname
Log in to the NetIntercept system as 'ni'. Create the script as shown, and save it as /usr/ni/autoop_scripts/syslog_10min. The script must be executable; this can be set by entering chmod 755 script_name at a command prompt.
Note: This extremely simple example does not examine the contents of the syslog message. Neither does it have any mechanism to read more than one message at a time; it runs once and stops, expecting syslog to start it again as necessary. Either action may be desirable in your environment, but they are beyond the scope of this document.
3. Configure syslog to Trigger the NetIntercept Script
If the documentation for your firewall is not specific about the facility and level of its syslog messages, capture some of its log traffic with NetIntercept. Double-click the "syslog" content type on the Forensics tab, and access an individual connection from the list that displays. Open the Packet View using the Packets toolbar button. Select View | Detail View from the Packet View menus. You'll see a number in angle brackets at the beginning of the data area of each packet. Decode it by dividing the number by 8. The integer number you get is the facility, and the remainder is the level (use the lists above to translate the numbers).
Log in to the NetIntercept system as 'root'. Add the line below to /etc/syslog.conf. It will launch a NetIntercept automatic operations script whenever a local0 event of severity notice or higher is received. Substitute the facility and level for your device, if different.
local0.notice | exec su ni -c /usr/ni/autoop_scripts/syslog_10min
The action (right-hand side of the line) above starts with a '|', which indicates the message should be sent to a shell. The exec command tells the shell to exit rather than wait, and the su ni -c portion of the command says the script file should be run as the 'ni' user.
In the example syslog.conf file given above, the new line must be inserted above !startslip (it will not work if it is inserted into a multi-line entry).
Note: Some firewalls don't offer any user control over log levels, so enabling syslog will cause a large number of log messages to be sent. The notice level in the example is set so that a reasonable number of messages are sent. Increasing it to warning may be necessary to reduce the flow of events to less than ten per hour.
| 
Sandstorm Home
Products
