 |
Snort XML Output Plugin
This web page contains the latest information for the XML output plugin of Snort v2.x. Documentation for the plugin found in Snort v1.x can be found here.
Overview
The XML plug-in formats alerts into an XML document and logs them to a file or remote server.
Currently, the only XML document type (DTD) supported is version 0.3 of the Simpled Network Markup Language (SNML).
Other tools to manage documents of this type can be found at http://aircert.sourceforge.net/.
Dependencies
The plug-in has the following dependencies that should be
installed prior to building Snort:
o Package: libairutil
Version: 0.2.24+
Description: catch-all library for common AirCERT component tasks;
it provides the networking code
Homepage: http://aircert.sourceforge.net/libairutil/
o Package: libih
Version: 0.2.20+
Description: SNML, IODEF, IDMEF XML manipulation library
Homepage: http://aircert.sourceforge.net/libih/
The above libraries have other dependencies such expat and OpenSSL.
Please read the documentation carefully.
Building from Source
In order to build a version of Snort with XML support, the --with-libih and --with-libairutil options must be passed to the ./configure script. For example, $ ./configure --with-libih --with-libairtutil These options inform the configure script to search for the libih-config and libairutil-config applications in the standard directories. If these applications have been installed in non-standard locations, specify the directory in which these programs have been installed. For example, $ ./configure --with-libih=/opt/bin --with-libairutil
Configuration
The XML plugin is configured via the Snort configuration file with an
"output xml" directive. This directive as the following format:
output xml: [log | alert], [parameter list]
Arguments:
[log | alert] - specify the Snort logging facility
[parameter list] - The parameter list consists of key value
pairs. The proper format is a list of key=value pairs each
separated a space.
----| File logging |----------------------------------------------
file - { file name }
The base file to which XML format alerts will be
logged. The plugin will append a timestamp, and
sequence number to this name.
See #define XML_FILE_SUFFIX_FORMAT in spo_xml.c
explicit details.
----| Network logging |-------------------------------------------
url - { <protocol>://<host>:<port>[/<script>] }
A uri to which the XML document will be sent
over the network. The uri has the following format:
<protocol> = { http, https, tls, tcp }
Protocol to use when sending the document
<host> = IP address or hostname of the computer
to which to send the document
<port> = destination port on host
<script> = [https and http only]
script to which to send the HTTP POST
keepalive - { 0, 1 } default=0
Should a new connection be established for each
XML document sent?
0 - (default) open/close the network connection for
each document sent
1 - open the network connection only once, and reuse
it for subsequent documents
--------| TLS/SSL Network logging |--------------------------------
The following parameters only apply when network logging via
the tls or https protocol are specified. They dictate the
authentication used by TLS/SSL
cert - client (snort) X.509 certificate (PEM formatted)
key - client (snort) private key (PEM formatted)
server - peer (server) X.509 certificate (PEM formatted). Used
for authentication purposes
ca - issuer X.509 certificate (PEM formatted). This
certificate needs to be the issuer of the certificates
specified for the client and peer.
----| Miscellaneous |---------------------------------------------
acnt - { number } default=1000
Number of alerts to embed in a document. When this
threshold is reached, a log file is generated or the
document is sent to the network target. Prior to being
flushed, the alert data is temporarily buffered in
memory.
Consideration of network latency, remote host
processing time, host machine memory, etc. should
be included in tuning this parameter. Generally,
network based logging should use a much smaller acnt,
than file based logging.
encoding - { hex, base64, ascii } default=hex
Encoding format for binary payload data found in
the packet payload or option data.
hex: (default) Represent binary data as a hex string
storage .......... 2x the size of the binary
searchability..... good
human readability. requires post processing
base64: Represent binary data as a base64 string.
storage .......... ~1.3x the size of the binary
searchability..... no substring matching
human readability. requires post processing
ascii: Represent binary data as an ascii string.
Non-printable characters are represented as ".";
Special XML characters are escaped.
Note: This data representation is lossy
storage .......... almost 1x the size of binary
searchability..... good for ascii data
impossible for binary data
human readability. good
detail - { full, fast } default=full
Completeness of the report.
full: (default) log all alert information
fast: log only a minimum amount of data (i.e., timestamp,
signature, source and destination IP/port, TCP flags,
and IP protocol)
Examples
o Example 1: output xml: log, file=/var/snort/log/output.xml
Using the log facility, write alerts to the files beginning with
"output.xml"
o Example 2: output xml: log, file=/var/snort/log/output.xml \
acnt=20000 detail=fast
Identical to example 1, but write 20000 alerts into each file with
a detail level of "fast"
o Example 3: output xml: alert, url=tcp://10.1.2.3:4000
Using the alert facility, send alerts to the host 10.1.2.3 on a
TCP socket on port 4000
o Example 4: output xml: alert, url=tcp://10.1.2.3:4000 keepalive=1
Identical to example 2, but do no close the socket after sending the
document
o Example 5: output xml: alert, url=https://10.1.2.3:443/foo.cgi \
cert=mycert.crt \
key=mykey.key \
ca=ca.crt \
server=peer.crt
Using the alert facility, send alerts to the host 10.1.2.3 via
HTTPS on port 443 to the foo.cgi script. The client certificate
and key will be 'mycert.{crt|key}', and the peer certificate is
'peer.crt'. All certificate were issued by 'ca.crt'.
Changelog
05/08/2003 : Initial v2.0 release
TODO
* speed optimizations on tree setting
- do not ih_create_tree()/destroy() on flush, mark isset=0
instead
- eliminate air_replace()s by pre-computing sibling cnts in
the set macros (i.e., make paths relative to current
/SNML-Message/event(x)
* acnt parameter takes a memory limit instead of an explicit alert
count
* investigate supporting other DTDs
Please direct any feedback to the snort-users mailing list or you can contact the authors directly.
- Roman Danyliw <rdd@cert.org>
Last updated May 14, 2003
Disclaimers and copyright information
