Install SNORT 3.0

The section will walk you through building and running Snort. It is not exhaustive but, once you master this material, you should be able to figure out more advanced usage.

Dependencies

Required:

• autotools or cmake to build from source
  
• daq from http://www.snort.org for packet IO
  
• g++ >= 4.8 or other recent C++11 compiler
  
• dnet from https://github.com/dugsong/libdnet.git for network utility functions
  
• hwloc from https://www.open-mpi.org/projects/hwloc/ for CPU affinity management
  
• LuaJIT from http://luajit.org for configuration and scripting
  
• OpenSSL from https://www.openssl.org/source/ for SHA and MD5 file signatures, the protected_content rule option, and SSL service detection
  
• pcap from http://www.tcpdump.org for tcpdump style logging
  
• pcre from http://www.pcre.org for regular expression pattern matching
  
• pkgconfig from https://www.freedesktop.org/wiki/Software/pkg-config/ to locate build dependencies
  
• zlib from http://www.zlib.net for decompression (>= 1.2.8 recommended)
  

Optional:

• asciidoc from http://www.methods.co.nz/asciidoc/ to build the HTML manual
  
• cpputest from http://cpputest.github.io to run additional unit tests with make check
  
• dblatex from http://dblatex.sourceforge.net to build the pdf manual (in addition to asciidoc)
  
• flatbuffers from https://google.github.io/flatbuffers/ for enabling the flatbuffers serialization format
  
• hyperscan >= 4.4.0 from https://github.com/01org/hyperscan to build new the regex and sd_pattern rule options and hyperscan search engine
  
• iconv from https://ftp.gnu.org/pub/gnu/libiconv/ for converting UTF16-LE filenames to UTF8 (usually included in glibc)
  
• lzma >= 5.1.2 from http://tukaani.org/xz/ for decompression of SWF and PDF files
  
• safec from https://sourceforge.net/projects/safeclib/ for runtime bounds checks on certain legacy C-library calls
  
• source-highlight from http://www.gnu.org/software/src-highlite/ to generate the dev guide
  
• w3m from http://sourceforge.net/projects/w3m/ to build the plain text manual
  
• uuid from uuid-dev package for unique identifiers
  

Building

• Optionally built features are listed in the reference section.
  
• Create an install path:
  

  export my_path=/path/to/snorty
  mkdir -p $my_path

• If you are using a github clone with autotools, do this:
  

  autoreconf -isvf

• Now do one of the following:
  
  1. To build with autotools, simply do the usual from the top level directory:
     

     ./configure --prefix=$my_path
     make -j 8
     make install

  2. To build with cmake and make, run configure_cmake.sh. It will automatically create and populate a new subdirectory named build.
     

     ./configure_cmake.sh --prefix=$my_path
     cd build
     make -j 8
     make install
     ln -s $my_path/conf $my_path/etc

  3. You can also specify a cmake project generator:
     

     ./configure_cmake.sh --generator=Xcode --prefix=$my_path

  4. Or use ccmake directly to configure and generate from an arbitrary build directory like one of these:
     

     ccmake -G Xcode /path/to/Snort++/tree
     open snort.xcodeproj

     ccmake -G "Eclipse CDT4 - Unix Makefiles" /path/to/Snort++/tree
     run eclipse and do File > Import > Existing Eclipse Project

• To build with g++ on OS X where clang is installed, do this first:
  

  export CXX=g++

Running

First set up the environment:

export LUA_PATH=$my_path/include/snort/lua/\?.lua\;\;
export SNORT_LUA_PATH=$my_path/etc/snort/

Then give it a go:

• Get some help:
  

  $my_path/bin/snort --help
  $my_path/bin/snort --help-module suppress
  $my_path/bin/snort --help-config | grep thread

• Examine and dump a pcap:
  

  $my_path/bin/snort -r <pcap>
  $my_path/bin/snort -L dump -d -e -q -r <pcap>

• Verify config, with or w/o rules:
  

  $my_path/bin/snort -c $my_path/etc/snort/snort.lua
  $my_path/bin/snort -c $my_path/etc/snort/snort.lua -R $my_path/etc/snort/sample.rules

• Run IDS mode. To keep it brief, look at the first n packets in each file:
  

  $my_path/bin/snort -c $my_path/etc/snort/snort.lua -R $my_path/etc/snort/sample.rules \
      -r <pcap> -A alert_test -n 100000

• Let’s suppress 1:2123. We could edit the conf or just do this:
  

  $my_path/bin/snort -c $my_path/etc/snort/snort.lua -R $my_path/etc/snort/sample.rules \
      -r <pcap> -A alert_test -n 100000 --lua "suppress = { { gid = 1, sid = 2123 } }"

