Thursday, March 12, 2015

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.