SnortSocket

A NodeJS listener to capture Snort events via the UNIX Socket output plugin, alert_unixsock

This project aims to provide a simple listener for the alerts raised by the popular Snort IDS, allowing for custom actions to be fired in response to the alerts.

Basics

The following shows the simplest way to start listening for Snort alerts, using the default options and echoing the alert information to the screen:

var SnortSocket = require('snort-socket').SnortSocket;
var socket = new SnortSocket();
socket.on('alert', function(a) { console.log(util.inspect(a)); });
socket.bind('/var/log/snort/snort_alert');

Dependencies

• Snort, Baker, Roesch, SourceFire Inc. This project is designed to capture alerts emitted by the Snort IDS, so Snort is required to generate these alerts.

• unix-dgram, Ben Noordhuis, et al Required when using NodeJS v0.6+, as native support for UNIX Datagram sockets was removed. Optional when using lesser versions of NodeJS, but can be invoked using the forceUnixDgram option (see below).

Setting up

You should include the following output plugin configuration in your snort.conf (or barnyard.conf, if you prefer):

output alert_unixsock

The NodeJS script that executes consuming code should run on the same machine and under the same user account as the Snort daemon, otherwise Snort will not write to the socket created by NodeJS. This may be resolvable with the correct owner/group permissions but these are not controllable via the SnortSocket object.

API

The module provides the following objects/methods:

Object: SnortSocket([options]);

Creates a new instance of the SnortSocket listener.

Examples

• var s = new SnortSocket();
• var s = new SnortSocket({ bigEndian: true });

Options

options is an object hash that can contain the following values:

• alertMessageLength [Number; defaults to 256] Defines the maximum length of the message that will be emitted by Snort. This is not expected to change from 256 but, if future/custom versions of Snort are released with a different value, this option will allow SnortSocket to be made to match. This should always be made to tally with the ALERTMSG_LENGTH definition in the source code of your version of Snort.

• snapshotLength [Number; defaults to 65536] Defines the maximum length of the data packet included in alerts emitted by Snort. Earlier versions of Snort had this fixed to 1500, but more-recent versions have increased this to 65536. This should always be made to tally with the SNAPLEN definition in the source code of your version of Snort.

• forceUnixDgram [Boolean; defaults to false] If true, SnortSocket will use the unix-dgram module to create the underlying UNIX datagram socket, regardless of the running version of NodeJS; otherwise, the native dgram module is used in versions of NodeJS less than v0.6.

• bigEndian [Boolean; defaults to false] If true, reads integers from the alert data using big-endian read routines; otherwise uses the little-endian routines. This does not affect data that is read from the packet snapshot, which should always be in network order (big endian). This may need to be set to true on known big-endian platforms (although I do not run one for test purposes).

• debug [Boolean; defaults to false] If true, spools debug messages to the console; otherwise the SnortSocket runs with no output.

Method: socket.bind(socketPath, [callback]);

Binds the listener to the supplied socketPath.

Parameters

• socketPath [String; no default] The path to the snort_alert socket, which typically exists in the logging directory configured in snort.conf. If a file already exists with that path, it is first unlinked (deleted) before the socket is bound.

• callback [Function(err:Error); default function() { }] A function to be run once the bind operation is completed. If an error occurs during the bind process, it is passed as the first argument to this function; otherwise the bind is successful.

Example

• socket.bind('/var/log/snort/snort_alert');
• socket.bind('/var/log/snort/snort_alert', function(err) { if (!!err) throw err; });

Method: socket.close([callback]);

Closes the underlying socket, preventing further alerts from being handled.

Parameters

• callback [Function(); default function() { }] A function to be run once the close operation is completed and the underlying socket has emitted its close event.

Example

• socket.close(function() { console.log('closed'); });
• socket.close();

Event: listening [Function()]

Emitted by the SnortSocket when it has initialized and is actively listening for alerts

Event: error [Function(err:Error)]

Emitted by the SnortSocket when it has recovered from an exception. The raised exception will be passed as the first parameter to the handler function

Event: close [Function(didError:Boolean)]

Emitted by the SnortSocket when it has disconnected from the underlying socket and is no longer listening for events. If the underling socket closed because of an exception, didError will be true; otherwise false

Event: alert [Function(alert:Alert)]

Emitted by the SnortSocket when it has received an alert from the Snort IDS. Details of the alert are provided as the first parameter to the handler function; see the Alert object section

Alerts

Alerts details are emitted by the alert event, as an nested object hash with a number of properties describing the event. These properties are as follows:

• message [String] — Descriptive text for the alert
• protocol.ip [Number] — The IP version of the packet that caused the alert
• protocol.id [Number] — The protocol number for the packet (e.g. 6 = TCP; 17 = UDP)
• protocol.name [String] — A name representation of the protocol ID (e.g. tcp, udp)
• protocol.fields [Object] — Reserved for protocol-specific fields (e.g. ICMP type)
• source.address [String] — The IP address from which the alerting packet arrived
• source.port [Number] — The TCP/UDP port on which the alerting packet arrived
• destination.address [String] — The IP address to which the alerting packet was sent
• destination.port [Number] — The TCP/UDP port to which the alerting packet was sent
• event.id [Number] — A unique event ID provided by Snort
• event.ref [Number] — A reference to a previous event ID, if linked
• event.class [Number] — The alert classification value provided by Snort
• event.priority [Number] — The alert priorty value provided by Snort
• event.timestamp.seconds [Number] — The alert time, in number of seconds since 1970-01-01T00:00:00Z
• event.timestamp.micros [Number] — The number of microseconds in addition to the alert time in seconds
• event.timestamp.date [Date] — The JS date representation of the alert time (to nearest millisecond)

Compatibility Issues

• The alert_unixsock output plugin for Snort only works in UNIX/Linux-type systems; likewise, the SnortSocket module is only supported on UNIX/Linux-type systems

• Earlier versions of NodeJS had native support for UNIX datagram sockets, but this was removed in v0.6. The optional dependency unix-dgram is required for use with NodeJS v0.6+

• The UNIX datagram support in earlier versions of NodeJS limited the maximum size of a received datagram to 65,536B. Newer versions of Snort exceed this datagram size, which makes capturing full details of the alert impossible. As such, SnortSocket will only work with the older, native UNIX datagram module if the Snort code was compiled with a SNAPLEN value (and, subsequently, the SnortSocket object was created with the snapshotLength option) small enough to fit inside the 65,536B limit. If not, the use of unix-dgram must be forced with the forceUnixDgram option.

Licensing

The SnortSocket code is licensed under the MIT license, where applicable, which is included at the top of each source file and is duplicated below:

Copyright (c) 2012 Jamie Barnes

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

The SnortSocket code does not include any portion of the Snort codebase but can read data exported by Snort, which requires knowledge of the data format derived from the Snort source files. As such, some artifacts from the original source files may exist within the SnortSocket source, in reference comments, but these do not form part of the executing code.

This project is not affiliated with the Snort project, or its creators/maintainers, and no warranty, copyright or ownership regarding the Snort project is implied. For the avoidance of doubt, however, Snort is licensed under the General Public License v2, the full text of which is available at http://www.gnu.org/licenses/gpl-2.0.html.

$Id: readme.md 22 2012-06-19 21:54:09Z jimbobmcgee $