• Go whole hog on a directory with multiple packet threads:
  

  $my_path/bin/snort -c $my_path/etc/snort/snort.lua -R $my_path/etc/snort/sample.rules \
      --pcap-filter \*.pcap --pcap-dir <dir> -A alert_fast -n 1000 --max-packet-threads 8

For more examples, see the usage section.

Tips

One of the goals of Snort 3 is to make it easier to configure your sensor. Here is a summary of tips and tricks you may find useful.

General Use

• Snort tries hard not to error out too quickly. It will report multiple semantic errors.
  
• Snort always assumes the simplest mode of operation. Eg, you can omit the -T option to validate the conf if you don’t provide a packet source.
  
• Warnings are not emitted unless --warn-* is specified. --warn-all enables all warnings, and --pedantic makes such warnings fatal.
  
• You can process multiple sources at one time by using the -z or --max-threads option.
  
• To make it easy to find the important data, zero counts are not output at shutdown.
  
• Load plugins from the command line with --plugin-path /path/to/install/lib.
  
• You can process multiple sources at one time by using the -z or --max-threads option.
  
• Unit tests are configured with --enable-unit-tests. They can then be run with snort --catch-test [tags]|all.
  

Lua Configuration

• Configure the wizard and default bindings will be created based on configured inspectors. No need to explicitly bind ports in this case.
  
• You can override or add to your Lua conf with the --lua command line option.
  
• The Lua conf is a live script that is executed when loaded. You can add functions, grab environment variables, compute values, etc.
  
• You can also rename symbols that you want to disable. For example, changing normalizer to Xnormalizer (an unknown symbol) will disable the normalizer. This can be easier than commenting in some cases.
  
• By default, symbols unknown to Snort are silently ignored. You can generate warnings for them with --warn-unknown. To ignore such symbols, export them in the environment variable SNORT_IGNORE.
  

Writing and Loading Rules

Snort rules allow arbitrary whitespace. Multi-line rules make it easier to structure your rule for clarity. There are multiple ways to add comments to your rules:

• The # character starts a comment to end of line. In addition, all lines between #begin and #end are comments.
  
• The rem option allows you to write a comment that is conveyed with the rule.
  
• C style multi-line comments are allowed, which means you can comment out portions of a rule while testing it out by putting the options between /* and */.
  

There are multiple ways to load rules too:

• Set ips.rules or ips.include.
  
• include statements can be used in rules files.
  
• Use -R to load a rules file.
  
• Use --stdin-rules with command line redirection.
  
• Use --lua to specify one or more rules as a command line argument.
  

Output Files

To make it simple to configure outputs when you run with multiple packet threads, output files are not explicitly configured. Instead, you can use the options below to format the paths:

