Basic 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

Note: 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 -K text

Dump packets with application data and layer 2 headers

    snort -r /path/to/my.pcap -K text -d -e

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

Dump packets from all pcaps in a directory:

    snort --pcap-dir /path/to/pcap/dir --pcap-filter '*.pcap' -K text -d -e

Log packets to a directory:

    snort --pcap-dir /path/to/pcap/dir --pcap-filter '*.pcap' -K pcap \
        -l /path/to/log/dir

Configuration

Validate a configuration file:

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

Validate a rules file and a configuration 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 $my_path/etc/snort/sample.rules \
        -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 $my_path/etc/snort/sample.rules \
        -r /path/to/my.pcap -A alert_full

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 \
        --lua 'ips = { enable_builtin_rules = true }'

Note: 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

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:

    /[][][]

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

NOTE: 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.

Shell

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

    snort --shell 

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 

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 

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 .

Modify and Reload Configuration:

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

Dump stats to stdout:

    kill -usr1 

Shutdown normally:

    kill -term 

Exit without flushing packets:

    kill -quit 

List available signals:

    snort --help-signals

Note: The available signals may vary from platform to platform.