Skip to content
unified2 parser for nodejs
JavaScript
Find file
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.
lib
tests
.gitignore
LICENSE
README.md
package.json

README.md

Unified2

A small library for unified2 parsing in node.js. Unified2 is a common output format for network intrusion detection devices such as Snort + Suricata.

See Sourcefire's documentation for the unified2 protocol: http://manual.snort.org/node44.html

Installation

$ npm install unified2 

Usage

Example

var unified2 = require('unified2');
parser = new unified2unified2.Parser('unified2.alert.14560142132', { offset: 0 });

parser.on('data', function(data) {
  // event data...
});

parser.on('error', function(error) {
  // error
});

parser.on('eof', function() {
  // triggered when an EOF (no data is received).  Useful to save a bookmark
  // when you are running in tail mode (see below).

});

parser.on('rollover', function() {
  // triggered when a rollover is detected (the file shrinks in size)
});

parser.on('end', function(data) {
  // triggered when parser ends (e.g., out of data)
});

parser.run()

Tailing a file

It is often useful to wait for more data as the file is being written, e.g. by a Snort sensor.

Simply pass tail: true in the options for the parser to wait for more logs, e.g.:

var unified2 = require('unified2');
parser = new unified2.Parser('unified2.alert.14560142132', { offset: 0, tail: true });
...
parser.run();

To stop the parser, you can do parser.stop() which will trigger an end event.

Bookmark

To read the current bookmark, you can use parser.last_read_position, which is the offset after the last read unified2 event. Useful after a 'eof' event or 'end' event if you wish to resume parsing again later, you can pass this into the offset: <value> parameter in the Parser constructor.

Debug logging

pass in DEBUG=unified2 as an environment variable to turn on debug logging.

Is it fast? This is javascript after all.

In tests, parsing happens at about ~7000k/events per second. Obviously, this slows down as you add processing and IO.

Here's reading ~4.6 MB and writing parsed objects (~34MB) to stdout.

unified2 (master*) $ time node tests/test.js > /tmp/test.js.output                                                                                                                                                                ~/src/unified2
node tests/test.js > /tmp/test  11.67s user 0.38s system 100% cpu 11.977 total

Missing?

Right now, this is just a bare bones parser. E.g., the pcaps and extra data are not correlated with the ids event messages. This is intentional.

Please refer to Pigsty (https://github.com/threatstack/pigsty) for a more complete unified2 parser and plugin framework for handling the output.

Bug Reporting

Please use Github or email support@threatstack.com.

License

Copyright (C) 2013 Threat Stack, Inc (https://www.threatstack.com)

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.

Something went wrong with that request. Please try again.