<logdir>/[<run_prefix>][<id#>][<X>]<name>

• logdir is set with -l and defaults to ./
  
• run_prefix is set with --run-prefix else not used
  
• id# is the packet thread number that writes the file; with one packet thread, id# (zero) is omitted without --id-zero
  
• X is / if you use --id-subdir, else _ if id# is used
  
• name is based on module name that writes the file
  
• all text mode outputs default to stdout
  

Help

Snort has several options to get more help:

-? list command line options (same as --help)
--help this overview of help
--help-commands [<module prefix>] output matching commands
--help-config [<module prefix>] output matching config options
--help-counts [<module prefix>] output matching peg counts
--help-module <module> output description of given module
--help-modules list all available modules with brief help
--help-plugins list all available plugins with brief help
--help-options [<option prefix>] output matching command line options
--help-signals dump available control signals
--list-buffers output available inspection buffers
--list-builtin [<module prefix>] output matching builtin rules
--list-gids [<module prefix>] output matching generators
--list-modules [<module type>] list all known modules
--list-plugins list all known modules
--show-plugins list module and plugin versions

--help* and --list* options preempt other processing so should be last on the
command line since any following options are ignored.  To ensure options like
--markup and --plugin-path take effect, place them ahead of the help or list
options.

Options that filter output based on a matching prefix, such as --help-config
won't output anything if there is no match.  If no prefix is given, everything
matches.

Report bugs to bugs@snort.org.

Common Errors

FATAL: snort_config is required

• add this line near top of file:
  

  require('snort_config')

PANIC: unprotected error in call to Lua API (cannot open snort_defaults.lua: No such file or directory)

• export SNORT_LUA_PATH to point to any dofiles
  

ERROR can’t find xyz

• if xyz is the name of a module, make sure you are not assigning a scalar where a table is required (e.g. xyz = 2 should be xyz = { }).
  

ERROR can’t find x.y

• module x does not have a parameter named y. check --help-module x for available parameters.
  

ERROR invalid x.y = z

• the value z is out of range for x.y. check --help-config x.y for the range allowed.
  

ERROR: x = { y = z } is in conf but is not being applied

• make sure that x = { } isn’t set later because it will override the earlier setting. same for x.y.
  

FATAL: can’t load lua/errors.lua: lua/errors.lua:68: = expected near ';'

• this is a syntax error reported by Lua to Snort on line 68 of errors.lua.
  

ERROR: rules(2) unknown rule keyword: find.

• this was due to not including the --script-path.
  

WARNING: unknown symbol x

• if you any variables, you can squelch such warnings by setting them in an environment variable SNORT_IGNORE. to ignore x, y, and z:
  

  export SNORT_IGNORE="x y z"

Gotchas

• A nil key in a table will not caught. Neither will a nil value in a table. Neither of the following will cause errors, nor will they actually set http_server.post_depth:
  

  http_server = { post_depth }
  http_server = { post_depth = undefined_symbol }

• It is not an error to set a value multiple times. The actual value applied may not be the last in the table either. It is best to avoid such cases.
  

  http_server =
  {
      post_depth = 1234,
      post_depth = 4321
  }

• Snort can’t tell you the exact filename or line number of a semantic error but it will tell you the fully qualified name.
  
• The dump DAQ will not work with multiple threads unless you use --daq-var file=/dev/null. This will be fixed in at some point to use the Snort log directory, etc.
  
• configure will use clang by default if it is installed. To compile with g instead:
  

  export CXX=g++

• If you build with hyperscan on OS X and see:
  

  dyld: Library not loaded: @rpath/libhs.4.0.dylib

  when you try to run src/snort, export DYLD_LIBRARY_PATH with the path to
  libhs.  You can also do:

  install_name_tool -change @rpath/libhs.4.0.dylib \
      /path-to/libhs.4.0.dylib src/snort

Usage

For the following examples "$my_path" is assumed to be the path to the Snort install directory. Additionally, it is assumed that "$my_path/bin" is in your PATH.

Environment

LUA_PATH is used directly by Lua to load and run required libraries. SNORT_LUA_PATH is used by Snort to load supplemental configuration files.

export LUA_PATH=$my_path/include/snort/lua/\?.lua\;\;
export SNORT_LUA_PATH=$my_path/etc/snort

Help

Print the help summary:

snort --help

Get help on a specific module ("stream", for example):

snort --help-module stream

Get help on the "-A" command line option:

snort --help-options A

Grep for help on threads:

snort --help-config | grep thread

Output help on "rule" options in AsciiDoc format:

snort --markup --help-options rule

Snort stops reading command-line options after the "--help-" and "--list-" options, so any other options should be placed before them.

Sniffing and Logging

Read a pcap:

snort -r /path/to/my.pcap

Dump the packets to stdout:

snort -r /path/to/my.pcap -L dump

Dump packets with application data and layer 2 headers

snort -r /path/to/my.pcap -L dump -d -e

Command line options must be specified separately. "snort -de" won’t work. You can still concatenate options and their arguments, however, so "snort -Ldump" will work.

Dump packets from all pcaps in a directory:

snort --pcap-dir /path/to/pcap/dir --pcap-filter '*.pcap' -L dump -d -e

Log packets to a directory:

snort --pcap-dir /path/to/pcap/dir --pcap-filter '*.pcap' -L dump -l /path/to/log/dir

Configuration

Validate a configuration file:

snort -c $my_path/etc/snort/snort.lua

Validate a configuration file and a separate rules file:

snort -c $my_path/etc/snort/snort.lua -R $my_path/etc/snort/sample.rules

Read rules from stdin and validate:

snort -c $my_path/etc/snort/snort.lua --stdin-rules < $my_path/etc/snort/sample.rules

Enable warnings for Lua configurations and make warnings fatal:

snort -c $my_path/etc/snort/snort.lua --warn-all --pedantic

Tell Snort where to look for additional Lua scripts:

snort --script-path /path/to/script/dir

IDS mode

Run Snort in IDS mode, reading packets from a pcap:

snort -c $my_path/etc/snort/snort.lua -r /path/to/my.pcap

Log any generated alerts to the console using the "-A" option:

snort -c $my_path/etc/snort/snort.lua -r /path/to/my.pcap -A alert_full

Capture separate stdout, stderr, and stdlog files (out has startup and shutdown output, err has warnings and errors, and log has alerts):

snort -c $my_path/etc/snort/snort.lua -r /path/to/my.pcap -A csv \
    1>out 2>err 3>log

Add or modify a configuration from the command line using the "--lua" option:

snort -c $my_path/etc/snort/snort.lua -r /path/to/my.pcap -A cmg \
    --lua 'ips = { enable_builtin_rules = true }'

The "--lua" option can be specified multiple times.

Run Snort in IDS mode on an entire directory of pcaps, processing each input source on a separate thread:

snort -c $my_path/etc/snort/snort.lua --pcap-dir /path/to/pcap/dir \
    --pcap-filter '*.pcap' --max-packet-threads 8

Run Snort on 2 interfaces, eth0 and eth1:

snort -c $my_path/etc/snort/snort.lua -i "eth0 eth1" -z 2 -A cmg

Run Snort inline with the afpacket DAQ:

snort -c $my_path/etc/snort/snort.lua --daq afpacket -i "eth0:eth1" \
    -A cmg

Plugins

Load external plugins and use the "ex" alert:

snort -c $my_path/etc/snort/snort.lua \
    --plugin-path $my_path/lib/snort_extra \
    -A alert_ex -r /path/to/my.pcap

Test the LuaJIT rule option find loaded from stdin:

snort -c $my_path/etc/snort/snort.lua \
    --script-path $my_path/lib/snort_extra \
    --stdin-rules -A cmg -r /path/to/my.pcap << END
alert tcp any any -> any 80 (
    sid:3; msg:"found"; content:"GET";
    find:"pat='HTTP/1%.%d'" ; )
END

Output Files

To make it simple to configure outputs when you run with multiple packet threads, output files are not explicitly configured. Instead, you can use the options below to format the paths:

<logdir>/[<run_prefix>][<id#>][<X>]<name>

Log to unified in the current directory:

snort -c $my_path/etc/snort/snort.lua -r /path/to/my.pcap -A unified2

Log to unified in the current directory with a different prefix:

snort -c $my_path/etc/snort/snort.lua -r /path/to/my.pcap -A unified2 \
    --run-prefix take2

Log to unified in /tmp:

snort -c $my_path/etc/snort/snort.lua -r /path/to/my.pcap -A unified2 -l /tmp

Run 4 packet threads and log with thread number prefix (0-3):

snort -c $my_path/etc/snort/snort.lua --pcap-dir /path/to/pcap/dir \
    --pcap-filter '*.pcap' -z 4 -A unified2

Run 4 packet threads and log in thread number subdirs (0-3):

snort -c $my_path/etc/snort/snort.lua --pcap-dir /path/to/pcap/dir \
    --pcap-filter '*.pcap' -z 4 -A unified2 --id-subdir

subdirectories are created automatically if required. Log filename is based on module name that writes the file. All text mode outputs default to stdout. These options can be combined.

DAQ Alternatives

Process hext packets from stdin:

snort -c $my_path/etc/snort/snort.lua \
    --daq-dir $my_path/lib/snort/daqs --daq hext -i tty << END
$packet 10.1.2.3 48620 -> 10.9.8.7 80
"GET / HTTP/1.1\r\n"
"Host: localhost\r\n"
"\r\n"
END

Process raw ethernet from hext file:

snort -c $my_path/etc/snort/snort.lua \
    --daq-dir $my_path/lib/snort/daqs --daq hext \
    --daq-var dlt=1 -r <hext-file>

Process a directory of plain files (ie non-pcap) with 4 threads with 8K buffers:

snort -c $my_path/etc/snort/snort.lua \
    --daq-dir $my_path/lib/snort/daqs --daq file \
    --pcap-dir path/to/files -z 4 -s 8192

Bridge two TCP connections on port 8000 and inspect the traffic:

snort -c $my_path/etc/snort/snort.lua \
    --daq-dir $my_path/lib/snort/daqs --daq socket

Logger Alternatives

Dump TCP stream payload in hext mode:

snort -c $my_path/etc/snort/snort.lua -L hext

Output timestamp, pkt_num, proto, pkt_gen, dgm_len, dir, src_ap, dst_ap, rule, action for each alert:

snort -c $my_path/etc/snort/snort.lua -A csv

Output the old test format alerts:

snort -c $my_path/etc/snort/snort.lua \
    --lua "alert_csv = { fields = 'pkt_num gid sid rev', separator = '\t' }"

Shell

You must build with --enable-shell to make the command line shell available.

Enable shell mode:

snort --shell <args>

You will see the shell mode command prompt, which looks like this:

o")~

(The prompt can be changed with the SNORT_PROMPT environment variable.)

You can pause immediately after loading the configuration and again before exiting with:

snort --shell --pause <args>

In that case you must issue the resume() command to continue. Enter quit() to terminate Snort or detach() to exit the shell. You can list the available commands with help().

To enable local telnet access on port 12345:

snort --shell -j 12345 <args>

The command line interface is still under development. Suggestions are welcome.

Signals

The following examples assume that Snort is currently running and has a process ID of <pid>.

Modify and Reload Configuration:

echo 'suppress = { { gid = 1, sid = 2215 } }' >> $my_path/etc/snort/snort.lua
kill -hup <pid>

Dump stats to stdout:

kill -usr1 <pid>

Shutdown normally:

kill -term <pid>

Exit without flushing packets:

kill -quit <pid>

List available signals:

snort --help-signals