2.6 Output Modules

Output modules are new as of version 1.6. They allow Snort to be much more flexible in the formatting and presentation of output to its users. The output modules are run when the alert or logging subsystems of Snort are called, after the preprocessors and detection engine. The format of the directives in the config file is very similar to that of the preprocessors.

Multiple output plugins may be specified in the Snort configuration file. When multiple plugins of the same type (log, alert) are specified, they are stacked and called in sequence when an event occurs. As with the standard logging and alerting systems, output plugins send their data to /var/log/snort by default or to a user directed directory (using the -l command line switch).

Output modules are loaded at runtime by specifying the output keyword in the config file:

    output <name>: <options>

    output alert_syslog: log_auth log_alert

2.6.1 alert_syslog

This module sends alerts to the syslog facility (much like the -s command line switch). This module also allows the user to specify the logging facility and priority within the Snort config file, giving users greater flexibility in logging alerts.

2.6.1.1 Available Keywords

2.6.1.1.1 Facilities

• log_auth
• log_authpriv
• log_daemon
• log_local0
• log_local1
• log_local2
• log_local3
• log_local4
• log_local5
• log_local6
• log_local7
• log_user

2.6.1.1.2 Priorities

• log_emerg
• log_alert
• log_crit
• log_err
• log_warning
• log_notice
• log_info
• log_debug

2.6.1.1.3 Options

• log_cons
• log_ndelay
• log_perror
• log_pid

2.6.1.2 Format

    alert_syslog: \
        <facility> <priority> <options>

Note:  

As WIN32 does not run syslog servers locally by default, a hostname and port can be passed as options. The default host is 127.0.0.1. The default port is 514.

    output alert_syslog: \
        [host=<hostname[:<port>],] \
        <facility> <priority> <options>

2.6.1.3 Example

    output alert_syslog: host=10.1.1.1:514, <facility> <priority> <options>

2.6.2 alert_fast

This will print Snort alerts in a quick one-line format to a specified output file. It is a faster alerting method than full alerts because it doesn't need to print all of the packet headers to the output file and because it logs to only 1 file.

