"Fossies" - the Fresh Open Source Software Archive

Member "snort-2.9.17/doc/snort_manual.tex" (30 Oct 2020, 688510 Bytes) of package /linux/misc/snort-2.9.17.tar.gz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) TeX and LaTeX source code syntax highlighting (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    1 % $Id$
    2 % 
    3 % BUILDING HTML VERSION:
    4 % latex2html -info 0 -local_icons -show_section_numbers -link +2 -split +2 -noaddress snort_manual.tex
    5 %
    6 % BUILDING PDF VERSION:
    7 % pdflatex snort_manual.tex
    8 
    9 \documentclass[english]{report}
   10 %\usepackage[T1]{fontenc}
   11 \usepackage[latin1]{inputenc}
   12 \usepackage{geometry}
   13 \usepackage{longtable}
   14 \geometry{verbose,letterpaper,tmargin=1in,bmargin=.5in,lmargin=1in,rmargin=1in}
   15 \usepackage{url}
   16 %\IfFileExists{url.sty}{\usepackage{url}}
   17 %                      {\newcommand{\url}{\texttt}}
   18 
   19 \usepackage{html}
   20 
   21 % \makeatletter
   22 
   23 \newcounter{slistnum}
   24 \newcounter{subslistnum}
   25 \newcounter{subsublistnum}
   26 
   27 \newenvironment{slist}
   28 { \begin{list}{ {\bf \arabic{slistnum}.} }{\usecounter{slistnum} } }
   29 { \end{list} }
   30 
   31 \newenvironment{subslist}
   32 { \begin{list} { {\bf \arabic{slistnum}-\Alph{subslistnum}. } }
   33         {\usecounter{subslistnum} }   }
   34 { \end{list} }
   35 
   36 \newenvironment{subsubslist} {
   37     \begin{list}{
   38         {\bf \arabic{slistnum}-\arabic{subslistnum}-\arabic{subsublistnum}. }
   39     }{
   40         \usecounter{subsubslistnum}
   41     }
   42 }{
   43     \end{list}
   44 }
   45 
   46 %\begin{latexonly}
   47 \newsavebox{\savepar}
   48 \newenvironment{note}{
   49 \samepage
   50     \vspace{10pt}{\textsf{
   51         {\hspace{7pt}\Huge{$\triangle$\hspace{-12.5pt}{\Large{$^!$}}}}\hspace{5pt}
   52         {\Large{NOTE}}
   53     }
   54     }
   55    \begin{center}
   56     \par\vspace{-17pt}
   57 
   58     \begin{lrbox}{\savepar}
   59     \begin{minipage}[r]{6in}
   60 }
   61 {
   62     \end{minipage}
   63     \end{lrbox}
   64     \fbox{
   65         \usebox{
   66             \savepar
   67     }
   68     }
   69     \par\vskip10pt
   70     \end{center}
   71 }
   72 %\end{latexonly}
   73 
   74 \begin{htmlonly}
   75 \newenvironment{note}{
   76         \begin{rawhtml}
   77         <p><table border="1"><tr><td><b>
   78         Note:&nbsp;&nbsp;</b>
   79         \end{rawhtml}
   80 }{
   81         \begin{rawhtml}
   82         </b></td></tr></table></p>
   83         \end{rawhtml}
   84 }
   85 \end{htmlonly}
   86 
   87 \usepackage{babel}
   88 
   89 % \makeatother
   90 
   91 \addtolength{\parindent}{-5mm}
   92 \addtolength{\parskip}{2mm}
   93 
   94 %\renewcommand\floatpagefraction{.9}
   95 %\renewcommand\topfraction{.9}
   96 %\renewcommand\bottomfraction{.9}
   97 %\renewcommand\textfraction{.1}   
   98 %\setcounter{totalnumber}{50}
   99 %\setcounter{topnumber}{50}
  100 %\setcounter{bottomnumber}{50}
  101 
  102 \begin{document}
  103 
  104 \title{SNORT\textsuperscript{\textregistered} Users Manual\\2.9.17}
  105 
  106 \author{The Snort Project}
  107 
  108 \maketitle
  109 
  110 \newpage
  111 
  112 Copyright \copyright 1998-2003 Martin Roesch
  113 
  114 Copyright \copyright 2001-2003 Chris Green
  115 
  116 Copyright \copyright 2003-2013 Sourcefire, Inc.
  117 
  118 Copyright \copyright 2014-2020 Cisco and/or its affiliates. All rights reserved.
  119 
  120 \tableofcontents{}
  121 
  122 \chapter{Snort Overview}
  123 
  124 This manual is based on \emph{Writing Snort Rules} by Martin Roesch and further
  125 work from Chris Green $<$cmg@snort.org$>$.  It was then maintained by Brian
  126 Caswell $<$bmc@snort.org$>$ and now is maintained by the Snort Team.  If you
  127 have a better way to say something or find that something in the documentation
  128 is outdated, drop us a line and we will update it.  If you would like to submit
  129 patches for this document, you can find the latest version of the documentation
  130 in \LaTeX\ format in the most recent source tarball under
  131 \verb!/doc/snort_manual.tex!.  Small documentation updates are the easiest way
  132 to help out the Snort Project.
  133 
  134 \section{Getting Started}
  135 
  136 Snort really isn't very hard to use, but there are a lot of command line
  137 options to play with, and it's not always obvious which ones go together well.
  138 This file aims to make using Snort easier for new users.
  139 
  140 Before we proceed, there are a few basic concepts you should understand about
  141 Snort. Snort can be configured to run in three modes:
  142 
  143 \begin{itemize}
  144 
  145 \item {\em Sniffer mode,} which simply reads the packets off of the network and
  146 displays them for you in a continuous stream on the console (screen). 
  147 
  148 \item {\em Packet Logger mode,} which logs the packets to disk. 
  149 
  150 \item {\em Network Intrusion Detection System (NIDS) mode,} which performs
  151 detection and analysis on network traffic. This is the most complex and
  152 configurable mode.
  153 
  154 \end{itemize}
  155 
  156 \section{Sniffer Mode}
  157 
  158 First, let's start with the basics. If you just want to print out the TCP/IP
  159 packet headers to the screen (i.e. sniffer mode), try this:
  160 
  161 \begin{verbatim}
  162     ./snort -v
  163 \end{verbatim}
  164 
  165 This command will run Snort and just show the IP and TCP/UDP/ICMP headers,
  166 nothing else. If you want to see the application data in transit, try the
  167 following:
  168 
  169 \begin{verbatim}
  170     ./snort -vd
  171 \end{verbatim}
  172 
  173 This instructs Snort to display the packet data as well as the headers.  If you
  174 want an even more descriptive display, showing the data link layer headers, do
  175 this:
  176 
  177 \begin{verbatim}
  178     ./snort -vde
  179 \end{verbatim}
  180 
  181 As an aside, notice that the command line switches can be listed separately or
  182 in a combined form. The last command could also be typed out as:
  183 
  184 \begin{verbatim}
  185     ./snort -d -v -e
  186 \end{verbatim}
  187 
  188 to produce the same result.
  189 
  190 \section{Packet Logger Mode}
  191 
  192 OK, all of these commands are pretty cool, but if you want to record the
  193 packets to the disk, you need to specify a logging directory and Snort will
  194 automatically know to go into packet logger mode:
  195 
  196 \begin{verbatim}
  197     ./snort -dev -l ./log
  198 \end{verbatim}
  199 
  200 Of course, this assumes you have a directory named \verb!log!  in the current
  201 directory. If you don't, Snort will exit with an error message. When Snort runs
  202 in this mode, it collects every packet it sees and places it in a directory
  203 hierarchy based upon the IP address of one of the hosts in the datagram.
  204 
  205 If you just specify a plain -l switch, you may notice that Snort sometimes uses
  206 the address of the remote computer as the directory in which it places packets
  207 and sometimes it uses the local host address. In order to log relative to the
  208 home network, you need to tell Snort which network is the home network:
  209 
  210 \begin{verbatim}
  211     ./snort -dev -l ./log -h 192.168.1.0/24
  212 \end{verbatim}
  213 
  214 This rule tells Snort that you want to print out the data link and TCP/IP
  215 headers as well as application data into the directory \verb!./log!, and you
  216 want to log the packets relative to the 192.168.1.0 class C network. All
  217 incoming packets will be recorded into subdirectories of the log directory,
  218 with the directory names being based on the address of the remote
  219 (non-192.168.1) host. 
  220 
  221 \begin{note}
  222 
  223 Note that if both the source and destination hosts are on the home network,
  224 they are logged to a directory with a name based on the higher of the two port
  225 numbers or, in the case of a tie, the source address.
  226 
  227 \end{note}
  228 
  229 If you're on a high speed network or you want to log the packets into a more
  230 compact form for later analysis, you should consider logging in binary mode.
  231 Binary mode logs the packets in tcpdump format to a single binary file in the
  232 logging directory:
  233 
  234 \begin{verbatim}
  235     ./snort -l ./log -b
  236 \end{verbatim}
  237 
  238 Note the command line changes here. We don't need to specify a home network any
  239 longer because binary mode logs everything into a single file, which eliminates
  240 the need to tell it how to format the output directory structure. Additionally,
  241 you don't need to run in verbose mode or specify the -d or -e switches because
  242 in binary mode the entire packet is logged, not just sections of it. All you
  243 really need to do to place Snort into logger mode is to specify a logging
  244 directory at the command line using the -l switch---the -b binary logging
  245 switch merely provides a modifier that tells Snort to log the packets in
  246 something other than the default output format of plain ASCII text.
  247 
  248 Once the packets have been logged to the binary file, you can read the packets
  249 back out of the file with any sniffer that supports the tcpdump binary format
  250 (such as tcpdump or Ethereal). Snort can also read the packets back by using
  251 the -r switch, which puts it into playback mode. Packets from any tcpdump
  252 formatted file can be processed through Snort in any of its run modes. For
  253 example, if you wanted to run a binary log file through Snort in sniffer mode
  254 to dump the packets to the screen, you can try something like this:
  255 
  256 \begin{verbatim}
  257     ./snort -dv -r packet.log
  258 \end{verbatim}
  259 
  260 You can manipulate the data in the file in a number of ways through Snort's
  261 packet logging and intrusion detection modes, as well as with the BPF interface
  262 that's available from the command line. For example, if you only wanted to see
  263 the ICMP packets from the log file, simply specify a BPF filter at the command
  264 line and Snort will only see the ICMP packets in the file:
  265 
  266 \begin{verbatim}
  267     ./snort -dvr packet.log icmp 
  268 \end{verbatim}
  269 
  270 For more info on how to use the BPF interface, read the Snort and tcpdump man
  271 pages.
  272 
  273 \section{Network Intrusion Detection System Mode}
  274 
  275 To enable Network Intrusion Detection System (NIDS) mode so that you don't
  276 record every single packet sent down the wire, try this:
  277 
  278 \begin{verbatim}
  279     ./snort -dev -l ./log -h 192.168.1.0/24 -c snort.conf
  280 \end{verbatim}
  281 
  282 where \texttt{snort.conf} is the name of your snort configuration file. This will
  283 apply the rules configured in the \verb!snort.conf! file to each packet to decide
  284 if an action based upon the rule type in the file should be taken. If you don't
  285 specify an output directory for the program, it will default to
  286 \verb!/var/log/snort!.
  287 
  288 One thing to note about the last command line is that if Snort is going to be
  289 used in a long term way as an IDS, the -v switch should be left off the command
  290 line for the sake of speed.  The screen is a slow place to write data to, and
  291 packets can be dropped while writing to the display.
  292 
  293 It's also not necessary to record the data link headers for most applications,
  294 so you can usually omit the -e switch, too.
  295 
  296 \begin{verbatim}
  297     ./snort -d -h 192.168.1.0/24 -l ./log -c snort.conf
  298 \end{verbatim}
  299 
  300 This will configure Snort to run in its most basic NIDS form, logging packets
  301 that trigger rules specified in the \texttt{snort.conf} in plain ASCII to disk
  302 using a hierarchical directory structure (just like packet logger mode). 
  303 
  304 
  305 \subsection{NIDS Mode Output Options}
  306 
  307 There are a number of ways to configure the output of Snort in NIDS mode. The
  308 default logging and alerting mechanisms are to log in decoded ASCII format and
  309 use full alerts. The full alert mechanism prints out the alert message in
  310 addition to the full packet headers. There are several other alert output modes
  311 available at the command line, as well as two logging facilities.
  312 
  313 Alert modes are somewhat more complex. There are seven alert modes available at
  314 the command line: full, fast, socket, syslog, console, cmg, and none. Six of
  315 these modes are accessed with the -A command line switch.  These options are:
  316 
  317 \begin{center}
  318 \begin{tabular}{| l | p{5.4in} |}
  319 
  320 \hline
  321 {\bf Option} & {\bf Description}\\
  322 \hline
  323 
  324 \hline
  325 {\tt -A fast} &
  326 
  327 Fast alert mode. Writes the alert in a simple format with a timestamp, alert
  328 message, source and destination IPs/ports.\\
  329 
  330 \hline
  331 {\tt -A full} &
  332 
  333 Full alert mode. This is the default alert mode and will be used automatically
  334 if you do not specify a mode.\\
  335 
  336 \hline
  337 {\tt -A unsock} &
  338 
  339 Sends alerts to a UNIX socket that another program can listen on.\\
  340 
  341 \hline
  342 {\tt -A none} &
  343 
  344 Turns off alerting.\\
  345 
  346 \hline
  347 {\tt -A console} &
  348 
  349 Sends ``fast-style'' alerts to the console (screen).\\
  350 
  351 \hline
  352 {\tt -A cmg} &
  353 
  354 Generates ``cmg style'' alerts.\\
  355 
  356 \hline
  357 \end{tabular}
  358 \end{center}
  359 
  360 Packets can be logged to their default decoded ASCII format or to a binary log
  361 file via the -b command line switch. To disable packet logging altogether, use
  362 the -N command line switch.
  363 
  364 For output modes available through the configuration file, see Section
  365 \ref{output config}.
  366 
  367 \begin{note}
  368 
  369 Command line logging options override any output options specified in the
  370 configuration file. This allows debugging of configuration issues quickly via
  371 the command line.
  372 
  373 \end{note}
  374 
  375 To send alerts to syslog, use the -s switch. The default facilities for the
  376 syslog alerting mechanism are LOG\_AUTHPRIV and LOG\_ALERT.  If you want to
  377 configure other facilities for syslog output, use the output plugin directives
  378 in snort.conf. See Section \ref{alert syslog label} for more details on
  379 configuring syslog output.
  380 
  381 For example, use the following command line to log to default (decoded ASCII)
  382 facility and send alerts to syslog: 
  383 
  384 \begin{verbatim}
  385     ./snort -c snort.conf -l ./log -h 192.168.1.0/24 -s
  386 \end{verbatim}
  387 
  388 As another example, use the following command line to log to the default
  389 facility in /var/log/snort and send alerts to a fast alert file: 
  390 
  391 \begin{verbatim}
  392     ./snort -c snort.conf -A fast -h 192.168.1.0/24
  393 \end{verbatim}
  394 
  395 \subsection{Understanding Standard Alert Output}
  396 
  397 When Snort generates an alert message, it will usually look like the following:
  398  
  399 \begin{verbatim}     
  400     [**] [116:56:1] (snort_decoder): T/TCP Detected [**]
  401 \end{verbatim}
  402      
  403 The first number is the Generator ID, this tells the user what component of
  404 Snort generated this alert. For a list of GIDs, please read etc/generators in
  405 the Snort source. In this case, we know that this event came from the
  406 ``decode'' (116) component of Snort.
  407      
  408 The second number is the Snort ID (sometimes referred to as Signature ID).
  409 For a list of preprocessor SIDs, please see etc/gen-msg.map.  Rule-based SIDs
  410 are written directly into the rules with the \emph{sid} option. In this case,
  411 \emph{56} represents a T/TCP event.
  412      
  413 The third number is the revision ID. This number is primarily used when
  414 writing signatures, as each rendition of the rule should increment this number
  415 with the \emph{rev} option.
  416 
  417 \subsection{High Performance Configuration}
  418 
  419 If you want Snort to go \emph{fast} (like keep up with a 1000 Mbps connection),
  420 you need to use unified2 logging and a unified2 log reader such as
  421 \emph{barnyard2}.  This allows Snort to log alerts in a binary form as fast as
  422 possible while another program performs the slow actions, such as writing to a
  423 database.
  424 
  425 If you want a text file that's easily parsed, but still somewhat fast, try
  426 using binary logging with the ``fast'' output mechanism. 
  427 
  428 This will log packets in tcpdump format and produce minimal alerts. For
  429 example:
  430 
  431 \begin{verbatim}
  432     ./snort -b -A fast -c snort.conf
  433 \end{verbatim}
  434 
  435 \subsection{Changing Alert Order}
  436 
  437 The default way in which Snort applies its rules to packets may not be
  438 appropriate for all installations.  The Pass rules are applied first, then the
  439 Drop rules, then the Alert rules and finally, Log rules are applied. 
  440 
  441 \begin{note}
  442 Sometimes an errant pass rule could cause alerts to not show up, in
  443 which case you can change the default ordering to allow Alert rules
  444 to be applied before Pass rules.  For more information, please refer
  445 to the \texttt{--alert-before-pass} option.
  446 \end{note}
  447 
  448 Several command line options are available to change the order in
  449 which rule actions are taken.
  450 
  451 \begin{itemize}
  452 
  453 \item \texttt{--alert-before-pass} option forces alert rules to take
  454 affect in favor of a pass rule.
  455 
  456 \item \texttt{--treat-drop-as-alert} causes drop and reject rules and 
  457 any associated alerts to be logged as alerts, rather then the normal 
  458 action.  This allows use of an inline policy with passive/IDS mode.
  459 The sdrop rules are not loaded.
  460 
  461 \item \texttt{--process-all-events} option causes Snort to process
  462 every event associated with a packet, while taking the actions based
  463 on the rules ordering.  Without this option (default case), only the
  464 events for the first action based on rules ordering are processed.
  465 
  466 \end{itemize}
  467 
  468 \begin{note}
  469 
  470 Pass rules are special cases here, in that the event processing is terminated
  471 when a pass rule is encountered, regardless of the use of
  472 \texttt{--process-all-events}.
  473 
  474 \end{note}
  475 
  476 \section{Packet Acquisition}
  477 
  478 Snort 2.9 introduces the DAQ, or Data Acquisition library, for packet I/O.  The
  479 DAQ replaces direct calls to libpcap functions with an abstraction layer that
  480 facilitates operation on a variety of hardware and software interfaces without
  481 requiring changes to Snort.  It is possible to select the DAQ type and mode
  482 when invoking Snort to perform pcap readback or inline operation, etc.
  483 
  484 \begin{note}
  485 
  486 Some network cards have features which can affect Snort. Two of these features
  487 are named "Large Receive Offload" (lro) and "Generic Receive Offload" (gro). 
  488 With these features enabled, the network card performs packet reassembly 
  489 before they're processed by the kernel.
  490 
  491 By default, Snort will truncate packets larger than the default snaplen of 1518
  492 bytes. In addition, LRO and GRO may cause issues with Stream target-based
  493 reassembly. We recommend that you turn off LRO and GRO. On linux systems, you can run:
  494 
  495 \begin{verbatim}
  496     $ ethtool -K eth1 gro off
  497     $ ethtool -K eth1 lro off
  498 \end{verbatim}
  499 
  500 \end{note}
  501 
  502 \subsection{Configuration}
  503 
  504 Assuming that you did not disable static modules or change the default DAQ
  505 type, you can run Snort just as you always did for file readback or sniffing an
  506 interface.  However, you can select and configure the DAQ when Snort is invoked
  507 as follows:
  508 
  509 \begin{verbatim}
  510     ./snort \
  511         [--daq <type>] \
  512         [--daq-mode <mode>] \
  513         [--daq-dir <dir>] \
  514         [--daq-var <var>]
  515 
  516     config daq: <type>
  517     config daq_dir: <dir>
  518     config daq_var: <var>
  519     config daq_mode: <mode>
  520 
  521     <type> ::= pcap | afpacket | dump | nfq | ipq | ipfw
  522     <mode> ::= read-file | passive | inline
  523     <var> ::= arbitrary <name>=<value> passed to DAQ
  524     <dir> ::= path where to look for DAQ module so's
  525 \end{verbatim}
  526 
  527 The DAQ type, mode, variable, and directory may be specified either via the 
  528 command line or in the conf file.  You may include as many variables and 
  529 directories as needed by repeating the arg / config.  DAQ type may be specified
  530 at most once in the conf and once on the command line; if configured in both
  531 places, the command line overrides the conf.
  532 
  533 
  534 If the mode is not set explicitly, -Q will force it to inline, and if that
  535 hasn't been set, -r will force it to read-file, and if that hasn't been set,
  536 the mode defaults to passive.  Also, -Q and --daq-mode inline are allowed,
  537 since there is no conflict, but -Q and any other DAQ mode will cause a fatal
  538 error at start-up.
  539 
  540 Note that if Snort finds multiple versions of a given library, the most recent
  541 version is selected.  This applies to static and dynamic versions of the same
  542 library.
  543 
  544 \begin{verbatim}
  545     ./snort --daq-list[=<dir>]
  546     ./snort --daq-dir=<dir> --daq-list
  547 \end{verbatim}
  548 
  549 The above commands search the specified directories for DAQ modules and print
  550 type, version, and attributes of each.  This feature is not available in the
  551 conf.  Snort stops processing after parsing --daq-list so if you want to add
  552 one or more directories add --daq-dir options before --daq-list on the command
  553 line.  (Since the directory is optional to --daq-list, you must use an =
  554 without spaces for this option.)
  555 
  556 \subsection{pcap}
  557 
  558 pcap is the default DAQ.  if snort is run w/o any DAQ arguments, it will
  559 operate as it always did using this module.  These are equivalent:
  560 
  561 \begin{verbatim}
  562     ./snort -i <device>
  563     ./snort -r <file>
  564 
  565     ./snort --daq pcap --daq-mode passive -i <device>
  566     ./snort --daq pcap --daq-mode read-file -r <file>
  567 \end{verbatim}
  568 
  569 You can specify the buffer size pcap uses with:
  570 
  571 \begin{verbatim}
  572     ./snort --daq pcap --daq-var buffer_size=<#bytes>
  573 \end{verbatim}
  574 
  575 Note that the pcap DAQ does not count filtered packets.
  576 
  577 \subsection{AFPACKET}
  578 
  579 afpacket functions similar to the memory mapped pcap DAQ but no external 
  580 library is required:
  581 
  582 \begin{verbatim}
  583     ./snort --daq afpacket -i <device>
  584             [--daq-var buffer_size_mb=<#MB>]
  585             [--daq-var debug]
  586 \end{verbatim}
  587 
  588 If you want to run afpacket in inline mode, you must set device to one or more
  589 interface pairs, where each member of a pair is separated by a single colon and 
  590 each pair is separated by a double colon like this:
  591 
  592 \begin{verbatim}
  593     eth0:eth1
  594 \end{verbatim}
  595 
  596 or this:
  597 
  598 \begin{verbatim}
  599     eth0:eth1::eth2:eth3
  600 \end{verbatim}
  601 
  602 By default, the afpacket DAQ allocates 128MB for packet memory.  You can change
  603 this with:
  604 
  605 \begin{verbatim}
  606     --daq-var buffer_size_mb=<#MB>
  607 \end{verbatim}
  608 
  609 Note that the total allocated is actually higher, here's why.  Assuming the
  610 default packet memory with a snaplen of 1518, the numbers break down like this:
  611 
  612 \begin{slist}
  613 \item
  614 The frame size is 1518 (snaplen) + the size of the AFPacket header (66
  615 bytes) = 1584 bytes.
  616 
  617 \item
  618 The number of frames is 128 MB / 1518 = 84733.
  619 
  620 \item
  621 The smallest block size that can fit at least one frame is  4 KB = 4096 bytes
  622   @ 2 frames per block.
  623 
  624 \item
  625 As a result, we need 84733 / 2 = 42366 blocks.
  626 
  627 \item
  628 Actual memory allocated is 42366 * 4 KB = 165.5 MB.
  629 \end{slist}
  630 
  631 \subsection{NFQ}
  632 
  633 NFQ is the new and improved way to process iptables packets:
  634 
  635 \begin{verbatim}
  636     ./snort --daq nfq \
  637         [--daq-var device=<dev>] \
  638         [--daq-var proto=<proto>] \
  639         [--daq-var queue=<qid>] \
  640     [--daq-var queue_len=<qlen>]
  641 
  642     <dev> ::= ip | eth0, etc; default is IP injection
  643     <proto> ::= ip4 | ip6 | ip*; default is ip4
  644     <qid> ::= 0..65535; default is 0
  645     <qlen> ::= 0..65535; default is 0
  646 \end{verbatim}
  647 
  648 Notes on iptables can be found in the DAQ distro README.
  649 
  650 \subsection{IPQ}
  651 
  652 IPQ is the old way to process iptables packets.  It replaces the inline version
  653 available in pre-2.9 versions built with this:
  654 
  655 \begin{verbatim}
  656     ./configure --enable-inline / -DGIDS
  657 \end{verbatim}
  658 
  659 Start the IPQ DAQ as follows:
  660 
  661 \begin{verbatim}
  662     ./snort --daq ipq \
  663         [--daq-var device=<dev>] \
  664         [--daq-var proto=<proto>] \
  665 
  666     <dev> ::= ip | eth0, etc; default is IP injection
  667     <proto> ::= ip4 | ip6; default is ip4
  668 \end{verbatim}
  669 
  670 \subsection{IPFW}
  671 
  672 IPFW is available for BSD systems.  It replaces the inline version available in
  673 pre-2.9 versions built with this:
  674 
  675 \begin{verbatim}
  676     ./configure --enable-ipfw / -DGIDS -DIPFW
  677 \end{verbatim}
  678 
  679 This command line argument is no longer supported:
  680 
  681 \begin{verbatim}
  682     ./snort -J <port#>
  683 \end{verbatim}
  684 
  685 Instead, start Snort like this:
  686 
  687 \begin{verbatim}
  688     ./snort --daq ipfw [--daq-var port=<port>]
  689 
  690     <port> ::= 1..65535; default is 8000
  691 \end{verbatim}
  692 
  693 * IPFW only supports ip4 traffic.
  694 
  695 \subsection{Dump}
  696 
  697 The dump DAQ allows you to test the various inline mode features available in
  698 2.9 Snort like injection and normalization.
  699 
  700 \begin{verbatim}
  701     ./snort -i <device> --daq dump
  702     ./snort -r <pcap> --daq dump
  703 \end{verbatim}
  704 
  705 By default a file named inline-out.pcap will be created containing all packets
  706 that passed through or were generated by snort.  You can optionally specify a
  707 different name.
  708 
  709 \begin{verbatim}
  710     ./snort --daq dump --daq-var file=<name>
  711 \end{verbatim}
  712 
  713 dump uses the pcap daq for packet acquisition.  It therefore does not count
  714 filtered packets.
  715 
  716 Note that the dump DAQ inline mode is not an actual inline mode.  Furthermore,
  717 you will probably want to have the pcap DAQ acquire in another mode like this:
  718 
  719 \begin{verbatim}
  720     ./snort -r <pcap> -Q --daq dump --daq-var load-mode=read-file
  721     ./snort -i <device> -Q --daq dump --daq-var load-mode=passive
  722 \end{verbatim}
  723 
  724 \subsection{Statistics Changes}
  725 
  726 The Packet Wire Totals and Action Stats sections of Snort's output include
  727 additional fields:
  728 
  729 \begin{itemize}
  730 \item \texttt{Filtered}
  731 count of packets filtered out and not handed to Snort for analysis.
  732 
  733 \item \texttt{Injected}
  734 packets Snort generated and sent, e.g. TCP resets.
  735 
  736 \item \texttt{Allow}
  737 packets Snort analyzed and did not take action on.
  738 
  739 \item \texttt{Block}
  740 packets Snort did not forward, e.g. due to a block rule.
  741 
  742 \item \texttt{Replace}
  743 packets Snort modified.
  744 
  745 \item \texttt{Whitelist}
  746 packets that caused Snort to allow a flow to pass w/o inspection by any
  747 analysis program.
  748 
  749 \item \texttt{Blacklist}
  750 packets that caused Snort to block a flow from passing.
  751 
  752 \item \texttt{Ignore}
  753 packets that caused Snort to allow a flow to pass w/o inspection by this
  754 instance of Snort.
  755 \end{itemize}
  756 
  757 The action stats show "blocked" packets instead of "dropped" packets to avoid
  758 confusion between dropped packets (those Snort didn't actually see) and blocked
  759 packets (those Snort did not allow to pass).
  760 
  761 \section{Reading pcap files}
  762 
  763 Instead of having Snort listen on an interface, you can give it a packet
  764 capture to read.  Snort will read and analyze the packets as if they came off
  765 the wire.  This can be useful for testing and debugging Snort.
  766 
  767 \subsection{Command line arguments}
  768 
  769 Any of the below can be specified multiple times on the command line
  770 (\texttt{-r} included) and in addition to other Snort command line options.
  771 Note, however, that specifying \texttt{--pcap-reset} and \texttt{--pcap-show}
  772 multiple times has the same effect as specifying them once.
  773 
  774 \begin{center}
  775 \begin{tabular}{| l | p{4.5in} |}
  776 
  777 \hline
  778 \textbf{Option} & \textbf{Description}\\
  779 \hline 
  780 
  781 \hline 
  782 \texttt{-r <file>} &
  783 
  784 Read a single pcap. \\
  785 
  786 \hline
  787 \texttt{--pcap-single=<file>} &
  788 
  789 Same as -r.  Added for completeness. \\
  790 
  791 \hline
  792 \texttt{--pcap-file=<file>} &
  793 
  794 File that contains a list of pcap files to read.  Can specify path to each
  795 pcap or directory to recurse to get pcaps. \\
  796 
  797 \hline
  798 \texttt{--pcap-list="<list>"} &
  799 
  800 A space separated list of pcaps to read. \\
  801 
  802 \hline
  803 \texttt{--pcap-dir=<dir>} &
  804 
  805 A directory to recurse to look for pcaps.  Sorted in ASCII order. \\
  806 
  807 \hline
  808 \texttt{--pcap-filter=<filter>} &
  809 
  810 Shell style filter to apply when getting pcaps from file or directory.  This
  811 filter will apply to any \texttt{--pcap-file} or \texttt{--pcap-dir} arguments
  812 following.  Use \texttt{--pcap-no-filter} to delete filter for following
  813 \texttt{--pcap-file} or \texttt{--pcap-dir} arguments or specify
  814 \texttt{--pcap-filter} again to forget previous filter and to apply to
  815 following \texttt{--pcap-file} or \texttt{--pcap-dir} arguments. \\
  816 
  817 \hline
  818 \texttt{--pcap-no-filter} &
  819 
  820 Reset to use no filter when getting pcaps from file or directory. \\
  821 
  822 \hline
  823 \texttt{--pcap-reset} &
  824 
  825 If reading multiple pcaps, reset snort to post-configuration state before
  826 reading next pcap.  The default, i.e. without this option, is not to reset
  827 state. \\
  828 
  829 \hline
  830 \texttt{--pcap-show} &
  831 
  832 Print a line saying what pcap is currently being read. \\
  833 
  834 \hline
  835 \end{tabular}
  836 \end{center}
  837 
  838 \subsection{Examples}
  839 
  840 \subsubsection{Read a single pcap}
  841 
  842 \begin{verbatim}
  843     $ snort -r foo.pcap
  844     $ snort --pcap-single=foo.pcap
  845 \end{verbatim}
  846 
  847 \subsubsection{Read pcaps from a file}
  848 
  849 \begin{verbatim}
  850     $ cat foo.txt
  851     foo1.pcap
  852     foo2.pcap
  853     /home/foo/pcaps
  854 \end{verbatim}
  855 
  856 \begin{verbatim}
  857     $ snort --pcap-file=foo.txt
  858 \end{verbatim}
  859 
  860 This will read foo1.pcap, foo2.pcap and all files under /home/foo/pcaps.  Note
  861 that Snort will not try to determine whether the files under that directory are
  862 really pcap files or not.
  863 
  864 \subsubsection{Read pcaps from a command line list}
  865 
  866 \begin{verbatim}
  867     $ snort --pcap-list="foo1.pcap foo2.pcap foo3.pcap"
  868 \end{verbatim}
  869 
  870 This will read foo1.pcap, foo2.pcap and foo3.pcap.
  871 
  872 \subsubsection{Read pcaps under a directory}
  873 
  874 \begin{verbatim}
  875     $ snort --pcap-dir="/home/foo/pcaps"
  876 \end{verbatim}
  877 
  878 This will include all of the files under /home/foo/pcaps.
  879 
  880 \subsubsection{Using filters}
  881 
  882 \begin{verbatim}
  883     $ cat foo.txt
  884     foo1.pcap
  885     foo2.pcap
  886     /home/foo/pcaps
  887 \end{verbatim}
  888 
  889 \begin{verbatim}
  890     $ snort --pcap-filter="*.pcap" --pcap-file=foo.txt
  891     $ snort --pcap-filter="*.pcap" --pcap-dir=/home/foo/pcaps
  892 \end{verbatim}
  893 
  894 The above will only include files that match the shell pattern "*.pcap", in
  895 other words, any file ending in ".pcap".
  896 
  897 \begin{verbatim}
  898     $ snort --pcap-filter="*.pcap --pcap-file=foo.txt \
  899     > --pcap-filter="*.cap" --pcap-dir=/home/foo/pcaps
  900 \end{verbatim}
  901 
  902 In the above, the first filter "*.pcap" will only be applied to the pcaps in
  903 the file "foo.txt" (and any directories that are recursed in that file).  The
  904 addition of the second filter "*.cap" will cause the first filter to be
  905 forgotten and then applied to the directory /home/foo/pcaps, so only files
  906 ending in ".cap" will be included from that directory.
  907 
  908 \begin{verbatim}
  909     $ snort --pcap-filter="*.pcap --pcap-file=foo.txt \
  910     > --pcap-no-filter --pcap-dir=/home/foo/pcaps
  911 \end{verbatim}
  912 
  913 In this example, the first filter will be applied to foo.txt, then no filter
  914 will be applied to the files found under /home/foo/pcaps, so all files found
  915 under /home/foo/pcaps will be included. 
  916 
  917 \begin{verbatim}
  918     $ snort --pcap-filter="*.pcap --pcap-file=foo.txt \
  919     > --pcap-no-filter --pcap-dir=/home/foo/pcaps \
  920     > --pcap-filter="*.cap" --pcap-dir=/home/foo/pcaps2
  921 \end{verbatim}
  922 
  923 In this example, the first filter will be applied to foo.txt, then no filter
  924 will be applied to the files found under /home/foo/pcaps, so all files found
  925 under /home/foo/pcaps will be included, then the filter "*.cap" will be applied
  926 to files found under /home/foo/pcaps2. 
  927 
  928 \subsubsection{Resetting state}
  929 
  930 \begin{verbatim}
  931     $ snort --pcap-dir=/home/foo/pcaps --pcap-reset
  932 \end{verbatim}
  933 
  934 The above example will read all of the files under /home/foo/pcaps, but after
  935 each pcap is read, Snort will be reset to a post-configuration state, meaning
  936 all buffers will be flushed, statistics reset, etc.  For each pcap, it will be
  937 like Snort is seeing traffic for the first time.
  938 
  939 \subsubsection{Printing the pcap}
  940 
  941 \begin{verbatim}
  942     $ snort --pcap-dir=/home/foo/pcaps --pcap-show
  943 \end{verbatim}
  944 
  945 The above example will read all of the files under /home/foo/pcaps and will
  946 print a line indicating which pcap is currently being read.
  947 
  948 \section{Basic Output}
  949 
  950 Snort does a lot of work and outputs some useful statistics when it is done.
  951 Many of these are self-explanatory.  The others are summarized below.  This
  952 does not include all possible output data, just the basics.
  953 
  954 \subsection{Timing Statistics}
  955 
  956 This section provides basic timing statistics.  It includes total seconds and
  957 packets as well as packet processing rates.  The rates are based on whole
  958 seconds, minutes, etc. and only shown when non-zero.
  959 
  960 Example:
  961 
  962 \begin{verbatim}
  963 ===============================================================================
  964 Run time for packet processing was 175.856509 seconds
  965 Snort processed 3716022 packets.
  966 Snort ran for 0 days 0 hours 2 minutes 55 seconds
  967    Pkts/min:      1858011
  968    Pkts/sec:        21234
  969 ===============================================================================
  970 \end{verbatim}
  971 
  972 \subsection{Packet I/O Totals}
  973 
  974 This section shows basic packet acquisition and injection peg counts obtained
  975 from the DAQ.  If you are reading pcaps, the totals are for all pcaps combined,
  976 unless you use --pcap-reset, in which case it is shown per pcap.
  977 
  978 \begin{itemize}
  979 \item Outstanding indicates how many packets are buffered awaiting processing.
  980 The way this is counted varies per DAQ so the DAQ documentation should be
  981 consulted for more info.
  982 
  983 \item Filtered packets are not shown for pcap DAQs.
  984 
  985 \item Injected packets are the result of active response which can be
  986 configured for inline or passive modes.
  987 \end{itemize}
  988 
  989 Example:
  990 
  991 \begin{verbatim}
  992 ===============================================================================
  993 Packet I/O Totals:
  994    Received:      3716022
  995    Analyzed:      3716022 (100.000%)
  996     Dropped:            0 (  0.000%)
  997    Filtered:            0 (  0.000%)
  998 Outstanding:            0 (  0.000%)
  999    Injected:            0
 1000 ===============================================================================
 1001 \end{verbatim}
 1002 
 1003 
 1004 \subsection{Protocol Statistics}
 1005 
 1006 Traffic for all the protocols decoded by Snort is summarized in the breakdown
 1007 section.  This traffic includes internal "pseudo-packets" if preprocessors such
 1008 as frag3 and stream5 are enabled so the total may be greater than the number of
 1009 analyzed packets in the packet I/O section.
 1010 
 1011 \begin{itemize}
 1012 \item Disc counts are discards due to basic encoding integrity flaws that
 1013 prevents Snort from decoding the packet.
 1014 
 1015 \item Other includes packets that contained an encapsulation that Snort doesn't
 1016 decode.
 1017 
 1018 \item S5 G 1/2 is the number of client/server sessions stream5 flushed due to
 1019 cache limit, session timeout, session reset.
 1020 \end{itemize}
 1021 
 1022 Example:
 1023 
 1024 \begin{verbatim}
 1025 ===============================================================================
 1026 Breakdown by protocol (includes rebuilt packets):
 1027         Eth:      3722347 (100.000%)
 1028        VLAN:            0 (  0.000%)
 1029         IP4:      1782394 ( 47.884%)
 1030        Frag:         3839 (  0.103%)
 1031        ICMP:        38860 (  1.044%)
 1032         UDP:       137162 (  3.685%)
 1033         TCP:      1619621 ( 43.511%)
 1034         IP6:      1781159 ( 47.850%)
 1035     IP6 Ext:      1787327 ( 48.016%)
 1036    IP6 Opts:         6168 (  0.166%)
 1037       Frag6:         3839 (  0.103%)
 1038       ICMP6:         1650 (  0.044%)
 1039        UDP6:       140446 (  3.773%)
 1040        TCP6:      1619633 ( 43.511%)
 1041      Teredo:           18 (  0.000%)
 1042     ICMP-IP:            0 (  0.000%)
 1043       EAPOL:            0 (  0.000%)
 1044     IP4/IP4:            0 (  0.000%)
 1045     IP4/IP6:            0 (  0.000%)
 1046     IP6/IP4:            0 (  0.000%)
 1047     IP6/IP6:            0 (  0.000%)
 1048         GRE:          202 (  0.005%)
 1049     GRE Eth:            0 (  0.000%)
 1050    GRE VLAN:            0 (  0.000%)
 1051     GRE IP4:            0 (  0.000%)
 1052     GRE IP6:            0 (  0.000%)
 1053 GRE IP6 Ext:            0 (  0.000%)
 1054    GRE PPTP:          202 (  0.005%)
 1055     GRE ARP:            0 (  0.000%)
 1056     GRE IPX:            0 (  0.000%)
 1057    GRE Loop:            0 (  0.000%)
 1058        MPLS:            0 (  0.000%)
 1059         ARP:       104840 (  2.817%)
 1060         IPX:           60 (  0.002%)
 1061    Eth Loop:            0 (  0.000%)
 1062    Eth Disc:            0 (  0.000%)
 1063    IP4 Disc:            0 (  0.000%)
 1064    IP6 Disc:            0 (  0.000%)
 1065    TCP Disc:            0 (  0.000%)
 1066    UDP Disc:         1385 (  0.037%)
 1067   ICMP Disc:            0 (  0.000%)
 1068 All Discard:         1385 (  0.037%)
 1069       Other:        57876 (  1.555%)
 1070 Bad Chk Sum:        32135 (  0.863%)
 1071     Bad TTL:            0 (  0.000%)
 1072      S5 G 1:         1494 (  0.040%)
 1073      S5 G 2:         1654 (  0.044%)
 1074       Total:      3722347
 1075 ===============================================================================
 1076 \end{verbatim}
 1077 
 1078 \subsection{Snort Memory Statistics}
 1079 On systems with mallinfo (3), you will see additional statistics. Check the man 
 1080 page of mallinfo for details
 1081 
 1082 Example:
 1083 \begin{verbatim}
 1084 ===============================================================================
 1085 Memory usage summary:
 1086   Total non-mmapped bytes (arena):       415481856
 1087   Bytes in mapped regions (hblkhd):      409612288
 1088   Total allocated space (uordblks):      92130384
 1089   Total free space (fordblks):           323351472
 1090   Topmost releasable block (keepcost):   3200
 1091 ===============================================================================
 1092 \end{verbatim}
 1093 
 1094 \subsection{Actions, Limits, and Verdicts}
 1095 
 1096 Action and verdict counts show what Snort did with the packets it analyzed.
 1097 This information is only output in IDS mode (when snort is run with the
 1098 \texttt{-c <conf>} option).
 1099 
 1100 \begin{itemize}
 1101 \item Alerts is the number of alert, and block actions processed as
 1102 determined by the rule actions.  Here block includes block, drop, and reject
 1103 actions.
 1104 \end{itemize}
 1105 
 1106 Limits arise due to real world constraints on processing time and available
 1107 memory.  These indicate potential actions that did not happen:
 1108 
 1109 \begin{itemize}
 1110 \item Match Limit counts rule matches were not processed due to the
 1111 \texttt{config detection: max\_queue\_events} setting.  The default is 5.
 1112 
 1113 \item Queue Limit counts events couldn't be stored in the event queue
 1114 due to the \texttt{config event\_queue: max\_queue} setting.  The default is 8.
 1115 
 1116 \item Log Limit counts events were not alerted due to the
 1117 \texttt{config event\_queue: log} setting.  The default is 3.
 1118 
 1119 \item Event Limit counts events not alerted due to 
 1120 \texttt{event\_filter} limits.
 1121 
 1122 \item Alert Limit counts events were not alerted because they already
 1123 were triggered on the session.
 1124 \end{itemize}
 1125 
 1126 Verdicts are rendered by Snort on each packet:
 1127 
 1128 \begin{itemize}
 1129 \item Allow = packets Snort analyzed and did not take action on. 
 1130 
 1131 \item Block = packets Snort did not forward, e.g. due to a block rule.  "Block"
 1132 is used instead of "Drop" to avoid confusion between dropped packets (those
 1133 Snort didn't actually see) and blocked packets (those Snort did not allow to
 1134 pass).
 1135 
 1136 \item Replace = packets Snort modified, for example, due to normalization or
 1137 replace rules.  This can only happen in inline mode with a compatible DAQ.
 1138 
 1139 \item Whitelist = packets that caused Snort to allow a flow to pass w/o
 1140 inspection by any analysis program.  Like blacklist, this is done by the DAQ or
 1141 by Snort on subsequent packets.
 1142 
 1143 \item Blacklist = packets that caused Snort to block a flow from passing.  This
 1144 is the case when a block TCP rule fires.  If the DAQ supports this in hardware,
 1145 no further packets will be seen by Snort for that session.  If not, snort will
 1146 block each packet and this count will be higher.
 1147 
 1148 \item Ignore = packets that caused Snort to allow a flow to pass w/o inspection
 1149 by this instance of Snort.  Like blacklist, this is done by the DAQ or by Snort
 1150 on subsequent packets.
 1151 
 1152 \item Int Blklst = packets that are GTP, Teredo, 6in4 or 4in6 encapsulated that are
 1153 being blocked.  These packets could get the Blacklist verdict if \texttt{config
 1154 tunnel\_verdicts} was set for the given protocol.  Note that these counts are
 1155 output only if non-zero.  Also, this count is incremented on the first packet
 1156 in the flow that alerts.  The alerting packet and all following packets on the
 1157 flow will be counted under Block.
 1158 
 1159 \item Int Whtlst = packets that are GTP, Teredo, 6in4 or 4in6 encapsulated that are
 1160 being allowed.  These packets could get the Whitelist verdict if \texttt{config
 1161 tunnel\_verdicts} was set for the given protocol.  Note that these counts are
 1162 output only if non-zero.  Also, this count is incremented for all packets on
 1163 the flow starting with the alerting packet.
 1164 \end{itemize}
 1165 
 1166 Example:
 1167 
 1168 \begin{verbatim}
 1169 ===============================================================================
 1170 Action Stats:
 1171      Alerts:            0 (  0.000%)
 1172      Logged:            0 (  0.000%)
 1173      Passed:            0 (  0.000%)
 1174 Limits:
 1175       Match:            0
 1176       Queue:            0
 1177         Log:            0
 1178       Event:            0
 1179       Alert:            0
 1180 Verdicts:
 1181       Allow:      3716022 (100.000%)
 1182       Block:            0 (  0.000%)
 1183     Replace:            0 (  0.000%)
 1184   Whitelist:            0 (  0.000%)
 1185   Blacklist:            0 (  0.000%)
 1186      Ignore:            0 (  0.000%)
 1187 ===============================================================================
 1188 \end{verbatim}
 1189 
 1190 \section{Tunneling Protocol Support}
 1191 
 1192 Snort supports decoding of many tunneling protocols, including GRE, PPTP over GRE,
 1193 MPLS, IP in IP, and ERSPAN, all of which are enabled by default.  
 1194 
 1195 To disable support for any GRE related encapsulation, PPTP over GRE, IPv4/IPv6 over
 1196 GRE, and ERSPAN, an extra configuration option is necessary:
 1197 
 1198 \begin{verbatim}
 1199     $ ./configure --disable-gre
 1200 \end{verbatim}
 1201 
 1202 To disable support for MPLS, an separate extra configuration option is necessary:
 1203 
 1204 \begin{verbatim}
 1205     $ ./configure --disable-mpls
 1206 \end{verbatim}
 1207 
 1208 \subsection{Multiple Encapsulations}
 1209 
 1210 Snort will not decode more than one encapsulation.  Scenarios such as
 1211 
 1212 \begin{verbatim}
 1213     Eth IPv4 GRE IPv4 GRE IPv4 TCP Payload
 1214 \end{verbatim}
 1215 
 1216 or
 1217 
 1218 \begin{verbatim}
 1219     Eth IPv4 IPv6 IPv4 TCP Payload
 1220 \end{verbatim}
 1221 
 1222 will not be handled and will generate a decoder alert.
 1223 
 1224 \subsection{Logging}
 1225 
 1226 Currently, only the encapsulated part of the packet is logged, e.g.
 1227 
 1228 \begin{verbatim}
 1229     Eth IP1 GRE IP2 TCP Payload
 1230 \end{verbatim}
 1231 
 1232 gets logged as
 1233 
 1234 \begin{verbatim}
 1235     Eth IP2 TCP Payload
 1236 \end{verbatim}
 1237 
 1238 and
 1239 
 1240 \begin{verbatim}
 1241     Eth IP1 IP2 TCP Payload
 1242 \end{verbatim}
 1243 
 1244 gets logged as
 1245 
 1246 \begin{verbatim}
 1247     Eth IP2 TCP Payload
 1248 \end{verbatim}
 1249 
 1250 \begin{note}
 1251 
 1252 Decoding of PPTP, which utilizes GRE and PPP, is not currently supported on
 1253 architectures that require word alignment such as SPARC.
 1254 
 1255 \end{note}
 1256 
 1257 \section{Miscellaneous}
 1258 
 1259 \subsection{Running Snort as a Daemon}
 1260 
 1261 If you want to run Snort as a daemon, you can the add -D switch to any
 1262 combination described in the previous sections. Please notice that if you want
 1263 to be able to restart Snort by sending a SIGHUP signal to the daemon, you {\em
 1264 must} specify the full path to the Snort binary when you start it, for example:
 1265 
 1266 \begin{verbatim}
 1267     /usr/local/bin/snort -d -h 192.168.1.0/24 \
 1268         -l /var/log/snortlogs -c /usr/local/etc/snort.conf -s -D
 1269 \end{verbatim}
 1270 
 1271 Relative paths are not supported due to security concerns.
 1272 
 1273 \subsubsection{Snort PID File}
 1274 
 1275 When Snort is run as a daemon , the daemon creates a PID file in the log
 1276 directory.  In Snort 2.6, the \texttt{--pid-path} command line switch causes
 1277 Snort to write the PID file in the directory specified.
 1278 
 1279 Additionally, the \texttt{--create-pidfile} switch can be used to force
 1280 creation of a PID file even when not running in daemon mode.
 1281 
 1282 The PID file will be locked so that other snort processes cannot start.  Use
 1283 the \texttt{--nolock-pidfile} switch to not lock the PID file.
 1284 
 1285 If you do not wish to include the name of the interface in the PID file, use
 1286 the \texttt{--no-interface-pidfile} switch.
 1287 
 1288 \subsection{Running in Rule Stub Creation Mode}
 1289 
 1290 If you need to dump the shared object rules stub to a directory, you must use the --dump-dynamic-rules command line option. These rule stub files are used in conjunction with the shared object rules. The path can be relative or absolute. 
 1291 
 1292 \begin{verbatim}
 1293     /usr/local/bin/snort -c /usr/local/etc/snort.conf \
 1294         --dump-dynamic-rules=/tmp
 1295 \end{verbatim}
 1296 
 1297 This path can also be configured in the snort.conf using the config option dump-dynamic-rules-path as follows:
 1298 
 1299 \begin{verbatim}
 1300     config dump-dynamic-rules-path: /tmp/sorules
 1301 \end{verbatim}
 1302 
 1303 The path configured by command line has precedence over the one configured using dump-dynamic-rules-path. 
 1304 
 1305 \begin{verbatim}
 1306     /usr/local/bin/snort -c /usr/local/etc/snort.conf \
 1307         --dump-dynamic-rules
 1308 
 1309     snort.conf:
 1310     config dump-dynamic-rules-path: /tmp/sorules
 1311 \end{verbatim}
 1312 
 1313 In the above mentioned scenario the dump path is set to /tmp/sorules.
 1314 
 1315 \subsection{Obfuscating IP Address Printouts}
 1316 
 1317 If you need to post packet logs to public mailing lists, you might want to use
 1318 the -O switch. This switch obfuscates your IP addresses in packet printouts.
 1319 This is handy if you don't want people on the mailing list to know the IP
 1320 addresses involved. You can also combine the -O switch with the -h switch to
 1321 only obfuscate the IP addresses of hosts on the home network.  This is useful
 1322 if you don't care who sees the address of the attacking host.  For example, you
 1323 could use the following command to read the packets from a log file and dump
 1324 them to the screen, obfuscating only the addresses from the 192.168.1.0/24
 1325 class C network:
 1326  
 1327 \begin{verbatim}
 1328     ./snort -d -v -r snort.log -O -h 192.168.1.0/24
 1329 \end{verbatim}
 1330 
 1331 \subsection{Specifying Multiple-Instance Identifiers}
 1332 
 1333 In Snort v2.4, the \texttt{-G} command line option was added that specifies an
 1334 instance identifier for the event logs.  This option can be used when running
 1335 multiple instances of snort, either on different CPUs, or on the same CPU but a
 1336 different interface.  Each Snort instance will use the value specified to
 1337 generate unique event IDs.  Users can specify either a decimal value
 1338 (\texttt{-G 1}) or hex value preceded by 0x (\texttt{-G 0x11}).  This is also
 1339 supported via a long option \texttt{--logid}.
 1340 
 1341 \subsection{Snort Modes}
 1342 
 1343 Snort can operate in three different modes namely tap (passive), inline, and inline-test.
 1344 Snort policies can be configured in these three modes too. 
 1345 
 1346 \subsubsection{Explanation of Modes}
 1347 
 1348 \begin{itemize}
 1349 
 1350 \item \texttt{Inline}
 1351 
 1352 When Snort is in Inline mode, it acts as an IPS allowing drop rules to trigger. Snort can be 
 1353 configured to run in inline mode using the command line argument -Q and snort config option 
 1354 \texttt{policy\_mode} as follows:
 1355 
 1356 \begin{verbatim}
 1357     snort -Q
 1358     config policy_mode:inline
 1359 \end{verbatim}
 1360 
 1361 \item \texttt{Passive}
 1362 
 1363 When Snort is in Passive mode, it acts as a IDS. Drop rules are not loaded (without --treat-drop-as-alert). 
 1364 Snort can be configured to passive mode using the snort config option \texttt{policy\_mode} as follows:
 1365 
 1366 \begin{verbatim}
 1367     config policy_mode:tap
 1368 \end{verbatim}
 1369 
 1370 
 1371 \item \texttt{Inline-Test}
 1372 
 1373 Inline-Test mode simulates the inline mode of snort, allowing evaluation of inline behavior without affecting 
 1374 traffic. The drop rules will be loaded and will be triggered as a Wdrop (Would Drop) alert. Snort can be 
 1375 configured to run in inline-test mode using the command line option (--enable-inline-test) or using the 
 1376 snort config option \texttt{policy\_mode} as follows:
 1377 
 1378 \begin{verbatim}
 1379     snort --enable-inline-test
 1380     config policy_mode:inline_test
 1381 \end{verbatim}
 1382 
 1383 \begin{note}
 1384 
 1385 Please note --enable-inline-test cannot be used in conjunction with -Q.
 1386 
 1387 \end{note}
 1388 
 1389 \end{itemize}
 1390 
 1391 \texttt{Behavior of different modes with rule options}
 1392 
 1393 
 1394 \begin{tabular}{|l|c|c|p{6cm}|}
 1395 \hline
 1396 Rule Option & Inline Mode & Passive Mode & Inline-Test Mode\\
 1397 \hline
 1398 \hline
 1399 \texttt{reject} & Drop + Response & Alert + Response & Wdrop + Response\\
 1400 \hline
 1401 \texttt{react} & Blocks and send notice & Blocks and send notice & Blocks and send notice\\
 1402 \hline
 1403 \texttt{normalize} & Normalizes packet & Doesn't normalize & Doesn't normalize\\
 1404 \hline
 1405 \texttt{replace} & replace content & Doesn't replace & Doesn't replace\\
 1406 \hline
 1407 \texttt{respond} & close session & close session & close session\\
 1408 \hline
 1409 \end{tabular}
 1410 
 1411 
 1412 \texttt{Behavior of different modes with rules actions}
 1413 
 1414 
 1415 \begin{tabular}{|l|c|c|c|}
 1416 \hline
 1417 Adapter Mode & Snort args & config policy\_mode & Drop Rule Handling\\
 1418 \hline
 1419 \hline
 1420 Passive & \texttt{ --treat-drop-as-alert} & tap & Alert\\
 1421 \hline
 1422 Passive & \texttt{ no args} & tap & Not Loaded\\
 1423 \hline
 1424 Passive & \texttt{ --treat-drop-as-alert} & inline\_test & Alert\\
 1425 \hline
 1426 Passive & \texttt{ no args} & inline\_test & Would Drop\\
 1427 \hline
 1428 Passive & \texttt{ --treat-drop-as-alert} & inline & Alert\\
 1429 \hline
 1430 Passive & \texttt{no args} & inline & Not loaded + warning\\
 1431 \hline
 1432 Inline Test & \texttt{ --enable-inline-test --treat-drop-as-alert} & tap & Alert\\
 1433 \hline
 1434 Inline Test & \texttt{ --enable-inline-test} & tap & Would Drop\\
 1435 \hline
 1436 Inline Test & \texttt{ --enable-inline-test --treat-drop-as-alert} & inline\_test & Alert\\
 1437 \hline
 1438 Inline Test & \texttt{ --enable-inline-test} & inline\_test & Would Drop\\
 1439 \hline
 1440 Inline Test & \texttt{ --enable-inline-test --treat-drop-as-alert} & inline & Alert\\
 1441 \hline
 1442 Inline Test  & \texttt{ --enable-inline-test} & inline & Would Drop\\
 1443 \hline
 1444 Inline & \texttt{ -Q --treat-drop-as-alert} & tap & Alert\\
 1445 \hline
 1446 Inline & \texttt{ -Q} & tap & Alert\\
 1447 \hline
 1448 Inline & \texttt{ -Q --treat-drop-as-alert} & inline\_test & Alert\\
 1449 \hline
 1450 Inline & \texttt{ -Q} & inline\_test & Would Drop\\
 1451 \hline
 1452 Inline & \texttt{ -Q --treat-drop-as-alert} & inline & Alert\\
 1453 \hline
 1454 Inline & \texttt{ -Q} & inline & Drop\\
 1455 \hline
 1456 \end{tabular}
 1457 
 1458 \section{Control socket}
 1459 \label{control_socket}
 1460 Snort can be configured to provide a Unix socket that can be used to issue commands 
 1461 to the running process. You must build snort with the 
 1462 \texttt{--enable-control-socket} option.  The control socket
 1463 functionality is supported on Linux only.\\
 1464 
 1465 Snort can be configured to use control socket using the command line argument \texttt{--cs-dir <path>}
 1466  and snort config option \texttt{cs\_dir} as follows:
 1467 
 1468 \begin{verbatim}
 1469     snort --cs-dir <path>
 1470     config cs_dir:<path>
 1471 \end{verbatim}
 1472 
 1473 \texttt{<path>} specifies the directory for snort to create the socket. If relative path is used, 
 1474 the path is relative to pid path specified. If there is no pid path specified, it is relative to 
 1475 current working directory. 
 1476 
 1477 A command \texttt{snort\_control} is made and installed along with snort in the same 
 1478 bin directory when configured with the \texttt{--enable-control-socket} option.
 1479 
 1480 \section{Configure signal value}
 1481 \label{configure_signal}
 1482 On some systems, signal used by snort might be used by other functions. To avoid conflicts, 
 1483 users can change the default signal value through \texttt{./configure} options for non-Windows system.
 1484 
 1485 These signals can be changed: 
 1486 \begin{itemize}
 1487 \item \texttt{SIGNAL\_SNORT\_RELOAD} 
 1488 \item \texttt{SIGNAL\_SNORT\_DUMP\_STATS}
 1489 \item \texttt{SIGNAL\_SNORT\_ROTATE\_STATS}
 1490 \item \texttt{SIGNAL\_SNORT\_READ\_ATTR\_TBL}
 1491 \end{itemize} 
 1492 
 1493 Syntax:
 1494 
 1495 \begin{verbatim}
 1496     ./configure SIGNAL_SNORT_RELOAD=<value/name>  SIGNAL_SNORT_DUMP_STATS=<value/name>\
 1497         SIGNAL_SNORT_READ_ATTR_TBL=<value/name> SIGNAL_SNORT_ROTATE_STATS=<value/name>
 1498 \end{verbatim}
 1499 
 1500 You can set those signals to user defined values or known signal names in the system.
 1501 The following example changes the rotate stats signal to 31 and reload attribute table to
 1502 signal SIGUSR2 :
 1503 
 1504 \begin{verbatim}
 1505     ./configure SIGNAL_SNORT_ROTATE_STATS=31 SIGNAL_SNORT_READ_ATTR_TBL=SIGUSR2
 1506 \end{verbatim}
 1507 
 1508 If the same signal is assigned more than once a warning will be logged 
 1509 during snort initialization. If a signal handler cannot be installed a warning
 1510 will be logged and that has to be fixed, otherwise the functionality will be lost.
 1511 
 1512 \texttt{Signals used in snort}
 1513 \label{signalactions}
 1514 \begin{tabular}{|l|l|l|}
 1515 \hline
 1516 Signal name & Default value & Action \\
 1517 \hline
 1518 \hline
 1519 SIGTERM & SIGTERM & exit \\
 1520 \hline
 1521 SIGINT & SIGINT & exit \\
 1522 \hline
 1523 SIGQUIT & SIGQUIT & exit \\
 1524 \hline
 1525 SIGPIPE & SIGPIPE & ignore \\
 1526 \hline
 1527 SIGNAL\_SNORT\_RELOAD & SIGHUP & reload snort \\
 1528 \hline
 1529 SIGNAL\_SNORT\_DUMP\_STATS & SIGUSR1 & dump stats \\
 1530 \hline
 1531 SIGNAL\_SNORT\_ROTATE\_STATS & SIGUSR2 & rotate stats \\
 1532 \hline
 1533 SIGNAL\_SNORT\_READ\_ATTR\_TBL & SIGURG & reload attribute table \\
 1534 \hline
 1535 SIGNAL\_SNORT\_CHILD\_READY & SIGCHLD & internal use in daemon mode \\
 1536 \hline
 1537 \end{tabular}
 1538 
 1539 \section{More Information}
 1540 
 1541 Chapter \ref{Configuring Snort} contains much information about many
 1542 configuration options available in the configuration file.  The Snort manual
 1543 page and the output of \texttt{snort -?} or \texttt{snort --help} contain
 1544 information that can help you get Snort running in several different modes.
 1545 
 1546 \begin{note}
 1547 
 1548 In many shells, a backslash (\textbackslash{}) is needed to escape the ?, so
 1549 you may have to type \texttt{snort -\textbackslash{}?} instead of \texttt{snort
 1550 -?} for a list of Snort command line options.
 1551 
 1552 \end{note}
 1553 
 1554 The Snort web page (\url{http://www.snort.org}) and the Snort Users mailing
 1555 list:
 1556 
 1557 \url{http://marc.theaimsgroup.com/?l=snort-users}
 1558 
 1559 at \verb?snort-users@lists.snort.org? provide informative announcements
 1560 as well as a venue for community discussion and support. There's a lot to
 1561 Snort, so sit back with a beverage of your choosing and read the documentation
 1562 and mailing list archives.
 1563 
 1564 \chapter{Configuring Snort}
 1565 \label{Configuring Snort}
 1566 
 1567 \section{Includes}
 1568 
 1569 The {\tt include} keyword allows other snort config files to be included within the
 1570 snort.conf indicated on the Snort command line. It works much like an \#include
 1571 from the C programming language, reading the contents of the named file and
 1572 adding the contents in the place where the include statement appears in the
 1573 file.
 1574 
 1575 \subsection{Format}
 1576 \begin{verbatim}
 1577     include <include file path/name>
 1578 \end{verbatim}
 1579 
 1580 \begin{note}
 1581 
 1582 Note that there is no semicolon at the end of this line. 
 1583 
 1584 \end{note}
 1585 
 1586 Included files will substitute any predefined variable values into their own
 1587 variable references.  See Section \ref{variables} for more information on
 1588 defining and using variables in Snort config files.
 1589 
 1590 \subsection{Variables}
 1591 \label{variables}
 1592 
 1593 Three types of variables may be defined in Snort:
 1594 
 1595 \begin{itemize}
 1596 \item var
 1597 \item portvar
 1598 \item ipvar
 1599 \end{itemize}
 1600 
 1601 These are simple substitution variables set with the {\tt var}, {\tt ipvar}, or
 1602 {\tt portvar} keywords as follows:
 1603 
 1604 \begin{verbatim}
 1605     var RULES_PATH rules/
 1606     portvar MY_PORTS [22,80,1024:1050]
 1607     ipvar MY_NET [192.168.1.0/24,10.1.1.0/24]
 1608     alert tcp any any -> $MY_NET $MY_PORTS (flags:S; msg:"SYN packet";)
 1609     include $RULE_PATH/example.rule
 1610 \end{verbatim}
 1611 
 1612 \subsubsection{IP Variables and IP Lists}
 1613 
 1614 IPs may be specified individually, in a list, as a CIDR block, or any
 1615 combination of the three.  IP variables should be specified using 'ipvar'
 1616 instead of 'var'.  Using 'var' for an IP variable is still allowed for backward
 1617 compatibility, but it will be deprecated in a future release.
 1618 
 1619 IP variable name can begin with an alphanumeric character [A-Za-z0-9] or '\_'
 1620 and should be followed by characters and numbers. Only numbers are not
 1621 accepted as variable names.
 1622 
 1623 IPs, IP lists, and CIDR blocks may be negated with '!'.  Negation is handled
 1624 differently compared with Snort versions 2.7.x and earlier.  Previously, each
 1625 element in a list was logically OR'ed together.  IP lists now OR non-negated
 1626 elements and AND the result with the OR'ed negated elements.  
 1627 
 1628 The following example list will match the IP 1.1.1.1 and IP from 2.2.2.0 to
 1629 2.2.2.255, with the exception of IPs 2.2.2.2 and 2.2.2.3.
 1630 
 1631 \begin{verbatim}
 1632     [1.1.1.1,2.2.2.0/24,![2.2.2.2,2.2.2.3]] 
 1633 \end{verbatim}
 1634 
 1635 The order of the elements in the list does not matter.  The element 'any' can
 1636 be used to match all IPs, although '!any' is not allowed.  Also, negated IP
 1637 ranges that are more general than non-negated IP ranges are not allowed.  
 1638 
 1639 See below for some valid examples if IP variables and IP lists.
 1640 
 1641 \begin{verbatim}
 1642     ipvar EXAMPLE [1.1.1.1,2.2.2.0/24,![2.2.2.2,2.2.2.3]] 
 1643     
 1644     alert tcp $EXAMPLE any -> any any (msg:"Example"; sid:1;)
 1645 
 1646     alert tcp [1.0.0.0/8,!1.1.1.0/24] any -> any any (msg:"Example";sid:2;)
 1647 \end{verbatim}
 1648 
 1649 The following examples demonstrate some invalid uses of IP variables and IP
 1650 lists.
 1651 
 1652 Use of !any:
 1653 
 1654 \begin{verbatim}
 1655     ipvar EXAMPLE any
 1656     alert tcp !$EXAMPLE any -> any any (msg:"Example";sid:3;)
 1657 \end{verbatim}
 1658 
 1659 Different use of !any:
 1660 
 1661 \begin{verbatim}
 1662     ipvar EXAMPLE !any
 1663     alert tcp $EXAMPLE any -> any any (msg:"Example";sid:3;)
 1664 \end{verbatim}
 1665         
 1666 Logical contradictions:
 1667 
 1668 \begin{verbatim}
 1669     ipvar EXAMPLE [1.1.1.1,!1.1.1.1]
 1670 \end{verbatim}
 1671 
 1672 Nonsensical negations:
 1673 
 1674 \begin{verbatim}
 1675     ipvar EXAMPLE [1.1.1.0/24,!1.1.0.0/16]
 1676 \end{verbatim}
 1677 
 1678 
 1679 \subsubsection{Port Variables and Port Lists}
 1680 
 1681 Portlists supports the declaration and lookup of ports and the representation
 1682 of lists and ranges of ports.  Variables, ranges, or lists may all be negated
 1683 with '!'.  Also, 'any' will specify any ports, but '!any' is not allowed.
 1684 Valid port ranges are from 0 to 65535.
 1685 
 1686 Lists of ports must be enclosed in brackets and port ranges may be specified
 1687 with a ':', such as in:
 1688 
 1689 \begin{verbatim}     
 1690     [10:50,888:900]
 1691 \end{verbatim}
 1692 
 1693 Port variables should be specified using 'portvar'.  The use of 'var' to
 1694 declare a port variable will be deprecated in a future release.  For backwards
 1695 compatibility, a 'var' can still be used to declare a port variable, provided
 1696 the variable name either ends with '\_PORT' or begins with 'PORT\_'. 
 1697 
 1698 The following examples demonstrate several valid usages of both port variables
 1699 and port lists.
 1700 
 1701 \begin{verbatim}     
 1702     portvar EXAMPLE1 80
 1703 
 1704     var EXAMPLE2_PORT [80:90]
 1705 
 1706     var PORT_EXAMPLE2 [1]
 1707 
 1708     portvar EXAMPLE3 any
 1709 
 1710     portvar EXAMPLE4 [!70:90]
 1711 
 1712     portvar EXAMPLE5 [80,91:95,100:200]
 1713 
 1714     alert tcp any $EXAMPLE1 -> any $EXAMPLE2_PORT (msg:"Example"; sid:1;)
 1715 
 1716     alert tcp any $PORT_EXAMPLE2 -> any any (msg:"Example"; sid:2;)
 1717 
 1718     alert tcp any 90 -> any [100:1000,9999:20000] (msg:"Example"; sid:3;)
 1719 \end{verbatim}
 1720 
 1721 Several invalid examples of port variables and port lists are demonstrated
 1722 below:
 1723 
 1724 Use of !any:
 1725 
 1726 \begin{verbatim}     
 1727     portvar EXAMPLE5 !any
 1728     var EXAMPLE5 !any
 1729 \end{verbatim}
 1730 
 1731 Logical contradictions:
 1732 
 1733 \begin{verbatim}     
 1734     portvar EXAMPLE6 [80,!80]
 1735 \end{verbatim}
 1736 
 1737 Ports out of range:
 1738 
 1739 \begin{verbatim}     
 1740     portvar EXAMPLE7 [65536]
 1741 \end{verbatim}
 1742 
 1743 Incorrect declaration and use of a port variable:
 1744 
 1745 \begin{verbatim}     
 1746     var EXAMPLE8 80 
 1747     alert tcp any $EXAMPLE8 -> any any (msg:"Example"; sid:4;)
 1748 \end{verbatim}
 1749 
 1750 Port variable used as an IP:
 1751 
 1752 \begin{verbatim}     
 1753     alert tcp $EXAMPLE1 any -> any any (msg:"Example"; sid:5;)
 1754 \end{verbatim}
 1755 
 1756 \subsubsection{Variable Modifiers}
 1757 
 1758 Rule variable names can be modified in several ways. You can define
 1759 meta-variables using the \$ operator. These can be used with the variable
 1760 modifier operators {\tt ?}  and {\tt -}, as described in the following table: 
 1761 
 1762 \begin{center}
 1763 \begin{tabular}{| l | p{4.5in} |}
 1764 
 1765 \hline
 1766 \textbf{Variable Syntax} & \textbf{Description}\\
 1767 \hline
 1768 
 1769 \hline
 1770 \texttt{var} &
 1771 
 1772 Defines a meta-variable.\\
 1773 
 1774 \hline
 1775 \texttt{\$(var) or \$var} &
 1776 
 1777 Replaces with the contents of variable \texttt{var}.\\
 1778 
 1779 \hline
 1780 \texttt{\$(var:-default)} &
 1781 
 1782 Replaces the contents of the variable \texttt{var} with ``default'' if
 1783 \texttt{var} is undefined.\\
 1784 
 1785 \hline
 1786 \texttt{\$(var:?message)} &
 1787 
 1788 Replaces with the contents of variable \texttt{var} or prints out the error
 1789 message and exits.\\
 1790 
 1791 \hline
 1792 \end{tabular}
 1793 \end{center}
 1794 
 1795 Here is an example of advanced variable usage in action:
 1796 
 1797 \begin{verbatim}
 1798     ipvar MY_NET 192.168.1.0/24
 1799     log tcp any any -> $(MY_NET:?MY_NET is undefined!) 23
 1800 \end{verbatim}
 1801 
 1802 \subsubsection{Limitations}
 1803 
 1804 When embedding variables, types can not be mixed.  For instance, port variables
 1805 can be defined in terms of other port variables, but old-style variables (with
 1806 the 'var' keyword) can not be embedded inside a 'portvar'.
 1807 
 1808 Valid embedded variable:
 1809 
 1810 \begin{verbatim}
 1811     portvar pvar1 80
 1812     portvar pvar2 [$pvar1,90]
 1813 \end{verbatim}
 1814 
 1815 Invalid embedded variable:
 1816         
 1817 \begin{verbatim}
 1818     var pvar1 80
 1819     portvar pvar2 [$pvar1,90]
 1820 \end{verbatim}
 1821 
 1822 Likewise, variables can not be redefined if they were previously defined as a
 1823 different type.  They should be renamed instead:
 1824 
 1825 Invalid redefinition:
 1826         
 1827 \begin{verbatim}
 1828     var pvar 80
 1829     portvar pvar 90
 1830 \end{verbatim}
 1831 
 1832 \subsection{Config}
 1833 \label{Config}
 1834 
 1835 Many configuration and command line options of Snort can be specified in the
 1836 configuration file. 
 1837 
 1838 \subsubsection{Format}
 1839 
 1840 \begin{verbatim}
 1841     config <directive> [: <value>]
 1842 \end{verbatim}
 1843 
 1844 \newpage
 1845 \begin{center}
 1846 \begin{longtable}[t]{| p{2.5in} | p{3.5in} |}
 1847 
 1848 \hline
 1849 {\bf Config Directive} & {\bf Description}\\
 1850 \hline
 1851 
 1852 % KEEP THESE IN ALPHABETICAL ORDER
 1853 \hline
 1854 \texttt{config alert\_with\_interface\_name} & Appends interface name to alert
 1855 (\texttt{snort -I}). \\
 1856 
 1857 \hline
 1858 \texttt{config alertfile: <filename>} & Sets the alerts output file. \\
 1859 
 1860 \hline
 1861 \texttt{config asn1: <max-nodes>} & Specifies the maximum number of nodes to track when
 1862 doing ASN1 decoding. See Section \ref{asn1} for more information and
 1863 examples.\\
 1864 
 1865 \hline
 1866 \texttt{config autogenerate\_preprocessor\newline \_decoder\_rules} & If Snort was
 1867 configured to enable decoder and preprocessor rules, this option will cause
 1868 Snort to revert back to its original behavior of alerting if the decoder or
 1869 preprocessor generates an event. \\
 1870 
 1871 \hline
 1872 \texttt{config bpf\_file: <filename>} & Specifies BPF filters (\texttt{snort
 1873 -F}). \\
 1874 
 1875 \hline
 1876 \texttt{config checksum\_drop: <types>} & Types of packets to drop if invalid
 1877 checksums. Values: \texttt{none}, \texttt{noip}, \texttt{notcp},
 1878 \texttt{noicmp}, \texttt{noudp}, \texttt{ip}, \texttt{tcp}, \texttt{udp},
 1879 \texttt{icmp} or \texttt{all} (only applicable in inline mode and for packets
 1880 checked per \texttt{checksum\_mode} config option). \\
 1881 
 1882 \hline
 1883 \texttt{config checksum\_mode: <types>} & Types of packets to calculate checksums.
 1884 Values: \texttt{none}, \texttt{noip}, \texttt{notcp}, \texttt{noicmp},
 1885 \texttt{noudp}, \texttt{ip}, \texttt{tcp}, \texttt{udp}, \texttt{icmp} or
 1886 \texttt{all}. \\
 1887 
 1888 \hline
 1889 \texttt{config chroot: <dir>} & Chroots to specified dir (\texttt{snort
 1890 -t}). \\
 1891 
 1892 \hline
 1893 \texttt{config classification: <class>} & See Table
 1894 \ref{Snort Default Classifications} for a list of classifications.\\
 1895 
 1896 \hline
 1897 \texttt{config cs\_dir: <path>} & configure snort to provide a Unix socket in the path
 1898 that can be used to issue commands to the running process. See Section
 1899 \ref{control_socket} for more details.\\
 1900 
 1901 \hline
 1902 \texttt{config daemon} & Forks as a daemon (\texttt{snort -D}). \\
 1903 
 1904 \hline
 1905 \texttt{config decode\_data\_link} & Decodes Layer2 headers (\texttt{snort
 1906 -e}). \\
 1907 
 1908 \hline
 1909 \texttt{config default\_rule\_state: <state>} & Global configuration directive
 1910 to enable or disable the loading of rules into the detection engine.  Default
 1911 (with or without directive) is enabled.  Specify \texttt{disabled} to disable
 1912 loading rules. \\
 1913 
 1914 \hline
 1915 \texttt{config daq: <type>} & Selects the type of DAQ to instantiate.  The
 1916 DAQ with the highest version of the given type is selected if there are 
 1917 multiple of the same type (this includes any built-in DAQs).\\
 1918 
 1919 \hline
 1920 \texttt{config daq\_mode: <mode>} & Select the DAQ mode: passive, inline, or
 1921 read-file.  Not all DAQs support modes.  See the DAQ distro README for
 1922 possible DAQ modes or list DAQ capabilities for a brief summary. \\
 1923 
 1924 \hline
 1925 \texttt{config daq\_var: <name=value>} & Set a DAQ specific variable.  Snort
 1926 just passes this information down to the DAQ.  See the DAQ distro README for
 1927 possible DAQ variables. \\
 1928 
 1929 \hline
 1930 \texttt{config daq\_dir: <dir>} & Tell Snort where to look for available
 1931 dynamic DAQ modules.  This can be repeated.  The selected DAQ will be the
 1932 one with the latest version. \\
 1933 
 1934 \hline \texttt{config daq\_list: [<dir>]} & Tell Snort to dump basic DAQ
 1935 capabilities and exit.  You can optionally specify a directory to include any
 1936 dynamic DAQs from that directory.  You can also precede this option with extra
 1937 DAQ directory options to look in multiple directories. \\
 1938 
 1939 \hline
 1940 \texttt{config decode\_esp: [enable | disable]} & Enable or disable the decoding of
 1941 Encapsulated Security Protocol (ESP). This is disabled by default.
 1942 Some networks use ESP for authentication without encryption, allowing their
 1943 content to be inspected. Encrypted ESP may cause some false positives if this
 1944 option is enabled.\\
 1945 
 1946 \hline
 1947 \texttt{config detection: [search-method <method>]} & Select type of fast pattern
 1948 matcher algorithm to use.
 1949 \begin{itemize}
 1950 \item \texttt{search-method <method>}
 1951 \begin{itemize}
 1952 \item Queued match search methods -  Matches are queued until the fast pattern
 1953 matcher is finished with the payload, then evaluated.  This was found to generally
 1954 increase performance through fewer cache misses (evaluating each rule would
 1955 generally blow away the fast pattern matcher
 1956 state in the cache).
 1957 \begin{itemize}
 1958 \item \texttt{ac} and \texttt{ac-q} - Aho-Corasick Full (high memory, best performance).
 1959 \item \texttt{ac-bnfa} and \texttt{ac-bnfa-q} - Aho-Corasick Binary NFA (low memory, high performance)
 1960 \item \texttt{lowmem} and \texttt{lowmem-q} - Low Memory Keyword Trie (low memory, moderate performance)
 1961 \item \texttt{ac-split} - Aho-Corasick Full with ANY-ANY port group evaluated separately (low memory, high performance).  Note this is shorthand for \texttt{search-method ac, split-any-any}
 1962 \item \texttt{intel-cpm} - Intel CPM library (must have compiled Snort with location of libraries to enable this)
 1963 \end{itemize}
 1964 \end{itemize}
 1965 \begin{itemize}
 1966 \item No queue search methods - The "nq" option specifies that matches should not
 1967 be queued and evaluated as they are found.
 1968 \begin{itemize}
 1969 \item \texttt{ac-nq} - Aho-Corasick Full (high memory, best performance).
 1970 \item \texttt{ac-bnfa-nq} - Aho-Corasick Binary NFA (low memory, high performance).
 1971 This is the default search method if none is specified.
 1972 \item \texttt{lowmem-nq} - Low Memory Keyword Trie (low memory, moderate performance)
 1973 \end{itemize}
 1974 \end{itemize}
 1975 \begin{itemize}
 1976 \item Other search methods (the above are considered superior to these)
 1977 \begin{itemize}
 1978 \item \texttt{ac-std} - Aho-Corasick Standard (high memory, high performance)
 1979 \item \texttt{acs} - Aho-Corasick Sparse (high memory, moderate performance)
 1980 \item \texttt{ac-banded} - Aho-Corasick Banded (high memory, moderate performance)
 1981 \item \texttt{ac-sparsebands} - Aho-Corasick Sparse-Banded (high memory, moderate performance)
 1982 \end{itemize}
 1983 \end{itemize}
 1984 \end{itemize} \\
 1985 
 1986 \hline
 1987 \texttt{config detection: [split-any-any] [search-optimize] [max-pattern-len <int>]} & Other options
 1988 that affect fast pattern matching.
 1989 \begin{itemize}
 1990 \item \texttt{split-any-any}
 1991 \begin{itemize}
 1992 \item A memory/performance tradeoff.  By default, ANY-ANY port rules are added to 
 1993 every non ANY-ANY port group so that only one port group rule evaluation needs to 
 1994 be done per packet.  Not putting the ANY-ANY port rule group into every other
 1995 port group can significantly reduce the memory footprint of the fast pattern
 1996 matchers if there are many ANY-ANY port rules.  But doing so may require two
 1997 port group evaluations per packet - one for the specific port group and one for
 1998 the ANY-ANY port group, thus potentially reducing performance.  This option is
 1999 generic and can be used with any \texttt{search-method} but was specifically
 2000 intended for use with the \texttt{ac} \texttt{search-method} where the memory
 2001 footprint is significantly reduced though overall fast pattern performance is
 2002 better than \texttt{ac-bnfa}.  Of note is that the lower memory footprint can
 2003 also increase performance through fewer cache misses.  Default is not to split
 2004 the ANY-ANY port group.
 2005 \end{itemize}
 2006 \item \texttt{search-optimize}
 2007 \begin{itemize}
 2008 \item Optimizes fast pattern memory when used with \texttt{search-method}
 2009 \texttt{ac} or \texttt{ac-split} by dynamically determining the size of a 
 2010 state based on the total number of states. When used with \texttt{ac-bnfa}, some
 2011 fail-state resolution will be attempted, potentially increasing performance.
 2012 Default is not to optimize.
 2013 \end{itemize}
 2014 \item \texttt{max-pattern-len <integer>}
 2015 \begin{itemize}
 2016 \item This is a memory optimization that specifies the maximum length of a pattern
 2017 that will be put in the fast pattern matcher.  Patterns longer than this length
 2018 will be truncated to this length before inserting into the pattern matcher.  Useful
 2019 when there are very long contents being used and truncating the pattern won't diminish
 2020 the uniqueness of the patterns.  Note that this may cause more false positive rule
 2021 evaluations, i.e. rules that will be evaluated because a fast pattern was matched,
 2022 but eventually fail, however CPU cache can play a part in performance so a smaller memory
 2023 footprint of the fast pattern matcher can potentially increase performance.  Default
 2024 is to not set a maximum pattern length.
 2025 \end{itemize}
 2026 \end{itemize} \\
 2027 
 2028 \hline
 2029 \texttt{config detection: [no\_stream\_inserts] [max\_queue\_events <int>] [enable-single-rule-group] [bleedover-port-limit]} & Other detection engine options.
 2030 \begin{itemize}
 2031 \item \texttt{no\_stream\_inserts}
 2032 \begin{itemize}
 2033 \item Specifies that stream inserted packets should not be evaluated against the detection engine.
 2034 This is a potential performance improvement with the idea that the stream rebuilt packet will
 2035 contain the payload in the inserted one so the stream inserted packet doesn't need to be
 2036 evaluated.  Default is to inspect stream inserts.
 2037 \end{itemize}
 2038 \item \texttt{max\_queue\_events <integer>}
 2039 \begin{itemize}
 2040 \item Specifies the maximum number of matching fast-pattern states to queue per packet.
 2041 Default is 5 events.
 2042 \end{itemize}
 2043 \item \texttt{enable-single-rule-group}
 2044 \begin{itemize}
 2045 \item Put all rules into one port group.  Not recommended.  Default is not to
 2046 do this.
 2047 \end{itemize}
 2048 \item \texttt{bleedover-port-limit}
 2049 \begin{itemize}
 2050 \item The maximum number of source or destination ports designated in a rule
 2051 before the rule is considered an ANY-ANY port group rule.  Default is 1024.
 2052 \end{itemize}
 2053 \end{itemize} \\
 2054 
 2055 \hline
 2056 \texttt{config detection: [debug] [debug-print-nocontent-rule-tests] [debug-print-rule-group-build-details] [debug-print-rule-groups-uncompiled] [debug-print-rule-groups-compiled] [debug-print-fast-pattern] [bleedover-warnings-enabled]} & Options for detection engine debugging.
 2057 \begin{itemize}
 2058 \item \texttt{debug}
 2059 \begin{itemize}
 2060 \item Prints fast pattern information for a particular port group.
 2061 \end{itemize}
 2062 \item \texttt{debug-print-nocontent-rule-tests}
 2063 \begin{itemize}
 2064 \item Prints port group information during packet evaluation.
 2065 \end{itemize}
 2066 \item \texttt{debug-print-rule-group-build-details}
 2067 \begin{itemize}
 2068 \item Prints port group information during port group compilation.
 2069 \end{itemize}
 2070 \item \texttt{debug-print-rule-groups-uncompiled}
 2071 \begin{itemize}
 2072 \item Prints uncompiled port group information.
 2073 \end{itemize}
 2074 \item \texttt{debug-print-rule-groups-compiled}
 2075 \begin{itemize}
 2076 \item Prints compiled port group information.
 2077 \end{itemize}
 2078 \item \texttt{debug-print-fast-pattern}
 2079 \begin{itemize}
 2080 \item For each rule with fast pattern content, prints information about the content
 2081 being used for the fast pattern matcher.
 2082 \end{itemize}
 2083 \item \texttt{bleedover-warnings-enabled}
 2084 \begin{itemize}
 2085 \item Prints a warning if the number of source or destination ports used in a
 2086 rule exceed the \texttt{bleedover-port-limit} forcing the rule to be moved into
 2087 the ANY-ANY port group.
 2088 \end{itemize}
 2089 \end{itemize} \\
 2090 
 2091 \hline
 2092 \texttt{config disable\_decode\_alerts} & Turns off the alerts generated by the
 2093 decode phase of Snort. \\
 2094 
 2095 \hline
 2096 \texttt{config disable\_inline\_init\_failopen} & Disables failopen thread that
 2097 allows inline traffic to pass while Snort is starting up.  Only useful if Snort
 2098 was configured with --enable-inline-init-failopen.  (\texttt{snort
 2099 --disable-inline-init-failopen}) \\
 2100 
 2101 \hline
 2102 \texttt{config disable\_ipopt\_alerts} & Disables IP option length validation
 2103 alerts. \\
 2104 
 2105 \hline
 2106 \texttt{config disable\_tcpopt\_alerts} & Disables option length validation
 2107 alerts. \\
 2108 
 2109 \hline
 2110 \texttt{config\newline disable\_tcpopt\_experimental\_alerts} & Turns off
 2111 alerts generated by experimental TCP options. \\
 2112 
 2113 \hline
 2114 \texttt{config disable\_tcpopt\_obsolete\_alerts} & Turns off alerts
 2115 generated by obsolete TCP options. \\
 2116 
 2117 \hline
 2118 \texttt{config disable\_tcpopt\_ttcp\_alerts} & Turns off alerts generated by
 2119 T/TCP options. \\
 2120 
 2121 \hline
 2122 \texttt{config disable\_ttcp\_alerts} & Turns off alerts generated by T/TCP
 2123 options. \\
 2124 
 2125 \hline
 2126 \texttt{config dump\_chars\_only} & Turns on character dumps (\texttt{snort
 2127 -C}). \\
 2128 
 2129 \hline
 2130 \texttt{config dump\_payload} & Dumps application layer (\texttt{snort -d}). \\
 2131 
 2132 \hline
 2133 \texttt{config dump\_payload\_verbose} & Dumps raw packet starting at link
 2134 layer (\texttt{snort -X}). \\
 2135 
 2136 \hline
 2137 \texttt{config enable\_decode\_drops} & Enables the dropping of bad packets
 2138 identified by decoder (only applicable in inline mode).\\
 2139 
 2140 \hline
 2141 \texttt{config enable\_decode\_oversized\_alerts} & Enable alerting
 2142 on packets that have headers containing length fields for which the value is
 2143 greater than the length of the packet. \\
 2144 
 2145 \hline
 2146 \texttt{config enable\_decode\_oversized\_drops} & Enable dropping
 2147 packets that have headers containing length fields for which the value is
 2148 greater than the length of the packet.
 2149 \texttt{enable\_decode\_oversized\_alerts} must also be enabled for this to be
 2150 effective (only applicable in inline mode). \\
 2151 
 2152 \hline
 2153 \texttt{config enable\_deep\_teredo\_inspection} & Snort's packet decoder only
 2154 decodes Teredo (IPv6 over UDP over IPv4) traffic on UDP port 3544. This option
 2155 makes Snort decode Teredo traffic on all UDP ports. \\
 2156 
 2157 \hline
 2158 \texttt{config enable\_ipopt\_drops} & Enables the dropping of bad packets with
 2159 bad/truncated IP options (only applicable in inline mode).\\
 2160 
 2161 \hline
 2162 \texttt{config enable\_mpls\_multicast} & Enables support for MPLS multicast.
 2163 This option is needed when the network allows MPLS multicast traffic. When this
 2164 option is off and MPLS multicast traffic is detected, Snort will generate an
 2165 alert. By default, it is off.\\
 2166 
 2167 \hline
 2168 \texttt{config enable\_mpls\_overlapping\_ip} & Enables support for overlapping
 2169 IP addresses in an MPLS network. In a normal situation, where there are no
 2170 overlapping IP addresses, this configuration option should not be turned on.
 2171 However, there could be situations where two private networks share the same IP
 2172 space and different MPLS labels are used to differentiate traffic from the two
 2173 VPNs. In such a situation, this configuration option should be turned on. By
 2174 default, it is off. \\
 2175 
 2176 \hline
 2177 \texttt{config enable\_tcpopt\_drops} & Enables the dropping of bad packets
 2178 with bad/truncated TCP option (only applicable in inline mode).\\
 2179 
 2180 \hline
 2181 \texttt{config\newline enable\_tcpopt\_experimental\_drops} & Enables the
 2182 dropping of bad packets with experimental TCP option.  (only applicable in
 2183 inline mode).\\
 2184 
 2185 \hline
 2186 \texttt{config enable\_tcpopt\_obsolete\_drops} & Enables the
 2187 dropping of bad packets with obsolete TCP option.  (only applicable in inline
 2188 mode).\\
 2189 
 2190 \hline
 2191 \texttt{config enable\_tcpopt\_ttcp\_drops} & Enables the dropping of bad packets with
 2192 T/TCP option. (only applicable in inline mode).\\
 2193 
 2194 \hline
 2195 \texttt{config enable\_ttcp\_drops} & Enables the dropping of bad packets with T/TCP
 2196 option. (only applicable in inline mode).\\
 2197 
 2198 \hline
 2199 \texttt{config event\_filter: memcap <bytes>} & Set global memcap in bytes for
 2200 thresholding. Default is 1048576 bytes (1 megabyte). \\
 2201 
 2202 \hline
 2203 \texttt{config event\_queue: [max\_queue <num>] [log <num>] [order\_events
 2204 <order>]} & Specifies conditions about Snort's event queue. You can use the
 2205 following options:
 2206 
 2207 \begin{itemize}
 2208 \item \texttt{max\_queue $<$integer$>$} (max events supported)
 2209 \item \texttt{log $<$integer$>$} (number of events to log) 
 2210 \item \texttt{order\_events [priority$|$content\_length]} (how to order events within the queue)
 2211 \end{itemize}
 2212 
 2213 See Section \ref{eventqueue} for more information and examples.\\
 2214 
 2215 \hline
 2216 \texttt{config flowbits\_size: <num-bits>} & Specifies the maximum number of
 2217 flowbit tags that can be used within a rule set.  The default is 1024 bits
 2218 and maximum is 2048. \\
 2219 
 2220 \hline
 2221 \texttt{config ignore\_ports: <proto> <port-list>} & Specifies ports to ignore
 2222 (useful for ignoring noisy NFS traffic). Specify the protocol (TCP, UDP, IP, or
 2223 ICMP), followed by a list of ports. Port ranges are supported.\\
 2224 
 2225 \hline
 2226 \texttt{config interface: <iface>} & Sets the network interface (\texttt{snort
 2227 -i}). \\
 2228 
 2229 \hline
 2230 \texttt{config ipv6\_frag: [bsd\_icmp\_frag\_alert on|off] [,
 2231 bad\_ipv6\_frag\_alert on|off] [, frag\_timeout <secs>] [, max\_frag\_sessions
 2232 <max-track>]} & The following options can be used:
 2233 
 2234 \begin{itemize}
 2235 
 2236 \item \texttt{bsd\_icmp\_frag\_alert on|off} (Specify whether or not to alert.
 2237 Default is on)
 2238 
 2239 \item \texttt{bad\_ipv6\_frag\_alert on|off} (Specify whether or not to alert.
 2240 Default is on)
 2241 
 2242 \item \texttt{frag\_timeout $<$integer$>$} (Specify amount of time in seconds
 2243 to timeout first frag in hash table)
 2244 
 2245 \item \texttt{max\_frag\_sessions $<$integer$>$} (Specify the number of
 2246 fragments to track in the hash table)
 2247 
 2248 \end{itemize} \\
 2249 
 2250 \hline
 2251 \texttt{config logdir: <dir>} & Sets the logdir (\texttt{snort -l}).
 2252 \\
 2253 
 2254 \hline
 2255 \texttt{config log\_ipv6\_extra\_data} & Set Snort to log IPv6 source and destination
 2256 addresses as unified2 extra data events.  \\
 2257 
 2258 \hline
 2259 \texttt{config max\_attribute\_hosts: <hosts>} & Sets a limit on the maximum
 2260 number of hosts to read from the attribute table.  Minimum value is 32 and the
 2261 maximum is 524288 (512k).  The default is 10000.  If the number of hosts in the
 2262 attribute table exceeds this value, an error is logged and the remainder of the
 2263 hosts are ignored.  This option is only supported with a Host Attribute Table
 2264 (see section \ref{targetbased}). \\
 2265 
 2266 \hline
 2267 \texttt{config max\_attribute\_services\_per\_host: <hosts>} & Sets a per host
 2268 limit on the maximum number of services to read from the attribute table. 
 2269 Minimum value is 1 and the maximum is 65535.  The default is 100.  For a given
 2270 host, if the number of services in the attribute table exceeds this value, an
 2271 error is logged and the remainder of the services for that host are ignored. 
 2272 This option is only supported with a Host Attribute Table (see section
 2273 \ref{targetbased}). \\
 2274 
 2275 \hline
 2276 \texttt{config max\_mpls\_labelchain\_len: <num-hdrs>} & Sets a Snort-wide
 2277 limit on the number of MPLS headers a packet can have. Its default value is -1,
 2278 which means that there is no limit on label chain length.\\
 2279 
 2280 \hline
 2281 \texttt{config max\_ip6\_extensions: <num-extensions>} & Sets the maximum number
 2282 of IPv6 extension headers that Snort will decode. Default is 8. \\
 2283 
 2284 \hline
 2285 \texttt{config min\_ttl: <ttl>} & Sets a Snort-wide minimum ttl to ignore all
 2286 traffic. \\
 2287 
 2288 \hline
 2289 \texttt{config mpls\_payload\_type: ipv4|ipv6|ethernet} & Sets a Snort-wide
 2290 MPLS payload type. In addition to ipv4, ipv6 and ethernet are also valid
 2291 options. The default MPLS payload type is ipv4\\
 2292 
 2293 \hline
 2294 \texttt{config no\_promisc} & Disables promiscuous mode (\texttt{snort -p}). \\
 2295 
 2296 \hline
 2297 \texttt{config nolog} & Disables logging. Note: Alerts will still occur.
 2298 (\texttt{snort -N}). \\
 2299 
 2300 \hline
 2301 \texttt{config nopcre} & Disables pcre pattern matching. \\
 2302 
 2303 \hline
 2304 \texttt{config obfuscate} & Obfuscates IP Addresses (\texttt{snort -O}). \\
 2305 
 2306 \hline
 2307 \texttt{config order: <order>} & Changes the order that rules
 2308 are evaluated, e.g.: pass alert log activation. \\
 2309 
 2310 \hline
 2311 \texttt{config pcre\_match\_limit: $<$integer$>$} & Restricts the amount of
 2312 backtracking a given PCRE option.  For example, it will limit the number of
 2313 nested repeats within a pattern.  A value of -1 allows for unlimited PCRE, up
 2314 to the PCRE library compiled limit (around 10 million).  A value of 0 results
 2315 in no PCRE evaluation.  The snort default value is 1500.  \\
 2316 
 2317 \hline
 2318 \texttt{config pcre\_match\_limit\_recursion: $<$integer$>$} & Restricts the
 2319 amount of stack used by a given PCRE option.  A value of -1 allows for
 2320 unlimited PCRE, up to the PCRE library compiled limit (around 10 million).  A
 2321 value of 0 results in no PCRE evaluation.  The snort default value is 1500.
 2322 This option is only useful if the value is less than the
 2323 \texttt{pcre\_match\_limit} \\
 2324 
 2325 \hline
 2326 \texttt{config pkt\_count: <N>} & Exits after N packets (\texttt{snort -n}). \\
 2327 
 2328 \hline
 2329 \texttt{config policy\_version: $<$base-version-string$>$ [$<$binding-version-string$>$]} &
 2330 Supply versioning information to configuration files.  Base version should be
 2331 a string in all configuration files including included ones.  In addition,
 2332 binding version must be in any file configured with \texttt{config binding}.
 2333 This option is used to avoid race conditions when modifying and loading a
 2334 configuration within a short time span - before Snort has had a chance to
 2335 load a previous configuration. \\
 2336 
 2337 \hline
 2338 \texttt{config profile\_preprocs} & Print statistics on preprocessor
 2339 performance.  See Section \ref{preproc profiling} for more details. \\
 2340 
 2341 
 2342 \hline
 2343 \texttt{config profile\_rules} & Print statistics on rule performance.  See
 2344 Section \ref{rule profiling} for more details. \\
 2345 
 2346 \hline
 2347 \texttt{config protected\_content:
 2348 md5|sha256|sha512} & Specifies a default algorithm to use for protected\_content rules.  \\
 2349 
 2350 \hline
 2351 \texttt{config quiet}& Disables banner and status reports (\texttt{snort -q}).
 2352 NOTE: The command line switch \texttt{-q} takes effect immediately after
 2353 processing the command line parameters, whereas using \texttt{config quiet}
 2354 in snort.conf takes effect when the configuration line in snort.conf is parsed.
 2355 That may occur after other configuration settings that result in output to
 2356 console or syslog.
 2357 \\
 2358 
 2359 \hline
 2360 \texttt{config reference: <ref>} & Adds a new reference system to Snort, e.g.:
 2361 myref http://myurl.com/?id=\\
 2362 
 2363 \hline
 2364 \texttt{config reference\_net <cidr>} & For IP obfuscation, the obfuscated net
 2365 will be used if the packet contains an IP address in the reference net.  Also
 2366 used to determine how to set up the logging directory structure for the
 2367 \texttt{session} post detection rule option and ASCII output plugin - an
 2368 attempt is made to name the log directories after the IP address that is not in
 2369 the reference net. \\
 2370 
 2371 \hline \texttt{config response: [attempts <count>] [, device <dev>]} & Set the
 2372 number of strafing attempts per injected response and/or the device, such as
 2373 eth0, from which to send responses.  These options may appear in any order but
 2374 must be comma separated.  The are intended for passive mode. \\
 2375 
 2376 \hline
 2377 \texttt{config set\_gid: <gid>} & Changes GID to specified GID (\texttt{snort
 2378 -g}). \\
 2379 
 2380 \hline
 2381 \texttt{config set\_uid: <uid>} & Sets UID to $<$id$>$ (\texttt{snort -u}). \\
 2382 
 2383 \hline
 2384 \texttt{config show\_year} & Shows year in timestamps (\texttt{snort -y}). \\
 2385 
 2386 \hline
 2387 \texttt{config snaplen: <bytes>} & Set the snaplength of packet, same effect as
 2388 \texttt{-P $<$snaplen$>$} or \texttt{--snaplen $<$snaplen$>$} options.\\
 2389 
 2390 \hline
 2391 \texttt{config so\_rule\_memcap: <bytes>} & Set global memcap in bytes for
 2392 so rules that dynamically allocate memory for storing session data in the
 2393 stream preprocessor.  A value of 0 disables the memcap.  Default is 0.
 2394 Maximum value is the maximum value an unsigned 32 bit integer can hold
 2395 which is 4294967295 or 4GB.\\
 2396 
 2397 \hline
 2398 \texttt{config stateful} & Sets assurance mode for stream (stream is
 2399 established). \\
 2400 
 2401 \hline
 2402 \texttt{config tagged\_packet\_limit: <max-tag>} & When a metric other than
 2403 \texttt{packets} is used in a tag option in a rule, this option sets the
 2404 maximum number of packets to be tagged regardless of the amount defined by the
 2405 other metric.  See Section \ref{tag section} on using the tag option when
 2406 writing rules for more details.  The default value when this option is not
 2407 configured is 256 packets.  Setting this option to a value of 0 will disable
 2408 the packet limit. \\
 2409 
 2410 \hline
 2411 \texttt{config threshold: memcap <bytes>} & Set global memcap in bytes for
 2412 thresholding. Default is 1048576 bytes (1 megabyte). (This is deprecated.
 2413 Use config event\_filter instead.)\\
 2414 
 2415 \hline
 2416 \texttt{config umask: <umask>} & Sets umask when running (\texttt{snort -m}). \\
 2417 
 2418 \hline
 2419 \texttt{config utc} & Uses UTC instead of local time for timestamps
 2420 (\texttt{snort -U}). \\
 2421 
 2422 \hline
 2423 \texttt{config verbose} & Uses verbose logging to STDOUT (\texttt{snort -v}).
 2424 \\
 2425 
 2426 \hline
 2427 \texttt{config vlan\_agnostic} & Causes Snort to ignore vlan headers for
 2428 the purposes of connection and frag tracking.  This option is only valid in the
 2429 base configuration when using multiple configurations, and the default is off.
 2430 \\
 2431 
 2432 \hline
 2433 \texttt{config address\_space\_agnostic} & Causes Snort to ignore DAQ
 2434 address space ID for the purposes of connection and frag tracking.  This option
 2435 is only valid in the base configuration when using multiple configurations, and
 2436 the default is off.  \\
 2437 
 2438 \hline
 2439 \texttt{config policy\_mode: tap|inline|inline\_test} & Sets the policy
 2440 mode to either \texttt{passive}, \texttt{inline} or \texttt{inline\_test}. \\
 2441 
 2442 \hline
 2443 \texttt{config disable\_replace} & Disables content replace option. Default
 2444 behaviour is to replace content. \\
 2445 
 2446 \hline \texttt{config tunnel\_verdicts: gtp|teredo|6in4|4in6} & By default, whitelist
 2447 and blacklist verdicts are handled internally by Snort for GTP, Teredo, 6in4 and 4in6
 2448 encapsulated traffic.  This means Snort actually gives the DAQ a pass or block
 2449 verdict instead.  This is to workaround cases where the DAQ would apply
 2450 the verdict to the whole tunnel instead of the individual session within the
 2451 tunnel.  If your DAQ decodes GTP, Teredo, 6in4 or 4in6 correctly, setting this config
 2452 will allow the whitelist or blacklist verdict to go to the DAQ.  There is a
 2453 modest performance boost by doing this where possible since Snort won't see the
 2454 remaining packets on the session. \\
 2455 
 2456 \hline
 2457 \end{longtable}
 2458 \end{center}
 2459 
 2460 \section{Preprocessors}
 2461 
 2462 Preprocessors were introduced in version 1.5 of Snort. They allow the
 2463 functionality of Snort to be extended by allowing users and programmers to drop
 2464 modular plugins into Snort fairly easily.  Preprocessor code is run before the
 2465 detection engine is called, but after the packet has been decoded. The packet
 2466 can be modified or analyzed in an out-of-band manner using this mechanism.
 2467 
 2468 Preprocessors are loaded and configured using the {\tt preprocessor} keyword.
 2469 The format of the preprocessor directive in the Snort config file is:
 2470 
 2471 \begin{verbatim}
 2472     preprocessor <name>: <options>
 2473 \end{verbatim}
 2474 
 2475 \subsection{Frag3}
 2476 \label{frag3 section}
 2477 
 2478 The frag3 preprocessor is a target-based IP defragmentation module for Snort.
 2479 Frag3 is designed with the following goals:
 2480 
 2481 \begin{slist}
 2482 \item Fast execution with less complex data management.
 2483 \item Target-based host modeling anti-evasion techniques.
 2484 \end{slist}
 2485 
 2486 Frag3 uses the sfxhash data structure and linked lists for data handling
 2487 internally which allows it to have much more predictable and deterministic
 2488 performance in any environment which should aid us in managing heavily
 2489 fragmented environments.
 2490 
 2491 Target-based analysis is a relatively new concept in network-based intrusion
 2492 detection.  The idea of a target-based system is to model the actual targets on
 2493 the network instead of merely modeling the protocols and looking for attacks
 2494 within them.  When IP stacks are written for different operating systems, they
 2495 are usually implemented by people who read the RFCs and then write their
 2496 interpretation of what the RFC outlines into code.  Unfortunately, there are
 2497 ambiguities in the way that the RFCs define some of the edge conditions that
 2498 may occur and when this happens different people implement certain aspects of
 2499 their IP stacks differently.  For an IDS this is a big problem.
 2500 
 2501 In an environment where the attacker can determine what style of IP
 2502 defragmentation is being used on a particular target, the attacker can try to
 2503 fragment packets such that the target will put them back together in a specific
 2504 manner while any passive systems trying to model the host traffic have to guess
 2505 which way the target OS is going to handle the overlaps and retransmits.  As I
 2506 like to say, if the attacker has more information about the targets on a
 2507 network than the IDS does, it is possible to evade the IDS.  This is where the
 2508 idea for ``target-based IDS'' came from.  For more detail on this issue and how
 2509 it affects IDS, check out the famous Ptacek \& Newsham paper at
 2510 \url{http://www.snort.org/docs/idspaper/}.
 2511 
 2512 The basic idea behind target-based IDS is that we tell the IDS information
 2513 about hosts on the network so that it can avoid Ptacek \& Newsham style evasion
 2514 attacks based on information about how an individual target IP stack operates.
 2515 Vern Paxson and Umesh Shankar did a great paper on this very topic in 2003 that
 2516 detailed mapping the hosts on a network and determining how their various IP
 2517 stack implementations handled the types of problems seen in IP defragmentation
 2518 and TCP stream reassembly.  Check it out at
 2519 \url{http://www.icir.org/vern/papers/activemap-oak03.pdf}.
 2520 
 2521 We can also present the IDS with topology information to avoid TTL-based
 2522 evasions and a variety of other issues, but that's a topic for another day.
 2523 Once we have this information we can start to really change the game for these
 2524 complex modeling problems.
 2525 
 2526 Frag3 was implemented to showcase and prototype a target-based module within
 2527 Snort to test this idea.
 2528 
 2529 \subsubsection{Frag 3 Configuration}
 2530 
 2531 There are at least two preprocessor directives required to activate frag3,
 2532 a global configuration directive and an engine instantiation.  There can
 2533 be an arbitrary number of engines defined at startup with their own
 2534 configuration, but only one global configuration.
 2535 
 2536 \textbf{Global Configuration}
 2537 
 2538 \begin{itemize}
 2539 
 2540 \item Preprocessor name: \texttt{frag3\_global}
 2541 
 2542 \item Available options: NOTE: Global configuration options are comma
 2543 separated.
 2544 
 2545 \begin{itemize}
 2546 
 2547 \item \texttt{max\_frags $<$number$>$} - Maximum simultaneous fragments to
 2548 track. Default is 8192.
 2549 
 2550 \item \texttt{memcap $<$bytes$>$} - Memory cap for self preservation.  Default
 2551 is 4MB.  
 2552 
 2553 \item \texttt{prealloc\_memcap $<$bytes$>$} - alternate memory management mode,
 2554 use preallocated fragment nodes based on a memory cap (faster in some
 2555 situations).
 2556 
 2557 \item \texttt{prealloc\_frags $<$number$>$} - Alternate memory management mode,
 2558 use preallocated fragment nodes (faster in some situations).
 2559 
 2560 \item \texttt{disabled} - This optional keyword is allowed with any
 2561 policy to avoid packet processing. This option disables the preprocessor
 2562 for this config, but not for other instances of multiple configurations.
 2563 Use the disable keyword in the base configuration to specify values for the
 2564 options \texttt{memcap}, \texttt{prealloc\_memcap}, and \texttt{prealloc\_frags}
 2565 without having the preprocessor inspect traffic for traffic applying to the base
 2566 configuration.  The other options are parsed but not used. Any valid
 2567 configuration may have "disabled" added to it.
 2568 
 2569 \end{itemize}                               
 2570 \end{itemize}    
 2571  
 2572 \textbf{Engine Configuration}
 2573 
 2574 \begin{itemize}
 2575 
 2576 \item Preprocessor name: \texttt{frag3\_engine}
 2577 
 2578 \item Available options:
 2579   NOTE: Engine configuration options are space separated.
 2580 
 2581 \begin{itemize}
 2582 
 2583 \item \texttt{timeout $<$seconds$>$} - Timeout for fragments.  Fragments in the
 2584 engine for longer than this period will be automatically dropped.  Default is
 2585 60 seconds.
 2586                         
 2587 \item \texttt{min\_ttl $<$value$>$} - Minimum acceptable TTL value for a
 2588 fragment packet.  Default is 1. The accepted range for this option is 1 - 255.
 2589                        
 2590 \item \texttt{detect\_anomalies} - Detect fragment anomalies.
 2591      
 2592 \item \texttt{bind\_to $<$ip\_list$>$} - IP List to bind this engine to.  This
 2593 engine will only run for packets with destination addresses contained within
 2594 the IP List.  Default value is \texttt{all}.
 2595                          
 2596 \item \texttt{overlap\_limit <number>} - Limits the number of overlapping
 2597 fragments per packet.  The default is "0" (unlimited). This config option takes
 2598 values equal to or greater than zero. This is an optional parameter. 
 2599 detect\_anomalies option must be configured for this option to take effect.
 2600 
 2601 \item \texttt{min\_fragment\_length <number>} - Defines smallest fragment size
 2602 (payload size) that should be considered valid.  Fragments smaller than or
 2603 equal to this limit are considered malicious and an event is raised, if
 2604 detect\_anomalies is also configured.  The default is "0" (unlimited), the
 2605 minimum is "0".  This is an optional parameter.  detect\_anomalies option 
 2606 must be configured for this option to take effect.
 2607 
 2608 \item \texttt{policy $<$type$>$} - Select a target-based defragmentation mode.
 2609 Available types are first, last, bsd, bsd-right, linux, windows and solaris.
 2610 Default type is bsd.
 2611 
 2612 The Paxson Active Mapping paper introduced the terminology frag3 is using to
 2613 describe policy types.  The known mappings are as follows.  Anyone who develops
 2614 more mappings and would like to add to this list please feel free to send us an
 2615 email!
 2616 
 2617 \begin{tabular}{| l | l |}
 2618 \hline
 2619 \textbf{Platform} & \textbf{Type}\\
 2620 \hline
 2621 \hline                     
 2622                         AIX 2  & BSD \\
 2623                         \hline
 2624                 AIX 4.3 8.9.3  & BSD \\
 2625                         \hline
 2626                     Cisco IOS  & Last \\
 2627                         \hline
 2628                       FreeBSD  & BSD\\
 2629                         \hline 
 2630        HP JetDirect (printer)  & BSD-right \\
 2631                         \hline
 2632                 HP-UX B.10.20  & BSD \\
 2633                         \hline
 2634                   HP-UX 11.00  & First \\
 2635                         \hline
 2636                   IRIX 4.0.5F  & BSD \\
 2637                         \hline
 2638                      IRIX 6.2  & BSD \\
 2639                         \hline
 2640                      IRIX 6.3  & BSD \\
 2641                         \hline
 2642                    IRIX64 6.4  & BSD \\
 2643                         \hline
 2644                  Linux 2.2.10  & linux \\
 2645                         \hline
 2646              Linux 2.2.14-5.0  & linux \\
 2647                         \hline
 2648                Linux 2.2.16-3  & linux \\
 2649                         \hline
 2650        Linux 2.2.19-6.2.10smp  & linux \\
 2651                         \hline
 2652                Linux 2.4.7-10  & linux \\
 2653                         \hline
 2654    Linux 2.4.9-31SGI 1.0.2smp  & linux \\
 2655                         \hline
 2656    Linux 2.4 (RedHat 7.1-7.3)  & linux \\
 2657                         \hline
 2658       MacOS (version unknown)  & First \\
 2659                         \hline
 2660              NCD Thin Clients  & BSD \\
 2661                         \hline
 2662     OpenBSD (version unknown)  & linux \\
 2663                         \hline
 2664     OpenBSD (version unknown)  & linux \\
 2665                         \hline
 2666                   OpenVMS 7.1  & BSD \\
 2667                         \hline
 2668        OS/2 (version unknown)  & BSD \\
 2669                         \hline
 2670                     OSF1 V3.0  & BSD \\
 2671                         \hline
 2672                     OSF1 V3.2  & BSD \\
 2673                         \hline
 2674             OSF1 V4.0,5.0,5.1  & BSD \\
 2675                         \hline
 2676                   SunOS 4.1.4  & BSD \\
 2677                         \hline
 2678       SunOS 5.5.1,5.6,5.7,5.8  & First \\
 2679                         \hline
 2680         Tru64 Unix V5.0A,V5.1  & BSD \\
 2681                         \hline
 2682                       Vax/VMS  & BSD \\
 2683                         \hline
 2684    Windows (95/98/NT4/W2K/XP)  & Windows\\
 2685 \hline
 2686 \end{tabular}
 2687 
 2688 \end{itemize}
 2689 \end{itemize}
 2690 
 2691 \subsubsection{Format}
 2692 
 2693 Note in the advanced configuration below that there are three engines specified
 2694 running with \emph{Linux}, \texttt{first} and \texttt{last} policies assigned.
 2695 The first two engines are bound to specific IP address ranges and the last one
 2696 applies to all other traffic.  Packets that don't fall within the address
 2697 requirements of the first two engines automatically fall through to the third
 2698 one.
 2699 
 2700 \paragraph{Basic Configuration}
 2701 \begin{verbatim}
 2702     preprocessor frag3_global
 2703     preprocessor frag3_engine
 2704 \end{verbatim}
 2705 
 2706 \paragraph{Advanced Configuration}
 2707 \begin{verbatim}
 2708     preprocessor frag3_global: prealloc_nodes 8192 
 2709     preprocessor frag3_engine: policy linux bind_to 192.168.1.0/24
 2710     preprocessor frag3_engine: policy first bind_to [10.1.47.0/24,172.16.8.0/24]
 2711     preprocessor frag3_engine: policy last detect_anomalies
 2712 \end{verbatim}
 2713 
 2714 \subsubsection{Frag 3 Alert Output}
 2715 \label{frag3 alert output}
 2716 
 2717 Frag3 is capable of detecting eight different types of anomalies.  Its event
 2718 output is packet-based so it will work with all output modes of Snort.  Read
 2719 the documentation in the \texttt{doc/signatures} directory with filenames that
 2720 begin with ``123-'' for information on the different event types.
 2721 
 2722 %%Need to doc these eight types of anomalies and truncate beginning of section.
 2723 
 2724 \subsection{Session}
 2725 \label{session section}
 2726 
 2727 The Session preprocessor is a global stream session management module
 2728 for Snort.  It is derived from the session management functions that
 2729 were part of the Stream5 preprocessor.
 2730 
 2731 Since Session implements part of the functionality and API that was
 2732 previously in Stream5 it cannot be used with Stream5 but must be
 2733 used in conjunction with the new Stream preprocessor.  Similarly, 
 2734 due to the API changes, the other preprocessors in Snort 2.9.7 work
 2735 only with the new Session and Stream preprocessers.
 2736 
 2737 \subsubsection{Session API}
 2738 
 2739 Session provides an API to enable the creation and management of
 2740 the session control block for a flow and the management of data
 2741 and state that may be associated with that flow by service and
 2742 application preprocessors (most of these functions were previously
 2743 supported by the Stream5 API). These methods are called to identify
 2744 sessions that may be ignored (large data transfers, etc), and 
 2745 update the identifying information about the session (application
 2746 protocol, direction, etc) that can later be used by rules.  
 2747 API methods to enable preprocessors to register for dispatch for
 2748 ports and services for which they should be called to process 
 2749 the packet have been added to the Session API. Session is required
 2750 for the use of the 'flow' and 'flowbits' keywords.
 2751 
 2752 \subsubsection{Session Global Configuration}
 2753 
 2754 Global settings for the Session preprocessor.
 2755 
 2756 \begin{verbatim}
 2757     preprocessor stream5_global: \
 2758         [track_tcp <yes|no>], [max_tcp <number>], \
 2759         [memcap <number bytes>], \
 2760         [track_udp <yes|no>], [max_udp <number>], \
 2761         [track_icmp <yes|no>], [max_icmp <number>], \
 2762         [track_ip <yes|no>], [max_ip <number>], \
 2763         [flush_on_alert], [show_rebuilt_packets], \
 2764         [prune_log_max <number bytes>], [disabled], \
 2765         [enable_ha]
 2766 \end{verbatim}
 2767 
 2768 \begin{center}
 2769 \begin{tabular}{| l | p{4.5in} |}
 2770 
 2771 \hline
 2772 \textbf{Option} & \textbf{Description}\\
 2773 \hline 
 2774 
 2775 \hline 
 2776 \texttt{track\_tcp <yes|no>} &
 2777 
 2778 Track sessions for TCP.  The default is "yes".\\
 2779 
 2780 \hline
 2781 \texttt{max\_tcp <num sessions>} &
 2782 
 2783 Maximum simultaneous TCP sessions tracked.  The default is "262144", maximum is
 2784 "1048576", minimum is "2".\\
 2785 
 2786 \hline
 2787 \texttt{memcap <num bytes>} &
 2788 
 2789 Memcap for TCP packet storage.  The default is "8388608" (8MB), maximum is
 2790 "1073741824" (1GB), minimum is "32768" (32KB).\\
 2791 
 2792 \hline
 2793 \texttt{track\_udp <yes|no>} &
 2794 
 2795 Track sessions for UDP.  The default is "yes".\\
 2796 
 2797 \hline
 2798 \texttt{max\_udp <num sessions>} &
 2799 
 2800 Maximum simultaneous UDP sessions tracked.  The default is "131072", maximum is
 2801 "1048576", minimum is "1".\\
 2802 
 2803 \hline
 2804 \texttt{track\_icmp <yes|no>} &
 2805 
 2806 Track sessions for ICMP.  The default is "no".\\
 2807 
 2808 \hline
 2809 \texttt{max\_icmp <num sessions>} &
 2810 
 2811 Maximum simultaneous ICMP sessions tracked.  The default is "65536", maximum is
 2812 "1048576", minimum is "1".\\
 2813 
 2814 \hline
 2815 \texttt{track\_ip <yes|no>} &
 2816 
 2817 Track sessions for IP.  The default is "no".  Note that "IP" includes all
 2818 non-TCP/UDP traffic over IP including ICMP if ICMP not otherwise configured.\\
 2819 
 2820 \hline
 2821 \texttt{max\_ip <num sessions>} &
 2822 
 2823 Maximum simultaneous IP sessions tracked.  The default is "16384", maximum is
 2824 "1048576", minimum is "1".\\
 2825 
 2826 \hline 
 2827 \texttt{disabled} &
 2828 
 2829 Option to disable the stream5 tracking. By default this option is turned off.
 2830 When the preprocessor is disabled only the options memcap, max\_tcp, max\_udp 
 2831 and max\_icmp are applied when specified with the configuration.\\
 2832 
 2833 \hline
 2834 \texttt{flush\_on\_alert} &
 2835 
 2836 Backwards compatibility.  Flush a TCP stream when an alert is generated on that
 2837 stream.  The default is set to off.\\
 2838 
 2839 \hline
 2840 \texttt{show\_rebuilt\_packets} &
 2841 
 2842 Print/display packet after rebuilt (for debugging).  The default is set to
 2843 off.\\
 2844 
 2845 \hline
 2846 \texttt{prune\_log\_max <num bytes>} &
 2847 
 2848 Print a message when a session terminates that was consuming more than the
 2849 specified number of bytes.  The default is "1048576" (1MB), minimum can be either "0"
 2850 (disabled) or if not disabled the minimum is "1024" and maximum is "1073741824".\\
 2851 
 2852 \hline
 2853 \texttt{enable\_ha} &
 2854 
 2855 
 2856 Enable High Availability state sharing.  The default is set to off.\\
 2857 
 2858 \hline
 2859 \end{tabular}
 2860 \end{center}
 2861 
 2862 \subsubsection{Session HA Configuration}
 2863 
 2864 Configuration for HA session state sharing.
 2865 
 2866 \begin{verbatim}
 2867     preprocessor stream5_ha: [min_session_lifetime <num millisecs>], \
 2868         [min_sync_interval <num millisecs>], [startup_input_file <filename>], \
 2869         [runtime_output_file <filename>], [use_side_channel]
 2870 \end{verbatim}
 2871 
 2872 \begin{center}
 2873 \begin{tabular}{| l | p{4.5in} |}
 2874 
 2875 \hline
 2876 \textbf{Option} & \textbf{Description}\\
 2877 \hline 
 2878 
 2879 \hline 
 2880 \texttt{min\_session\_lifetime <num millisecs>} &
 2881 
 2882 Minimum session liftime in milliseconds.  HA update messages will only be generated once a session has existed for
 2883 at least this long.  The default is 0, the minimum is 0, and the maximum is 65535.\\
 2884 
 2885 \hline 
 2886 \texttt{min\_sync\_interval <num millisecs>} &
 2887 
 2888 Minimum synchronization interval in milliseconds.  HA update messages will not be generated more often than
 2889 once per interval on a given session.  The default is 0, the minimum is 0, and the maximum is 65535.\\
 2890 
 2891 \hline
 2892 \texttt{startup\_input\_file <filename>} &
 2893 
 2894 The name of a file for snort to read HA messages from at startup.\\
 2895 
 2896 \hline
 2897 \texttt{runtime\_output\_file <filename>} &
 2898 
 2899 The name of a file to which Snort will write all HA messages that are generated while it is running.\\
 2900 
 2901 \hline
 2902 \texttt{use\_side\_channel} &
 2903 
 2904 Indicates that all HA messages should also be sent to the side channel for processing.\\
 2905 
 2906 \hline
 2907 \end{tabular}
 2908 \end{center}
 2909 
 2910 \subsubsection{Example Configurations}
 2911 
 2912 \begin{enumerate}
 2913 
 2914 \item{}
 2915 
 2916 This example configuration sets a maximum number of TCP session control blocks to 8192, 
 2917 enables tracking of TCP and UPD sessions, and disables tracking of ICMP sessions.  The 
 2918 number of UDP session control blocks will be set to the compiled default. 
 2919 
 2920 \begin{verbatim}
 2921     preprocessor stream5_global: \
 2922         max_tcp 8192, track_tcp yes, track_udp yes, track_icmp no
 2923 
 2924     preprocessor stream5_tcp: \
 2925         policy first, use_static_footprint_sizes
 2926 
 2927     preprocessor stream5_udp: \
 2928         ignore_any_rules
 2929 \end{verbatim}
 2930 
 2931 \end{enumerate}
 2932 
 2933 
 2934 
 2935 \subsection{Stream}
 2936 \label{stream5 section}
 2937 
 2938 The Stream preprocessor is a target-based TCP reassembly module for Snort.  It
 2939 is capable of tracking sessions for both TCP and UDP.  
 2940 
 2941 \subsubsection{Transport Protocols}
 2942 
 2943 TCP sessions are identified via the classic TCP "connection".  UDP sessions are
 2944 established as the result of a series of UDP packets from two end points via
 2945 the same set of ports.  ICMP messages are tracked for the purposes of checking
 2946 for unreachable and service unavailable messages, which effectively terminate a
 2947 TCP or UDP session.
 2948 
 2949 \subsubsection{Target-Based}
 2950 
 2951 Stream, like Frag3, introduces target-based actions for handling of
 2952 overlapping data and other TCP anomalies.  The methods for handling overlapping
 2953 data, TCP Timestamps, Data on SYN, FIN and Reset sequence numbers, etc. and the
 2954 policies supported by Stream are the results of extensive research with many
 2955 target operating systems.
 2956 
 2957 \subsubsection{Stream API}
 2958 
 2959 Stream supports the modified Stream API that is now focused on
 2960 functions specific to reassembly and protocol aware flushing
 2961 operations.  Session management functions have been moved to the
 2962 Session API.  The remaining API functions enable other protocol 
 2963 normalizers/preprocessors to dynamically configure reassembly 
 2964 behavior as required by the application layer protocol.
 2965 
 2966 \subsubsection{Anomaly Detection}
 2967 
 2968 TCP protocol anomalies, such as data on SYN packets, data received outside the
 2969 TCP window, etc are configured via the \texttt{detect\_anomalies} option to the
 2970 TCP configuration.  Some of these anomalies are detected on a per-target basis.
 2971 For example, a few operating systems allow data in TCP SYN packets, while
 2972 others do not.
 2973 
 2974 \subsubsection{Protocol Aware Flushing}
 2975 
 2976 Protocol aware flushing of HTTP, SMB and DCE/RPC can be enabled with this option:
 2977 
 2978 \begin{verbatim}
 2979 config paf_max: <max-pdu>
 2980 \end{verbatim}
 2981 
 2982 where \texttt{<max-pdu>} is between zero (off) and 63780.  This allows Snort to
 2983 statefully scan a stream and reassemble a complete PDU regardless of
 2984 segmentation.  For example, multiple PDUs within a single TCP segment, as well
 2985 as one PDU spanning multiple TCP segments will be reassembled into one PDU per
 2986 packet for each PDU.  PDUs larger than the configured maximum will be split
 2987 into multiple packets.
 2988 
 2989 \subsubsection{Stream TCP Configuration}
 2990 
 2991 Provides a means on a per IP address target to configure TCP policy.  This can
 2992 have multiple occurrences, per policy that is bound to an IP address or network.
 2993 One default policy must be specified, and that policy is not bound to an IP
 2994 address or network.
 2995 
 2996 \begin{verbatim}
 2997     preprocessor stream5_tcp: \
 2998         [log_asymmetric_traffic <yes|no>], \
 2999         [bind_to <ip_addr>], \
 3000         [timeout <number secs>], [policy <policy_id>], \
 3001         [overlap_limit <number>], [max_window <number>], \
 3002         [require_3whs [<number secs>]], [detect_anomalies], \
 3003         [check_session_hijacking], [use_static_footprint_sizes], \
 3004         [dont_store_large_packets], [dont_reassemble_async], \
 3005         [max_queued_bytes <bytes>], [max_queued_segs <number segs>], \
 3006         [small_segments <number> bytes <number> [ignore_ports number [number]*]],  \
 3007         [ports <client|server|both> <all|number|!number [number]* [!number]*>], \
 3008         [protocol <client|server|both> <all|service name [service name]*>], \
 3009         [ignore_any_rules], [flush_factor <number segs>]
 3010 \end{verbatim}
 3011 
 3012 \begin{longtable}[h]{| p{2in} | p{4in} |}
 3013 
 3014 \hline
 3015 \textbf{Option} & \textbf{Description}\\
 3016 \hline 
 3017 
 3018 \hline 
 3019 \texttt{bind\_to <ip\_addr>} &
 3020 
 3021 IP address or network for this policy.  The default is set to any.\\
 3022 
 3023 \hline
 3024 \texttt{timeout <num seconds>} &
 3025 
 3026 Session timeout.  The default is "30",  the minimum is "1", and the maximum is
 3027 "86400" (approximately 1 day).\\
 3028 
 3029 \hline
 3030 \texttt{policy <policy\_id>} &
 3031 
 3032 The Operating System policy for the target OS.  The policy\_id can be one of
 3033 the following:
 3034 
 3035 \begin{tabular}{| l | p{2.5in} |}
 3036 \hline
 3037 Policy Name & Operating Systems.\\
 3038 \hline
 3039 
 3040 \hline
 3041 \texttt{first} &
 3042 
 3043 Favor first overlapped segment.\\
 3044 
 3045 \hline
 3046 \texttt{last} & Favor last overlapped segment.\\
 3047 
 3048 \hline
 3049 \texttt{bsd} & FresBSD 4.x and newer, NetBSD 2.x and newer, OpenBSD 3.x and newer\\
 3050 
 3051 \hline
 3052 \texttt{linux} & Linux 2.4 and newer\\
 3053 
 3054 \hline
 3055 \texttt{old-linux} & Linux 2.2 and earlier\\
 3056 
 3057 \hline
 3058 \texttt{windows} & Windows 2000, Windows XP, Windows 95/98/ME\\
 3059 
 3060 \hline
 3061 \texttt{win2003} & Windows 2003 Server\\
 3062 
 3063 \hline
 3064 \texttt{vista} & Windows Vista\\
 3065 
 3066 \hline
 3067 \texttt{solaris} & Solaris 9.x and newer\\
 3068 
 3069 \hline
 3070 \texttt{hpux} & HPUX 11 and newer\\
 3071 
 3072 \hline
 3073 \texttt{hpux10} & HPUX 10\\
 3074 
 3075 \hline
 3076 \texttt{irix} & IRIX 6 and newer\\
 3077 
 3078 \hline
 3079 \texttt{macos} & MacOS 10.3 and newer\\
 3080 
 3081 \hline
 3082 \end{tabular}\\
 3083 
 3084 \hline
 3085 \texttt{overlap\_limit <number>} &
 3086 
 3087 Limits the number of overlapping packets per session.  The default is "0"
 3088 (unlimited), the minimum is "0", and the maximum is "255".\\
 3089 
 3090 \hline
 3091 \texttt{max\_window <number>} &
 3092 
 3093 Maximum TCP window allowed.  The default is "0" (unlimited), the minimum is
 3094 "0", and the maximum is "1073725440" (65535 left shift 14).  That is the
 3095 highest possible TCP window per RFCs.  This option is intended to prevent a DoS
 3096 against Stream by an attacker using an abnormally large window, so using a
 3097 value near the maximum is discouraged.\\
 3098 
 3099 \hline
 3100 \texttt{require\_3whs [<number seconds>]} &
 3101 
 3102 Establish sessions only on completion of a SYN/SYN-ACK/ACK handshake.  The
 3103 default is set to off.  The optional number of seconds specifies a startup
 3104 timeout.  This allows a grace period for existing sessions to be considered
 3105 established during that interval immediately after Snort is started.  The
 3106 default is "0" (don't consider existing sessions established), the minimum is
 3107 "0", and the maximum is "86400" (approximately 1 day).\\
 3108 
 3109 \hline
 3110 \texttt{detect\_anomalies} &
 3111 
 3112 Detect and alert on TCP protocol anomalies.  The default is set to off.\\
 3113 
 3114 \hline
 3115 \texttt{check\_session\_hijacking} &
 3116 
 3117 Check for TCP session hijacking.  This check validates the hardware (MAC)
 3118 address from both sides of the connect -- as established on the 3-way handshake
 3119 against subsequent packets received on the session.  If an ethernet layer is
 3120 not part of the protocol stack received by Snort, there are no checks
 3121 performed.  Alerts are generated (per '\texttt{detect\_anomalies}' option) for
 3122 either the client or server when the MAC address for one side or the other does
 3123 not match.  The default is set to off.\\
 3124 
 3125 \hline
 3126 \texttt{use\_static\_footprint\_sizes} &
 3127 
 3128 Use static values for determining when to build a reassembled packet to
 3129 allow for repeatable tests.  This option should not be used production
 3130 environments.  The default is set to off.\\
 3131 
 3132 \hline
 3133 \texttt{dont\_store\_large\_packets} &
 3134 
 3135 Performance improvement to not queue large packets in reassembly buffer.  The
 3136 default is set to off.  Using this option may result in missed attacks.\\
 3137 
 3138 \hline
 3139 \texttt{dont\_reassemble\_async} &
 3140 
 3141 Don't queue packets for reassembly if traffic has not been seen in both
 3142 directions.  The default is set to queue packets.\\
 3143 
 3144 \hline
 3145 \texttt{max\_queued\_bytes <bytes>} &
 3146 
 3147 Limit the number of bytes queued for reassembly on a given TCP session to
 3148 bytes.  Default is "1048576" (1MB).  A value of "0" means unlimited, with a
 3149 non-zero minimum of "1024", and a maximum of "1073741824" (1GB).  A message is
 3150 written to console/syslog when this limit is enforced.\\
 3151 
 3152 \hline
 3153 \texttt{max\_queued\_segs <num>} &
 3154 
 3155 Limit the number of segments queued for reassembly on a given TCP session.  The
 3156 default is "2621", derived based on an average size of 400 bytes.  A value of
 3157 "0" means unlimited, with a non-zero minimum of "2", and a maximum of
 3158 "1073741824" (1GB).  A message is written to console/syslog when this limit is
 3159 enforced.\\
 3160 
 3161 \hline
 3162 \texttt{small\_segments <number> bytes <number> [ignore\_ports <number(s)> ]} &
 3163 
 3164 Configure the maximum small segments queued. This feature requires that 
 3165 detect\_anomalies be enabled. The first number is the number of consecutive segments 
 3166 that will trigger the detection rule. The default value is "0" (disabled), with a 
 3167 maximum of "2048". The second number is the minimum bytes for a segment to be 
 3168 considered "small". The default value is "0" (disabled), with a maximum of "2048".  
 3169 ignore\_ports is optional, defines the list of ports in which will be ignored for 
 3170 this rule. The number of ports can be up to "65535".  A message is written to 
 3171 console/syslog when this limit is enforced.\\
 3172 
 3173 \hline
 3174 \texttt{ports <client|server|both> <all|number(s)|!number(s)>} &
 3175 
 3176 
 3177 Specify the client, server, or both and list of ports in which to perform
 3178 reassembly.  This can appear more than once in a given config.  The default
 3179 settings are \texttt{ports client 21 23 25 42 53 80 110 111 135 136 137 139 143
 3180 445 513 514 1433 1521 2401 3306}.  The minimum port allowed is "1" and the
 3181 maximum allowed is "65535".  To disable reassembly for a port specifiy the port
 3182 number preceeded by an '!', e.g. !8080 !25\\
 3183 
 3184 \hline
 3185 \texttt{protocol <client|server|both> <all|service name(s)>} &
 3186 
 3187 
 3188 Specify the client, server, or both and list of services in which to perform
 3189 reassembly.  This can appear more than once in a given config.  The default
 3190 settings are \texttt{ports client ftp telnet smtp nameserver dns http pop3
 3191 sunrpc dcerpc netbios-ssn imap login shell mssql oracle cvs mysql}.  The
 3192 service names can be any of those used in the host attribute table (see
 3193 \ref{targetbased}), including any of the internal defaults (see
 3194 \ref{attribute:service names}) or others specific to the network.\\
 3195 
 3196 \hline
 3197 \texttt{ignore\_any\_rules} &
 3198 
 3199 Don't process any \texttt{->} any (ports) rules for TCP that attempt to match
 3200 payload if there are no port specific rules for the src or destination port.
 3201 Rules that have flow or flowbits will never be ignored.  This is a performance
 3202 improvement and may result in missed attacks.  Using this does not affect rules
 3203 that look at protocol headers, only those with content, PCRE, or byte test
 3204 options.  The default is "off". This option can be used only in default
 3205 policy.\\
 3206 
 3207 \hline
 3208 \texttt{flush\_factor} &
 3209 
 3210 Useful in ips mode to flush upon seeing a drop in segment size after N
 3211 segments of non-decreasing size.  The drop in size often indicates an
 3212 end of request or response.\\
 3213 
 3214 \hline
 3215 \end{longtable}
 3216 
 3217 \begin{note}
 3218 
 3219 If no options are specified for a given TCP policy, that is the default TCP
 3220 policy.  If only a bind\_to option is used with no other options that TCP
 3221 policy uses all of the default values.
 3222 
 3223 \end{note}
 3224 
 3225 \subsubsection{Stream UDP Configuration}
 3226 
 3227 Configuration for UDP session tracking.  Since there is no target based
 3228 binding, there should be only one occurrence of the UDP configuration.
 3229 
 3230 \begin{verbatim}
 3231     preprocessor stream5_udp: [timeout <number secs>], [ignore_any_rules]
 3232 \end{verbatim}
 3233 
 3234 \begin{center}
 3235 \begin{tabular}{| l | p{4.5in} |}
 3236 
 3237 \hline
 3238 \textbf{Option} & \textbf{Description}\\
 3239 \hline 
 3240 
 3241 \hline 
 3242 \texttt{timeout <num seconds>} &
 3243 
 3244 Session timeout.  The default is "30", the minimum is "1", and the maximum is
 3245 "86400" (approximately 1 day).\\
 3246 
 3247 \hline
 3248 \texttt{ignore\_any\_rules} &
 3249 
 3250 Don't process any \texttt{->} any (ports) rules for UDP that attempt to match
 3251 payload if there are no port specific rules for the src or destination port.
 3252 Rules that have flow or flowbits will never be ignored.  This is a performance
 3253 improvement and may result in missed attacks.  Using this does not affect rules
 3254 that look at protocol headers, only those with content, PCRE, or byte test
 3255 options.  The default is "off".\\
 3256 
 3257 \hline
 3258 \end{tabular}
 3259 \end{center}
 3260 
 3261 \begin{note}
 3262 
 3263 With the ignore\_any\_rules option, a UDP rule will be ignored except when
 3264 there is another port specific rule that may be applied to the traffic.  For
 3265 example, if a UDP rule specifies destination port 53, the 'ignored' any
 3266 \texttt{->} any rule will be applied to traffic to/from port 53, but NOT to any
 3267 other source or destination port.  A list of rule SIDs affected by this option
 3268 are printed at Snort's startup.
 3269 
 3270 \end{note}
 3271 
 3272 \begin{note}
 3273 
 3274 With the ignore\_any\_rules option, if a UDP rule that uses any \texttt{->} any
 3275 ports includes either flow or flowbits, the ignore\_any\_rules option is
 3276 effectively pointless.  Because of the potential impact of disabling a flowbits
 3277 rule, the ignore\_any\_rules option will be disabled in this case.
 3278 
 3279 \end{note}
 3280 
 3281 \subsubsection{Stream ICMP Configuration}
 3282 
 3283 Configuration for ICMP session tracking.  Since there is no target based
 3284 binding, there should be only one occurrence of the ICMP configuration.
 3285 
 3286 \begin{note}
 3287 
 3288 ICMP is currently untested, in minimal code form and is NOT ready for use in
 3289 production networks.  It is not turned on by default.
 3290 
 3291 \end{note}
 3292 
 3293 \begin{verbatim}
 3294     preprocessor stream5_icmp: [timeout <number secs>]
 3295 \end{verbatim}
 3296 
 3297 \begin{center}
 3298 \begin{tabular}{| l | p{4.5in} |}
 3299 
 3300 \hline
 3301 \textbf{Option} & \textbf{Description}\\
 3302 \hline 
 3303 
 3304 \hline 
 3305 \texttt{timeout <num seconds>} &
 3306 
 3307 Session timeout.  The default is "30", the minimum is "1", and the maximum is
 3308 "86400" (approximately 1 day).\\
 3309 
 3310 \hline
 3311 \end{tabular}
 3312 \end{center}
 3313 
 3314 \subsubsection{Stream IP Configuration}
 3315 
 3316 Configuration for IP session tracking.  Since there is no target based
 3317 binding, there should be only one occurrence of the IP configuration.
 3318 
 3319 \begin{note}
 3320 
 3321 "IP" includes all non-TCP/UDP traffic over IP including ICMP if ICMP
 3322 not otherwise configured.  It is not turned on by default.
 3323 
 3324 \end{note}
 3325 
 3326 \begin{verbatim}
 3327     preprocessor stream5_ip: [timeout <number secs>]
 3328 \end{verbatim}
 3329 
 3330 \begin{center}
 3331 \begin{tabular}{| l | p{4.5in} |}
 3332 
 3333 \hline
 3334 \textbf{Option} & \textbf{Description}\\
 3335 \hline 
 3336 
 3337 \hline 
 3338 \texttt{timeout <num seconds>} &
 3339 
 3340 Session timeout.  The default is "30", the minimum is "1", and the maximum is
 3341 "86400" (approximately 1 day).\\
 3342 
 3343 \hline
 3344 \end{tabular}
 3345 \end{center}
 3346 
 3347 \subsubsection{Example Configurations}
 3348 
 3349 \begin{enumerate}
 3350 
 3351 \item{}
 3352 
 3353 This example configuration is the default configuration in snort.conf and
 3354 can be used for repeatable tests of stream reassembly in readback mode.
 3355 
 3356 \begin{verbatim}
 3357     preprocessor stream5_global: \
 3358         max_tcp 8192, track_tcp yes, track_udp yes, track_icmp no
 3359 
 3360     preprocessor stream5_tcp: \
 3361         policy first, use_static_footprint_sizes
 3362 
 3363     preprocessor stream5_udp: \
 3364         ignore_any_rules
 3365 \end{verbatim}
 3366 
 3367 \item{}
 3368 
 3369 This configuration maps two network segments to different OS policies, one for
 3370 Windows and one for Linux, with all other traffic going to the default policy
 3371 of Solaris.
 3372 
 3373 \begin{verbatim}
 3374     preprocessor stream5_global: track_tcp yes
 3375     preprocessor stream5_tcp: bind_to 192.168.1.0/24, policy windows
 3376     preprocessor stream5_tcp: bind_to 10.1.1.0/24, policy linux
 3377     preprocessor stream5_tcp: policy solaris
 3378 \end{verbatim}
 3379 
 3380 \end{enumerate}
 3381 
 3382 \subsection{sfPortscan}
 3383 
 3384 The sfPortscan module, developed by Sourcefire, is designed to detect the first
 3385 phase in a network attack: Reconnaissance. In the Reconnaissance phase, an
 3386 attacker determines what types of network protocols or services a host
 3387 supports. This is the traditional place where a portscan takes place. This
 3388 phase assumes the attacking host has no prior knowledge of what protocols or
 3389 services are supported by the target; otherwise, this phase would not be
 3390 necessary.
 3391 
 3392 As the attacker has no beforehand knowledge of its intended target, most
 3393 queries sent by the attacker will be negative (meaning that the service ports
 3394 are closed). In the nature of legitimate network communications, negative
 3395 responses from hosts are rare, and rarer still are multiple negative responses
 3396 within a given amount of time.  Our primary objective in detecting portscans is
 3397 to detect and track these negative responses.
 3398 
 3399 One of the most common portscanning tools in use today is Nmap. Nmap
 3400 encompasses many, if not all, of the current portscanning techniques.
 3401 sfPortscan was designed to be able to detect the different types of scans Nmap
 3402 can produce.
 3403 
 3404 sfPortscan will currently alert for the following types of Nmap scans:
 3405 
 3406 \begin{itemize}
 3407 \item TCP Portscan
 3408 \item UDP Portscan
 3409 \item IP Portscan
 3410 \end{itemize}
 3411 
 3412 These alerts are for one$\rightarrow$one portscans, which are the traditional
 3413 types of scans; one host scans multiple ports on another host. Most of the port
 3414 queries will be negative, since most hosts have relatively few services
 3415 available.
 3416 
 3417 sfPortscan also alerts for the following types of decoy portscans:
 3418 
 3419 \begin{itemize}
 3420 \item TCP Decoy Portscan
 3421 \item UDP Decoy Portscan
 3422 \item IP Decoy Portscan
 3423 \end{itemize}
 3424 
 3425 Decoy portscans are much like the Nmap portscans described above, only the
 3426 attacker has a spoofed source address inter-mixed with the real scanning
 3427 address. This tactic helps hide the true identity of the attacker.
 3428 
 3429 sfPortscan alerts for the following types of distributed portscans:
 3430 
 3431 \begin{itemize}
 3432 \item TCP Distributed Portscan
 3433 \item UDP Distributed Portscan
 3434 \item IP Distributed Portscan
 3435 \end{itemize}
 3436 
 3437 These are many$\rightarrow$one portscans. Distributed portscans occur when
 3438 multiple hosts query one host for open services. This is used to evade an IDS
 3439 and obfuscate command and control hosts.
 3440 
 3441 \begin{note}
 3442 
 3443 Negative queries will be distributed among scanning hosts, so we track this
 3444 type of scan through the scanned host.
 3445 
 3446 \end{note}
 3447 
 3448 sfPortscan alerts for the following types of portsweeps:
 3449 
 3450 \begin{itemize}
 3451 \item TCP Portsweep
 3452 \item UDP Portsweep
 3453 \item IP Portsweep
 3454 \item ICMP Portsweep
 3455 \end{itemize}
 3456 
 3457 These alerts are for one$\rightarrow$many portsweeps. One host scans a single
 3458 port on multiple hosts. This usually occurs when a new exploit comes out and
 3459 the attacker is looking for a specific service. 
 3460 
 3461 \begin{note}
 3462 
 3463 The characteristics of a portsweep scan may not result in many negative
 3464 responses. For example, if an attacker portsweeps a web farm for port 80, we
 3465 will most likely not see many negative responses.
 3466 
 3467 \end{note}
 3468 
 3469 sfPortscan alerts on the following filtered portscans and portsweeps:
 3470 
 3471 \begin{itemize}
 3472 \item TCP Filtered Portscan
 3473 \item UDP Filtered Portscan
 3474 \item IP Filtered Portscan
 3475 
 3476 \item TCP Filtered Decoy Portscan
 3477 \item UDP Filtered Decoy Portscan
 3478 \item IP Filtered Decoy Portscan
 3479 
 3480 \item TCP Filtered Portsweep
 3481 \item UDP Filtered Portsweep
 3482 \item IP Filtered Portsweep
 3483 \item ICMP Filtered Portsweep
 3484 
 3485 \item TCP Filtered Distributed Portscan
 3486 \item UDP Filtered Distributed Portscan
 3487 \item IP Filtered Distributed Portscan
 3488 \end{itemize}
 3489 
 3490 ``Filtered'' alerts indicate that there were no network errors (ICMP
 3491 unreachables or TCP RSTs) or responses on closed ports have been suppressed.
 3492 It's also a good indicator of whether the alert is just a very active
 3493 legitimate host. Active hosts, such as NATs, can trigger these alerts because
 3494 they can send out many connection attempts within a very small amount of time.
 3495 A filtered alert may go off before responses from the remote hosts are
 3496 received.
 3497 
 3498 sfPortscan only generates one alert for each host pair in question during the
 3499 time window (more on windows below). On TCP scan alerts, sfPortscan will also
 3500 display any open ports that were scanned. On TCP sweep alerts however,
 3501 sfPortscan will only track open ports after the alert has been triggered. Open
 3502 port events are not individual alerts, but tags based on the original scan
 3503 alert.
 3504 
 3505 \subsubsection{sfPortscan Configuration}
 3506 
 3507 Use of the Stream preprocessor is required for sfPortscan. Stream gives
 3508 portscan direction in the case of connectionless protocols like ICMP and UDP.
 3509 You should enable the Stream preprocessor in your \texttt{snort.conf}, as
 3510 described in Section \ref{stream5 section}.
 3511 
 3512 The parameters you can use to configure the portscan module are:
 3513 
 3514 \begin{slist}
 3515 \item \textbf{proto $<$protocol$>$}
 3516 
 3517 Available options:
 3518 
 3519 \begin{itemize}
 3520 \item \texttt{TCP}
 3521 \item \texttt{UDP}
 3522 \item \texttt{ICMP}
 3523 \item \texttt{ip\_proto}
 3524 \item \texttt{all}
 3525 \end{itemize}
 3526 
 3527 \item \textbf{scan\_type $<$scan\_type$>$}
 3528 
 3529 Available options: 
 3530 
 3531 \begin{itemize}
 3532 \item \texttt{portscan} 
 3533 \item \texttt{portsweep} 
 3534 \item \texttt{decoy\_portscan}
 3535 \item \texttt{distributed\_portscan}
 3536 \item \texttt{all}
 3537 \end{itemize}
 3538 
 3539 \item \textbf{sense\_level $<$level$>$}
 3540 
 3541 Available options:
 3542 
 3543 \begin{itemize}
 3544 
 3545 \item \texttt{low} - ``Low'' alerts are only generated on error packets sent
 3546 from the target host, and because of the nature of error responses, this
 3547 setting should see very few false positives. However, this setting will never
 3548 trigger a Filtered Scan alert because of a lack of error responses. This
 3549 setting is based on a static time window of 60 seconds, after which this window
 3550 is reset.
 3551 
 3552 \item \texttt{medium} - ``Medium'' alerts track connection counts, and so will
 3553 generate filtered scan alerts. This setting may false positive on active hosts
 3554 (NATs, proxies, DNS caches, etc), so the user may need to deploy the use of
 3555 Ignore directives to properly tune this directive.
 3556 
 3557 \item \texttt{high} - ``High'' alerts continuously track hosts on a network
 3558 using a time window to evaluate portscan statistics for that host. A "High"
 3559 setting will catch some slow scans because of the continuous monitoring, but is
 3560 very sensitive to active hosts. This most definitely will require the user to
 3561 tune sfPortscan.
 3562 
 3563 \end{itemize}
 3564 
 3565 \item \textbf{watch\_ip $<$ip1$|$ip2/cidr[ [port$|$port2-port3]]$>$ }
 3566 
 3567 Defines which IPs, networks, and specific ports on those hosts to watch.  The
 3568 list is a comma separated list of IP addresses, IP address using CIDR notation.
 3569 Optionally, ports are specified after the IP address/CIDR using a space and can
 3570 be either a single port or a range denoted by a dash.  IPs or networks not
 3571 falling into this range are ignored if this option is used.
 3572 
 3573 \item \textbf{ignore\_scanners $<$ip1$|$ip2/cidr[ [port$|$port2-port3]]$>$ }
 3574 
 3575 Ignores the source of scan alerts.  The parameter is the same format as that of
 3576 \texttt{watch\_ip}.
 3577 
 3578 \item \textbf{ignore\_scanned $<$ip1$|$ip2/cidr[ [port$|$port2-port3]]$>$ }
 3579 
 3580 Ignores the destination of scan alerts.  The parameter is the same format as
 3581 that of \texttt{watch\_ip}.
 3582 
 3583 \item \textbf{logfile $<$file$>$ } 
 3584 
 3585 This option will output portscan events to the file specified. If \texttt{file}
 3586 does not contain a leading slash, this file will be placed in the Snort config
 3587 dir.
 3588 
 3589 \item \textbf{include\_midstream}
 3590 
 3591 This option will include sessions picked up in midstream by Stream.
 3592 This can lead to false alerts, especially under heavy load with dropped
 3593 packets; which is why the option is off by default.
 3594 
 3595 \item \textbf{detect\_ack\_scans}
 3596 
 3597 This option will include sessions picked up in midstream by the stream module,
 3598 which is necessary to detect ACK scans.  However, this can lead to false
 3599 alerts, especially under heavy load with dropped packets; which is why the
 3600 option is off by default.
 3601 
 3602 \item \textbf{disabled}
 3603 
 3604 This optional keyword is allowed with any policy to avoid packet processing.
 3605 This option disables the preprocessor. When the preprocessor is disabled
 3606 only the memcap option is applied when specified with the configuration.
 3607 The other options are parsed but not used. Any valid configuration may have
 3608 "disabled" added to it.
 3609 
 3610 \end{slist}
 3611 
 3612 \subsubsection{Format}
 3613 
 3614 \begin{verbatim}
 3615     preprocessor sfportscan: proto <protocols> \
 3616         scan_type <portscan|portsweep|decoy_portscan|distributed_portscan|all> \
 3617         sense_level <low|medium|high> \
 3618         watch_ip <IP or IP/CIDR> \
 3619         ignore_scanners <IP list> \
 3620         ignore_scanned <IP list> \
 3621         logfile <path and filename> \
 3622         disabled 
 3623 \end{verbatim}
 3624 
 3625 \subsubsection{Example}
 3626 
 3627 \begin{verbatim}
 3628     preprocessor flow: stats_interval 0 hash 2
 3629     preprocessor sfportscan:\
 3630         proto { all } \
 3631         scan_type { all } \
 3632         sense_level { low }
 3633 \end{verbatim}
 3634 
 3635 \subsubsection{sfPortscan Alert Output}
 3636 
 3637 \paragraph{Unified Output}
 3638 
 3639 In order to get all the portscan information logged with the alert, snort
 3640 generates a pseudo-packet and uses the payload portion to store the additional
 3641 portscan information of priority count, connection count, IP count, port count,
 3642 IP range, and port range.  The characteristics of the packet are:
 3643 
 3644 \begin{verbatim}
 3645     Src/Dst MAC Addr == MACDAD
 3646     IP Protocol == 255
 3647     IP TTL == 0
 3648 \end{verbatim}
 3649 
 3650 Other than that, the packet looks like the IP portion of the packet that caused
 3651 the portscan alert to be generated.  This includes any IP options, etc.  The
 3652 payload and payload size of the packet are equal to the length of the
 3653 additional portscan information that is logged.  The size tends to be around
 3654 100 - 200 bytes.
 3655 
 3656 Open port alerts differ from the other portscan alerts, because open port
 3657 alerts utilize the tagged packet output system.  This means that if an output
 3658 system that doesn't print tagged packets is used, then the user won't see open
 3659 port alerts.  The open port information is stored in the IP payload and
 3660 contains the port that is open.
 3661 
 3662 The sfPortscan alert output was designed to work with unified2 packet logging,
 3663 so it is possible to extend favorite Snort GUIs to display portscan alerts and
 3664 the additional information in the IP payload using the above packet
 3665 characteristics.
 3666 
 3667 \paragraph{Log File Output}
 3668 
 3669 Log file output is displayed in the following format, and explained further
 3670 below:
 3671 
 3672 \begin{verbatim}
 3673     Time: 09/08-15:07:31.603880
 3674     event_id: 2
 3675     192.168.169.3 -> 192.168.169.5 (portscan) TCP Filtered Portscan
 3676     Priority Count: 0
 3677     Connection Count: 200
 3678     IP Count: 2
 3679     Scanner IP Range: 192.168.169.3:192.168.169.4
 3680     Port/Proto Count: 200
 3681     Port/Proto Range: 20:47557
 3682 \end{verbatim}
 3683 
 3684 If there are open ports on the target, one or more additional tagged packet(s)
 3685 will be appended:
 3686 
 3687 \begin{verbatim}
 3688     Time: 09/08-15:07:31.603881
 3689     event_ref: 2
 3690     192.168.169.3 -> 192.168.169.5 (portscan) Open Port
 3691     Open Port: 38458
 3692 \end{verbatim}
 3693 
 3694 \begin{slist}
 3695 
 3696 \item \textbf{Event\_id/Event\_ref}
 3697 
 3698 These fields are used to link an alert with the corresponding \texttt{Open
 3699 Port} tagged packet
 3700 
 3701 \item \textbf{Priority Count}
 3702 
 3703 \texttt{Priority Count} keeps track of bad responses (resets, unreachables).
 3704 The higher the priority count, the more bad responses have been received.
 3705 
 3706 \item \textbf{Connection Count}
 3707      
 3708 \texttt{Connection Count} lists how many connections are active on the hosts
 3709 (src or dst). This is accurate for connection-based protocols, and is more of
 3710 an estimate for others. Whether or not a portscan was filtered is determined
 3711 here. High connection count and low priority count would indicate filtered (no
 3712 response received from target).
 3713 
 3714 \item \textbf{IP Count}
 3715 
 3716 IP Count keeps track of the last IP to contact a host, and increments the count
 3717 if the next IP is different. For one-to-one scans, this is a low number. For
 3718 active hosts this number will be high regardless, and one-to-one scans may
 3719 appear as a distributed scan.
 3720 
 3721 \item \textbf{Scanned/Scanner IP Range}
 3722 
 3723 This field changes depending on the type of alert. Portsweep (one-to-many)
 3724 scans display the scanned IP range; Portscans (one-to-one) display the scanner
 3725 IP. 
 3726 
 3727 \item \textbf{Port Count}
 3728 
 3729 Port Count keeps track of the last port contacted and increments this number
 3730 when that changes. We use this count (along with IP Count) to determine the
 3731 difference between one-to-one portscans and one-to-one decoys.  \end{slist}
 3732 
 3733 \subsubsection{Tuning sfPortscan}
 3734 \label{tuning sfportscan}
 3735 
 3736 The most important aspect in detecting portscans is tuning the detection engine
 3737 for your network(s).  Here are some tuning tips:
 3738 
 3739 \begin{slist}
 3740 
 3741 \item \textbf{Use the watch\_ip, ignore\_scanners, and ignore\_scanned options.}
 3742   
 3743 It's important to correctly set these options.  The \texttt{watch\_ip} option
 3744 is easy to understand.  The analyst should set this option to the list of CIDR
 3745 blocks and IPs that they want to watch.  If no \texttt{watch\_ip} is defined,
 3746 sfPortscan will watch all network traffic.
 3747      
 3748 The \texttt{ignore\_scanners} and \texttt{ignore\_scanned} options come into
 3749 play in weeding out legitimate hosts that are very active on your network.
 3750 Some of the most common examples are NAT IPs, DNS cache servers, syslog
 3751 servers, and nfs servers.  sfPortscan may not generate false positives for
 3752 these types of hosts, but be aware when first tuning sfPortscan for these IPs.
 3753 Depending on the type of alert that the host generates, the analyst will know
 3754 which to ignore it as.  If the host is generating portsweep events, then add it
 3755 to the \texttt{ignore\_scanners} option.  If the host is generating portscan
 3756 alerts (and is the host that is being scanned), add it to the
 3757 \texttt{ignore\_scanned} option.
 3758   
 3759 \item \textbf{Filtered scan alerts are much more prone to false positives.}
 3760   
 3761 When determining false positives, the alert type is very important.  Most of
 3762 the false positives that sfPortscan may generate are of the filtered scan alert
 3763 type.  So be much more suspicious of filtered portscans.  Many times this just
 3764 indicates that a host was very active during the time period in question.  If
 3765 the host continually generates these types of alerts, add it to the
 3766 \texttt{ignore\_scanners} list or use a lower sensitivity level.
 3767      
 3768 \item \textbf{Make use of the Priority Count, Connection Count, IP Count, Port
 3769 Count, IP Range, and Port Range to determine false positives.}
 3770      
 3771 The portscan alert details are vital in determining the scope of a portscan and
 3772 also the confidence of the portscan.  In the future, we hope to automate much
 3773 of this analysis in assigning a scope level and confidence level, but for now
 3774 the user must manually do this.  The easiest way to determine false positives
 3775 is through simple ratio estimations.  The following is a list of ratios to
 3776 estimate and the associated values that indicate a legitimate scan and not a
 3777 false positive.
 3778      
 3779 \textbf{Connection Count / IP Count:}  This ratio indicates an estimated
 3780 average of connections per IP.  For portscans, this ratio should be high, the
 3781 higher the better.  For portsweeps, this ratio should be low.
 3782      
 3783 \textbf{Port Count / IP Count:}  This ratio indicates an estimated average of
 3784 ports connected to per IP.  For portscans, this ratio should be high and
 3785 indicates that the scanned host's ports were connected to by fewer IPs.  For
 3786 portsweeps, this ratio should be low, indicating that the scanning host
 3787 connected to few ports but on many hosts.
 3788      
 3789 \textbf{Connection Count / Port Count:}  This ratio indicates an estimated
 3790 average of connections per port.  For portscans, this ratio should be low.
 3791 This indicates that each connection was to a different port.  For portsweeps,
 3792 this ratio should be high.  This indicates that there were many connections to
 3793 the same port.
 3794      
 3795 The reason that \texttt{Priority Count} is not included, is because the
 3796 priority count is included in the connection count and the above comparisons
 3797 take that into consideration.  The Priority Count play an important role in
 3798 tuning because the higher the priority count the more likely it is a real
 3799 portscan or portsweep (unless the host is firewalled).
 3800      
 3801 \item \textbf{If all else fails, lower the sensitivity level.}
 3802      
 3803 If none of these other tuning techniques work or the analyst doesn't have the
 3804 time for tuning, lower the sensitivity level.  You get the best protection the
 3805 higher the sensitivity level, but it's also important that the portscan
 3806 detection engine generate alerts that the analyst will find informative.  The
 3807 low sensitivity level only generates alerts based on error responses.  These
 3808 responses indicate a portscan and the alerts generated by the low sensitivity
 3809 level are highly accurate and require the least tuning.  The low sensitivity
 3810 level does not catch filtered scans; since these are more prone to false
 3811 positives.  \end{slist}
 3812 
 3813 \subsection{RPC Decode}
 3814 \label{sub:rpc-decoder}
 3815 
 3816 The rpc\_decode preprocessor normalizes RPC multiple fragmented records into a
 3817 single un-fragmented record.  It does this by normalizing the packet into the
 3818 packet buffer.  If stream5 is enabled, it will only process client-side
 3819 traffic.  By default, it runs against traffic on ports 111 and 32771.
 3820 
 3821 \subsubsection{Format}
 3822 
 3823 \begin{verbatim}
 3824     preprocessor rpc_decode: \
 3825         <ports> [ alert_fragments ] \
 3826         [no_alert_multiple_requests] \
 3827         [no_alert_large_fragments] \
 3828         [no_alert_incomplete]
 3829 \end{verbatim}
 3830 
 3831 \begin{table}[h]
 3832 \begin{center}
 3833 \begin{tabular}{| l | l |}
 3834 
 3835 \hline 
 3836 \textbf{Option}& \textbf{Description}\\
 3837 \hline
 3838 
 3839 \hline 
 3840 \texttt{alert\_fragments}&
 3841 
 3842 Alert on any fragmented RPC record.\\
 3843 
 3844 \hline 
 3845 \texttt{no\_alert\_multiple\_requests}&
 3846 
 3847 Don't alert when there are multiple records in one packet.\\
 3848 
 3849 \hline 
 3850 \texttt{no\_alert\_large\_fragments}&
 3851 
 3852 Don't alert when the sum of fragmented records exceeds one packet.\\
 3853 
 3854 \hline 
 3855 \texttt{no\_alert\_incomplete}&
 3856 
 3857 Don't alert when a single fragment record exceeds the size of one packet.\\
 3858 
 3859 \hline
 3860 \end{tabular}
 3861 \end{center}
 3862 \end{table}
 3863 
 3864 \subsection{Performance Monitor}
 3865 \label{sub:perfmonitor}
 3866 
 3867 This preprocessor measures Snort's real-time and theoretical maximum
 3868 performance.  Whenever this preprocessor is turned on, it should have an output
 3869 mode enabled, either ``console'' which prints statistics to the console window
 3870 or ``file'' with a file name, where statistics get printed to the specified
 3871 file name. By default, Snort's real-time statistics are processed. This
 3872 includes:
 3873 
 3874 \begin{itemize}
 3875 \item Time Stamp
 3876 \item Drop Rate
 3877 \item Mbits/Sec (wire) [duplicated below for easy comparison with other rates]
 3878 \item Alerts/Sec 
 3879 \item K-Pkts/Sec (wire) [duplicated below for easy comparison with other rates]
 3880 \item Avg Bytes/Pkt (wire) [duplicated below for easy comparison with other rates]
 3881 \item Pat-Matched [percent of data received that Snort processes in pattern matching]
 3882 \item Syns/Sec
 3883 \item SynAcks/Sec
 3884 \item New Sessions Cached/Sec
 3885 \item Sessions Del fr Cache/Sec
 3886 \item Current Cached Sessions
 3887 \item Max Cached Sessions
 3888 \item Stream Flushes/Sec
 3889 \item Stream Session Cache Faults
 3890 \item Stream Session Cache Timeouts
 3891 \item New Frag Trackers/Sec
 3892 \item Frag-Completes/Sec
 3893 \item Frag-Inserts/Sec
 3894 \item Frag-Deletes/Sec
 3895 \item Frag-Auto Deletes/Sec [memory DoS protection]
 3896 \item Frag-Flushes/Sec
 3897 \item Frag-Current [number of current Frag Trackers]
 3898 \item Frag-Max [max number of Frag Trackers at any time]
 3899 \item Frag-Timeouts
 3900 \item Frag-Faults
 3901 \item Number of CPUs [*** Only if compiled with LINUX\_SMP ***, the next three appear for each CPU]
 3902 \item CPU usage (user)
 3903 \item CPU usage (sys)
 3904 \item CPU usage (Idle)
 3905 \item Mbits/Sec (wire) [average mbits of total traffic]
 3906 \item Mbits/Sec (ipfrag) [average mbits of IP fragmented traffic]
 3907 \item Mbits/Sec (ipreass) [average mbits Snort injects after IP reassembly]
 3908 \item Mbits/Sec (tcprebuilt) [average mbits Snort injects after TCP reassembly]
 3909 \item Mbits/Sec (applayer) [average mbits seen by rules and protocol decoders]
 3910 \item Avg Bytes/Pkt (wire)
 3911 \item Avg Bytes/Pkt (ipfrag)
 3912 \item Avg Bytes/Pkt (ipreass)
 3913 \item Avg Bytes/Pkt (tcprebuilt)
 3914 \item Avg Bytes/Pkt (applayer)
 3915 \item K-Pkts/Sec (wire)
 3916 \item K-Pkts/Sec (ipfrag)
 3917 \item K-Pkts/Sec (ipreass)
 3918 \item K-Pkts/Sec (tcprebuilt)
 3919 \item K-Pkts/Sec (applayer)
 3920 \item Total Packets Received
 3921 \item Total Packets Dropped (not processed)
 3922 \item Total Packets Blocked (inline)
 3923 \item Percentage of Packets Dropped
 3924 \item Total Filtered TCP Packets
 3925 \item Total Filtered UDP Packets
 3926 \item Midstream TCP Sessions/Sec
 3927 \item Closed TCP Sessions/Sec
 3928 \item Pruned TCP Sessions/Sec
 3929 \item TimedOut TCP Sessions/Sec
 3930 \item Dropped Async TCP Sessions/Sec
 3931 \item TCP Sessions Initializing
 3932 \item TCP Sessions Established
 3933 \item TCP Sessions Closing
 3934 \item Max TCP Sessions (interval)
 3935 \item New Cached UDP Sessions/Sec
 3936 \item Cached UDP Ssns Del/Sec
 3937 \item Current Cached UDP Sessions
 3938 \item Max Cached UDP Sessions
 3939 \item Current Attribute Table Hosts (Target Based)
 3940 \item Attribute Table Reloads (Target Based)
 3941 \item Mbits/Sec (Snort)
 3942 \item Mbits/Sec (sniffing)
 3943 \item Mbits/Sec (combined)
 3944 \item uSeconds/Pkt (Snort)
 3945 \item uSeconds/Pkt (sniffing)
 3946 \item uSeconds/Pkt (combined)
 3947 \item KPkts/Sec (Snort)
 3948 \item KPkts/Sec (sniffing)
 3949 \item KPkts/Sec (combined)
 3950 \end{itemize}
 3951 
 3952 There are over 100 individual statistics included.  A header line is output at startup and
 3953 rollover that labels each column.
 3954 
 3955 The following options can be used with the performance monitor:
 3956 
 3957 \begin{itemize}
 3958 
 3959 \item \texttt{flow} - Prints out statistics about the type and amount of traffic
 3960 and protocol distributions that Snort is seeing. This option can produce large
 3961 amounts of output.
 3962 
 3963 \item \texttt{flow-file} - Prints \texttt{flow} statistics in a comma-delimited
 3964 format to the file that is specified.
 3965 \begin{itemize}
 3966 \item Timestamp
 3967 \item Total \% TCP bytes
 3968 \item Total \% UDP bytes
 3969 \item Total \% ICMP bytes
 3970 \item Total \% OTHER bytes
 3971 \item Number of Packet length entries
 3972 \item Packet length entries - bytes,\%total
 3973 \item Number of TCP port flow entries
 3974 \item TCP port flow entries : port,\%total,\%src,\%dst
 3975 \item \% TCP high port to high port
 3976 \item Number of UDP port flow entries
 3977 \item UDP port flow entries : port,\%total,\%src,\%dst
 3978 \item \% UDP high port to high port
 3979 \item Number of ICMP type entries
 3980 \item ICMP type entries : type,\%total
 3981 \end{itemize}
 3982 Specifying this option implicitly enables \texttt{flow} statistics.
 3983 
 3984 \item \texttt{events} - Turns on event reporting.  This prints out statistics
 3985 as to the number of rules that were evaluated and didn't match
 3986 (\textit{non-qualified events}) vs. the number of rules that were evaluated and
 3987 matched (\textit{qualified events}).  A high \textit{non-qualified event} to
 3988 \textit{qualified event} ratio can indicate there are many rules with either
 3989 minimal content or no content that are being evaluated without success.  The
 3990 fast pattern matcher is used to select a set of rules for evaluation based on
 3991 the longest \texttt{content} or a \texttt{content} modified with the
 3992 \texttt{fast\_pattern} rule option in a rule.  Rules with short, generic
 3993 contents are more likely to be selected for evaluation than those with
 3994 longer, more unique contents.  Rules without \texttt{content} are not
 3995 filtered via the fast pattern matcher and are always evaluated, so if
 3996 possible, adding a \texttt{content} rule option to those rules can decrease the
 3997 number of times they need to be evaluated and improve performance.
 3998 
 3999 \item \texttt{max} - Turns on the theoretical maximum performance that Snort
 4000 calculates given the processor speed and current performance.  This is only
 4001 valid for uniprocessor machines, since many operating systems don't keep
 4002 accurate kernel statistics for multiple CPUs.  
 4003 
 4004 \item \texttt{console} - Prints statistics at the console.
 4005 
 4006 \item \texttt{file} - Prints statistics in a comma-delimited format to the file
 4007 that is specified.  Not all statistics are output to this file.  You may also
 4008 use \texttt{snortfile} which will output into your defined Snort log directory.
 4009 Both of these directives can be overridden on the command line with the
 4010 \texttt{-Z} or \texttt{--perfmon-file} options.  At startup, Snort will log
 4011 a distinctive line to this file with a timestamp to all readers to easily identify
 4012 gaps in the stats caused by Snort not running.
 4013 
 4014 \item \texttt{pktcnt} - Adjusts the number of packets to process before
 4015 checking for the time sample.  This boosts performance, since checking the time
 4016 sample reduces Snort's performance.  By default, this is 10000.  
 4017 
 4018 \item \texttt{time} - Represents the number of seconds between intervals.
 4019 
 4020 \item \texttt{accumulate} or \texttt{reset} - Defines which type of drop
 4021 statistics are kept by the operating system. By default, \texttt{reset} is
 4022 used.
 4023 
 4024 \item \texttt{atexitonly} - Dump stats for entire life of Snort.
 4025 One or more of the following arguments can be given to specify specific
 4026 statistic types to dump at exit:
 4027 \begin{itemize}
 4028 \item \texttt{base-stats}
 4029 \item \texttt{flow-stats}
 4030 \item \texttt{flow-ip-stats}
 4031 \item \texttt{events-stats}
 4032 \end{itemize}
 4033 Without any arguments, all enabled stats will be dumped only when Snort exits.
 4034 
 4035 \item \texttt{max\_file\_size} - Defines the maximum size of the
 4036 comma-delimited file.  Before the file exceeds this size, it will be rolled
 4037 into a new date stamped file of the format YYYY-MM-DD, followed by
 4038 YYYY-MM-DD.x, where x will be incremented each time the comma delimited file
 4039 is rolled over.  The minimum is 4096 bytes and the maximum is 2147483648 bytes
 4040 (2GB).  The default is the same as the maximum.
 4041 
 4042 \item \texttt{flow-ip} - Collects IP traffic distribution statistics based on
 4043 host pairs.  For each pair of hosts for which IP traffic has been seen, the
 4044 following statistics are collected for both directions (A to B and B to A):
 4045 \begin{itemize}
 4046 \item TCP Packets
 4047 \item TCP Traffic in Bytes
 4048 \item TCP Sessions Established
 4049 \item TCP Sessions Closed
 4050 \item UDP Packets
 4051 \item UDP Traffic in Bytes
 4052 \item UDP Sessions Created
 4053 \item Other IP Packets
 4054 \item Other IP Traffic in Bytes
 4055 \end{itemize}
 4056 These statistics are printed and reset at the end of each interval.
 4057 
 4058 \item \texttt{flow-ip-file} - Prints the flow IP statistics in a
 4059 comma-delimited format to the file that is specified.  All of the statistics
 4060 mentioned above, as well as the IP addresses of the host pairs in
 4061 human-readable format, are included.
 4062 
 4063 Each line in the file will have its values correspond (in order) to those below:
 4064 \begin{itemize}
 4065 \item IP Address A (String)
 4066 \item IP Address B (String)
 4067 \item TCP Packets from A to B
 4068 \item TCP Traffic in Bytes from A to B
 4069 \item TCP Packets from B to A
 4070 \item TCP Traffic in Bytes from B to A
 4071 \item UDP Packets from A to B
 4072 \item UDP Traffic in Bytes from A to B
 4073 \item UDP Packets from B to A
 4074 \item UDP Traffic in Bytes from B to A
 4075 \item Other IP Packets from A to B
 4076 \item Other IP Traffic in Bytes from A to B
 4077 \item Other IP Packets from B to A
 4078 \item Other IP Traffic in Bytes from B to A
 4079 \item TCP Sessions Established
 4080 \item TCP Sessions Closed
 4081 \item UDP Sessions Created
 4082 \end{itemize}
 4083 
 4084 \item \texttt{flow-ip-memcap} - Sets the memory cap on the hash table used to
 4085 store IP traffic statistics for host pairs.  Once the cap has been reached, the
 4086 table will start to prune the statistics for the least recently seen host pairs
 4087 to free memory.  This value is in bytes and the default value is
 4088 52428800 (50MB).
 4089 
 4090 \end{itemize}
 4091 \subsubsection{Examples}
 4092 
 4093 \begin{verbatim}
 4094     preprocessor perfmonitor: \
 4095         time 30 events flow file stats.profile max console pktcnt 10000 
 4096 
 4097     preprocessor perfmonitor: \
 4098         time 300 file /var/tmp/snortstat pktcnt 10000
 4099 
 4100     preprocessor perfmonitor: \
 4101         time 30 flow-ip flow-ip-file flow-ip-stats.csv pktcnt 1000
 4102 
 4103     preprocessor perfmonitor: \
 4104         time 30 pktcnt 1000 snortfile base.csv flow-file flows.csv atexitonly flow-stats
 4105 
 4106     preprocessor perfmonitor: \
 4107         time 30 pktcnt 1000 flow events atexitonly base-stats flow-stats console
 4108 \end{verbatim}
 4109 
 4110 \subsection{HTTP Inspect}
 4111 \label{sub:http-inspect}
 4112 
 4113 HTTP Inspect is a generic HTTP decoder for user applications.  Given a data
 4114 buffer, HTTP Inspect will decode the buffer, find HTTP fields, and normalize
 4115 the fields.  HTTP Inspect works on both client requests and server responses.
 4116 
 4117 HTTP Inspect has a very ``rich'' user configuration.  Users can configure
 4118 individual HTTP servers with a variety of options, which should allow the user
 4119 to emulate any type of web server. Within HTTP Inspect, there are two areas of
 4120 configuration: global and server.
 4121 
 4122 \subsubsection{Global Configuration}
 4123 
 4124 The global configuration deals with configuration options that determine the
 4125 global functioning of HTTP Inspect.  The following example gives the generic
 4126 global configuration format:
 4127 
 4128 \subsubsection{Format}
 4129 \begin{verbatim}
 4130     preprocessor http_inspect: \
 4131         global \
 4132         iis_unicode_map <map_filename> \
 4133         codemap <integer> \
 4134         [detect_anomalous_servers] \
 4135         [proxy_alert] \
 4136         [max_gzip_mem <num>] \
 4137         [compress_depth <num>] [decompress_depth <num>] \
 4138         [memcap <num>] \
 4139         disabled
 4140 \end{verbatim}
 4141 
 4142 You can only have a single global configuration, you'll get an error if you try
 4143 otherwise.
 4144 
 4145 \paragraph{Configuration}
 4146 \begin{slist}
 4147 \item \texttt{iis\_unicode\_map $<$map\_filename$>$ [codemap $<$integer$>$]}
 4148 
 4149 This is the global \texttt{iis\_unicode\_map} file.  The
 4150 \texttt{iis\_unicode\_map} is a required configuration parameter.  The map file
 4151 can reside in the same directory as \texttt{snort.conf} or be specified via a
 4152 fully-qualified path to the map file.
 4153 
 4154 The \texttt{iis\_unicode\_map} file is a Unicode codepoint map which tells HTTP
 4155 Inspect which codepage to use when decoding Unicode characters.  For US
 4156 servers, the codemap is usually 1252.
 4157 
 4158 A Microsoft US Unicode codepoint map is provided in the Snort source
 4159 \texttt{etc} directory by default.  It is called \texttt{unicode.map} and
 4160 should be used if no other codepoint map is available.  A tool is supplied with
 4161 Snort to generate custom Unicode \texttt{maps--ms\_unicode\_generator.c}, which
 4162 is available at \url{http://www.snort.org/dl/contrib/}.
 4163 
 4164 \begin{note}
 4165 
 4166 Remember that this configuration is for the global IIS Unicode map, individual
 4167 servers can reference their own IIS Unicode map.
 4168 
 4169 \end{note}
 4170 
 4171 \item \texttt{detect\_anomalous\_servers}
 4172 
 4173 This global configuration option enables generic HTTP server traffic inspection
 4174 on non-HTTP configured ports, and alerts if HTTP traffic is seen.  Don't turn
 4175 this on if you don't have a default server configuration that encompasses all
 4176 of the HTTP server ports that your users might access.  In the future, we want
 4177 to limit this to specific networks so it's more useful, but for right now, this
 4178 inspects all network traffic. This option is turned off by default.
 4179 
 4180 \item \texttt{proxy\_alert}
 4181 
 4182 This enables global alerting on HTTP server proxy usage.  By configuring HTTP
 4183 Inspect servers and enabling \texttt{allow\_proxy\_use}, you will only receive
 4184 proxy use alerts for web users that aren't using the configured proxies or are
 4185 using a rogue proxy server.
 4186 
 4187 Please note that if users aren't required to configure web proxy use, then you
 4188 may get a lot of proxy alerts.  So, please only use this feature with
 4189 traditional proxy environments. Blind firewall proxies don't count.
 4190 
 4191 \item \texttt{compress\_depth $<$integer$>$}
 4192 This option specifies the maximum amount of packet payload to decompress. This
 4193 value can be set from 1 to 65535. The default for this option is 1460.
 4194 
 4195 \begin{note}
 4196 
 4197 Please note, in case of multiple policies, the value specified in the default policy
 4198 is used and this value overwrites the values specified in the other policies. In case
 4199 of \texttt{unlimited\_decompress} this should be set to its max value. This value should 
 4200 be specified in the default policy even when the HTTP inspect preprocessor is turned off 
 4201 using the \texttt{disabled} keyword.
 4202 
 4203 \end{note}
 4204 
 4205 \item \texttt{decompress\_depth $<$integer$>$}
 4206 This option specifies the maximum amount of decompressed data to obtain from the
 4207 compressed packet payload. This value can be set from 1 to 65535. The default for
 4208 this option is 2920.
 4209 
 4210 \begin{note}
 4211 
 4212 Please note, in case of multiple policies, the value specified in the default policy
 4213 is used and this value overwrites the values specified in the other policies. In case
 4214 of \texttt{unlimited\_decompress} this should be set to its max value. This value should 
 4215 be specified in the default policy even when the HTTP inspect preprocessor is turned off 
 4216 using the \texttt{disabled} keyword.
 4217 
 4218 \end{note}
 4219 
 4220 \item \texttt{max\_gzip\_mem $<$integer$>$}
 4221 
 4222 This option determines (in bytes) the maximum amount of memory the HTTP Inspect preprocessor 
 4223 will use for decompression. The minimum allowed value for this option is 3276 bytes. This option
 4224 determines the number of concurrent sessions that can be decompressed at any given instant.
 4225 The default value for this option is 838860.
 4226 
 4227 This value is also used for the optional SWF/PDF file decompression.  If these modes are enabled
 4228 this same value sets the maximum about of memory used for file decompression session state
 4229 information.
 4230 
 4231 \begin{note}
 4232 
 4233 This value should be specified in the default policy even when the HTTP inspect preprocessor is 
 4234 turned off using the \texttt{disabled} keyword.
 4235 
 4236 \end{note}
 4237 
 4238 \item \texttt{memcap $<$integer$>$}
 4239 
 4240 This option determines (in bytes) the maximum amount of memory the HTTP Inspect preprocessor
 4241 will use for logging the URI and Hostname data. This value can be set from 2304 to 603979776 (576 MB).
 4242 This option along with the maximum uri and hostname logging size (which is defined in snort) will
 4243 determine the maximum HTTP sessions that will log the URI and hostname data at any given instant. The
 4244 maximum size for logging URI data is 2048 and for hostname is 256. The default value for this
 4245 option is 150994944 (144 MB).
 4246 
 4247 \begin {note}
 4248 
 4249 This value should be specified in the default policy even when the HTTP inspect preprocessor is turned off 
 4250 using the \texttt{disabled} keyword. In case of multiple policies, the value specified in the
 4251 default policy will overwrite the value specified in other policies.
 4252 
 4253 max http sessions logged = memcap /( max uri logging size + max hostname logging size )
 4254 max uri logging size defined in snort : 2048
 4255 max hostname logging size defined in snort : 256
 4256 
 4257 \end{note}
 4258 
 4259 \item \texttt{normalize\_random\_nulls\_in\_text}
 4260 
 4261 This option normalizes the text content with randomly encoded null bytes in 16LE,16BE,32LE and
 4262 32BE UTF encodings to UTF8 in the server response. It relies on file preprocessor to determine
 4263 if the content is text. Hence file preprocessor should be enabled and configured with prepackaged
 4264 file magics wihtout which this option is not effective.
 4265 
 4266 \begin {note}
 4267 This opton relies on file prepreprocessor to determine if content can safely be considered as text
 4268 before normalizing. However, it is possible that non text file types unknown to file preprocessor
 4269 may get normalized as this option treats file types unknown to file preprocessor as text. Such cases
 4270 may result in false positives or false negatives in detection. 
 4271 
 4272 \end{note}
 4273 
 4274 \item \texttt{fast\_blocking}
 4275 
 4276 This option enables inspecting http data before the data is flushed. This enables early IPS rule
 4277 evaluation so that the block rules will take into effect and the connection is blocked at the earliest
 4278 instead of blocking later after flushing the data. This config will be effective only when inline
 4279 normalisation is enabled.
 4280 
 4281 \item \texttt{disabled}
 4282 
 4283 This optional keyword is allowed with any policy to avoid packet processing.
 4284 This option disables the preprocessor. When the preprocessor is disabled
 4285 only the "memcap", "max\_gzip\_mem", "compress\_depth" and "decompress\_depth" 
 4286 options are applied when specified with the configuration. Other options are
 4287 parsed but not used. Any valid configuration may have "disabled" added to it.
 4288 
 4289 \end{slist}
 4290 \subsubsection{Example Global Configuration}
 4291 
 4292 \begin{verbatim}
 4293     preprocessor http_inspect: \
 4294         global iis_unicode_map unicode.map 1252
 4295 \end{verbatim}
 4296 
 4297 \subsubsection{Server Configuration}
 4298 
 4299 There are two types of server configurations: default and by IP address.
 4300 
 4301 \paragraph{Default}
 4302 
 4303 This configuration supplies the default server configuration for any server
 4304 that is not individually configured.  Most of your web servers will most likely
 4305 end up using the default configuration.
 4306 
 4307 \subsubsection{Example Default Configuration}
 4308 
 4309 \begin{verbatim}
 4310     preprocessor http_inspect_server: \
 4311         server default profile all ports { 80 }
 4312 \end{verbatim}
 4313 
 4314 \paragraph{Configuration by IP Address}
 4315 
 4316 This format is very similar to ``default'', the only difference being that
 4317 specific IPs can be configured.
 4318 
 4319 \subsubsection{Example IP Configuration}
 4320 
 4321 \begin{verbatim}
 4322     preprocessor http_inspect_server: \
 4323         server 10.1.1.1 profile all ports { 80 }
 4324 \end{verbatim}
 4325 
 4326 \paragraph{Configuration by Multiple IP Addresses}
 4327 
 4328 This format is very similar to ``Configuration by IP Address'', the only
 4329 difference being that multiple IPs can be specified via a space separated list.
 4330 There is a limit of 40 IP addresses or CIDR notations per
 4331 \texttt{http\_inspect\_server} line.
 4332 
 4333 \subsubsection{Example Multiple IP Configuration}
 4334 
 4335 \begin{verbatim}
 4336     preprocessor http_inspect_server: \
 4337         server { 10.1.1.1 10.2.2.0/24 } profile all ports { 80 }
 4338 \end{verbatim}
 4339 
 4340 \subsubsection{Server Configuration Options}
 4341 
 4342 Important: Some configuration options have an argument of `yes' or `no'.  This
 4343 argument specifies whether the user wants the configuration option to generate
 4344 an HTTP Inspect alert or not.  The `yes/no' argument does not specify whether
 4345 the configuration option itself is on or off, only the alerting functionality.
 4346 In other words, whether set to `yes' or 'no', HTTP normalization will still
 4347 occur, and rules based on HTTP traffic will still trigger.
 4348 
 4349 \begin{slist}
 4350 \item \texttt{profile $<$all$|$apache$|$iis$|$iis5\_0$|$iis4\_0$>$}
 4351 
 4352 Users can configure HTTP Inspect by using pre-defined HTTP server profiles.
 4353 Profiles allow the user to easily configure the preprocessor for a certain type
 4354 of server, but are not required for proper operation. 
 4355 
 4356 There are five profiles available: all, apache, iis, iis5\_0, and iis4\_0.
 4357 
 4358 \begin{subslist}
 4359 
 4360 \item \texttt{all}
 4361 
 4362 The \texttt{all} profile is meant to normalize the URI using most of the common
 4363 tricks available.  We alert on the more serious forms of evasions.  This is a
 4364 great profile for detecting all types of attacks, regardless of the HTTP
 4365 server.  \texttt{profile all} sets the configuration options described in Table
 4366 \ref{profile_all_options}.
 4367 
 4368 \begin{table}[h]
 4369 \begin{center}
 4370 \caption{Options for the ``all'' Profile}
 4371 \label{profile_all_options}
 4372 \begin{tabular}{| l | p{3in} |}
 4373 
 4374 \hline
 4375 \textbf{Option} & \textbf{Setting} \\
 4376 \hline
 4377 
 4378 \hline
 4379 server\_flow\_depth & 300 \\
 4380 \hline
 4381 client\_flow\_depth & 300 \\
 4382 \hline
 4383 post\_depth & 0 \\
 4384 \hline
 4385 chunk encoding & alert on chunks larger than 500000 bytes \\
 4386 \hline
 4387 iis\_unicode\_map & codepoint map in the global configuration \\
 4388 \hline
 4389 ASCII decoding & on, alert off \\
 4390 \hline
 4391 multiple slash & on, alert off \\
 4392 \hline
 4393 directory normalization & on, alert off \\
 4394 \hline
 4395 apache whitespace & on, alert off \\
 4396 \hline
 4397 double decoding & on, alert on \\
 4398 \hline
 4399 \%u decoding & on, alert on \\
 4400 \hline
 4401 bare byte decoding & on, alert on \\
 4402 \hline
 4403 iis unicode codepoints & on, alert on \\
 4404 \hline
 4405 iis backslash & on, alert off \\
 4406 \hline
 4407 iis delimiter & on, alert off \\
 4408 \hline
 4409 webroot & on, alert on\\
 4410 \hline
 4411 non\_strict URL parsing & on\\
 4412 \hline
 4413 tab\_uri\_delimiter & is set\\
 4414 \hline
 4415 max\_header\_length & 0, header length not checked\\
 4416 \hline
 4417 max\_spaces & 200 \\
 4418 \hline
 4419 max\_headers & 0, number of headers not checked\\
 4420 
 4421 \hline
 4422 \end{tabular}
 4423 \end{center}
 4424 \end{table}
 4425 
 4426 \item \texttt{apache} 
 4427 
 4428 The \texttt{apache} profile is used for Apache web servers.  This differs from
 4429 the \texttt{iis} profile by only accepting UTF-8 standard Unicode encoding and
 4430 not accepting backslashes as legitimate slashes, like IIS does.  Apache also
 4431 accepts tabs as whitespace.  \texttt{profile apache} sets the configuration
 4432 options described in Table \ref{profile_apache_options}.
 4433 
 4434 \begin{table}[h]
 4435 \begin{center}
 4436 \caption{Options for the \texttt{apache} Profile}
 4437 \label{profile_apache_options}
 4438 \begin{tabular}{| l | p{3in} |}
 4439 
 4440 \hline
 4441 \textbf{Option} & \textbf{Setting}\\
 4442 \hline
 4443 
 4444 \hline
 4445 server\_flow\_depth & 300 \\
 4446 \hline
 4447 client\_flow\_depth & 300 \\
 4448 \hline
 4449 post\_depth & 0 \\
 4450 \hline
 4451 chunk encoding & alert on chunks larger than 500000 bytes \\
 4452 \hline
 4453 ASCII decoding & on, alert off \\
 4454 \hline
 4455 multiple slash & on, alert off \\
 4456 \hline
 4457 directory normalization & on, alert off \\
 4458 \hline
 4459 webroot & on, alert on\\
 4460 \hline
 4461 apache whitespace & on, alert on \\
 4462 \hline
 4463 utf\_8 encoding & on, alert off \\
 4464 \hline
 4465 non\_strict url parsing & on \\
 4466 \hline
 4467 tab\_uri\_delimiter & is set\\
 4468 \hline
 4469 max\_header\_length & 0, header length not checked\\
 4470 \hline
 4471 max\_spaces & 200 \\
 4472 \hline
 4473 max\_headers & 0, number of headers not checked\\
 4474 \hline
 4475 
 4476 \hline
 4477 \end{tabular}
 4478 \end{center}
 4479 \end{table}
 4480 
 4481 \item \texttt{iis}
 4482 
 4483 The \texttt{iis} profile mimics IIS servers.  So that means we use IIS Unicode
 4484 codemaps for each server, \%u encoding, bare-byte encoding, double decoding,
 4485 backslashes, etc. \texttt{profile iis} sets the configuration options described
 4486 in Table \ref{profile_iis_options}.
 4487 
 4488 \begin{table}[h]
 4489 \begin{center}
 4490 \caption{Options for the \texttt{iis} Profile}
 4491 \label{profile_iis_options}
 4492 \begin{tabular}{| l | p{3in} |}
 4493 
 4494 \hline
 4495 \textbf{Option} & \textbf{Setting}\\
 4496 \hline
 4497 
 4498 \hline
 4499 server\_flow\_depth & 300 \\
 4500 \hline
 4501 client\_flow\_depth & 300 \\
 4502 \hline
 4503 post\_depth & -1 \\
 4504 \hline
 4505 chunk encoding & alert on chunks larger than 500000 bytes\\
 4506 \hline
 4507 iis\_unicode\_map & codepoint map in the global configuration \\
 4508 \hline
 4509 ASCII decoding & on, alert off \\
 4510 \hline
 4511 multiple slash & on, alert off \\
 4512 \hline
 4513 directory normalization & on, alert off \\
 4514 \hline
 4515 webroot & on, alert on\\
 4516 \hline
 4517 double decoding & on, alert on \\
 4518 \hline
 4519 \%u decoding & on, alert on \\
 4520 \hline
 4521 bare byte decoding & on, alert on \\
 4522 \hline
 4523 iis unicode codepoints & on, alert on \\
 4524 \hline
 4525 iis backslash & on, alert off \\
 4526 \hline
 4527 iis delimiter & on, alert on \\
 4528 \hline
 4529 apache whitespace & on, alert on \\
 4530 \hline
 4531 non\_strict URL parsing & on\\
 4532 \hline
 4533 max\_header\_length & 0, header length not checked\\
 4534 \hline
 4535 max\_spaces & 200 \\
 4536 \hline
 4537 max\_headers & 0, number of headers not checked\\
 4538 
 4539 \hline
 4540 \end{tabular}
 4541 \end{center}
 4542 \end{table}
 4543 
 4544 \item \texttt{iis4\_0, iis5\_0}
 4545 
 4546 In IIS 4.0 and IIS 5.0, there was a double decoding vulnerability.  These two
 4547 profiles are identical to \texttt{iis}, except they will alert by default if a
 4548 URL has a double encoding.  Double decode is not supported in IIS 5.1 and
 4549 beyond, so it's disabled by default.
 4550 
 4551 \item \texttt{default, no profile}
 4552 
 4553 The default options used by HTTP Inspect do not use a profile and are described
 4554 in Table \ref{default_HTTP_Inspect_options}.
 4555 
 4556 \begin{table}[h]
 4557 \begin{center}
 4558 \caption{Default HTTP Inspect Options}
 4559 \label{default_HTTP_Inspect_options}
 4560 \begin{tabular}{| l | p{3in} |}
 4561 
 4562 \hline
 4563 \textbf{Option} & \textbf{Setting}\\
 4564 \hline
 4565 
 4566 \hline
 4567 port & 80\\
 4568 \hline
 4569 server\_flow\_depth & 300 \\
 4570 \hline
 4571 client\_flow\_depth & 300 \\
 4572 \hline
 4573 post\_depth & -1 \\
 4574 \hline
 4575 chunk encoding & alert on chunks larger than 500000 bytes\\
 4576 \hline
 4577 ASCII decoding & on, alert off \\
 4578 \hline
 4579 utf\_8 encoding & on, alert off\\
 4580 \hline
 4581 multiple slash & on, alert off \\
 4582 \hline
 4583 directory normalization & on, alert off \\
 4584 \hline
 4585 webroot & on, alert on\\
 4586 \hline
 4587 iis backslash & on, alert off \\
 4588 \hline
 4589 apache whitespace & on, alert off \\
 4590 \hline
 4591 iis delimiter & on, alert off \\
 4592 \hline
 4593 non\_strict URL parsing & on\\
 4594 \hline
 4595 max\_header\_length & 0, header length not checked\\
 4596 \hline
 4597 max\_spaces & 200 \\
 4598 \hline
 4599 max\_headers & 0, number of headers not checked\\
 4600 \hline
 4601 \end{tabular}
 4602 \end{center}
 4603 \end{table}
 4604 
 4605 Profiles must be specified as the first server option and cannot be combined
 4606 with any other options except:
 4607 
 4608 \begin{itemize}
 4609 \item \texttt{ports}
 4610 \item \texttt{iis\_unicode\_map}
 4611 \item \texttt{allow\_proxy\_use}
 4612 \item \texttt{server\_flow\_depth}
 4613 \item \texttt{client\_flow\_depth}
 4614 \item \texttt{post\_depth}
 4615 \item \texttt{no\_alerts}
 4616 \item \texttt{inspect\_uri\_only}
 4617 \item \texttt{oversize\_dir\_length} 
 4618 \item \texttt{normalize\_headers} 
 4619 \item \texttt{normalize\_cookies} 
 4620 \item \texttt{normalize\_utf}
 4621 \item \texttt{max\_header\_length} 
 4622 \item \texttt{max\_spaces} 
 4623 \item \texttt{max\_headers} 
 4624 \item \texttt{extended\_response\_inspection}
 4625 \item \texttt{enable\_cookie}
 4626 \item \texttt{inspect\_gzip}
 4627 \item \texttt{unlimited\_decompress}
 4628 \item \texttt{normalize\_javascript}
 4629 \item \texttt{max\_javascript\_whitespaces}
 4630 \item \texttt{enable\_xff}
 4631 \item \texttt{http\_methods}
 4632 \item \texttt{log\_uri}
 4633 \item \texttt{log\_hostname}
 4634 \item \texttt{small\_chunk\_length}
 4635 \item \texttt{decompress\_swf}
 4636 \item \texttt{decompress\_pdf}
 4637 \item \texttt{legacy\_mode}
 4638 \end{itemize}
 4639 
 4640 These options must be specified after the \texttt{profile} option.
 4641 
 4642 \end{subslist}
 4643 
 4644 \subsubsection{Example}
 4645 
 4646 \begin{verbatim}
 4647     preprocessor http_inspect_server: \
 4648         server 1.1.1.1 profile all ports { 80 3128 }
 4649 \end{verbatim}
 4650                              
 4651 \item \texttt{ports $\{ <$port$> [<$port$> <...>] \}$}
 4652 
 4653 This is how the user configures which ports to decode on the HTTP server.
 4654 However, HTTPS traffic is encrypted and cannot be decoded with HTTP Inspect.
 4655 To ignore HTTPS traffic, use the SSL preprocessor.
 4656 
 4657 \item \texttt{iis\_unicode\_map $<$map\_filename$>$ codemap $<$integer$>$}
 4658 
 4659 The IIS Unicode map is generated by the program ms\_unicode\_generator.c.  This
 4660 program is located on the Snort.org web site at
 4661 \url{http://www.snort.org/dl/contrib/} directory.  Executing this program
 4662 generates a Unicode map for the system that it was run on.  So, to get the
 4663 specific Unicode mappings for an IIS web server, you run this program on that
 4664 server and use that Unicode map in this configuration.
 4665 
 4666 When using this option, the user needs to specify the file that contains the
 4667 IIS Unicode map and also specify the Unicode map to use.  For US servers, this
 4668 is usually 1252.  But the ms\_unicode\_generator program tells you which
 4669 codemap to use for you server; it's the ANSI code page.  You can select the
 4670 correct code page by looking at the available code pages that the
 4671 ms\_unicode\_generator outputs.
 4672 
 4673 \item \texttt{extended\_response\_inspection}
 4674 
 4675 This enables the extended HTTP response inspection. The default http response
 4676 inspection does not inspect the various fields of a HTTP response. By turning
 4677 this option the HTTP response will be thoroughly inspected. The different fields
 4678 of a HTTP response such as status code, status message, headers, cookie (when
 4679 enable\_cookie is configured) and body are extracted and saved into buffers.
 4680 Different rule options are provided to inspect these buffers.
 4681 
 4682 This option must be enabled to make use of the decompress\_swf or decompress\_pdf
 4683 options.
 4684 
 4685 \begin{note}
 4686 
 4687 When this option is turned on, if the HTTP response packet has a body then any
 4688 content pattern matches ( without http modifiers ) will search the response body
 4689 ((decompressed in case of gzip) and not the entire packet payload. To search for 
 4690 patterns in the header of the response, one should use the http modifiers with 
 4691 content such as \texttt{http\_header}, \texttt{http\_stat\_code}, \texttt{http\_stat\_msg} 
 4692 and \texttt{http\_cookie}.
 4693 
 4694 \end{note}
 4695 
 4696 \item \texttt{enable\_cookie}
 4697 
 4698 This options turns on the cookie extraction from HTTP requests and HTTP response.
 4699 By default the cookie inspection and extraction will be turned off. The cookie from 
 4700 the \texttt{Cookie} header line is extracted and stored in HTTP Cookie buffer for 
 4701 HTTP requests and cookie from the \texttt{Set-Cookie} is extracted and stored in 
 4702 HTTP Cookie buffer for HTTP responses. The \texttt{Cookie:} and \texttt{Set-Cookie:} 
 4703 header names itself along with leading spaces and the CRLF terminating the header 
 4704 line are stored in the HTTP header buffer and are not stored in the HTTP cookie buffer.
 4705 
 4706 \begin{verbatim}
 4707 Ex: Set-Cookie: mycookie \r\n
 4708 
 4709 In this case, Set-Cookie: \r\n will be in the HTTP header buffer and the pattern
 4710 mycookie will be in the HTTP cookie buffer.
 4711 
 4712 \end{verbatim}
 4713 
 4714 \item \texttt{inspect\_gzip}
 4715 
 4716 This option specifies the HTTP inspect module to uncompress the compressed
 4717 data(gzip/deflate) in HTTP response. You should select the config option
 4718 "extended\_response\_inspection" before configuring this option.  Decompression 
 4719 is done across packets. So the decompression will end when either the 
 4720 'compress\_depth' or 'decompress\_depth' is reached or when the compressed data ends.
 4721 When the compressed data is spanned across multiple packets, the state of the last 
 4722 decompressed packet is used to decompressed the data of the next packet. 
 4723 But the decompressed data are individually inspected. (i.e. the 
 4724 decompressed data from different packets are not combined while inspecting). 
 4725 Also the amount of decompressed data that will be inspected depends on the 
 4726 'server\_flow\_depth' configured.
 4727 
 4728 Http Inspect generates a preprocessor alert with gid 120 and sid 6 when the decompression
 4729 fails. When the decompression fails due to a CRC error encountered by zlib, HTTP Inspect
 4730 will also provide the detection module with the data that was decompressed by zlib.
 4731 
 4732 \item \texttt{unlimited\_decompress}
 4733 
 4734 This option enables the user to decompress unlimited gzip data (across multiple 
 4735 packets).Decompression will stop when the compressed data ends or when a out of 
 4736 sequence packet is received. To ensure unlimited decompression, user should set 
 4737 the 'compress\_depth' and 'decompress\_depth' to its maximum values in the default 
 4738 policy. The decompression in a single packet is still limited by the 'compress\_depth' 
 4739 and 'decompress\_depth'.
 4740 
 4741 \item \texttt{decompress\_swf $\{ mode [mode] \}$ } 
 4742 
 4743 This option will enable decompression of compressed SWF (Adobe Flash content) files
 4744 encountered as the HTTP Response body in a GET transaction.  The available decompression
 4745 modes are 'deflate' and 'lzma'.  A prerequisite is enabling
 4746 extended\_response\_inspection (described above).  When enabled, the preprocessor will
 4747 examine the response body for the corresponding file signature.  'CWS' for Deflate/ZLIB
 4748 compressed and 'ZWS' for LZMA compressed.  Each decompression mode can be individually enabled.
 4749 e.g. ... { lzma } or { deflate } or { lzma deflate }.  The compressed content is decompressed
 4750 'in-place' with the content made available to the detection/rules 'file\_data' option.
 4751 If enabled and located, the compressed SWF file signature is converted to 'FWS' to indicate
 4752 an uncompressed file.
 4753 
 4754 The 'decompress\_depth', 'compress\_depth', and 'unlimited\_decompress' are optionally used to 
 4755 place limits on the decompression process.  The semantics for SWF files are similar to the
 4756 gzip decompression process.
 4757 
 4758 During the decompression process, the preprocessor may generate alert 120:12 if Deflate
 4759 decompression fails or alert 120:13 if LZMA decompression fails.
 4760 
 4761 \begin{note}
 4762 LZMA decompression is only available if Snort is built with the liblzma package present
 4763 and functional.  If the LZMA package is not present, then the { lzma } option will indicate
 4764 a fatal parsing error.  If the liblzma package IS present, but one desires to disable LZMA
 4765 support, then the --disable-lzma option on configure will disable usage of the library.
 4766 \end{note}
 4767 
 4768 \item \texttt{decompress\_pdf $\{ mode [mode] \}$ } 
 4769 
 4770 This option will enable decompression of the compressed portions of PDF files encountered
 4771 as the HTTP Response body in a GET transaction.  A prerequisite is enabling
 4772 extended\_response\_inspection (described above).
 4773 
 4774 When enabled, the preprocessor will examine the response body for the '%PDF-' file signature.
 4775 PDF files are then parsed, locating PDF 'streams' with a single '/FlateDecode' filter.  These
 4776 streams are decompressed in-place, replacing the compressed content.
 4777 
 4778 The 'decompress\_depth', 'compress\_depth', and 'unlimited\_decompress' are optionally used to 
 4779 place limits on the decompression process.  The semantics for PDF files are similar to the
 4780 gzip decompression process.
 4781 
 4782 During the file parsing/decompression process, the preprocessor may generate several alerts:
 4783 
 4784 \begin{center}
 4785 \begin{tabular}{| l | p{4.5in} |}
 4786 
 4787 \hline
 4788 \textbf{Alert} & \textbf{Description}\\
 4789 \hline 
 4790 
 4791 \hline 
 4792 120:14 & Deflate decompression failure \\
 4793 
 4794 \hline 
 4795 120:15 & Located a 'stream' with an unsupported compression ('/Filter') algorithm \\
 4796 
 4797 \hline 
 4798 120:16 & Located a 'stream' with unsupported cascaded '/FlateDecode' options, e.g.: \begin{verbatim}/Filter [ /FlateDecode /FlateDecode ]\end{verbatim} \\
 4799 
 4800 \hline 
 4801 120:17 & PDF File parsing error \\
 4802 
 4803 \hline
 4804 \end{tabular}
 4805 \end{center}
 4806 
 4807 \item \texttt{normalize\_javascript}
 4808 This option enables the normalization of Javascript within the HTTP response body.
 4809 You should select the config option \texttt{extended\_response\_inspection} before configuring 
 4810 this option. When this option is turned on, Http Inspect searches for a Javascript within the 
 4811 HTTP response body by searching for the $<$script$>$ tags and starts normalizing it. 
 4812 When Http Inspect sees the $<$script$>$ tag without a type, it is considered as a javascript.
 4813 The obfuscated data within the javascript functions such as unescape, String.fromCharCode, decodeURI, 
 4814 decodeURIComponent will be normalized. The different encodings handled within the unescape/
 4815 decodeURI/decodeURIComponent are \texttt{\%XX}, \texttt{\%uXXXX}, \texttt{\\XX} and \texttt{\\uXXXXi}. 
 4816 Apart from these encodings, Http Inspect will also detect the consecutive whitespaces and normalize 
 4817 it to a single space. Http Inspect will also normalize the plus and concatenate the strings. 
 4818 The rule option \texttt{file\_data} can be used to access this normalized buffer from the rule.
 4819 A preprocessor alert with SID 9 and GID 120 is generated when the obfuscation levels within the 
 4820 Http Inspect is equal to or greater than 2.
 4821 
 4822 \begin{verbatim}
 4823 
 4824 Example:
 4825 
 4826 HTTP/1.1 200 OK\r\n
 4827 Date: Wed, 29 Jul 2009 13:35:26 GMT\r\n
 4828 Server: Apache/2.2.3 (Debian) PHP/5.2.0-8+etch10 mod_ssl/2.2.3 OpenSSL/0.9.8c\r\n
 4829 Last-Modified: Sun, 20 Jan 2008 12:01:21 GMT\r\n
 4830 Accept-Ranges: bytes\r\n
 4831 Content-Length: 214\r\n
 4832 Keep-Alive: timeout=15, max=99\r\n
 4833 Connection: Keep-Alive\r\n
 4834 Content-Type: application/octet-stream\r\n\r\n 
 4835 <html xmlns="http://www.w3.org/1999/xhtml">
 4836 <head>
 4837 <title>FIXME</title>
 4838 </head>
 4839 <body>
 4840 <script>document.write(unescape(unescape("%48%65%6C%6C%6F%2C%20%73%6E%6F%72%74%20%74%65%61%6D%21")));
 4841 </script>
 4842 </body>
 4843 </html>
 4844 
 4845 \end{verbatim}
 4846 
 4847 The above javascript will generate the preprocessor alert with SID 9 and GIDF 120 when \texttt{normalize\_javascript}
 4848 is turned on.
 4849 
 4850 Http Inspect will also generate a preprocessor alert with GID 120 and SID 11 when there are more than one type 
 4851 of encodings within the escaped/encoded data.
 4852 
 4853 \begin{verbatim}
 4854 
 4855 For example:
 4856 
 4857 unescape("%48\x65%6C%6C%6F%2C%20%73%6E%6F%72%74%20%74%65%61%6D%21");
 4858 String.fromCharCode(0x48, 0x65, 0x6c, 0x6c, 111, 44, 32, 115, 110, 111, 114, 116, 32, 116, 101, 97, 109, 33)
 4859 
 4860 \\end{verbatim}
 4861 
 4862 The above obfuscation will generate the preprocessor alert with GID 120 and SID 11.
 4863 
 4864 This option is turned off by default in HTTP Inspect.
 4865 
 4866 \item \texttt{max\_javascript\_whitespaces $<$positive integer up to 65535$>$}
 4867 This option takes an integer as an argument.  The integer determines the maximum number
 4868 of consecutive whitespaces allowed within the Javascript obfuscated data in a HTTP
 4869 response body. The config option \texttt{normalize\_javascript} should be turned on before configuring
 4870  this config option. When the whitespaces in the javascript obfuscated data is equal to or more
 4871 than this value a preprocessor alert with GID 120 and SID 10 is generated. The default value for 
 4872 this option is 200.  To enable, specify an integer argument to \texttt{max\_javascript\_spaces} of 1 to 65535.
 4873 Specifying a value of 0 is treated as disabling the alert.
 4874 
 4875 \item \texttt{enable\_xff}
 4876 
 4877 This option enables Snort to parse and log the original client IP present in the
 4878 X-Forwarded-For or True-Client-IP HTTP request headers along with the generated
 4879 events. The XFF/True-Client-IP Original client IP address is logged only with
 4880 unified2 output and is not logged with console (-A cmg) output.
 4881 
 4882 \item \texttt{xff\_headers}
 4883 
 4884 If/When the \texttt{enable\_xff} option is present, the \texttt{xff\_headers} option specifies a set of custom 'xff'
 4885 headers.  This option allows the definition of up to six custom headers in addition to the
 4886 two default (and always present) X-Forwarded-For and True-Client-IP headers.  The option
 4887 permits both the custom and default headers to be prioritized.  The headers/priority pairs
 4888 are specified as a list.  Lower numerical values imply a higher priority.  The headers do
 4889 not need to be specified in priority order.  Nor do the priorities need to be contiguous.
 4890 Priority values can range from 1 to 255.  The priority values and header names must be unique.
 4891 The header names must not collide with known http headers such as 'host', 'cookie',
 4892 'content-length', etc.
 4893 
 4894 A example of the \texttt{xff\_header} syntax is:
 4895 \begin{verbatim}
 4896 xff_headers { [ x-forwarded-highest-priority 1 ] [ x-forwarded-second-highest-priority 2 ] \
 4897               [ x-forwarded-lowest-priority-custom 3 ] }
 4898 \end{verbatim}
 4899 
 4900 The default X-Forwarded-For and True-Client-IP headers are always present.  They may be explicitly
 4901 specified in the \texttt{xff\_headers} config in order to determine their priority.  If not specified, they
 4902 will be automatically added to the xff list as the lowest priority headers.
 4903 
 4904 For example, let us say that we have the following (abbreviated) HTTP request header:
 4905 
 4906 \begin{verbatim}
 4907 ...
 4908 Host: www.snort.org
 4909 X-Forwarded-For: 192.168.1.1
 4910 X-Was-Originally-Forwarded-From: 10.1.1.1
 4911 ...
 4912 \end{verbatim}
 4913  
 4914 With the default xff behavior (no \texttt{xff\_headers}), the 'X-Forwarded-For' header would be used to
 4915 provide a 192.168.1.1 Original Client IP address in the unified2 log.  Custom headers are not
 4916 parsed.
 4917 
 4918 With:
 4919 \begin{verbatim}
 4920 xff_headers { [ x-was-originally-forwarded-from 1 ] [ x-another-forwarding-header 2 ] \
 4921               [ x-forwarded-for 3 ] }
 4922 \end{verbatim}
 4923 
 4924 The X-Was-Originally-Forwarded-From header is the highest priority present and its value
 4925 of 10.1.1.1 will be logged as the Original Client IP in the unified2 log.
 4926 
 4927 But with:
 4928 \begin{verbatim}
 4929 xff_headers { [ x-was-originally-forwarded-from 3 ] [ x-another-forwarding-header 2 ] \
 4930               [ x-forwarded-for 1 ] }
 4931 \end{verbatim}
 4932 
 4933 Now the X-Forwarded-For header is the highest priority and its value of 192.168.1.1 is logged.
 4934 
 4935 
 4936 \begin{note}
 4937 
 4938 The original client IP from XFF/True-Client-IP in unified2 logs can be viewed using 
 4939 the tool u2spewfoo. This tool is present in the tools/u2spewfoo directory of snort 
 4940 source tree.
 4941 
 4942 \end{note}
 4943 
 4944 \item \texttt{server\_flow\_depth $<$integer$>$}
 4945 
 4946 This specifies the amount of server response payload to inspect. When
 4947 \texttt{extended\_response\_inspection} is turned on, it is applied to the HTTP response 
 4948 body (decompressed data when \texttt{inspect\_gzip} is turned on) and not the HTTP headers.
 4949 When \texttt{extended\_response\_inspection} is turned off the \texttt{server\_flow\_depth} 
 4950 is applied to the entire HTTP response (including headers). Unlike \texttt{client\_flow\_depth} 
 4951 this option is applied per TCP session. This option can be used to balance the needs of 
 4952 IDS performance and level of inspection of HTTP server response data.  Snort rules are       
 4953 targeted at HTTP server response traffic and when used with a small flow\_depth value 
 4954 may cause false negatives. Most of these rules target either the HTTP header, or 
 4955 the content that is likely to be in the first hundred or so bytes of non-header data.  
 4956 Headers are usually under 300 bytes long, but your mileage may vary. 
 4957 It is suggested to set the \texttt{server\_flow\_depth} to its maximum value.
 4958 
 4959 This value can be set from -1 to 65535. A value of -1 causes Snort
 4960 to ignore all server side traffic for ports defined in \texttt{ports} when
 4961 \texttt{extended\_response\_inspection} is turned off. When the \texttt{extended\_response\_inspection}
 4962  is turned on, value of -1 causes Snort to ignore the HTTP response body data and
 4963  not the HTTP headers.  Inversely, a value of 0 causes Snort to inspect all HTTP server
 4964 payloads defined in "ports" (note that this will likely slow down IDS
 4965 performance).  Values above 0 tell Snort the number of bytes to
 4966 inspect of the server response (excluding the HTTP headers when \texttt{extended\_response\_inspection}
 4967 is turned on) in a given HTTP session.  Only packets payloads starting with 'HTTP' will
 4968 be considered as the first packet of a server response.  If less than flow\_depth bytes
 4969 are in the payload of the HTTP response packets in a given session, the entire payload will be
 4970 inspected.  If more than flow\_depth bytes are in the payload of the HTTP response packet in a session
 4971 only flow\_depth bytes of the payload will be inspected for that session.  Rules that are meant to
 4972 inspect data in the payload of the HTTP response packets in a session beyond 65535 bytes will be
 4973 ineffective unless flow\_depth is set to 0. The default value for \texttt{server\_flow\_depth} is 300.
 4974 Note that the 65535 byte maximum flow\_depth applies to stream reassembled packets as well. 
 4975 It is suggested to set the \texttt{server\_flow\_depth} to its maximum value.
 4976 
 4977 \begin{note}
 4978 
 4979 \texttt{server\_flow\_depth} is the same as the old \texttt{flow\_depth}
 4980 option, which will be deprecated in a future release.
 4981 
 4982 \end{note}
 4983 
 4984 \item \texttt{client\_flow\_depth $<$integer$>$}
 4985 
 4986 This specifies the amount of raw client request payload to inspect. This
 4987 value can be set from -1 to 1460. Unlike \texttt{server\_flow\_depth} this value is applied
 4988 to the first packet of the HTTP request. It is not a session based flow depth.
 4989 It has a default value of 300.  It primarily eliminates Snort from inspecting
 4990 larger HTTP Cookies that appear at the end of many client request Headers.
 4991 
 4992 A value of -1 causes Snort to ignore all client side traffic for ports
 4993 defined in "ports." Inversely, a value of 0 causes Snort to inspect all HTTP client
 4994  side traffic defined in "ports" (note that this will likely slow down IDS
 4995 performance).  Values above 0 tell Snort the number of bytes to
 4996 inspect in the first packet of the client request.  If less than flow\_depth bytes
 4997 are in the TCP payload (HTTP request) of the first packet, the entire payload will be inspected.
 4998 If more than flow\_depth bytes are in the payload of the first packet only flow\_depth
 4999 bytes of the payload will be inspected.  Rules that are meant to
 5000 inspect data in the payload of the first packet of a client request beyond 1460 bytes 
 5001 will be ineffective unless flow\_depth is set to 0. Note that the 1460 byte 
 5002 maximum flow\_depth applies to stream reassembled packets as well. It is 
 5003 suggested to set the \texttt{client\_flow\_depth} to its maximum value.
 5004 
 5005 \item \texttt{post\_depth $<$integer$>$}
 5006 
 5007 This specifies the amount of data to inspect in a client post message. The
 5008 value can be set from -1 to 65495. The default value is -1. A value of -1 
 5009 causes Snort to ignore all the data in the post message. Inversely, a value 
 5010 of 0 causes Snort to inspect all the client post message. This increases    
 5011 the performance by inspecting only specified bytes in the post message.
 5012 
 5013 \item \texttt{ascii $<$yes$|$no$>$}
 5014 
 5015 The \texttt{ascii} decode option tells us whether to decode encoded ASCII
 5016 chars, a.k.a \%2f = /, \%2e = ., etc.  It is normal to see ASCII encoding usage
 5017 in URLs, so it is recommended that you disable HTTP Inspect alerting for this
 5018 option.
 5019 
 5020 \item \texttt{extended\_ascii\_uri}
 5021 
 5022 This option enables the support for extended ASCII codes in the HTTP request
 5023 URI. This option is turned off by default and is not supported with any of
 5024 the profiles.
 5025 
 5026 \item \texttt{utf\_8 $<$yes$|$no$>$}
 5027 
 5028 The \texttt{utf-8} decode option tells HTTP Inspect to decode standard UTF-8
 5029 Unicode sequences that are in the URI.  This abides by the Unicode standard and
 5030 only uses \% encoding.  Apache uses this standard, so for any Apache servers,
 5031 make sure you have this option turned on.  As for alerting, you may be
 5032 interested in knowing when you have a UTF-8 encoded URI, but this will be prone
 5033 to false positives as legitimate web clients use this type of encoding.  When
 5034 \texttt{utf\_8} is enabled, ASCII decoding is also enabled to enforce correct
 5035 functioning.  
 5036 
 5037 \item \texttt{u\_encode $<$yes$|$no$>$}
 5038 
 5039 This option emulates the IIS \%u encoding scheme.  How the \%u encoding scheme
 5040 works is as follows:  the encoding scheme is started by a \%u followed by 4
 5041 characters, like \%uxxxx.  The xxxx is a hex-encoded value that correlates to
 5042 an IIS Unicode codepoint.  This value can most definitely be ASCII.  An ASCII
 5043 character is encoded like \%u002f = /, \%u002e = ., etc.  If no
 5044 iis\_unicode\_map is specified before or after this option, the default codemap
 5045 is used.
 5046 
 5047 You should alert on \%u encodings, because we are not aware of any legitimate
 5048 clients that use this encoding.  So it is most likely someone trying to be
 5049 covert.
 5050 
 5051 \item \texttt{bare\_byte $<$yes$|$no$>$}
 5052 
 5053 Bare byte encoding is an IIS trick that uses non-ASCII characters as valid
 5054 values when decoding UTF-8 values.  This is not in the HTTP standard, as all
 5055 non-ASCII values have to be encoded with a \%.  Bare byte encoding allows the
 5056 user to emulate an IIS server and interpret non-standard encodings correctly.
 5057 
 5058 The alert on this decoding should be enabled, because there are no legitimate
 5059 clients that encode UTF-8 this way since it is non-standard.
 5060 
 5061 \item \texttt{iis\_unicode $<$yes$|$no$>$}
 5062 
 5063 The \texttt{iis\_unicode} option turns on the Unicode codepoint mapping.  If
 5064 there is no iis\_unicode\_map option specified with the server config,
 5065 \texttt{iis\_unicode} uses the default codemap.  The \texttt{iis\_unicode}
 5066 option handles the mapping of non-ASCII codepoints that the IIS server accepts
 5067 and decodes normal UTF-8 requests.
 5068 
 5069 You should alert on the \texttt{iis\_unicode option}, because it is seen mainly
 5070 in attacks and evasion attempts.  When \texttt{iis\_unicode} is enabled, ASCII
 5071 and UTF-8 decoding are also enabled to enforce correct decoding.  To alert on
 5072 UTF-8 decoding, you must enable also enable \texttt{utf\_8 yes}. 
 5073 
 5074 \item \texttt{double\_decode $<$yes$|$no$>$}
 5075 
 5076 The \texttt{double\_decode} option is once again IIS-specific and emulates IIS
 5077 functionality.  How this works is that IIS does two passes through the request
 5078 URI, doing decodes in each one.  In the first pass, it seems that all types of
 5079 iis encoding is done: utf-8 unicode, ASCII, bare byte, and \%u.  In the second
 5080 pass, the following encodings are done:  ASCII, bare byte, and \%u.  We leave
 5081 out utf-8 because I think how this works is that the \% encoded utf-8 is
 5082 decoded to the Unicode byte in the first pass, and then UTF-8 is decoded in the
 5083 second stage.  Anyway, this is really complex and adds tons of different
 5084 encodings for one character.  When \texttt{double\_decode} is enabled, so ASCII
 5085 is also enabled to enforce correct decoding.
 5086 
 5087 \item \texttt{non\_rfc\_char $\{ <$byte$> [<$byte ...$>] \}$}
 5088 
 5089 This option lets users receive an alert if certain non-RFC chars are used in a
 5090 request URI.  For instance, a user may not want to see null bytes in the
 5091 request URI and we can alert on that.  Please use this option with care,
 5092 because you could configure it to say, alert on all `/' or something like that.
 5093 It's flexible, so be careful.
 5094 
 5095 \item \texttt{multi\_slash $<$yes$|$no$>$}
 5096 
 5097 This option normalizes multiple slashes in a row, so something like:
 5098 ``foo/////////bar'' get normalized to ``foo/bar.''
 5099 
 5100 If you want an alert when multiple slashes are seen, then configure with a
 5101 \texttt{yes}; otherwise, use \texttt{no}.
 5102 
 5103 \item \texttt{iis\_backslash $<$yes$|$no$>$}
 5104 
 5105 Normalizes backslashes to slashes.  This is again an IIS emulation.  So a
 5106 request URI of ``/foo$\backslash$bar'' gets normalized to ``/foo/bar.''
 5107 
 5108 \item \texttt{directory $<$yes$|$no$>$}
 5109 
 5110 This option normalizes directory traversals and self-referential directories.
 5111 
 5112 The directory:
 5113 
 5114 \begin{verbatim}
 5115     /foo/fake\_dir/../bar
 5116 \end{verbatim}
 5117 
 5118 gets normalized to:
 5119 
 5120 \begin{verbatim}
 5121     /foo/bar
 5122 \end{verbatim}
 5123 
 5124 The directory:
 5125 
 5126 \begin{verbatim}
 5127     /foo/./bar
 5128 \end{verbatim}
 5129 
 5130 gets normalized to:
 5131 
 5132 \begin{verbatim}
 5133     /foo/bar
 5134 \end{verbatim}
 5135 
 5136 If you want to configure an alert, specify \texttt{yes}, otherwise, specify
 5137 \texttt{no}.  This alert may give false positives, since some web sites refer
 5138 to files using directory traversals.
 5139 
 5140 \item \texttt{apache\_whitespace $<$yes$|$no$>$}
 5141 
 5142 This option deals with the non-RFC standard of using tab for a space delimiter.
 5143 Apache uses this, so if the emulated web server is Apache, enable this option.
 5144 Alerts on this option may be interesting, but may also be false positive prone.
 5145 
 5146 \item \texttt{iis\_delimiter $<$yes$|$no$>$}
 5147 
 5148 This started out being IIS-specific, but Apache takes this non-standard
 5149 delimiter was well.  Since this is common, we always take this as standard
 5150 since the most popular web servers accept it.  But you can still get an alert
 5151 on this option.
 5152 
 5153 \item \texttt{chunk\_length $<$non-zero positive integer$>$}
 5154 
 5155 This option is an anomaly detector for abnormally large chunk sizes.  This
 5156 picks up the Apache chunk encoding exploits, and may also alert on HTTP
 5157 tunneling that uses chunk encoding.
 5158 
 5159 \item \texttt{small\_chunk\_length \{ $<$chunk size$>$ $<$consecutive chunks$>$ \} }
 5160 
 5161 This option is an evasion detector for consecutive small chunk sizes when
 5162 either the client or server use \texttt{Transfer-Encoding: chunked}.
 5163 $<$chunk size$>$ specifies the maximum chunk size for which a chunk will be
 5164 considered small.  $<$consecutive chunks$>$ specifies the number of consecutive
 5165 small chunks $<$= $<$chunk size$>$ before an event will be generated.  This option
 5166 is turned off by default.  Maximum values for each are 255 and a $<$chunk size$>$ of 0
 5167 disables.  Events generated are gid:119, sid:26 for client small
 5168 chunks and gid:120, sid:7 for server small chunks.
 5169 
 5170 Example:
 5171 \begin{verbatim}
 5172 small_chunk_length { 10 5 }
 5173 \end{verbatim}
 5174 Meaning alert if we see 5 consecutive chunk sizes of 10 or less.
 5175 
 5176 \item \texttt{no\_pipeline\_req}
 5177 
 5178 This option turns HTTP pipeline decoding off, and is a performance enhancement
 5179 if needed.  By default, pipeline requests are inspected for attacks, but when
 5180 this option is enabled, pipeline requests are not decoded and analyzed per HTTP
 5181 protocol field.  It is only inspected with the generic pattern matching.
 5182 
 5183 \item \texttt{non\_strict}
 5184 
 5185 This option turns on non-strict URI parsing for the broken way in which Apache
 5186 servers will decode a URI.  Only use this option on servers that will accept
 5187 URIs like this: "get /index.html alsjdfk alsj lj aj  la jsj s$\backslash$n".
 5188 The non\_strict option assumes the URI is between the first and second space
 5189 even if there is no valid HTTP identifier after the second space.
 5190 
 5191 \item \texttt{allow\_proxy\_use}
 5192 
 5193 By specifying this keyword, the user is allowing proxy use on this server.
 5194 This means that no alert will be generated if the \texttt{proxy\_alert} global
 5195 keyword has been used.  If the proxy\_alert keyword is not enabled, then this
 5196 option does nothing.  The \texttt{allow\_proxy\_use} keyword is just a way to
 5197 suppress unauthorized proxy use for an authorized server.  
 5198 
 5199 \item \texttt{no\_alerts}
 5200 
 5201 This option turns off all alerts that are generated by the HTTP Inspect
 5202 preprocessor module.  This has no effect on HTTP rules in the rule set.  No
 5203 argument is specified.
 5204 
 5205 \item \texttt{oversize\_dir\_length $<$non-zero positive integer$>$}
 5206 
 5207 This option takes a non-zero positive integer as an argument.  The argument
 5208 specifies the max char directory length for URL directory.  If a url directory
 5209 is larger than this argument size, an alert is generated. A good argument value
 5210 is 300 characters.  This should limit the alerts to IDS evasion type attacks,
 5211 like whisker -i 4.
 5212 
 5213 \item \texttt{inspect\_uri\_only}
 5214 
 5215 This is a performance optimization.  When enabled, only the URI portion of HTTP
 5216 requests will be inspected for attacks.  As this field usually contains 90-95\%
 5217 of the web attacks, you'll catch most of the attacks.  So if you need extra
 5218 performance, enable this optimization.  It's important to note that if this
 5219 option is used without any \texttt{uricontent} rules, then no inspection will
 5220 take place.  This is obvious since the URI is only inspected with
 5221 \texttt{uricontent} rules, and if there are none available, then there is
 5222 nothing to inspect.
 5223 
 5224 For example, if we have the following rule set:
 5225 
 5226 \begin{verbatim}
 5227     alert tcp any any -> any 80 ( msg:"content"; content: "foo"; )
 5228 \end{verbatim}
 5229 
 5230 and the we inspect the following URI:
 5231 
 5232 \begin{verbatim}
 5233     get /foo.htm http/1.0\r\n\r\n
 5234 \end{verbatim}
 5235 
 5236 No alert will be generated when \texttt{inspect\_uri\_only} is enabled.  The
 5237 \texttt{inspect\_uri\_only} configuration turns off all forms of detection
 5238 except \texttt{uricontent} inspection.
 5239 
 5240 \item \texttt{max\_header\_length $<$positive integer up to 65535$>$}
 5241 
 5242 This option takes an integer as an argument.  The integer is the maximum length
 5243 allowed for an HTTP client request header field.  Requests that exceed this
 5244 length will cause a "Long Header" alert.  This alert is off by default.  To
 5245 enable, specify an integer argument to max\_header\_length of 1 to 65535.
 5246 Specifying a value of 0 is treated as disabling the alert.
 5247 
 5248 \item \texttt{max\_spaces $<$positive integer up to 65535$>$}
 5249 
 5250 This option takes an integer as an argument.  The integer determines the maximum number
 5251 of whitespaces allowed with HTTP client request line folding. Requests headers
 5252 folded with whitespaces equal to or more than this value will cause a
 5253 "Space Saturation" alert with SID 26 and GID 119.  The default value for this
 5254 option is 200.  To enable, specify an integer argument to \texttt{max\_spaces} of 1 to 65535.
 5255 Specifying a value of 0 is treated as disabling the alert.
 5256 
 5257 
 5258 \item \texttt{webroot $<$yes$|$no$>$}
 5259 
 5260 This option generates an alert when a directory traversal traverses past the
 5261 web server root directory.  This generates much fewer false positives than the
 5262 directory option, because it doesn't alert on directory traversals that stay
 5263 within the web server directory structure.  It only alerts when the directory
 5264 traversals go past the web server root directory, which is associated with
 5265 certain web attacks.
 5266 
 5267 \item \texttt{tab\_uri\_delimiter}
 5268 
 5269 This option turns on the use of the tab character (0x09) as a delimiter for a
 5270 URI.  Apache accepts tab as a delimiter; IIS does not.  For IIS, a tab in the
 5271 URI should be treated as any other character.  Whether this option is on or
 5272 not, a tab is treated as whitespace if a space character (0x20) precedes it.
 5273 No argument is specified.
 5274 
 5275 \item \texttt{normalize\_headers}
 5276 
 5277 This option turns on normalization for HTTP Header Fields, not including
 5278 Cookies (using the same configuration parameters as the URI normalization (i.e.,
 5279 multi-slash, directory, etc.).  It is useful for normalizing Referrer URIs that
 5280 may appear in the HTTP Header.
 5281 
 5282 \item \texttt{normalize\_cookies}
 5283 
 5284 This option turns on normalization for HTTP Cookie Fields (using the same
 5285 configuration parameters as the URI normalization (i.e., multi-slash, directory,
 5286 etc.).  It is useful for normalizing data in HTTP Cookies that may be encoded.
 5287 
 5288 \item \texttt{normalize\_utf}
 5289 
 5290 This option turns on normalization of HTTP response bodies where the Content-Type
 5291 header lists the character set as "utf-16le", "utf-16be", "utf-32le", or
 5292 "utf-32be". HTTP Inspect will attempt to normalize these back into 8-bit encoding,
 5293 generating an alert if the extra bytes are non-zero.
 5294 
 5295 \item \texttt{max\_headers $<$positive integer up to 1024$>$}
 5296 
 5297 This option takes an integer as an argument.  The integer is the maximum number
 5298 of HTTP client request header fields.  Requests that contain more HTTP Headers
 5299 than this value will cause a "Max Header" alert.  The alert is off by default.
 5300 To enable, specify an integer argument to max\_headers of 1 to 1024.
 5301 Specifying a value of 0 is treated as disabling the alert.
 5302 
 5303 \item \texttt{http\_methods $\{ cmd [cmd] \}$ } 
 5304 This specifies additional HTTP Request Methods outside of those checked by
 5305 default within the preprocessor (GET and POST). The list should be enclosed
 5306 within braces and delimited by spaces, tabs, line feed or carriage return. 
 5307 The config option, braces and methods also needs to be separated by braces.
 5308 
 5309 \begin{verbatim}
 5310     http_methods { PUT CONNECT }
 5311 \end{verbatim}
 5312 
 5313 \begin{note}
 5314 
 5315 Please note the maximum length for a method name is 256.
 5316 
 5317 \end{note}
 5318 
 5319 \item \texttt{log\_uri}
 5320 
 5321 This option enables HTTP Inspect preprocessor to parse the URI data from the
 5322 HTTP request and log it along with all the generated events for that session.
 5323 Stream reassembly needs to be turned on HTTP ports to enable the logging.
 5324 If there are multiple HTTP requests in the session, the URI data of the most recent
 5325 HTTP request during the alert will be logged. The maximum URI logged is 2048.
 5326 
 5327 \begin{note}
 5328 
 5329 Please note, this is logged only with the unified2 output and is not logged
 5330 with console output (-A cmg). \texttt{u2spewfoo} can be used to read this data from
 5331 the unified2.
 5332 
 5333 \end{note}
 5334 
 5335 \item \texttt{log\_hostname}
 5336 
 5337 This option enables HTTP Inspect preprocessor to parse the hostname data from the
 5338 "Host" header of the HTTP request and log it along with all the generated events
 5339 for that session. Stream reassembly needs to be turned on HTTP ports to enable
 5340 the logging. If there are multiple HTTP requests in the session, the Hostname data
 5341 of the most recent HTTP request during the alert will be logged. In case of
 5342 multiple "Host" headers within one HTTP request, a preprocessor alert with sid 24 is
 5343 generated. The maximum hostname length logged is 256.
 5344 
 5345 \begin{note}
 5346 
 5347 Please note, this is logged only with the unified2 output and is not logged
 5348 with console output (-A cmg). \texttt{u2spewfoo} can be used to read this data from
 5349 the unified2.
 5350 
 5351 \end{note}
 5352 
 5353 \begin{verbatim}
 5354 ##########################################
 5355 # HTTP2 SUPPORT IS STILL EXPERIMENTAL!
 5356 # DO NOT USE IN PRODUCTION ENVIRONMENTS.
 5357 # Please send any issues to the Snort team
 5358 ##########################################
 5359 \end{verbatim}
 5360 
 5361 \item \texttt{legacy\_mode}
 5362 By default, HTTP2 traffic is not supported. You can use "legacy\_mode no"
 5363 to enable HTTP2 support.
 5364 If http legacy mode is configured, HTTP2 inspection is disabled.
 5365 
 5366 \end{slist}
 5367 
 5368 \subsubsection{Examples}
 5369 
 5370 \begin{verbatim}
 5371     preprocessor http_inspect_server: \
 5372         server 10.1.1.1 \
 5373         ports { 80 3128 8080 } \
 5374         server_flow_depth 0 \
 5375         ascii no \
 5376         double_decode yes \
 5377         non_rfc_char { 0x00 } \
 5378         chunk_length 500000 \
 5379         non_strict \
 5380         no_alerts
 5381 
 5382     preprocessor http_inspect_server: \
 5383         server default \ 
 5384         ports  { 80 3128 }  \
 5385         non_strict \
 5386         non_rfc_char  { 0x00 }  \
 5387         server_flow_depth 300  \
 5388         apache_whitespace yes \
 5389         directory no \
 5390         iis_backslash no \
 5391         u_encode yes \
 5392         ascii no \
 5393         chunk_length 500000 \
 5394         bare_byte yes \
 5395         double_decode yes \
 5396         iis_unicode yes \ 
 5397         iis_delimiter yes \
 5398         multi_slash no
 5399 
 5400     preprocessor http_inspect_server: \
 5401         server default \
 5402         profile all \
 5403         ports { 80 8080 }
 5404 \end{verbatim}
 5405 
 5406 \subsection{SMTP Preprocessor}
 5407 \label{SMTP}
 5408 
 5409 The SMTP preprocessor is an SMTP decoder for user applications.  Given a data
 5410 buffer, SMTP will decode the buffer and find SMTP commands and responses.  It
 5411 will also mark the command, data header data body sections, and TLS data.
 5412 
 5413 SMTP handles stateless and stateful processing.  It saves state between
 5414 individual packets.  However maintaining correct state is dependent on the
 5415 reassembly of the client side of the stream (i.e., a loss of coherent stream data
 5416 results in a loss of state).
 5417 
 5418 \subsubsection{Configuration}
 5419 
 5420 SMTP has the usual configuration items, such as \texttt{port} and
 5421 \texttt{inspection\_type}.  Also, SMTP command lines can be normalized to
 5422 remove extraneous spaces.  TLS-encrypted traffic can be ignored, which improves
 5423 performance.  In addition, regular mail data can be ignored for an additional
 5424 performance boost.  Since so few (none in the current snort rule set) exploits
 5425 are against mail data, this is relatively safe to do and can improve the
 5426 performance of data inspection.
 5427 
 5428 The configuration options are described below:
 5429 
 5430 \begin{slist}
 5431 
 5432 \item \texttt{ports \{ <port> [<port>] ... \}}
 5433 
 5434 This specifies on what ports to check for SMTP data.  Typically, this will
 5435 include 25 and possibly 465, for encrypted SMTP.
 5436 
 5437 \item \texttt{inspection\_type <stateful | stateless>}
 5438 
 5439 Indicate whether to operate in stateful or stateless mode.
 5440 
 5441 \item \texttt{normalize <all | none | cmds>}
 5442 
 5443 This turns on normalization.  Normalization checks for more than one space
 5444 character after a command.  Space characters are defined as space (ASCII 0x20)
 5445 or tab (ASCII 0x09).
 5446 
 5447 \texttt{all} checks all commands
 5448 
 5449 \texttt{none} turns off normalization for all commands.
 5450 
 5451 \texttt{cmds} just checks commands listed with the \texttt{normalize\_cmds} parameter.
 5452 
 5453 \item \texttt{ignore\_data}
 5454 
 5455 Ignore data section of mail (except for mail headers) when processing rules.
 5456 
 5457 \item \texttt{ignore\_tls\_data}
 5458 
 5459 Ignore TLS-encrypted data when processing rules.
 5460 
 5461 \item \texttt{max\_command\_line\_len <int>}
 5462 
 5463 Alert if an SMTP command line is longer than this value.  Absence of this
 5464 option or a "0" means never alert on command line length.  RFC 2821 recommends
 5465 512 as a maximum command line length.
 5466 
 5467 \item \texttt{max\_header\_line\_len <int>}
 5468 
 5469 Alert if an SMTP DATA header line is longer than this value.  Absence of this
 5470 option or a "0" means never alert on data header line length.  RFC 2821
 5471 recommends 1024 as a maximum data header line length.
 5472 
 5473 \item \texttt{max\_response\_line\_len <int>}
 5474 
 5475 Alert if an SMTP response line is longer than this value.  Absence of this
 5476 option or a "0" means never alert on response line length.  RFC 2821 recommends
 5477 512 as a maximum response line length.
 5478 
 5479 \item \texttt{alt\_max\_command\_line\_len <int> \{ <cmd> [<cmd>] \}}
 5480 
 5481 Overrides \texttt{max\_command\_line\_len} for specific commands.
 5482 
 5483 \item \texttt{no\_alerts}
 5484 
 5485 Turn off all alerts for this preprocessor.
 5486 
 5487 \item \texttt{invalid\_cmds \{ <Space-delimited list of commands> \}}
 5488 
 5489 Alert if this command is sent from client side.  Default is an empty list.
 5490 
 5491 \item \texttt{valid\_cmds \{ <Space-delimited list of commands> \}}
 5492 
 5493 List of valid commands.  We do not alert on commands in this list.  Default is
 5494 an empty list, but preprocessor has this list hard-coded:
 5495 
 5496 \begin{itemize}
 5497 \item[]
 5498 \{ ATRN AUTH BDAT DATA DEBUG EHLO EMAL ESAM ESND ESOM ETRN EVFY EXPN
 5499 HELO HELP IDENT MAIL NOOP QUIT RCPT RSET SAML SOML SEND ONEX QUEU
 5500 STARTTLS TICK TIME TURN TURNME VERB VRFY X-EXPS X-LINK2STATE
 5501 XADR XAUTH XCIR XEXCH50 XGEN XLICENSE XQUE XSTA XTRN XUSR \}
 5502 \end{itemize}
 5503 
 5504 \item \texttt{data\_cmds \{ <Space-delimited list of commands> \}}
 5505 
 5506 List of commands that initiate sending of data with an end of data delimiter
 5507 the same as that of the DATA command per RFC 5321 - \texttt{"<CRLF>.<CRLF>"}.
 5508 Default is \{ DATA \}.
 5509 
 5510 \item \texttt{binary\_data\_cmds \{ <Space-delimited list of commands> \}}
 5511 
 5512 List of commands that initiate sending of data and use a length value after
 5513 the command to indicate the amount of data to be sent, similar to that of the
 5514 BDAT command per RFC 3030.  Default is \{ BDAT XEXCH50 \}.
 5515 
 5516 \item \texttt{auth\_cmds \{ <Space-delimited list of commands> \}}
 5517 
 5518 List of commands that initiate an authentication exchange between client
 5519 and server.  Default is \{ AUTH XAUTH X-EXPS \}.
 5520 
 5521 \item \texttt{alert\_unknown\_cmds}
 5522 
 5523 Alert if we don't recognize command.  Default is off.
 5524 
 5525 \item \texttt{normalize\_cmds \{ <Space-delimited list of commands> \}}
 5526 
 5527 Normalize this list of commands Default is \{ RCPT VRFY EXPN \}.
 5528 
 5529 \item \texttt{xlink2state \{ enable | disable [drop] \}}
 5530 
 5531 Enable/disable xlink2state alert.  Drop if alerted.  Default is
 5532 \texttt{enable}.
 5533 
 5534 \item \texttt{print\_cmds}
 5535 
 5536 List all commands understood by the preprocessor.  This not normally printed
 5537 out with the configuration because it can print so much data.
 5538 
 5539 \item \texttt{disabled}
 5540 
 5541 Disables the SMTP preprocessor in a config. This is useful when specifying
 5542 the decoding depths such as \texttt{b64\_decode\_depth}, \texttt{qp\_decode\_depth}, 
 5543 \texttt{uu\_decode\_depth}, \texttt{bitenc\_decode\_depth} or the memcap used for 
 5544 decoding \texttt{max\_mime\_mem} in default config without turning on the SMTP preprocessor.
 5545 
 5546 \item \texttt{b64\_decode\_depth}
 5547 
 5548 This config option is used to turn off/on or set the base64 decoding depth used to
 5549 decode the base64 encoded MIME attachments. The value ranges from -1 to 65535.
 5550 A value of -1 turns off the base64 decoding of MIME attachments. The value of 0
 5551 sets the decoding of base64 encoded MIME attachments to unlimited. A value other
 5552 than 0 or -1 restricts the decoding of base64 MIME attachments, and applies per attachment. 
 5553 A SMTP preprocessor alert with sid 10 is generated (if enabled) when the decoding fails.
 5554 
 5555 Multiple MIME attachments/data in one packet are pipelined. When stateful inspection 
 5556 is turned on the base64 encoded MIME attachments/data across multiple packets are decoded too.
 5557 
 5558 The decoded data is available for detection using the rule option \texttt{file\_data}. 
 5559 See \ref{sub:file_data} rule option for more details.
 5560 
 5561 This option replaces the deprecated options, \texttt{enable\_mime\_decoding} and 
 5562 \texttt{max\_mime\_depth}.  It is recommended that user inputs a value that is a 
 5563 multiple of 4. When the value specified is not a multiple of 4, the SMTP preprocessor 
 5564 will round it up to the next multiple of 4.
 5565 
 5566 In case of multiple configs, the value specified in the non-default config cannot
 5567 exceed the value specified in the default config.
 5568 
 5569 \item \texttt{qp\_decode\_depth}
 5570 
 5571 This config option is used to turn off/on or set the Quoted-Printable decoding depth
 5572 used to decode the Quoted-Printable(QP) encoded MIME attachments. The value ranges
 5573 from -1 to 65535. A value of -1 turns off the QP decoding of MIME attachments.
 5574 The value of 0 sets the decoding of QP encoded MIME attachments to unlimited. A
 5575 value other than 0 or -1 restricts the decoding of QP MIME attachments, and applies per 
 5576 attachment. A SMTP preprocessor alert with sid 11 is generated (if enabled) when the decoding fails.
 5577 
 5578 Multiple MIME attachments/data in one packet are pipelined. When stateful inspection 
 5579 is turned on the QP encoded MIME attachments/data across multiple packets are decoded too.
 5580 
 5581 The decoded data is available for detection using the rule option \texttt{file\_data}.
 5582 See \ref{sub:file_data} rule option for more details.
 5583 
 5584 In case of multiple configs, the value specified in the non-default config cannot exceed
 5585 the value specified in the default config.
 5586 
 5587 \item \texttt{bitenc\_decode\_depth}
 5588 
 5589 This config option is used to turn off/on or set the non-encoded MIME extraction
 5590 depth used to extract the non-encoded MIME attachments. The value ranges from -1 
 5591 to 65535. A value of -1 turns off the extraction of these MIME attachments. 
 5592 The value of 0 sets the extraction of these MIME attachments to unlimited.
 5593 A value other than 0 or -1 restricts the extraction of these MIME attachments, and applies 
 5594 per attachment.
 5595 
 5596 Multiple MIME attachments/data in one packet are pipelined. When stateful inspection 
 5597 is turned on the non-encoded MIME attachments/data across multiple packets are extracted too.
 5598 
 5599 The extracted data is available for detection using the rule option \texttt{file\_data}.
 5600 See \ref{sub:file_data} rule option for more details.
 5601 
 5602 In case of multiple configs, the value specified in the non-default config cannot exceed
 5603 the value specified in the default config.
 5604 
 5605 \item \texttt{uu\_decode\_depth}
 5606 
 5607 This config option is used to turn off/on or set the Unix-to-Unix decoding depth
 5608 used to decode the Unix-to-Unix(UU) encoded attachments. The value ranges
 5609 from -1 to 65535. A value of -1 turns off the UU decoding of SMTP attachments.
 5610 The value of 0 sets the decoding of UU encoded SMTP attachments to unlimited. A
 5611 value other than 0 or -1 restricts the decoding of UU SMTP attachments, and applies 
 5612 per attachment. A SMTP preprocessor alert with sid 13 is generated (if enabled) when the decoding fails.
 5613 
 5614 Multiple UU attachments/data in one packet are pipelined. When stateful inspection
 5615 is turned on the UU encoded SMTP attachments/data across multiple packets are decoded too.
 5616 
 5617 The decoded data is available for detection using the rule option \texttt{file\_data}.
 5618 See \ref{sub:file_data} rule option for more details.
 5619 
 5620 In case of multiple configs, the value specified in the non-default config cannot exceed
 5621 the value specified in the default config.
 5622 
 5623 \item \texttt{enable\_mime\_decoding}
 5624 
 5625 Enables Base64 decoding of Mime attachments/data. Multiple base64 encoded MIME
 5626 attachments/data in one packet are pipelined. When stateful inspection is turned
 5627 on the base64 encoded MIME attachments/data across multiple packets are decoded too.
 5628 The decoding of base64 encoded attachments/data ends when either the 
 5629 \texttt{max\_mime\_depth} or maximum MIME sessions (calculated using 
 5630 \texttt{max\_mime\_depth} and \texttt{max\_mime\_mem}) is reached or when the 
 5631 encoded data ends. The decoded data is available for detection using the rule option 
 5632 \texttt{file\_data}. See \ref{sub:file_data} rule option for more details.
 5633 
 5634 This option is deprecated. Use the option \texttt{b64\_decode\_depth} to turn off
 5635 or on the base64 decoding instead.
 5636 
 5637 \item \texttt{max\_mime\_depth <int>}
 5638 
 5639 Specifies the maximum number of base64 encoded data to decode per SMTP attachment.
 5640 The option take values ranging from 4 to 20480 bytes. The default value for this
 5641 in snort in 1460 bytes.
 5642 
 5643 It is recommended that user inputs a value that is a multiple of 4. When the value 
 5644 specified is not a multiple of 4, the SMTP preprocessor will round it up to the next 
 5645 multiple of 4.
 5646 
 5647 This option is deprecated. Use the option \texttt{b64\_decode\_depth} to turn off
 5648 or on the base64 decoding instead.
 5649 
 5650 \item \texttt{max\_mime\_mem <int>}
 5651 
 5652 This option determines (in bytes) the maximum amount of memory the SMTP preprocessor
 5653 will use for decoding base64 encoded/quoted-printable/non-encoded MIME attachments/data
 5654 or Unix-to-Unix encoded attachments. This value can be set from 3276 bytes to 100MB.
 5655 
 5656 This option along with the maximum of the decoding depths will determine the SMTP
 5657 sessions that will be decoded at any given instant. The default value for this option
 5658 is 838860.
 5659 
 5660 Note: It is suggested to set this value such that the max smtp session calculated as
 5661 follows is at least 1.
 5662 
 5663 max smtp session = \texttt{max\_mime\_mem} /(2 * max of (\texttt{b64\_decode\_depth}, 
 5664                     \texttt{uu\_decode\_depth}, \texttt{qp\_decode\_depth}
 5665                                         or \texttt{bitenc\_decode\_depth}))
 5666 
 5667 For example, if \texttt{b64\_decode\_depth} is 0 (indicates unlimited decoding) and 
 5668 \texttt{qp\_decode\_depth} is 100, then
 5669 
 5670 max smtp session = \texttt{max\_mime\_mem}/2*65535 (max value for \texttt{b64\_decode\_depth})
 5671 
 5672 In case of multiple configs, the \texttt{max\_mime\_mem} of the non-default configs will be overwritten by the
 5673 default config's value. Hence user needs to define it in the default config with the new keyword
 5674 disabled (used to disable SMTP preprocessor in a config).
 5675 
 5676 \item \texttt{log\_mailfrom}
 5677 This option enables SMTP preprocessor to parse and log the sender's email address extracted 
 5678 from the "MAIL FROM" command along with all the generated events for that session. The maximum
 5679 number of bytes logged for this option is 1024.
 5680 
 5681 Please note, this is logged only with the unified2 output and is not logged with console output (-A cmg).
 5682 u2spewfoo can be used to read this data from the unified2.
 5683 
 5684 \item \texttt{log\_rcptto}
 5685 This option enables SMTP preprocessor to parse and log the recipient's email addresses 
 5686 extracted from the "RCPT TO" command along with all the generated events for that session. 
 5687 Multiple recipients are appended with commas. The maximum number of bytes logged for this option is 1024.
 5688 
 5689 Please note, this is logged only with the unified2 output and is not logged with console output (-A cmg).
 5690  u2spewfoo can be used to read this data from the unified2.
 5691 
 5692 \item \texttt{log\_filename}
 5693 This option enables SMTP preprocessor to parse and log the MIME attachment filenames extracted 
 5694 from the Content-Disposition header within the MIME body along with all the generated events 
 5695 for that session. Multiple filenames are appended with commas. The maximum number of bytes logged 
 5696 for this option is 1024.
 5697 
 5698 Please note, this is logged only with the unified2 output and is not logged with the 
 5699 console output (-A cmg). u2spewfoo can be used to read this data from the unified2.
 5700 
 5701 \item \texttt{log\_email\_hdrs}
 5702 This option enables SMTP preprocessor to parse and log the SMTP email headers extracted from 
 5703 SMTP data along with all generated events for that session. The number of bytes extracted and 
 5704 logged depends upon the \texttt{email\_hdrs\_log\_depth}.
 5705 
 5706 Please note, this is logged only with the unified2 output and is not logged with the console output (-A cmg). 
 5707 u2spewfoo can be used to read this data from the unified2.
 5708 
 5709 \item \texttt{email\_hdrs\_log\_depth <int>} 
 5710 This option specifies the depth for logging email headers. The allowed range for this option is 
 5711 0 - 20480. A value of 0 will disable email headers logging. The default value for this option is 1464. 
 5712 
 5713 Please note, in case of multiple policies, the value specified in the default policy is used and the values 
 5714 specified in the targeted policies are overwritten by the default value. 
 5715 This option must be configured in the default policy even if the SMTP configuration is disabled.
 5716 
 5717 \item \texttt{memcap <int>}
 5718 This option determines in bytes the maximum amount of memory the SMTP preprocessor will
 5719 use for logging of filename, MAIL FROM addresses, RCPT TO addresses and email headers. This value
 5720 along with the buffer size used to log MAIL FROM, RCPT TO, filenames and \texttt{email\_hdrs\_log\_depth} 
 5721 will determine the maximum SMTP sessions that will log the email headers at any given time. When this memcap 
 5722 is reached SMTP will stop logging the filename, MAIL FROM address, RCPT TO addresses and email headers
 5723 until memory becomes available.
 5724 
 5725 Max SMTP sessions logging email headers at any given time
 5726                 = memcap/(1024 + 1024 + 1024 + \texttt{email\_hdrs\_log\_depth})
 5727 
 5728 The size 1024 is the maximum buffer size used for logging filename, RCPTTO and MAIL FROM addresses.
 5729 
 5730 Default value for this option is 838860. The allowed range for this option is 3276 to 104857600.
 5731 The value specified in the default config is used when this option is specified in multiple configs.
 5732 This option must be configured in the default config even if the SMTP configuration is disabled.
 5733 
 5734 Please note, in case of multiple policies, the value specified in the default policy is used and the values 
 5735 specified in the targeted policies are overwritten by the default value.                                                  
 5736 This option must be configured in the default policy even if the SMTP configuration is disabled.
 5737 
 5738 \end{slist}
 5739 
 5740 \subsubsection{Example}
 5741 
 5742 \begin{verbatim}
 5743     preprocessor SMTP: \
 5744         ports { 25 } \
 5745         inspection_type stateful \
 5746         normalize cmds \
 5747         normalize_cmds { EXPN VRFY RCPT } \
 5748         ignore_data \
 5749         ignore_tls_data \
 5750         max_command_line_len  512 \
 5751         max_header_line_len   1024 \
 5752         max_response_line_len 512 \
 5753         no_alerts \
 5754         alt_max_command_line_len 300 { RCPT } \
 5755         invalid_cmds { } \
 5756         valid_cmds { } \
 5757         xlink2state { disable } \
 5758     print_cmds \
 5759     log_filename \
 5760     log_email_hdrs \
 5761     log_mailfrom \
 5762     log_rcptto \
 5763     email_hdrs_log_depth 2920 \
 5764     memcap 6000
 5765 
 5766     preprocessor SMTP: \
 5767     b64_decode_depth 0\
 5768         max_mime_mem 4000 \
 5769     memcap 6000 \
 5770     email_hdrs_log_depth 2920 \
 5771     disabled
 5772 \end{verbatim}
 5773 
 5774 \subsubsection{Default}
 5775 
 5776 \begin{verbatim}
 5777     preprocessor SMTP: \
 5778         ports { 25 } \
 5779         inspection_type stateful \
 5780         normalize cmds \
 5781         normalize_cmds { EXPN VRFY RCPT } \
 5782         alt_max_command_line_len 260 { MAIL } \
 5783         alt_max_command_line_len 300 { RCPT } \
 5784         alt_max_command_line_len 500 { HELP HELO ETRN } \
 5785         alt_max_command_line_len 255 { EXPN VRFY }
 5786 \end{verbatim}
 5787 
 5788 \subsubsection{Note}
 5789 
 5790 \texttt{RCPT TO:} and \texttt{MAIL FROM:} are SMTP commands.  For the
 5791 preprocessor configuration, they are referred to as RCPT and MAIL,
 5792 respectively.  Within the code, the preprocessor actually maps RCPT and MAIL to
 5793 the correct command name.
 5794 
 5795 \subsection{POP Preprocessor}
 5796 \label{POP}
 5797 
 5798 POP is an POP3 decoder for user applications. Given a data buffer,
 5799 POP will decode the buffer and find POP3 commands and responses.
 5800 It will also mark the command, data header data body sections and
 5801 extract the POP3 attachments and decode it appropriately.
 5802 
 5803 POP will handle stateful processing. It saves state between individual
 5804 packets. However maintaining correct state is dependent on the reassembly
 5805 of the server side of the stream (i.e., a loss of coherent stream data results
 5806 in a loss of state).
 5807 
 5808 Stream should be turned on for POP. Please ensure that the POP ports are added
 5809  to the stream5 ports for proper reassembly.
 5810 
 5811 The POP preprocessor uses GID 142 to register events.
 5812 
 5813 \subsubsection{Configuration}
 5814 
 5815 The configuration options are described below:
 5816 
 5817 \begin{slist}
 5818 
 5819 \item \texttt{ports \{ <port> [<port>] ... \}}
 5820 
 5821 This specifies on what ports to check for POP data.  Typically, this will
 5822 include 110. Default ports if none are specified are 110 .
 5823 
 5824 \item \texttt{disabled}
 5825 
 5826 Disables the POP preprocessor in a config. This is useful when specifying
 5827 the decoding depths such as \texttt{b64\_decode\_depth}, \texttt{qp\_decode\_depth},
 5828 \texttt{uu\_decode\_depth}, \texttt{bitenc\_decode\_depth} or the memcap used for
 5829 decoding \texttt{memcap} in default config without turning on the POP preprocessor.
 5830 
 5831 \item \texttt{b64\_decode\_depth}
 5832 
 5833 This config option is used to turn off/on or set the base64 decoding depth used to
 5834 decode the base64 encoded MIME attachments. The value ranges from -1 to 65535.
 5835 A value of -1 turns off the base64 decoding of MIME attachments. The value of 0
 5836 sets the decoding of base64 encoded MIME attachments to unlimited. A value other
 5837 than 0 or -1 restricts the decoding of base64 MIME attachments, and applies per 
 5838 attachment. A POP preprocessor alert with sid 4 is generated (if enabled) when the decoding fails.
 5839 
 5840 Multiple MIME attachments/data in one packet are pipelined. When stateful inspection
 5841 is turned on the base64 encoded MIME attachments/data across multiple packets are decoded too.
 5842 
 5843 The decoded data is available for detection using the rule option \texttt{file\_data}.
 5844 See \ref{sub:file_data} rule option for more details.
 5845 
 5846 It is recommended that user inputs a value that is a multiple of 4. When the value specified 
 5847 is not a multiple of 4, the POP preprocessor will round it up to the next multiple of 4.
 5848 
 5849 In case of multiple configs, the value specified in the non-default config cannot
 5850 exceed the value specified in the default config.
 5851 
 5852 \item \texttt{qp\_decode\_depth}
 5853 
 5854 This config option is used to turn off/on or set the Quoted-Printable decoding depth
 5855 used to decode the Quoted-Printable(QP) encoded MIME attachments. The value ranges
 5856 from -1 to 65535. A value of -1 turns off the QP decoding of MIME attachments.
 5857 The value of 0 sets the decoding of QP encoded MIME attachments to unlimited. A
 5858 value other than 0 or -1 restricts the decoding of QP MIME attachments, and applies per 
 5859 attachment. A POP preprocessor alert with sid 5 is generated (if enabled) when the decoding fails.
 5860 
 5861 Multiple MIME attachments/data in one packet are pipelined. When stateful inspection
 5862 is turned on the QP encoded MIME attachments/data across multiple packets are decoded too.
 5863 
 5864 The decoded data is available for detection using the rule option \texttt{file\_data}.
 5865 See \ref{sub:file_data} rule option for more details.
 5866 
 5867 In case of multiple configs, the value specified in the non-default config cannot exceed
 5868 the value specified in the default config.
 5869 
 5870 \item \texttt{bitenc\_decode\_depth}
 5871 
 5872 This config option is used to turn off/on or set the non-encoded MIME extraction
 5873 depth used to extract the non-encoded MIME attachments. The value ranges from -1 
 5874 to 65535. A value of -1 turns off the extraction of these MIME attachments. 
 5875 The value of 0 sets the extraction of these MIME attachments to unlimited.
 5876 A value other than 0 or -1 restricts the extraction of these MIME attachments, and applies 
 5877 per attachment.
 5878 
 5879 Multiple MIME attachments/data in one packet are pipelined. When stateful inspection
 5880 is turned on the non-encoded MIME attachments/data across multiple packets are extracted too.
 5881 
 5882 The extracted data is available for detection using the rule option \texttt{file\_data}.
 5883 See \ref{sub:file_data} rule option for more details.
 5884 
 5885 In case of multiple configs, the value specified in the non-default config cannot exceed
 5886 the value specified in the default config.
 5887 
 5888 \item \texttt{uu\_decode\_depth}
 5889 
 5890 This config option is used to turn off/on or set the Unix-to-Unix decoding depth
 5891 used to decode the Unix-to-Unix(UU) encoded attachments. The value ranges
 5892 from -1 to 65535. A value of -1 turns off the UU decoding of POP attachments.
 5893 The value of 0 sets the decoding of UU encoded POP attachments to unlimited. A
 5894 value other than 0 or -1 restricts the decoding of UU POP attachments, and applies per 
 5895 attachment. A POP preprocessor alert with sid 7 is generated (if enabled) when the decoding fails.
 5896 
 5897 Multiple UU attachments/data in one packet are pipelined. When stateful inspection
 5898 is turned on the UU encoded POP attachments/data across multiple packets are decoded too.
 5899 
 5900 The decoded data is available for detection using the rule option \texttt{file\_data}.
 5901 See \ref{sub:file_data} rule option for more details.
 5902 
 5903 In case of multiple configs, the value specified in the non-default config cannot exceed
 5904 the value specified in the default config.
 5905 
 5906 \item \texttt{memcap <int>}
 5907 
 5908 This option determines (in bytes) the maximum amount of memory the POP preprocessor
 5909 will use for decoding base64 encoded/quoted-printable/non-encoded MIME attachments/data
 5910 or Unix-to-Unix encoded attachments. This value can be set from 3276 bytes to 100MB.
 5911 
 5912 This option along with the maximum of the decoding depths will determine the POP 
 5913 sessions that will be decoded at any given instant. The default value for this option
 5914 is 838860.
 5915 
 5916 Note: It is suggested to set this value such that the max pop session calculated as
 5917 follows is at least 1.
 5918 
 5919 max pop session = \texttt{memcap} /(2 * max of (\texttt{b64\_decode\_depth},
 5920                                         \texttt{uu\_decode\_depth}, \texttt{qp\_decode\_depth}
 5921                                         or \texttt{bitenc\_decode\_depth}))
 5922 
 5923 For example, if \texttt{b64\_decode\_depth} is 0 (indicates unlimited decoding) and
 5924 \texttt{qp\_decode\_depth} is 100, then
 5925 
 5926 max pop session = \texttt{memcap}/2*65535 (max value for \texttt{b64\_decode\_depth})
 5927 
 5928 In case of multiple configs, the \texttt{memcap} of the non-default configs will be overwritten by the
 5929 default config's value. Hence user needs to define it in the default config with the new keyword
 5930 disabled (used to disable POP preprocessor in a config).
 5931 
 5932 When the memcap for decoding (\texttt{memcap}) is exceeded the POP preprocessor alert with sid 3 is
 5933 generated (when enabled).
 5934 
 5935 \end{slist}
 5936 
 5937 \subsubsection{Example}
 5938 
 5939 \begin{verbatim}
 5940     preprocessor pop: \
 5941       ports { 110 } \
 5942       memcap 1310700 \
 5943       qp_decode_depth -1 \
 5944       b64_decode_depth 0 \
 5945       bitenc_decode_depth 100
 5946 
 5947 
 5948     preprocessor pop: \
 5949       memcap 1310700 \
 5950       qp_decode_depth 0 \
 5951       disabled
 5952 \end{verbatim}
 5953 
 5954 \subsubsection{Default}
 5955 
 5956 \begin{verbatim}
 5957     preprocessor pop: \
 5958       ports { 110 } \
 5959       b64_decode_depth 1460 \
 5960       qp_decode_depth 1460 \
 5961       bitenc_decode_depth 1460 \
 5962       uu_decode_depth 1460
 5963 \end{verbatim}
 5964 
 5965 \subsection{IMAP Preprocessor}
 5966 \label{IMAP}
 5967 
 5968 IMAP is an IMAP4 decoder for user applications. Given a data buffer,
 5969 IMAP will decode the buffer and find IMAP4 commands and responses.
 5970 It will also mark the command, data header data body sections and
 5971 extract the IMAP4 attachments and decode it appropriately.
 5972 
 5973 IMAP will handle stateful processing. It saves state between individual
 5974 packets. However maintaining correct state is dependent on the reassembly
 5975 of the server side of the stream (i.e., a loss of coherent stream data results
 5976 in a loss of state).
 5977 
 5978 Stream should be turned on for IMAP. Please ensure that the IMAP ports are added
 5979  to the stream5 ports for proper reassembly.
 5980 
 5981 The IMAP preprocessor uses GID 141 to register events.
 5982 
 5983 \subsubsection{Configuration}
 5984 
 5985 The configuration options are described below:
 5986 
 5987 \begin{slist}
 5988 
 5989 \item \texttt{ports \{ <port> [<port>] ... \}}
 5990 
 5991 This specifies on what ports to check for IMAP data.  Typically, this will
 5992 include 143. Default ports if none are specified are 143 .
 5993 
 5994 \item \texttt{disabled}
 5995 
 5996 Disables the IMAP preprocessor in a config. This is useful when specifying
 5997 the decoding depths such as \texttt{b64\_decode\_depth}, \texttt{qp\_decode\_depth},
 5998 \texttt{uu\_decode\_depth}, \texttt{bitenc\_decode\_depth} or the memcap used for
 5999 decoding \texttt{memcap} in default config without turning on the IMAP preprocessor.
 6000 
 6001 \item \texttt{b64\_decode\_depth}
 6002 
 6003 This config option is used to turn off/on or set the base64 decoding depth used to
 6004 decode the base64 encoded MIME attachments. The value ranges from -1 to 65535.
 6005 A value of -1 turns off the base64 decoding of MIME attachments. The value of 0
 6006 sets the decoding of base64 encoded MIME attachments to unlimited. A value other
 6007 than 0 or -1 restricts the decoding of base64 MIME attachments, and applies per attachment. 
 6008 A IMAP preprocessor alert with sid 4 is generated (if enabled) when the decoding fails.
 6009 
 6010 Multiple MIME attachments/data in one packet are pipelined. When stateful inspection
 6011 is turned on the base64 encoded MIME attachments/data across multiple packets are decoded too.
 6012 
 6013 The decoded data is available for detection using the rule option \texttt{file\_data}.
 6014 See \ref{sub:file_data} rule option for more details.
 6015 
 6016 It is recommended that user inputs a value that is a multiple of 4. When the value specified 
 6017 is not a multiple of 4, the IMAP preprocessor will round it up to the next multiple of 4.
 6018 
 6019 In case of multiple configs, the value specified in the non-default config cannot
 6020 exceed the value specified in the default config.
 6021 
 6022 \item \texttt{qp\_decode\_depth}
 6023 
 6024 This config option is used to turn off/on or set the Quoted-Printable decoding depth
 6025 used to decode the Quoted-Printable(QP) encoded MIME attachments. The value ranges
 6026 from -1 to 65535. A value of -1 turns off the QP decoding of MIME attachments.
 6027 The value of 0 sets the decoding of QP encoded MIME attachments to unlimited. A
 6028 value other than 0 or -1 restricts the decoding of QP MIME attachments, and applies per 
 6029 attachment. A IMAP preprocessor alert with sid 5 is generated (if enabled) when the decoding fails.
 6030 
 6031 Multiple MIME attachments/data in one packet are pipelined. When stateful inspection
 6032 is turned on the QP encoded MIME attachments/data across multiple packets are decoded too.
 6033 
 6034 The decoded data is available for detection using the rule option \texttt{file\_data}.
 6035 See \ref{sub:file_data} rule option for more details.
 6036 
 6037 In case of multiple configs, the value specified in the non-default config cannot exceed
 6038 the value specified in the default config.
 6039 
 6040 \item \texttt{bitenc\_decode\_depth}
 6041 
 6042 This config option is used to turn off/on or set the non-encoded MIME extraction
 6043 depth used to extract the non-encoded MIME attachments. The
 6044 value ranges from -1 to 65535. A value of -1 turns off the extraction of these MIME
 6045 attachments. The value of 0 sets the extraction of these MIME attachments to unlimited.
 6046 A value other than 0 or -1 restricts the extraction of these MIME attachments, and applies 
 6047 per attachment.
 6048 
 6049 Multiple MIME attachments/data in one packet are pipelined. When stateful inspection
 6050 is turned on the non-encoded MIME attachments/data across multiple packets are extracted too.
 6051 
 6052 The extracted data is available for detection using the rule option \texttt{file\_data}.
 6053 See \ref{sub:file_data} rule option for more details.
 6054 
 6055 In case of multiple configs, the value specified in the non-default config cannot exceed
 6056 the value specified in the default config.
 6057 
 6058 \item \texttt{uu\_decode\_depth}
 6059 
 6060 This config option is used to turn off/on or set the Unix-to-Unix decoding depth
 6061 used to decode the Unix-to-Unix(UU) encoded attachments. The value ranges
 6062 from -1 to 65535. A value of -1 turns off the UU decoding of IMAP attachments.
 6063 The value of 0 sets the decoding of UU encoded IMAP attachments to unlimited. A
 6064 value other than 0 or -1 restricts the decoding of UU IMAP attachments, and applies per 
 6065 attachment. A IMAP preprocessor alert with sid 7 is generated (if enabled) when the decoding fails.
 6066 
 6067 Multiple UU attachments/data in one packet are pipelined. When stateful inspection
 6068 is turned on the UU encoded IMAP attachments/data across multiple packets are decoded too.
 6069 
 6070 The decoded data is available for detection using the rule option \texttt{file\_data}.
 6071 See \ref{sub:file_data} rule option for more details.
 6072 
 6073 In case of multiple configs, the value specified in the non-default config cannot exceed
 6074 the value specified in the default config.
 6075 
 6076 \item \texttt{memcap <int>}
 6077 
 6078 This option determines (in bytes) the maximum amount of memory the IMAP preprocessor
 6079 will use for decoding base64 encoded/quoted-printable/non-encoded MIME attachments/data
 6080 or Unix-to-Unix encoded attachments. This value can be set from 3276 bytes to 100MB.
 6081 
 6082 This option along with the maximum of the decoding depths will determine the IMAP 
 6083 sessions that will be decoded at any given instant. The default value for this option
 6084 is 838860.
 6085 
 6086 Note: It is suggested to set this value such that the max imap session calculated as
 6087 follows is at least 1.
 6088 
 6089 max imap session = \texttt{memcap} /(2 * max of (\texttt{b64\_decode\_depth},
 6090                                         \texttt{uu\_decode\_depth}, \texttt{qp\_decode\_depth}
 6091                                         or \texttt{bitenc\_decode\_depth}))
 6092 
 6093 For example, if \texttt{b64\_decode\_depth} is 0 (indicates unlimited decoding) and
 6094 \texttt{qp\_decode\_depth} is 100, then
 6095 
 6096 max imap session = \texttt{memcap}/2*65535 (max value for \texttt{b64\_decode\_depth})
 6097 
 6098 In case of multiple configs, the \texttt{memcap} of the non-default configs will be overwritten by the
 6099 default config's value. Hence user needs to define it in the default config with the new keyword
 6100 disabled (used to disable IMAP preprocessor in a config).
 6101 
 6102 When the memcap for decoding (\texttt{memcap}) is exceeded the IMAP preprocessor alert with sid 3 is
 6103 generated (when enabled).
 6104 
 6105 \end{slist}
 6106 
 6107 \subsubsection{Example}
 6108 
 6109 \begin{verbatim}
 6110     preprocessor imap: \
 6111       ports { 110 } \
 6112       memcap 1310700 \
 6113       qp_decode_depth -1 \
 6114       b64_decode_depth 0 \
 6115       bitenc_decode_depth 100
 6116 
 6117 
 6118     preprocessor imap: \
 6119       memcap 1310700 \
 6120       qp_decode_depth 0 \
 6121       disabled
 6122 \end{verbatim}
 6123 
 6124 \subsubsection{Default}
 6125 
 6126 \begin{verbatim}
 6127     preprocessor imap: \
 6128       ports { 110 } \
 6129       b64_decode_depth 1460 \
 6130       qp_decode_depth 1460 \
 6131       bitenc_decode_depth 1460 \
 6132       uu_decode_depth 1460
 6133 \end{verbatim}
 6134 
 6135 \subsection{FTP/Telnet Preprocessor}
 6136 \label{sub:ftptelnet}
 6137 
 6138 FTP/Telnet is an improvement to the Telnet decoder and provides stateful
 6139 inspection capability for both FTP and Telnet data streams.  FTP/Telnet will
 6140 decode the stream, identifying FTP commands and responses and Telnet escape
 6141 sequences and normalize the fields.  FTP/Telnet works on both client requests
 6142 and server responses.
 6143 
 6144 FTP/Telnet has the capability to handle stateless processing, meaning it only
 6145 looks for information on a packet-by-packet basis.  
 6146 
 6147 The default is to run FTP/Telnet in stateful inspection mode, meaning it looks
 6148 for information and handles reassembled data correctly.
 6149 
 6150 FTP/Telnet has a very ``rich'' user configuration, similar to that of HTTP
 6151 Inspect (See \ref{sub:http-inspect}).  Users can configure individual FTP
 6152 servers and clients with a variety of options, which should allow the user to
 6153 emulate any type of FTP server or FTP Client.  Within FTP/Telnet, there are
 6154 four areas of configuration: Global, Telnet, FTP Client, and FTP Server.
 6155 
 6156 \begin{note}
 6157 
 6158 Some configuration options have an argument of \texttt{yes} or \texttt{no}.
 6159 This argument specifies whether the user wants the configuration option to
 6160 generate a ftptelnet alert or not.  The presence of the option indicates the
 6161 option itself is on, while the \texttt{yes/no} argument applies to the alerting
 6162 functionality associated with that option.
 6163 
 6164 \end{note}
 6165 
 6166 \subsubsection{Global Configuration}
 6167 
 6168 The global configuration deals with configuration options that determine the
 6169 global functioning of FTP/Telnet.  The following example gives the generic
 6170 global configuration format:
 6171 
 6172 \subsubsection{Format}
 6173 
 6174 \begin{verbatim}
 6175     preprocessor ftp_telnet: \
 6176         global \
 6177         inspection_type stateful \
 6178         encrypted_traffic yes \
 6179         check_encrypted
 6180 \end{verbatim}
 6181 
 6182 You can only have a single global configuration, you'll get an error if you try
 6183 otherwise.  The FTP/Telnet global configuration must appear before the other
 6184 three areas of configuration.
 6185 
 6186 \paragraph{Configuration}
 6187 \begin{slist}
 6188 \item \texttt{inspection\_type}
 6189 
 6190 This indicates whether to operate in stateful or stateless mode.
 6191 
 6192 \item \texttt{encrypted\_traffic $<$yes|no$>$}
 6193 
 6194 This option enables detection and alerting on encrypted Telnet and FTP command
 6195 channels.
 6196 
 6197 \begin{note}
 6198 
 6199 When \texttt{inspection\_type} is in stateless mode, checks for encrypted
 6200 traffic will occur on every packet, whereas in stateful mode, a particular
 6201 session will be noted as encrypted and not inspected any further.
 6202 
 6203 \end{note}
 6204 
 6205 \item \texttt{check\_encrypted}
 6206 
 6207 Instructs the preprocessor to continue to check an encrypted session for a
 6208 subsequent command to cease encryption.
 6209 
 6210 \end{slist}
 6211 
 6212 \subsubsection{Example Global Configuration}
 6213 
 6214 \begin{verbatim}
 6215     preprocessor ftp_telnet: \
 6216         global inspection_type stateful encrypted_traffic no
 6217 \end{verbatim}
 6218 
 6219 \subsubsection{Telnet Configuration}
 6220 
 6221 The telnet configuration deals with configuration options that determine the
 6222 functioning of the Telnet portion of the preprocessor.  The following example
 6223 gives the generic telnet configuration format:
 6224 
 6225 \subsubsection{Format}
 6226 \begin{verbatim}
 6227     preprocessor ftp_telnet_protocol: \
 6228         telnet \
 6229         ports { 23 } \
 6230         normalize \
 6231         ayt_attack_thresh 6 \
 6232         detect_anomalies
 6233 
 6234 \end{verbatim}
 6235 
 6236 There should  only be a single telnet configuration, and subsequent instances
 6237 will override previously set values.
 6238 
 6239 \paragraph{Configuration}
 6240 \begin{slist}
 6241 \item \texttt{ports $\{ <$port$> [<$port$> <...>] \}$}
 6242 
 6243 This is how the user configures which ports to decode as telnet traffic.  SSH
 6244 tunnels cannot be decoded, so adding port 22 will only yield false positives.
 6245 Typically port 23 will be included.
 6246 
 6247 \item \texttt{normalize}
 6248 
 6249 This option tells the preprocessor to normalize the telnet traffic by
 6250 eliminating the telnet escape sequences.  It functions similarly to its
 6251 predecessor, the telnet\_decode preprocessor.  Rules written with 'raw' content
 6252 options will ignore the normalized buffer that is created when this option is
 6253 in use.
 6254 
 6255 \item \texttt{ayt\_attack\_thresh $<$ number $>$}
 6256 
 6257 This option causes the preprocessor to alert when the number of consecutive
 6258 telnet Are You There (AYT) commands reaches the number specified.  It is only
 6259 applicable when the mode is stateful.
 6260 
 6261 \item \texttt{detect\_anomalies}
 6262 
 6263 In order to support certain options, Telnet supports subnegotiation. Per the
 6264 Telnet RFC, subnegotiation begins with SB (subnegotiation begin) and must end
 6265 with an SE (subnegotiation end). However, certain implementations of Telnet
 6266 servers will ignore the SB without a corresponding SE. This is anomalous
 6267 behavior which could be an evasion case. Being that FTP uses the Telnet
 6268 protocol on the control connection, it is also susceptible to this behavior.
 6269 The \texttt{detect\_anomalies} option enables alerting on Telnet SB without the
 6270 corresponding SE.
 6271 
 6272 \end{slist}
 6273 
 6274 \subsubsection{Example Telnet Configuration}
 6275 
 6276 \begin{verbatim}
 6277     preprocessor ftp_telnet_protocol: \
 6278         telnet ports { 23 } normalize ayt_attack_thresh 6
 6279 \end{verbatim}
 6280 
 6281 \subsubsection{FTP Server Configuration}
 6282 
 6283 There are two types of FTP server configurations: default and by IP address.
 6284 
 6285 \paragraph{Default}
 6286 
 6287 This configuration supplies the default server configuration for any FTP server
 6288 that is not individually configured.  Most of your FTP servers will most likely
 6289 end up using the default configuration.
 6290 
 6291 \subsubsection{Example Default FTP Server Configuration}
 6292 
 6293 \begin{verbatim}
 6294     preprocessor ftp_telnet_protocol: \
 6295         ftp server default ports { 21 } 
 6296 \end{verbatim}
 6297 
 6298 Refer to \pageref{sub:default ftp server config} for the list of options set in default ftp server configuration.
 6299 
 6300 \paragraph{Configuration by IP Address}
 6301 
 6302 This format is very similar to ``default'', the only difference being that
 6303 specific IPs can be configured.
 6304 
 6305 \subsubsection{Example IP specific FTP Server Configuration}
 6306 
 6307 \begin{verbatim}
 6308     preprocessor _telnet_protocol: \
 6309         ftp server 10.1.1.1 ports { 21 } ftp_cmds { XPWD XCWD }
 6310 \end{verbatim}
 6311 
 6312 \subsubsection{FTP Server Configuration Options}
 6313 
 6314 \begin{slist}
 6315 \item \texttt{ports $\{ <$port$> [<$port$> <...>] \}$}
 6316 
 6317 This is how the user configures which ports to decode as FTP command channel
 6318 traffic.  Typically port 21 will be included.
 6319 
 6320 \item \texttt{print\_cmds}
 6321 
 6322 During initialization, this option causes the preprocessor to print the
 6323 configuration for each of the FTP commands for this server.  
 6324 
 6325 \item \texttt{ftp\_cmds $\{ cmd [cmd] \}$ }
 6326 
 6327 The preprocessor is configured to alert when it sees an FTP command that is not
 6328 allowed by the server.
 6329 
 6330 This option specifies a list of additional commands allowed by this server,
 6331 outside of the default FTP command set as specified in RFC 959.  This may be
 6332 used to allow the use of the 'X' commands identified in RFC 775, as well as any
 6333 additional commands as needed.
 6334 
 6335 For example:
 6336 
 6337 \begin{verbatim}
 6338     ftp_cmds { XPWD XCWD XCUP XMKD XRMD }
 6339 \end{verbatim}
 6340 
 6341 \item \texttt{def\_max\_param\_len $<$number$>$}
 6342 
 6343 This specifies the default maximum allowed parameter length for an FTP command.
 6344 It can be used as a basic buffer overflow detection.
 6345 
 6346 \item \texttt{alt\_max\_param\_len $<$number$>$ $\{ cmd [cmd] \}$}
 6347 
 6348 This specifies the maximum allowed parameter length for the specified FTP
 6349 command(s).  It can be used as a more specific buffer overflow detection.  For
 6350 example the USER command -- usernames may be no longer than 16 bytes, so the
 6351 appropriate configuration would be:
 6352 
 6353 \begin{verbatim}
 6354     alt_max_param_len 16 { USER }
 6355 \end{verbatim}
 6356 
 6357 \item \texttt{chk\_str\_fmt $\{ cmd [cmd] \}$}
 6358 
 6359 This option causes a check for string format attacks in the specified commands. 
 6360 
 6361 \item \texttt{cmd\_validity cmd $<$ fmt $>$}
 6362 
 6363 This option specifies the valid format for parameters of a given command.
 6364 
 6365 fmt must be enclosed in $<>$'s and may contain the following:
 6366 
 6367 \begin{center}
 6368 \begin{tabular}{| l | p{3in} |}
 6369 
 6370 \hline
 6371 \textbf{Value} & \textbf{Description} \\
 6372 \hline
 6373 
 6374 \hline
 6375 int & Parameter must be an integer \\
 6376 
 6377 \hline
 6378 number & Parameter must be an integer between 1 and 255 \\
 6379 
 6380 \hline
 6381 char $<$chars$>$ & Parameter must be a single character, one of $<$chars$>$ \\
 6382 
 6383 \hline
 6384 date $<$datefmt$>$ & Parameter follows format specified, where:
 6385 
 6386 \begin{tabular}{ l l }
 6387 n & Number \\
 6388 C & Character \\
 6389 $[]$ & optional format enclosed \\
 6390 $|$ & OR \\
 6391 $\{\}$ & choice of options \\
 6392 . + - & literal \\
 6393 \end{tabular} \\
 6394 
 6395 \hline
 6396 string & Parameter is a string (effectively unrestricted) \\
 6397 
 6398 \hline
 6399 host\_port & Parameter must be a host/port specified, per RFC 959 \\
 6400 
 6401 \hline
 6402 long\_host\_port & Parameter must be a long host port specified, per RFC 1639 \\
 6403 
 6404 \hline
 6405 extended\_host\_port & Parameter must be an extended host port specified, per RFC 2428 \\
 6406 
 6407 \hline
 6408 $\{\}$, $|$ & One of choices enclosed within, separated by $|$ \\
 6409 
 6410 \hline
 6411 $\{\}$, $[]$ & One of the choices enclosed within $\{\}$, optional value enclosed within $[]$ \\
 6412 
 6413 \hline
 6414 \end{tabular}
 6415 \end{center}
 6416 
 6417 Examples of the cmd\_validity option are shown below.  These examples are the
 6418 default checks, per RFC 959 and others performed by the preprocessor.
 6419 
 6420 \begin{verbatim}
 6421     cmd_validity MODE <char SBC>
 6422     cmd_validity STRU <char FRP>
 6423     cmd_validity ALLO < int [ char R int ] >
 6424     cmd_validity TYPE < { char AE [ char NTC ] | char I | char L [ number ] } >
 6425     cmd_validity PORT < host_port >
 6426 \end{verbatim}
 6427 
 6428 A cmd\_validity line can be used to override these defaults and/or add a check
 6429 for other commands.
 6430 
 6431 \begin{verbatim}
 6432     # This allows additional modes, including mode Z which allows for
 6433     # zip-style compression.
 6434     cmd_validity MODE < char ASBCZ >
 6435     
 6436     # Allow for a date in the MDTM command.
 6437     cmd_validity MDTM < [ date nnnnnnnnnnnnnn[.n[n[n]]] ] string >
 6438 \end{verbatim}
 6439 
 6440 MDTM is an off case that is worth discussing.  While not part of an established
 6441 standard, certain FTP servers accept MDTM commands that set the modification
 6442 time on a file.  The most common among servers that do, accept a format using
 6443 YYYYMMDDHHmmss[.uuu].  Some others accept a format using YYYYMMDDHHmmss[+|-]TZ
 6444 format.  The example above is for the first case (time format as specified in
 6445 http://www.ietf.org/internet-drafts/draft-ietf-ftpext-mlst-16.txt)
 6446 
 6447 To check validity for a server that uses the TZ format, use the following:
 6448 
 6449 \begin{verbatim}
 6450     cmd_validity MDTM < [ date nnnnnnnnnnnnnn[{+|-}n[n]] ] string >
 6451 \end{verbatim}
 6452 
 6453 \item \texttt{telnet\_cmds $<$yes$|$no$>$}
 6454 
 6455 This option turns on detection and alerting when telnet escape sequences are
 6456 seen on the FTP command channel.  Injection of telnet escape sequences could be
 6457 used as an evasion attempt on an FTP command channel.
 6458 
 6459 \item \texttt{ignore\_telnet\_erase\_cmds $<$yes|no$>$}
 6460 
 6461 This option allows Snort to ignore telnet escape sequences for erase character
 6462 (TNC EAC) and erase line (TNC EAL) when normalizing FTP command channel.  Some FTP
 6463 servers do not process those telnet escape sequences.
 6464 
 6465 \item \texttt{data\_chan}
 6466 
 6467 This option causes the rest of snort (rules, other preprocessors) to ignore FTP
 6468 data channel connections.  Using this option means that \textbf{NO INSPECTION}
 6469 other than TCP state will be performed on FTP data transfers.  It can be used
 6470 to improve performance, especially with large file transfers from a trusted
 6471 source.   If your rule set includes virus-type rules, it is recommended that
 6472 this option not be used.
 6473 
 6474 Use of the "data\_chan" option is deprecated in favor of the
 6475 "ignore\_data\_chan" option. "data\_chan" will be removed in a future release.
 6476 
 6477 \item \texttt{ignore\_data\_chan $<$yes$|$no$>$}
 6478 
 6479 This option causes the rest of Snort (rules, other preprocessors) to ignore FTP
 6480 data channel connections.  Setting this option to "yes" means that \textbf{NO
 6481 INSPECTION} other than TCP state will be performed on FTP data transfers.  It
 6482 can be used to improve performance, especially with large file transfers from a
 6483 trusted source.  If your rule set includes virus-type rules, it is recommended
 6484 that this option not be used.
 6485 
 6486 \end{slist}
 6487 
 6488 \subsubsection{FTP Server Base Configuration Options}
 6489 \label{sub:default ftp server config}
 6490 
 6491 The base FTP server configuration is as follows.  Options specified in the
 6492 configuration file will modify this set of options.  FTP commands are added to
 6493 the set of allowed commands.  The other options will override those in the base
 6494 configuration.
 6495 
 6496 \begin{verbatim}
 6497     def_max_param_len 100
 6498     ftp_cmds { USER PASS ACCT CWD CDUP SMNT 
 6499            QUIT REIN TYPE STRU MODE RETR 
 6500            STOR STOU APPE ALLO REST RNFR 
 6501            RNTO ABOR DELE RMD MKD PWD LIST 
 6502                NLST SITE SYST STAT HELP NOOP } 
 6503     ftp_cmds { AUTH ADAT PROT PBSZ CONF ENC } 
 6504     ftp_cmds { PORT PASV LPRT LPSV EPRT EPSV } 
 6505     ftp_cmds { FEAT OPTS } 
 6506     ftp_cmds { MDTM REST SIZE MLST MLSD } 
 6507     alt_max_param_len 0 { CDUP QUIT REIN PASV STOU ABOR PWD SYST NOOP } 
 6508     cmd_validity MODE < char SBC > 
 6509     cmd_validity STRU < char FRPO [ string ] > 
 6510     cmd_validity ALLO < int [ char R int ] > 
 6511     cmd_validity TYPE < { char AE [ char NTC ] | char I | char L [ number ] } > 
 6512     cmd_validity PORT < host_port > 
 6513     cmd_validity LPRT < long_host_port > 
 6514     cmd_validity EPRT < extd_host_port > 
 6515     cmd_validity EPSV < [ { '1' | '2' | 'ALL' } ] >
 6516 \end{verbatim}
 6517 
 6518 \subsubsection{FTP Client Configuration}
 6519 
 6520 Similar to the FTP Server configuration, the FTP client configurations has two
 6521 types: default, and by IP address.
 6522 
 6523 \paragraph{Default}
 6524 
 6525 This configuration supplies the default client configuration for any FTP client
 6526 that is not individually configured.  Most of your FTP clients will most likely
 6527 end up using the default configuration.
 6528 
 6529 \subsubsection{Example Default FTP Client Configuration}
 6530 \begin{verbatim}
 6531     preprocessor ftp_telnet_protocol: \
 6532         ftp client default bounce no max_resp_len 200
 6533 \end{verbatim}
 6534 
 6535 \paragraph{Configuration by IP Address}
 6536 
 6537 This format is very similar to ``default'', the only difference being that
 6538 specific IPs can be configured.
 6539 
 6540 \subsubsection{Example IP specific FTP Client Configuration}
 6541 
 6542 \begin{verbatim}
 6543     preprocessor ftp_telnet_protocol: \
 6544         ftp client 10.1.1.1 bounce yes max_resp_len 500
 6545 \end{verbatim}
 6546 
 6547 \subsubsection{FTP Client Configuration Options}
 6548 
 6549 \begin{slist}
 6550 \item \texttt{max\_resp\_len $<$number$>$}
 6551 
 6552 This specifies the maximum allowed response length to an FTP command accepted
 6553 by the client.  It can be used as a basic buffer overflow detection.
 6554 
 6555 \item \texttt{bounce $<$yes|no$>$}
 6556 
 6557 This option turns on detection and alerting of FTP bounce attacks.  An FTP
 6558 bounce attack occurs when the FTP PORT command is issued and the specified host
 6559 does not match the host of the client.
 6560 
 6561 \item \texttt{bounce\_to $<$ CIDR,[port$|$portlow,porthi] $>$}
 6562 
 6563 When the bounce option is turned on, this allows the PORT command to use the IP
 6564 address (in CIDR format) and port (or inclusive port range) without generating
 6565 an alert.  It can be used to deal with proxied FTP connections where the FTP
 6566 data channel is different from the client.
 6567 
 6568 A few examples:
 6569 
 6570 \begin{itemize}
 6571 \item Allow bounces to 192.162.1.1 port 20020 -- i.e., the use of
 6572 \texttt{PORT 192,168,1,1,78,52}.
 6573 
 6574 \begin{verbatim}
 6575     bounce_to { 192.168.1.1,20020 }
 6576 \end{verbatim}
 6577 
 6578 \item Allow bounces to 192.162.1.1 ports 20020 through 20040 -- i.e., the use of
 6579 \texttt{PORT 192,168,1,1,78,xx}, where xx is 52 through 72 inclusive.
 6580 
 6581 \begin{verbatim}
 6582     bounce_to { 192.168.1.1,20020,20040 }
 6583 \end{verbatim}
 6584 
 6585 \item Allow bounces to 192.162.1.1 port 20020 and 192.168.1.2 port 20030.
 6586 
 6587 \begin{verbatim}
 6588     bounce_to { 192.168.1.1,20020 192.168.1.2,20030 }
 6589 \end{verbatim}
 6590 
 6591 \item Allows bounces to IPv6 address fe8::5 port 59340.  
 6592 
 6593 \begin{verbatim}
 6594     bounce_to { fe8::5,59340 }
 6595 \end{verbatim}
 6596 
 6597 
 6598 \end{itemize}
 6599 
 6600 \item \texttt{telnet\_cmds $<$yes|no$>$}
 6601 
 6602 This option turns on detection and alerting when telnet escape sequences are
 6603 seen on the FTP command channel.  Injection of telnet escape sequences could be
 6604 used as an evasion attempt on an FTP command channel.
 6605 
 6606 \item \texttt{ignore\_telnet\_erase\_cmds $<$yes|no$>$}
 6607 
 6608 This option allows Snort to ignore telnet escape sequences for erase character
 6609 (TNC EAC) and erase line (TNC EAL) when normalizing FTP command channel.  Some FTP
 6610 clients do not process those telnet escape sequences.
 6611 
 6612 \end{slist}
 6613 
 6614 \subsubsection{Examples/Default Configuration from snort.conf}
 6615 \begin{verbatim}
 6616     preprocessor ftp_telnet: \
 6617         global \
 6618         encrypted_traffic yes \
 6619         inspection_type stateful
 6620 
 6621     preprocessor ftp_telnet_protocol:\
 6622         telnet \
 6623         normalize \
 6624         ayt_attack_thresh 200
 6625 
 6626     # This is consistent with the FTP rules as of 18 Sept 2004.
 6627     # Set CWD to allow parameter length of 200
 6628     # MODE has an additional mode of Z (compressed)
 6629     # Check for string formats in USER & PASS commands
 6630     # Check MDTM commands that set modification time on the file.
 6631 
 6632     preprocessor ftp_telnet_protocol: \
 6633         ftp server default \
 6634         def_max_param_len 100 \
 6635         alt_max_param_len 200 { CWD } \
 6636         cmd_validity MODE < char ASBCZ > \
 6637         cmd_validity MDTM < [ date nnnnnnnnnnnnnn[.n[n[n]]] ] string > \
 6638         chk_str_fmt { USER PASS RNFR RNTO SITE MKD } \
 6639         telnet_cmds yes \
 6640         ignore_data_chan yes
 6641 
 6642     preprocessor ftp_telnet_protocol: \
 6643         ftp client default \
 6644         max_resp_len 256 \
 6645         bounce yes \
 6646         telnet_cmds yes
 6647 \end{verbatim}
 6648 
 6649 \subsection{SSH}
 6650 \label{sub:ssh}
 6651 
 6652 The SSH preprocessor detects the following exploits: Challenge-Response Buffer
 6653 Overflow, CRC 32, Secure CRT, and the Protocol Mismatch exploit.
 6654 
 6655 Both Challenge-Response Overflow and CRC 32 attacks occur after the key
 6656 exchange, and are therefore encrypted.  Both attacks involve sending a large
 6657 payload (20kb+) to the server immediately after the authentication challenge.
 6658 To detect the attacks, the SSH preprocessor counts the number of bytes
 6659 transmitted to the server.  If those bytes exceed a predefined limit within a
 6660 predefined number of packets, an alert is generated.  Since the
 6661 Challenge-Response Overflow only effects SSHv2 and CRC 32 only effects SSHv1,
 6662 the SSH version string exchange is used to distinguish the attacks.
 6663 
 6664 The Secure CRT and protocol mismatch exploits are observable before the key
 6665 exchange.
 6666 
 6667 \subsubsection{Configuration}
 6668 
 6669 By default, all alerts are disabled and the preprocessor checks traffic on port
 6670 22.
 6671 
 6672 The available configuration options are described below.
 6673 
 6674 \begin{slist}
 6675 
 6676 \item \texttt{server\_ports $\{ <$port$> [<$port$> <...>] \}$}
 6677 
 6678 This option specifies which ports the SSH preprocessor should inspect traffic
 6679 to.
 6680 
 6681 \item \texttt{max\_encrypted\_packets $<$ number $>$}
 6682 
 6683 The number of stream reassembled encrypted packets that Snort will inspect before ignoring a given
 6684 SSH session. The SSH vulnerabilities that Snort can detect all happen at the
 6685 very beginning of an SSH session. Once max\_encrypted\_packets packets have been
 6686 seen, Snort ignores the session to increase performance. The default is set to 25.
 6687 This value can be set from 0 to 65535.
 6688 
 6689 \item \texttt{max\_client\_bytes $<$ number $>$}
 6690 
 6691 The number of unanswered bytes allowed to be transferred before alerting on
 6692 Challenge-Response Overflow or CRC 32. This number must be hit before
 6693 max\_encrypted\_packets packets are sent, or else Snort will ignore the traffic.
 6694 The default is set to 19600. This value can be set from 0 to 65535.
 6695 
 6696 \item \texttt{max\_server\_version\_len $<$ number $>$}
 6697 
 6698 The maximum number of bytes allowed in the SSH server version string before
 6699 alerting on the Secure CRT server version string overflow. The default is set to
 6700 80. This value can be set from 0 to 255.
 6701 
 6702 \item \texttt{autodetect}
 6703 
 6704 Attempt to automatically detect SSH.
 6705 
 6706 \item \texttt{enable\_respoverflow}
 6707 
 6708 Enables checking for the Challenge-Response Overflow exploit.
 6709 
 6710 \item \texttt{enable\_ssh1crc32}
 6711 
 6712 Enables checking for the CRC 32 exploit.
 6713 
 6714 \item \texttt{enable\_srvoverflow}
 6715 
 6716 Enables checking for the Secure CRT exploit.
 6717 
 6718 \item \texttt{enable\_protomismatch}
 6719 
 6720 Enables checking for the Protocol Mismatch exploit.
 6721 
 6722 \item \texttt{enable\_badmsgdir}
 6723 
 6724 Enable alerts for traffic flowing the wrong direction. For instance, if the
 6725 presumed server generates client traffic, or if a client generates server
 6726 traffic.
 6727 
 6728 \item \texttt{enable\_paysize}
 6729 
 6730 Enables alerts for invalid payload sizes.
 6731 
 6732 \item \texttt{enable\_recognition}
 6733 
 6734 Enable alerts for non-SSH traffic on SSH ports.
 6735 
 6736 \end{slist}
 6737 
 6738 The SSH preprocessor should work by default.  After max\_encrypted\_packets is
 6739 reached, the preprocessor will stop processing traffic for a given session.  If
 6740 Challenge-Response Overflow or CRC 32 false positive, try increasing the number
 6741 of required client bytes with max\_client\_bytes.
 6742 
 6743 \subsubsection{Example Configuration from snort.conf}
 6744 
 6745 Looks for attacks on SSH server port 22.  Alerts at 19600 unacknowledged bytes
 6746 within 20 encrypted packets for the Challenge-Response Overflow/CRC32 exploits.
 6747 
 6748 \begin{verbatim}
 6749     preprocessor ssh: \
 6750         server_ports { 22 } \
 6751         max_client_bytes 19600 \
 6752         max_encrypted_packets 20 \
 6753         enable_respoverflow \
 6754         enable_ssh1crc32
 6755 \end{verbatim}
 6756 
 6757 \subsection{DNS}
 6758 \label{sub:dns}
 6759 
 6760 The DNS preprocessor decodes DNS Responses and can detect the following
 6761 exploits: DNS Client RData Overflow, Obsolete Record Types, and Experimental
 6762 Record Types.
 6763 
 6764 DNS looks at DNS Response traffic over UDP and TCP and it requires Stream
 6765 preprocessor to be enabled for TCP decoding.
 6766 
 6767 \subsubsection{Configuration}
 6768 
 6769 By default, all alerts are disabled and the preprocessor checks traffic on port
 6770 53.
 6771 
 6772 The available configuration options are described below.
 6773 
 6774 \begin{slist}
 6775 
 6776 \item \texttt{ports $\{ <$port$> [<$port$> <...>] \}$}
 6777 
 6778 This option specifies the source ports that the DNS preprocessor should inspect
 6779 traffic.
 6780 
 6781 \item \texttt{enable\_obsolete\_types}
 6782 
 6783 Alert on Obsolete (per RFC 1035) Record Types
 6784 
 6785 \item \texttt{enable\_experimental\_types}
 6786 
 6787 Alert on Experimental (per RFC 1035) Record Types
 6788 
 6789 \item \texttt{enable\_rdata\_overflow}
 6790 
 6791 Check for DNS Client RData TXT Overflow
 6792 
 6793 \end{slist}
 6794 
 6795 The DNS preprocessor does nothing if none of the 3 vulnerabilities it checks
 6796 for are enabled.  It will not operate on TCP sessions picked up midstream, and
 6797 it will cease operation on a session if it loses state because of missing data
 6798 (dropped packets).
 6799 
 6800 \subsubsection{Examples/Default Configuration from snort.conf}
 6801 
 6802 Looks for traffic on DNS server port 53.  Check for the DNS Client RData
 6803 overflow vulnerability.  Do not alert on obsolete or experimental RData record
 6804 types.
 6805 
 6806 \begin{verbatim}
 6807     preprocessor dns: \
 6808         ports { 53 } \
 6809         enable_rdata_overflow
 6810 \end{verbatim}
 6811 
 6812 \subsection{SSL/TLS}
 6813 \label{sub:SSL/TLS}
 6814 
 6815 Encrypted traffic should be ignored by Snort for both performance reasons and
 6816 to reduce false positives.  The SSL Dynamic Preprocessor (SSLPP) decodes SSL
 6817 and TLS traffic and optionally determines if and when Snort should stop
 6818 inspection of it.
 6819 
 6820 Typically, SSL is used over port 443 as HTTPS.  By enabling the SSLPP to
 6821 inspect port 443 and enabling the noinspect\_encrypted option, only the SSL
 6822 handshake of each connection will be inspected.  Once the traffic is determined
 6823 to be encrypted, no further inspection of the data on the connection is made.
 6824 
 6825 By default, SSLPP looks for a handshake followed by encrypted traffic traveling
 6826 to both sides.  If one side responds with an indication that something has
 6827 failed, such as the handshake, the session is not marked as encrypted.
 6828 Verifying that faultless encrypted traffic is sent from both endpoints ensures
 6829 two things: the last client-side handshake packet was not crafted to evade
 6830 Snort, and that the traffic is legitimately encrypted.
 6831 
 6832 In some cases, especially when packets may be missed, the only observed
 6833 response from one endpoint will be TCP ACKs.  Therefore, if a user knows that
 6834 server-side encrypted data can be trusted to mark the session as encrypted, the
 6835 user should use the 'trustservers' option, documented below.
 6836 
 6837 \subsubsection{Configuration}
 6838 
 6839 \begin{slist}
 6840 
 6841 \item \texttt{ports $\{ <$port$> [<$port$> <...>] \}$}
 6842 
 6843 This option specifies which ports SSLPP will inspect traffic on.
 6844 
 6845 By default, SSLPP watches the following ports:
 6846     
 6847 \begin{itemize}
 6848     \item \texttt{443}     HTTPS   
 6849     \item \texttt{465}     SMTPS   
 6850     \item \texttt{563}     NNTPS                                                                
 6851     \item \texttt{636}     LDAPS
 6852     \item \texttt{989}     FTPS
 6853     \item \texttt{992}     TelnetS  
 6854     \item \texttt{993}     IMAPS                 
 6855     \item \texttt{994}     IRCS
 6856     \item \texttt{995}     POPS
 6857 \end{itemize}
 6858 
 6859 \item \texttt{noinspect\_encrypted}
 6860 
 6861 Disable inspection on traffic that is encrypted.  Default is off.
 6862 
 6863 \item \texttt{max\_heartbeat\_length}
 6864 
 6865 Maximum length of heartbeat record allowed.  This config option is 
 6866 used to detect the heartbleed attacks.  The allowed range is 0 to 65535. 
 6867 Setting the value to 0 turns off the heartbeat length checks. For heartbeat 
 6868 requests, if the payload size of the request record is greater than the 
 6869 max\_heartbeat\_length an alert with sid 3 and gid 137 is generated.  
 6870 For heartbeat responses, if the record size itself is greater than 
 6871 the max\_heartbeat\_length an alert with sid 4 and gid 137 is generated. Default
 6872 is off.
 6873 
 6874 \item \texttt{trustservers}
 6875 
 6876 Disables the requirement that application (encrypted) data must be observed on
 6877 both sides of the session before a session is marked encrypted.  Use this
 6878 option for slightly better performance if you trust that your servers are not
 6879 compromised.  This requires the \texttt{noinspect\_encrypted} option to be
 6880 useful.  Default is off.  \end{slist}
 6881 
 6882 \subsubsection{Examples/Default Configuration from snort.conf}
 6883 
 6884 Enables the SSL preprocessor and tells it to disable inspection on encrypted
 6885 traffic.
 6886 
 6887 \begin{verbatim}
 6888     preprocessor ssl: noinspect_encrypted
 6889 \end{verbatim}
 6890 
 6891 \subsubsection{Rule Options}
 6892 
 6893 The following rule options are supported by enabling the \texttt{ssl} preprocessor:
 6894 
 6895 \begin{itemize}
 6896 \item[]
 6897 \begin{verbatim}
 6898     ssl_version
 6899     ssl_state
 6900 \end{verbatim}
 6901 \end{itemize}
 6902 
 6903 \texttt{ssl\_version}
 6904 \label{ssl:ssl_version}
 6905 \begin{itemize}
 6906 
 6907 \item[] The \texttt{ssl\_version} rule option tracks the version negotiated between
 6908 the endpoints of the SSL encryption.  The list of version identifiers are below, and
 6909 more than one identifier can be specified, via a comma separated list.  Lists of
 6910 identifiers are OR'ed together.
 6911 
 6912 The option will match if any one of the OR'ed versions are used in the SSL
 6913 connection.  To check for two or more SSL versions in use simultaneously, multiple
 6914 \texttt{ssl\_version} rule options should be used.
 6915 
 6916 \textit{Syntax}
 6917 \footnotesize
 6918 \begin{verbatim}
 6919    ssl_version: <version-list>
 6920 
 6921    version-list = version | version , version-list
 6922    version      = ["!"] "sslv2" | "sslv3" | "tls1.0" | "tls1.1" | "tls1.2"
 6923 \end{verbatim}
 6924 
 6925 \textit{Examples}
 6926 \begin{verbatim}
 6927    ssl_version:sslv3;
 6928    ssl_version:tls1.0,tls1.1,tls1.2;
 6929    ssl_version:!sslv2;
 6930 \end{verbatim}
 6931 
 6932 \end{itemize}
 6933 
 6934 \texttt{ssl\_state}
 6935 \label{ssl:ssl_state}
 6936 \begin{itemize}
 6937     
 6938 \item[] The \texttt{ssl\_state} rule option tracks the state of the SSL encryption
 6939 during the process of hello and key exchange.  The list of states are below.  More than
 6940 one state can be specified, via a comma separated list, and are OR'ed together.
 6941 
 6942 The option will match if the connection is currently in any one of the OR'ed states.
 6943 To ensure the connection has reached each of a set of states, multiple rules using
 6944 the \texttt{ssl\_state} rule option should be used.
 6945 
 6946 \textit{Syntax}
 6947 \footnotesize
 6948 \begin{verbatim}
 6949    ssl_state: <state-list>
 6950 
 6951    state-list = state | state , state-list
 6952    state      = ["!"] "client_hello" | "server_hello" | "client_keyx" | "server_keyx" | "unknown"
 6953 \end{verbatim}
 6954 
 6955 
 6956 \textit{Examples}
 6957 \begin{verbatim}
 6958    ssl_state:client_hello;
 6959    ssl_state:client_keyx,server_keyx;
 6960    ssl_state:!server_hello;
 6961 \end{verbatim}
 6962 
 6963 \end{itemize}
 6964 
 6965 \subsection{ARP Spoof Preprocessor}
 6966 \label{sub:arpspoof}
 6967 
 6968 The ARP spoof preprocessor decodes ARP packets and detects ARP attacks, unicast
 6969 ARP requests, and inconsistent Ethernet to IP mapping.
 6970 
 6971 When no arguments are specified to arpspoof, the preprocessor inspects Ethernet
 6972 addresses and the addresses in the ARP packets. When inconsistency occurs, an
 6973 alert with GID 112 and SID 2 or 3 is generated.
 6974 
 6975 When "\texttt{-unicast}" is specified as the argument of arpspoof, the
 6976 preprocessor checks for unicast ARP requests. An alert with GID 112 and SID 1
 6977 will be generated if a unicast ARP request is detected.
 6978 
 6979 Specify a pair of IP and hardware address as the argument to
 6980 \texttt{arpspoof\_detect\_host}.  The host with the IP address should be on the
 6981 same layer 2 segment as Snort is.  Specify one host IP MAC combo per line. The
 6982 preprocessor will use this list when detecting ARP cache overwrite attacks.
 6983 Alert SID 4 is used in this case.
 6984 
 6985 \subsubsection{Format}
 6986 
 6987 \begin{verbatim}
 6988     preprocessor arpspoof[: -unicast]
 6989     preprocessor arpspoof_detect_host: ip mac                   
 6990 \end{verbatim}
 6991 
 6992 \begin{table}[h]
 6993 \begin{center}
 6994 \begin{tabular}{| l | l |}
 6995 
 6996 \hline 
 6997 \textbf{Option} & \textbf{Description}\\
 6998 \hline
 6999 
 7000 \hline
 7001 \texttt{ip} & IP address.\\
 7002 
 7003 \hline 
 7004 \texttt{mac} & The Ethernet address corresponding to the preceding IP. \\
 7005 \hline
 7006 
 7007 \end{tabular}
 7008 \end{center}
 7009 \end{table}
 7010 
 7011 \subsubsection{Example Configuration}
 7012 
 7013 The first example configuration does neither unicast detection nor ARP mapping
 7014 monitoring. The preprocessor merely looks for Ethernet address inconsistencies.
 7015 
 7016 \begin{verbatim}
 7017     preprocessor arpspoof
 7018 \end{verbatim}
 7019 
 7020 The next example configuration does not do unicast detection but monitors ARP
 7021 mapping for hosts 192.168.40.1 and 192.168.40.2.
 7022 
 7023 \begin{verbatim}
 7024     preprocessor arpspoof
 7025     preprocessor arpspoof_detect_host: 192.168.40.1 f0:0f:00:f0:0f:00
 7026     preprocessor arpspoof_detect_host: 192.168.40.2 f0:0f:00:f0:0f:01
 7027 \end{verbatim}
 7028 
 7029 The third example configuration has unicast detection enabled.
 7030 
 7031 \begin{verbatim}
 7032     preprocessor arpspoof: -unicast
 7033     preprocessor arpspoof_detect_host: 192.168.40.1 f0:0f:00:f0:0f:00
 7034     preprocessor arpspoof_detect_host: 192.168.40.2 f0:0f:00:f0:0f:01
 7035 \end{verbatim}
 7036 
 7037 \subsection{DCE/RPC 2 Preprocessor}
 7038 \label{sub:dcerpc2}
 7039 
 7040 The main purpose of the preprocessor is to perform SMB desegmentation and
 7041 DCE/RPC defragmentation to avoid rule evasion using these techniques.  SMB
 7042 desegmentation is performed for the following commands that can be used to
 7043 transport DCE/RPC requests and responses: \texttt{Write}, \texttt{Write Block
 7044 Raw}, \texttt{Write and Close}, \texttt{Write AndX}, \texttt{Transaction},
 7045 \texttt{Transaction Secondary}, \texttt{Read}, \texttt{Read Block Raw} and
 7046 \texttt{Read AndX}.  The following transports are supported for DCE/RPC: SMB,
 7047 TCP, UDP and RPC over HTTP v.1 proxy and server.  New rule options have been
 7048 implemented to improve performance, reduce false positives and reduce the count
 7049 and complexity of DCE/RPC based rules.
 7050 
 7051 \subsubsection{Dependency Requirements}
 7052 
 7053 For proper functioning of the preprocessor:
 7054 
 7055 \begin{itemize}
 7056 
 7057 \item Stream session tracking must be enabled, i.e. \texttt{stream5}.  The
 7058 preprocessor requires a session tracker to keep its data.
 7059 
 7060 \item Stream reassembly must be performed for TCP sessions. If it is decided
 7061 that a session is SMB or DCE/RPC, either through configured ports, servers or
 7062 autodetecting, the \texttt{dcerpc2} preprocessor will enable stream reassembly
 7063 for that session if necessary.
 7064 
 7065 \item IP defragmentation should be enabled, i.e. the \texttt{frag3}
 7066 preprocessor should be enabled and configured.
 7067 
 7068 \end{itemize}
 7069 
 7070 \subsubsection{Target Based}
 7071 
 7072 There are enough important differences between Windows and Samba versions that
 7073 a target based approach has been implemented. Some important differences:\\
 7074 
 7075 \textit{Named pipe instance tracking}
 7076 
 7077 \begin{itemize}
 7078 
 7079 \item[] A combination of valid login handle or UID, share handle or TID and
 7080 file/named pipe handle or FID must be used to write data to a named pipe.  The
 7081 binding between these is dependent on OS/software version.
 7082 
 7083 \begin{itemize}
 7084 
 7085 \item[] Samba 3.0.22 and earlier
 7086 
 7087 \begin{itemize}
 7088 
 7089 \item[] Any valid UID and TID, along with a valid FID can be used to make a
 7090 request, however, if the TID used in creating the FID is deleted (via a tree
 7091 disconnect), the FID that was created using this TID becomes invalid, i.e. no
 7092 more requests can be written to that named pipe instance.
 7093 
 7094 \end{itemize}
 7095 
 7096 \item[] Samba greater than 3.0.22
 7097 
 7098 \begin{itemize}
 7099 
 7100 \item[] Any valid TID, along with a valid FID can be used to make a request.
 7101 However, only the UID used in opening the named pipe can be used to make a
 7102 request using the FID handle to the named pipe instance. If the TID used to
 7103 create the FID is deleted (via a tree disconnect), the FID that was created
 7104 using this TID becomes invalid, i.e. no more requests can be written to that
 7105 named pipe instance. If the UID used to create the named pipe instance is
 7106 deleted (via a \texttt{Logoff AndX}), since it is necessary in making a request
 7107 to the named pipe, the FID becomes invalid.
 7108 
 7109 \end{itemize}
 7110 
 7111 \item[] Windows 2003
 7112 \item[] Windows XP
 7113 \item[] Windows Vista
 7114 
 7115 \begin{itemize}
 7116 
 7117 \item[] These Windows versions require strict binding between the UID, TID and
 7118 FID used to make a request to a named pipe instance. Both the UID and TID used
 7119 to open the named pipe instance must be used when writing data to the same
 7120 named pipe instance. Therefore, deleting either the UID or TID invalidates the
 7121 FID.
 7122 
 7123 \end{itemize}
 7124 
 7125 \item[] Windows 2000
 7126 
 7127 \begin{itemize}
 7128 
 7129 \item[] Windows 2000 is interesting in that the first request to a named pipe
 7130 must use the same binding as that of the other Windows versions. However,
 7131 requests after that follow the same binding as Samba 3.0.22 and earlier, i.e.
 7132 no binding. It also follows Samba greater than 3.0.22 in that deleting the UID
 7133 or TID used to create the named pipe instance also invalidates it.
 7134 
 7135 \end{itemize}
 7136 \end{itemize}
 7137 \end{itemize}
 7138 
 7139 \textit{Accepted SMB commands}
 7140 \begin{itemize}
 7141 
 7142 \item[] Samba in particular does not recognize certain commands under an
 7143 \texttt{IPC\$} tree.
 7144 \begin{itemize}
 7145 \item[] Samba (all versions)
 7146 \begin{itemize}
 7147 \item[] Under an \texttt{IPC\$} tree, does not accept:
 7148 \begin{itemize}
 7149 \item[] \texttt{Open}
 7150 \item[] \texttt{Write And Close}
 7151 \item[] \texttt{Read}
 7152 \item[] \texttt{Read Block Raw}
 7153 \item[] \texttt