2.6.2.1 Format

    output alert_fast: [<filename> ["packet"] [<limit>]]
    <limit> ::= <number>[('G'|'M'|K')]

• filename: the name of the log file. The default name is $<$logdir$>$/alert. You may specify "stdout" for terminal output. The name may include an absolute or relative path.

• packet: this option will cause multiline entries with full packet headers to be logged. By default, only brief single-line entries are logged.

• limit: an optional limit on file size which defaults to 128 MB. The minimum is 1 KB. See for more information.

2.6.2.2 Example

    output alert_fast: alert.fast

2.6.3 alert_full

This will print Snort alert messages with full packet headers. The alerts will be written in the default logging directory (/var/log/snort) or in the logging directory specified at the command line.

Inside the logging directory, a directory will be created per IP. These files will be decoded packet dumps of the packets that triggered the alerts. The creation of these files slows Snort down considerably. This output method is discouraged for all but the lightest traffic situations.

2.6.3.1 Format

    output alert_full: [<filename> [<limit>]]
    <limit> ::= <number>[('G'|'M'|K')]

• filename: the name of the log file. The default name is $<$logdir$>$/alert. You may specify "stdout" for terminal output. The name may include an absolute or relative path.

• limit: an optional limit on file size which defaults to 128 MB. The minimum is 1 KB. See for more information.

2.6.3.2 Example

    output alert_full: alert.full

2.6.4 alert_unixsock

Sets up a UNIX domain socket and sends alert reports to it. External programs/processes can listen in on this socket and receive Snort alert and packet data in real time.

2.6.4.1 Format

    alert_unixsock

2.6.4.2 Example

    output alert_unixsock

Note:   On FreeBSD, the default sysctl value for net.local.dgram.recvspace is too low for alert_unixsock datagrams and you will likely not receive any data. You can change this value after booting by running:

$ sudo sysctl net.local.dgram.recvspace=100000

To have this value set on each boot automatically, add the following to /etc/sysctl.conf:

net.local.dgram.recvspace=100000

Note that the value of 100000 may be slightly generous, but the value should be at least 65864.

2.6.5 log_tcpdump

The log_tcpdump module logs packets to a tcpdump-formatted file. This is useful for performing post-process analysis on collected traffic with the vast number of tools that are available for examining tcpdump-formatted files.

2.6.5.1 Format

    output log_tcpdump: [<filename> [<limit>]]
    <limit> ::= <number>[('G'|'M'|K')]

• filename: the name of the log file. The default name is $<$logdir$>$/snort.log. The name may include an absolute or relative path. A UNIX timestamp is appended to the filename.

• limit: an optional limit on file size which defaults to 128 MB. When a sequence of packets is to be logged, the aggregate size is used to test the rollover condition. See for more information.

2.6.5.2 Example

    output log_tcpdump: snort.log

2.6.6 csv

The csv output plugin allows alert data to be written in a format easily importable to a database. The output fields and their order may be customized.

2.6.6.1 Format

    output alert_csv: [<filename> [<format> [<limit>]]]
    <format> ::= "default"|<list>
    <list> ::= <field>(,<field>)*
    <field> ::= "dst"|"src"|"ttl" ...
    <limit> ::= <number>[('G'|'M'|K')]

• filename: the name of the log file. The default name is $<$logdir$>$/alert.csv. You may specify "stdout" for terminal output. The name may include an absolute or relative path.

• format: The list of formatting options is below. If the formatting option is "default", the output is in the order of the formatting options listed.
  • timestamp
  • sig_generator
  • sig_id
  • sig_rev
  • msg
  • proto
  • src
  • srcport
  • dst
  • dstport
  • ethsrc
  • ethdst
  • ethlen
  • tcpflags
  • tcpseq
  • tcpack
  • tcplen
  • tcpwindow
  • ttl
  • tos
  • id
  • dgmlen
  • iplen
  • icmptype
  • icmpcode
  • icmpid
  • icmpseq

• limit: an optional limit on file size which defaults to 128 MB. The minimum is 1 KB. See for more information.

2.6.6.2 Example

    output alert_csv: /var/log/alert.csv default

    output alert_csv: /var/log/alert.csv timestamp, msg

2.6.7 unified 2

Unified2 can work in one of three modes, packet logging, alert logging, or true unified logging. Packet logging includes a capture of the entire packet and is specified with log_unified2. Likewise, alert logging will only log events and is specified with alert_unified2. To include both logging styles in a single, unified file, simply specify unified2.

When MPLS support is turned on, MPLS labels can be included in unified2 events. Use option mpls_event_types to enable this. If option mpls_event_types is not used, then MPLS labels will be not be included in unified2 events.

Note:  

By default, unified 2 files have the file creation time (in Unix Epoch format) appended to each file when it is created.

2.6.7.1 Format

    output alert_unified2: \
        filename <base filename> [, <limit <size in MB>] [, nostamp] [, mpls_event_types] \
        [, vlan_event_types]

    output log_unified2: \
        filename <base filename> [, <limit <size in MB>] [, nostamp]

    output unified2: \
        filename <base file name> [, <limit <size in MB>] [, nostamp] [, mpls_event_types] \
        [, vlan_event_types]

2.6.7.2 Example

    output alert_unified2: filename snort.alert, limit 128, nostamp
    output log_unified2: filename snort.log, limit 128, nostamp
    output unified2: filename merged.log, limit 128, nostamp
    output unified2: filename merged.log, limit 128, nostamp, mpls_event_types
    output unified2: filename merged.log, limit 128, nostamp, vlan_event_types

2.6.7.3 Extra Data Configurations

Unified2 also has logging support for various extra data. The following configuration items will enable these extra data logging facilities.

config log_ipv6_extra_data

This option enables Snort to log IPv6 source and destination address as unified2 extra data events.

See section for more information

enable_xff

This option enables HTTP Inspect to parse and log the original client IP present in the X-Forwarded-For, True-Client-IP, or custom HTTP request headers along with the generated events.

See section for more information

log_uri

This option enables HTTP Inspect to parse and log the URI data from the HTTP request and log it along with all the generated events for that session.

See section for more information

log_hostname

This option enables HTTP Inspect to parse and log the Host header data from the HTTP request and log it along with all the generated events for that session.

See section for more information

log_hostname

This option enables HTTP Inspect to parse and log the Host header data from the HTTP request and log it along with all the generated events for that session.

See section for more information

log_mailfrom

This option enables SMTP preprocessor to parse and log the senders email address extracted from the "MAIL FROM" command along with all the generated events for that session.

See section for more information

log_rcptto

This option enables SMTP preprocessor to parse and log the recipients email address extracted from the "RCPT TO" command along with all the generated events for that session.

See section for more information

log_filename

This option enables SMTP preprocessor to parse and log the MIME attachment filenames extracted from the Content-Disposition header within the MIME body along with all the generated events for that session.

See section for more information

log_email_hdrs

This option enables SMTP preprocessor to parse and log the SMTP email headers extracted from the SMTP data along with all the generated events for that session.

See section for more information

2.6.7.4 Reading Unified2 Files

2.6.7.5 U2SpewFoo

U2SpewFoo is a lightweight tool for dumping the contents of unified2 files to stdout.

Example usage:

    
    u2spewfoo snort.log

Example Output:

(Event)
    sensor id: 0    event id: 4 event second: 1299698138    event microsecond: 146591
    sig id: 1   gen id: 1   revision: 0  classification: 0
    priority: 0 ip source: 10.1.2.3 ip destination: 10.9.8.7
    src port: 60710 dest port: 80   protocol: 6 impact_flag: 0  blocked: 0

Packet
    sensor id: 0    event id: 4 event second: 1299698138
    packet second: 1299698138   packet microsecond: 146591
    linktype: 1 packet_length: 54
[    0] 02 09 08 07 06 05 02 01 02 03 04 05 08 00 45 00  ..............E.
[   16] 00 28 00 06 00 00 40 06 5C B7 0A 01 02 03 0A 09  .(....@.\.......
[   32] 08 07 ED 26 00 50 00 00 00 62 00 00 00 2D 50 10  ...&.P...b...-P.
[   48] 01 00 A2 BB 00 00                                ......

(ExtraDataHdr)
    event type: 4   event length: 33

(ExtraData)
    sensor id: 0    event id: 2 event second: 1299698138
    type: 9 datatype: 1 bloblength: 9   HTTP URI: /

(ExtraDataHdr)
    event type: 4   event length: 78

(ExtraData)
    sensor id: 0    event id: 2 event second: 1299698138
    type: 10    datatype: 1 bloblength: 12  HTTP Hostname: example.com

2.6.7.6 U2Boat

U2boat is a tool for converting unified2 files into different formats.

Currently supported conversion formats are: pcap

Example usage:

    u2boat -t pcap <infile> <outfile>

2.6.8 log null

Sometimes it is useful to be able to create rules that will alert to certain types of traffic but will not cause packet log entries. In Snort 1.8.2, the log_null plugin was introduced. This is equivalent to using the -n command line option but it is able to work within a ruletype.

2.6.8.1 Format

    output log_null

2.6.8.2 Example

    output log_null  # like using snort -n
    
    ruletype info {
        type alert
        output alert_fast: info.alert
        output log_null
    }

2.6.9 Log Limits

This section pertains to logs produced by alert_fast, alert_full, alert_csv, and log_tcpdump. unified2 also may be given limits. Those limits are described in the respective sections.

When a configured limit is reached, the current log is closed and a new log is opened with a UNIX timestamp appended to the configured log name.

Limits are configured as follows:

    <limit> ::= <number>[(<gb>|<mb>|<kb>)]
    <gb> ::= 'G'|'g'
    <mb> ::= 'M'|'m'
    <kb> ::= 'K'|'k'

Rollover will occur at most once per second so if limit is too small for logging rate, limit will be exceeded. Rollover works correctly if snort is stopped/restarted.