binder.txt
bugs.txt
building.txt
+ concepts.txt
daq.txt
dcerpc.txt
differences.txt
snort_manual.text
snort_manual.txt
snorty.png
- start.txt
style.txt
terms.txt
+ tutorial.txt
usage.txt
wizard.txt
)
COMMAND mkdir -p ${PDF_DOC_TMP}
)
- add_custom_command (
+ add_custom_command (
OUTPUT snort_manual.pdf
COMMAND cp ${LIST_DIR_SOURCES} ${BINARY_DIR_BUILT_SOURCES} .
COMMAND ${ASCIIDOC_A2X_EXE} ${PDF_A2X_ARGS} snort_manual.txt
binder.txt \
bugs.txt \
building.txt \
+concepts.txt \
config_changes.txt \
daq.txt \
dcerpc.txt \
snort3x.png \
snort_manual.txt \
snorty.png \
-start.txt \
style.txt \
terms.txt \
+tutorial.txt \
usage.txt \
wizard.txt
-One of the fundamental differences between Snort and Snort++ concerns configuration
-related to networks and ports. Here is a brief review of Snort's configuration for
+One of the fundamental differences between Snort 2 and Snort 3 concerns configuration
+related to networks and ports. Here is a brief review of Snort 2 configuration for
network and service related components:
* Snort's configuration has a default policy and optional policies selected by
* The default policy may also contain a list of ports to ignore.
-In Snort++, the above configurations are done in a single module called the
+In Snort 3, the above configurations are done in a single module called the
binder. Here is an example:
binder =
{
-- allow all tcp port 22:
- -- (similar to snort 2.X config ignore_ports)
+ -- (similar to Snort 2 config ignore_ports)
{ when = { proto = 'tcp', ports = '22' }, use = { action = 'allow' } },
-- select a config file by vlan
- -- (similar to snort 2.X config binding by vlan)
+ -- (similar to Snort 2 config binding by vlan)
{ when = { vlans = '1024' }, use = { file = 'vlan.lua' } },
-- use a non-default HTTP inspector for port 8080:
- -- (similar to a snort 2.X targeted preprocessor config)
+ -- (similar to a Snort 2 targeted preprocessor config)
{ when = { nets = '192.168.0.0/16', proto = 'tcp', ports = '8080' },
use = { name = 'alt_http', type = 'http_inspect' } },
-- use the default inspectors:
- -- (similar to a snort 2.X default preprocessor config)
+ -- (similar to a Snort 2 default preprocessor config)
{ when = { proto = 'tcp' }, use = { type = 'stream_tcp' } },
{ when = { service = 'http' }, use = { type = 'http_inspect' } },
==== Build
-* With cmake, make install will rebuild the docs even though when already
- built.
-
* Enabling large pcap may erroneously affect the number of packets processed
from pcaps.
clang: warning: argument unused during compilation: '-pthread'
-* It is not possible to build dynamic plugins using apple clang due to its
- limited support for thread local variables.
-
==== Config
* ip_proto doesn't work properly with reassembled packets so it can't be
used to restrict the protocol of service rules.
-* Inspector events generated while parsing TCP payload in non-IPS mode will
- indicate the wrong direction (ie they will be based on the ACK packet).
- (Same is true for Snort.)
-
==== snort2lua
* stream_tcp alert squash mechanism incorrectly squashes alerts for
different TCP packets.
-* stream_tcp gap count is broken.
-
--- /dev/null
+
+=== Terminology
+
+include::terms.txt[]
+
+=== Parameters
+
+include::params.txt[]
+
+=== Operation
+
+Snort is a signature-based IPS, which means that as it receives network
+packets it reassembles and normalizes the content so that a set of rules can
+be evaluated to detect the presence of any significant conditions that
+merit further action. A rough processing flow is as follows:
+
+////
+(pkt) -> [decode] -> [preprocess] -> [detect] -> [log] -> (verdict)
+////
+image::snort2x.png["Snort 2",width="480"]
+
+The steps are:
+
+1. Decode each packet to determine the basic network characteristics such
+as source and destination addresses and ports. A typical packet might have
+ethernet containing IP containing TCP containing HTTP (ie eth:ip:tcp:http).
+The various encapsulating protocols are examined for sanity and anomalies
+as the packet is decoded. This is essentially a stateless effort.
+
+2. Preprocess each decoded packet using accumulated state to determine the
+purpose and content of the innermost message. This step may involve
+reordering and reassembling IP fragments and TCP segments to produce the
+original application protocol data unit (PDU). Such PDUs are analyzed and
+normalized as needed to support further processing.
+
+3. Detection is a two step process. For efficiency, most rules contain a
+specific content pattern that can be searched for such that if no match is
+found no further processing is necessary. Upon start up, the rules are
+compiled into pattern groups such that a single, parallel search can be
+done for all patterns in the group. If any match is found, the full rule
+is examined according to the specifics of the signature.
+
+4. The logging step is where Snort saves any pertinent information
+resulting from the earlier steps. More generally, this is where other
+actions can be taken as well such as blocking the packet.
+
+
+==== Snort 2 Processing
+
+The preprocess step in Snort 2 is highly configurable. Arbitrary
+preprocessors can be loaded dynamically at startup, configured in
+snort.conf, and then executed at runtime. Basically, the preprocessors are
+put into a list which is iterated for each packet. Recent versions have
+tweaked the list handling some, but the same basic architecture has allowed
+Snort 2 to grow from a sniffer, with no preprocessing, to a full-fledged
+IPS, with lots of preprocessing.
+
+While this "list of plugins" approach has considerable flexibility, it
+hampers future development when the flow of data from one preprocessor to
+the next depends on traffic conditions, a common situation with advanced
+features like application identification. In this case, a preprocessor
+like HTTP may be extracting and normalizing data that ultimately is not
+used, or appID may be repeatedly checking for data that is just not
+available.
+
+Callbacks help break out of the preprocess straitjacket. This is where one
+preprocessor supplies another with a function to call when certain data is
+available. Snort has started to take this approach to pass some HTTP and
+SIP preprocessor data to appID. However, it remains a peripheral feature
+and still requires the production of data that may not be consumed.
+
+
+==== Snort 3 Processing
+
+One of the goals of Snort 3 is to provide a more flexible framework for
+packet processing by implementing an event-driven approach. Another is to
+produce data only when needed to minimize expensive normalizations.
+However, the basic packet processing provides very similar functionality.
+
+The basic processing steps Snort 3 takes are similar to Snort 2 as seen
+in the following diagram. The preprocess step employs specific inspector
+types instead of a generalized list, but the basic procedure includes
+stateless packet decoding, TCP stream reassembly, and service specific
+analysis in both cases. (Snort 3 provides hooks for arbitrary inspectors,
+but they are not central to basic flow processing and are not shown.)
+
+////
+(pkt) -> [decode] -> [stream] -> [service] -> [detect] -> [log] -> (verdict)
+ -----------------------------------------------------
+ [appid] [firewall] [other]
+////
+image::snort3x.png["Snort 3",width="480"]
+
+However, Snort 3 also provides a more flexible mechanism than callback
+functions. By using inspection events, it is possible for an inspector to
+supply data that other inspectors can process. This is known as the
+observer pattern or publish-subscribe pattern.
+
+Note that the data is not actually published. Instead, access to the data
+is published, and that means that subscribers can access the raw or
+normalized version(s) as needed. Normalizations are done only on the first
+access, and subsequent accesses get the previously normalized data. This
+results in just in time (JIT) processing.
+
+A basic example of this in action is provided by the extra data_log plugin.
+It is a passive inspector, ie it does nothing until it receives the data it
+subscribed for ('other' in the above diagram). By adding the following to
+your snort.lua configuration, you will get a simple URI logger.
+
+ data_log = { key = 'http_raw_uri' }
+
+Inspection events coupled with pluggable inspectors provide a very flexible
+framework for implementing new features. And JIT buffer stuffers allow
+Snort to work smarter, not harder. These capabilities will be leveraged
+more and more as Snort development continues.
+
+
+=== Rules
+
+Rules tell Snort how to detect interesting conditions, such as an attack,
+and what to do when the condition is detected. Here is an example rule:
+
+ alert tcp any any -> 192.168.1.1 80 ( msg:"A ha!"; content:"attack"; sid:1; )
+
+The structure is:
+
+ action proto source dir dest ( body )
+
+Where:
+
+action - tells Snort what to do when a rule "fires", ie when the signature
+matches. In this case Snort will log the event. It can also do thing like
+block the flow when running inline.
+
+proto - tells Snort what protocol applies. This may be ip, icmp, tcp, udp,
+http, etc.
+
+source - specifies the sending IP address and port, either of which can be
+the keyword any, which is a wildcard.
+
+dir - must be either unidirectional as above or bidirectional indicated by
+<>.
+
+dest - similar to source but indicates the receiving end.
+
+body - detection and other information contained in parenthesis.
+
+There are many rule options available to construct as sophisticated a
+signature as needed. In this case we are simply looking for the "attack"
+in any TCP packet. A better rule might look like this:
+
+ alert http
+ (
+ msg:"Gotcha!";
+ flow:established, to_server;
+ http_uri:"attack";
+ sid:2;
+ )
+
+Note that these examples have a sid option, which indicates the signature
+ID. In general rules are specified by gid:sid:rev notation, where gid is
+the generator ID and rev is the revision of the rule. By default, text
+rules are gid 1 and shared-object (SO) rules are gid 3. The various
+components within Snort that generate events have 1XX gids, for example the
+decoder is gid 116. You can list the internal gids and sids with these
+commands:
+
+ $ snort --list-gids
+ $ snort --list-builtin
+
+For details on these and other options, see the reference section.
+
+=== Pattern Matching
+
+Snort evaluates rules in a two-step process which includes a fast pattern
+search and full evaluation of the signature. More details on this process
+follow.
+
+==== Rule Groups
+
+When Snort starts or reloads configuration, rules are grouped by protocol,
+port and service. For example, all TCP rules using the HTTP_PORTS variable
+will go in one group and all service HTTP rules will go in another group.
+These rule groups are compiled into multipattern search engines (MPSE)
+which are designed to search for all patterns with just a single pass
+through a given packet or buffer. You can select the algorithm to use for
+fast pattern searches with search_engine.search_method which defaults to
+'ac_bnfa', which balances speed and memory. For a faster search at the
+expense of significantly more memory, use 'ac_full'. For best performance
+and reasonable memory, download the hyperscan source from Intel.
+
+==== Fast Patterns
+
+Fast patterns are content strings that have the fast_pattern option or
+which have been selected by Snort automatically to be used as a fast
+pattern. Snort will by default choose the longest pattern in the rule
+since that is likely to be most unique. That is not always the case so add
+fast_pattern to the appropriate content option for best performance. The
+ideal fast pattern is one which, if found, is very likely to result in a
+rule match. Fast patterns that match frequently for unrelated traffic will
+cause Snort to work hard with little to show for it.
+
+Certain contents are not eligible to be used as fast patterns.
+Specifically, if a content is negated, then if it is also relative to
+another content, case sensitive, or has non-zero offset or depth, then it
+is not eligible to be used as a fast pattern.
+
+==== Rule Evaluation
+
+For each fast pattern match, the corresponding rule(s) are evaluated
+left-to-right. Rule evaluation requires checking each detection option in
+a rule and is a fairly costly process which is why fast patterns are so
+important. Rule evaluation aborts on the first non-matching option.
+
+When rule evaluation takes place, the fast pattern may or may not need to
+be searched for a second time. Note that this differs from Snort 2 which
+provided the fast_pattern:only option to designate such cases. This was
+removed because it is difficult for the rule writer get it right.
+
+=== Plugins and Scripts
+
+There are several plugin types:
+
+* Codec - to decode and encode packets
+* Inspector - like the prior preprocessors, for normalization, etc.
+* IpsOption - for detection in Snort IPS rules
+* IpsAction - for custom rule actions
+* Logger - for handling events
+* Mpse - for fast pattern matching
+* So - for dynamic rules
+
+Most plugins can be built statically or dynamically. By default they are
+all static. There is no difference in functionality between static or
+dynamic plugins but the dynamic build generates a slightly lighter weight
+binary. Either way you can add dynamic plugins with --plugin-path and
+newer versions will replace older versions, even when built statically.
+
+The power of plugins is that they have a very focused purpose and can be
+created with relative ease. For example, you can extend the rule language
+by writing your own IpsOption and it will plug in and function just like
+existing options. The extra directory has examples of each type of plugin.
+
+Some things just need to be tweaked or prototyped quickly. In addition to
+the Lua conf, which is a script that can contain functions to compute
+settings, etc., you can also script Loggers and IpsOptions.
+
other platforms.
The DAQ library is provided as an external package on snort.org. There are
-a few additional modules provided with Snort++. This section summarizes
+a few additional modules provided with Snort 3. This section summarizes
the important things you need to know to use these DAQ modules. There are
also 3rd DAQ modules available.
=== Dump Module
The dump DAQ allows you to test the various inline mode features available in
-2.9 Snort like injection and normalization.
+Snort like injection and normalization.
./snort -i <device> --daq dump
./snort -r <pcap> --daq dump
The socket module provides provides a stream socket server that will accept
up to 2 simultaneous connections and bridge them together while also
-passing data to Snort++ for inspection. The first connection accepted is
+passing data to Snort for inspection. The first connection accepted is
considered the client and the second connection accepted is considered the
server. If there is only one connection, stream data can't be forwarded
but it is still inspected.
Each read from a socket of up to snaplen bytes is passed as a packet to
-Snort++ along with a DAQ_SktHdr_t pointer in DAQ_PktHdr_t->priv_ptr.
+Snort along with a DAQ_SktHdr_t pointer in DAQ_PktHdr_t->priv_ptr.
DAQ_SktHdr_t conveys IP4 address, ports, protocol, and direction. Socket
packets can be configured to be TCP or UDP. The socket DAQ can be operated
in inline mode and is able to block packets.
-The socket DAQ uses DLT_SOCKET and requires that Snort++ load the socket
+The socket DAQ uses DLT_SOCKET and requires that Snort load the socket
codec which is included in the extra package.
-To use the socket DAQ, start Snort++ like this:
+To use the socket DAQ, start Snort like this:
./snort --plugin-path /path/to/lib/snort_extra \
--daq socket [--daq-var port=<port>] [--daq-var proto=<proto>] [-Q]
* This module only supports ip4 traffic.
-* This module is only supported by Snort++. It is not compatible with
- Snort.
+* This module is only supported by Snort 3. It is not compatible with
+ Snort 2.
* This module is primarily for development and test.
--pcap-dir path -z 8
-* This module is only supported by Snort++. It is not compatible with
- Snort.
+* This module is only supported by Snort 3. It is not compatible with
+ Snort 2.
* This module is primarily for development and test.
* This module only supports ip4 traffic.
-* This module is only supported by Snort++. It is not compatible with
- Snort.
+* This module is only supported by Snort 3. It is not compatible with
+ Snort 2.
* This module is primarily for development and test.
New rule options have been implemented to improve performance, reduce false
positives and reduce the count and complexity of DCE/RPC based rules.
-Different from snort 2x, the DCE-RPC preprocessor is split into three inspectors
+Different from Snort 2, the DCE-RPC preprocessor is split into three inspectors
- one for each transport: dce_smb, dce_tcp, dce_udp. This includes the
-configuration as well as the inspector modules. The Snort 2x server configuration
+configuration as well as the inspector modules. The Snort 2 server configuration
is now split between the inspectors. Options that are meaningful to all
inspectors, such as policy and defragmentation, are copied into each inspector
configuration. The address/port mapping is handled by the binder. Autodetect
-Snort++ differs from Snort in the following ways:
+Snort 3 differs from Snort 2 in the following ways:
* command line and conf file syntax made more uniform
* removed unused and deprecated features
(e.g.: no upper bounds on memcaps)
* assume the simplest mode of operation
(e.g.: never assume input from or output to some hardcoded filename)
-* all Snort config options are grouped into Snort++ modules
+* all Snort 2 config options are grouped into Snort 3 modules
=== Build Options
=== Conf File
-* Snort++ has a default unicode.map
-* Snort++ will not enforce an upper bound on memcaps and the like within 64 bits
-* Snort++ will supply a default *_global config if not specified
- (Snort would fatal; e.g. http_inspect_server w/o http_inspect_global)
+* Snort 3 has a default unicode.map
+* Snort 3 will not enforce an upper bound on memcaps and the like within 64 bits
+* Snort 3 will supply a default *_global config if not specified
+ (Snort 2 would fatal; e.g. http_inspect_server w/o http_inspect_global)
* address list syntax changes: [[ and ]] must be [ [ and ] ] to avoid Lua string
parsing errors (unless in quoted string)
* because the Lua conf is live code, we lose file:line locations in app error messages
* deleted layer2resets and flexresp2_*
* deleted log_ascii
* general output guideline: don't print zero counts
-* Snort++ queues decoder and inspector events to the main event queue before ips policy
+* Snort 3 queues decoder and inspector events to the main event queue before ips policy
is selected; since some events may not be enabled, the queue needs to be sized larger
- than with Snort which used an intermediate queue for decoder events.
+ than with Snort 2 which used an intermediate queue for decoder events.
* deleted the intermediate http and ftp_telnet event queues
* alert_unified2 and log_unified2 have been deleted
This section describes the changes to the Http Inspect config option "profile".
-Snort 2.X allows users to select pre-defined HTTP server profiles using the
+Snort 2 allows users to select pre-defined HTTP server profiles using the
config option "profile". The user can choose one of five predefined profiles.
When defined, this option will set defaults for other config options within
Http Inspect.
-With Snort++, the user has the flexibility of defining and fine tuning custom
+With Snort 3, the user has the flexibility of defining and fine tuning custom
profiles along with the five predefined profiles.
-Snort 2.X conf
+Snort 2 conf
preprocessor http_inspect_server: server default \
profile apache ports { 80 3128 } max_headers 200
-Snort 3.0 conf
+Snort 3 conf
http_inspect = { profile = http_profile_apache }
http_inspect.profile.max_headers = 200
Conversion
-Snort2lua can convert the existing snort.conf with the "profile" option to
-Snort3.0 compatible "profile". Please refer to the Snort2Lua post for more
+snort2lua can convert the existing snort.conf with the "profile" option to
+Snort 3 compatible "profile". Please refer to the snort2Lua post for more
details.
Examples
=== Plugins
-Snort++ uses a variety of plugins to accomplish much of its processing
+Snort uses a variety of plugins to accomplish much of its processing
objectives, including:
* Codec - to decode and encode packets
* Inspector - like the prior preprocessors, for normalization, etc.
-* IpsOption - for detection in Snort++ rules
+* IpsOption - for detection in Snort rules
* IpsAction - for custom actions
* Logger - for handling events
* Mpse - for fast pattern matching
=== Modules
-The Module is pervasive in Snort\++. It is how everything, including
-plugins, are configured. It also provides access to builtin rules. And as
-the glue that binds functionality to Snort++, the capabilities of a Module
-are expected to grow to include statistics support, etc.
+The Module is pervasive in Snort. It is how everything, including plugins,
+are configured. It also provides access to builtin rules. And as the glue
+that binds functionality to Snort, the capabilities of a Module are
+expected to grow to include statistics support, etc.
Module configuration is handled by a list of Parameters. Most parameters
can be validated by the framework, which means for example that conversion
claw = 3
}
-When the gadget table is processed, Snort++ will look for a module called
+When the gadget table is processed, Snort will look for a module called
gadget. If that Module has an associated API, it will be used to configure
a new instance of the plugin. In this case, a GadgetModule would be
instantiated, brain and claw would be set, and the Module instance would be
Module has three key virtual methods:
-* *begin()* - called when Snort++ starts processing the associated Lua
+* *begin()* - called when Snort starts processing the associated Lua
table. This is a good place to allocate any required data and set
defaults.
* *set()* - called to set each parameter after validation.
-* *end()* - called when Snort++ finishes processing the associated Lua
+* *end()* - called when Snort finishes processing the associated Lua
table. This is where additional integrity checks of related parameters
should be done.
Note that there is at most one instance of a given Module, even if multiple
plugin instances are created which use that Module. (Multiple instances
-require Snort++ binding configuration.)
+require Snort binding configuration.)
=== Inspectors
=== Codecs
-The Snort3.0 Codecs decipher raw packets. These Codecs are now completely
-pluggable; almost every Snort3.0 Codec can be built dynamically and replaced
-with an alternative, customized Codec. The pluggable nature has also made it
-easier to build new Codecs for protocols without having to touch the Snort3.0
-code base.
+The Snort Codecs decipher raw packets. These Codecs are now completely
+pluggable; almost every Snort Codec can be built dynamically and replaced
+with an alternative, customized Codec. The pluggable nature has also made
+it easier to build new Codecs for protocols without having to touch the
+Snort code base.
-The first step in creating a Codec is defining its class and protocol. Every
-Codec must inherit from the Snort3.0 Codec class defined in
-"framework/codec.h". The following is an example Codec named "example" and has
-an associated struct that is 14 bytes long.
+The first step in creating a Codec is defining its class and protocol.
+Every Codec must inherit from the Snort Codec class defined in
+"framework/codec.h". The following is an example Codec named "example" and
+has an associated struct that is 14 bytes long.
#include <cstdint>
#include <arpa/inet.h>
pointer to the raw data that has come from a wire and the length of that raw
data. The function takes this information and validates that there are enough
bytes for this protocol. If the raw data's length is less than 14 bytes, the
-function returns false and Snort3.0 discards the packet; the packet is neither
+function returns false and Snort discards the packet; the packet is neither
inspected nor processed. If the length is greater than 14 bytes, the function
populates two fields in the CodecData struct, next_prot_id and lyr_len. The
-lyr_len field tells Snort3.0 the number of bytes that this layer contains. The
-next_prot_id field provides Snort3.0 the value of the next EtherType or IP
+lyr_len field tells Snort the number of bytes that this layer contains. The
+next_prot_id field provides Snort the value of the next EtherType or IP
protocol number.
bool ExCodec::decode(const RawData& raw, CodecData& codec, DecodeData&)
45 00 00 38 00 01 00 00 40 06 5c ac 0a 01 02 03
0a 09
-How does Snort3.0 know that the IPv4 Codec has an EtherType of 0x0800? The
+How does Snort know that the IPv4 Codec has an EtherType of 0x0800? The
Codec class has a second virtual function named get_protocol_ids(). When
implementing the function, a Codec can register for any number of values
between 0x0000 - 0xFFFF. Then, if the next_proto_id is set to a value for which
get_data_link_type() can be similarly implemented.
The final step to creating a pluggable Codec is the snort_plugins array. This
-array is important because when Snort3.0 loads a dynamic library, the program
+array is important because when Snort loads a dynamic library, the program
only find plugins that are inside the snort_plugins array. In other words, if a
plugin has not been added to the snort_plugins array, that plugin will not be
-loaded into Snort3.0.
+loaded into Snort.
Although the details will not be covered in this post, the following code
-snippet is a basic CodecApi that Snort3.0 can load. This snippet can be copied
+snippet is a basic CodecApi that Snort can load. This snippet can be copied
and used with only three minor changes. First, in the function ctor, ExCodec
should be replaced with the name of the Codec that is being built. Second,
EX_NAME must match the Codec's name or Snort will be unable to load this Codec.
Third, EX_HELP should be replaced with the general description of this Codec.
Once this code snippet has been added, ExCodec is ready to be compiled and
-plugged into Snort3.0.
+plugged into Snort.
static Codec* ctor(Module*)
{ return new ExCodec; }
};
Two example Codecs are available in the extra directory on git and the extra
-tarball on the Snort3.0 page. One of those examples is the Token Ring Codec
+tarball on the Snort page. One of those examples is the Token Ring Codec
while the other example is the PIM Codec.
As a final note, there are four more virtual functions that a Codec should
packet. Unlike format, this function only sets length fields.
* log is called when either the log_codecs logger or a custom logger that calls
- PacketManager::log_protocols is used when running Snort3.0.
+ PacketManager::log_protocols is used when running Snort.
=== IPS Actions
as enable/disable/configure file type identification, file signature, or
file capture.
-In addition to all capabilities from snort 2x, we support customized file
+In addition to all capabilities from Snort 2, we support customized file
policy along with file event log.
* Supported protocols: HTTP, SMTP, IMAP, POP3, FTP, and SMB.
-One of the major undertakings for Snort 3.0 is developing a completely new
+One of the major undertakings for Snort 3 is developing a completely new
HTTP inspector. You can configure it by adding:
http_inspect = {}
changes can be made just by updating these tables.
Http_inspect is the first inspector written specifically for the new
-Snort 3.0 architecture. That provides access to one of the very best
-features of Snort 3.0: purely PDU-based inspection. The classic preprocessor
+Snort 3 architecture. That provides access to one of the very best
+features of Snort 3: purely PDU-based inspection. The classic preprocessor
processes HTTP messages, but even while doing so it is constantly aware of
IP packets and how they divide up the TCP data stream. The same HTTP
message might be processed differently depending on how the sender (bad
Google’s SPDY project and is in the process of being standardized. Despite
the name, it is better to think of HTTP/2 not as a newer version of
HTTP/1.1, but rather a separate protocol layer that runs under HTTP/1.1 and
-on top of TLS or TCP. It’s a perfect fit for the new Snort 3.0 architecture
+on top of TLS or TCP. It’s a perfect fit for the new Snort 3 architecture
because a new HTTP/2 inspector would naturally output HTTP/1.1 messages but
not any underlying packets. Exactly what http_inspect wants to input.
Snort 3.0 is an updated version of the Snort Intrusion Prevention System
-(IPS) which features a new design that provides a superset of 2.9
-functionality with better throughput, detection, scalability, and usability.
-Some of the key features of Snort 3.0 are:
+(IPS) which features a new design that provides a superset of Snort 2.X
+functionality with better throughput, detection, scalability, and
+usability. Some of the key features of Snort 3.0 are:
* Support multiple packet processing threads
* Use a shared configuration and attribute table
* Automake and Cmake
* Autogenerate reference documentation
-Additional are already under development:
+Additional features are on the road map:
* Use a shared network map
* Support hardware offload for fast pattern acceleration
* Anomaly detection
* and more!
-The remainder of this section provides some background and overview
-information. The next section describes how to use the major features of
-Snort. Most of the rest of the manual is reference material.
-
-The 2.X Snort manual may be useful only for some background information not
-yet documented here.
-
-
-=== Background
-
-Snort is a signature-based IPS, which means that as it receives network
-packets it reassembles and normalizes the content so that a set of rules can
-be evaluated to detect the presence of any significant conditions that
-merit further action. A rough processing flow is as follows:
-
-////
-(pkt) -> [decode] -> [preprocess] -> [detect] -> [log] -> (verdict)
-////
-image::snort2x.png["Snort 2X",width="480"]
-
-The steps are:
-
-1. Decode each packet to determine the basic network characteristics such
-as source and destination addresses and ports. A typical packet might have
-ethernet containing IP containing TCP containing HTTP (ie eth:ip:tcp:http).
-The various encapsulating protocols are examined for sanity and anomalies
-as the packet is decoded. This is essentially a stateless effort.
-
-2. Preprocess each decoded packet using accumulated state to determine the
-purpose and content of the innermost message. This step may involve
-reordering and reassembling IP fragments and TCP segments to produce the
-original application protocol data unit (PDU). Such PDUs are analyzed and
-normalized as needed to support further processing.
-
-3. Detection is a two step process. For efficiency, most rules contain a
-specific content pattern that can be searched for such that if no match is
-found no further processing is necessary. Upon start up, the rules are
-compiled into pattern groups such that a single, parallel search can be
-done for all patterns in the group. If any match is found, the full rule
-is examined according to the specifics of the signature.
-
-4. The logging step is where Snort saves any pertinent information
-resulting from the earlier steps. More generally, this is where other
-actions can be taken as well such as blocking the packet.
-
-
-==== Snort 2.X Processing
-
-The preprocess step in Snort 2.X is highly configurable. Arbitrary
-preprocessors can be loaded dynamically at startup, configured in
-snort.conf, and then executed at runtime. Basically, the preprocessors are
-put into a list which is iterated for each packet. Recent versions have
-tweaked the list handling some, but the same basic architecture has allowed
-Snort to grow from a sniffer, with no preprocessing, to a full-fledged IPS,
-with lots of preprocessing.
-
-While this "list of plugins" approach has considerable flexibility, it
-hampers future development when the flow of data from one preprocessor to
-the next depends on traffic conditions, a common situation with advanced
-features like application identification. In this case, a preprocessor
-like HTTP may be extracting and normalizing data that ultimately is not
-used, or appID may be repeatedly checking for data that is just not
-available.
-
-Callbacks help break out of the preprocess straightjacket. This is where
-one preprocessor supplies another with a function to call when certain data
-is available. Snort has started to take this approach to pass some HTTP and
-SIP preprocessor data to appID. However, it remains a peripheral feature
-and still requires the production of data that may not be consumed.
-
-
-==== Snort 3.0 Processing
-
-One of the goals of Snort++ is to provide a more flexible framework for
-packet processing by implementing an event-driven approach. Another is to
-produce data only when needed to minimize expensive normalizations.
-However, the basic packet processing provides very similar functionality.
-
-The basic processing steps Snort\++ takes are similar to Snort's as seen in
-the following diagram. The preprocess step employs specific inspector
-types instead of a generalized list, but the basic procedure includes
-stateless packet decoding, TCP stream reassembly, and service specific
-analysis in both cases. (Snort++ provides hooks for arbitrary inspectors,
-but they are not central to basic flow processing and are not shown.)
-
-////
-(pkt) -> [decode] -> [stream] -> [service] -> [detect] -> [log] -> (verdict)
- -----------------------------------------------------
- [appid] [firewall] [other]
-////
-image::snort3x.png["Snort 3X",width="480"]
-
-However, Snort++ also provides a more flexible mechanism than callback
-functions. By using inspection events, it is possible for an inspector to
-supply data that other inspectors can process. This is known as the
-observer pattern or publish-subscribe pattern.
-
-Note that the data is not actually published. Instead, access to the data
-is published, and that means that subscribers can access the raw or
-normalized version(s) as needed. Normalizations are done only on the first
-access, and subsequent accesses get the previously normalized data. This
-results in just in time (JIT) processing.
-
-A basic example of this in action is provided by the extra data_log plugin.
-It is a passive inspector, ie it does nothing until it receives the data it
-subscribed for ('other' in the above diagram). By adding data_log = { key
-= 'http_raw_uri' } to your snort.lua configuration, you will get a simple
-URI logger.
-
-Inspection events coupled with pluggable inspectors provide a very flexible
-framework for implementing new features. And JIT buffer stuffers allow
-Snort\++ to work smarter, not harder. These capabilities will be leveraged
-more and more as Snort++ development continues.
+The remainder of this section provides a high level survey of the inputs,
+processing, and outputs available with Snort 3.0.
+
+Snort++ is the project that is creating Snort 3.0. In this manual "Snort"
+or "Snort 3" refers to the 3.0 version and earlier versions will be
+referred to as "Snort 2" where the distinction is relevant.
+
+
+=== First Steps
+
+Snort can be configured to perform complex packet processing and deep
+packet inspection but it is best start simply and work up to more
+interesting tasks. Snort won't do anything you didn't specifically ask it
+to do so it is safe to just try things out and see what happens. Let's
+start by just running Snort with no arguments:
+
+ $ snort
+
+That will output usage information including some basic help commands. You
+should run all of these commands now to see what is available:
+
+ $ snort -V
+ $ snort -?
+ $ snort --help
+
+Note that Snort has extensive command line help available so if anything
+below isn't clear, there is probably a way to get the exact information you
+need from the command line.
+
+Now let's examine the packets in a capture file (pcap):
+
+ $ snort -r a.pcap
+
+Snort will decode and count the packets in the file and output some
+statistics. Note that the output excludes non-zero numbers so it is easy
+to see what is there.
+
+You may have noticed that there are command line options to limit the
+number of packets examined or set a filter to select particular packets.
+Now is a good time to experiment with those options.
+
+If you want to see details on each packet, you can dump the packets to
+console like this:
+
+ $ snort -r a.pcap -L dump
+
+Add the -d option to see the TCP and UDP payload. Now let's switch to live
+traffic. Replace eth0 in the below command with an available network
+interface:
+
+ $ snort -i eth0 -L dump
+
+Unless the interface is taken down, Snort will just keep running, so enter
+Control-C to terminate or use the -n option to limit the number of packets.
+
+Generally it is better to capture the packets for later analysis like this:
+
+ $ snort -i eth0 -L pcap -n 10
+
+Snort will write 10 packets to log.pcap.# where # is a timestamp value.
+You can read these back with -r and dump to console or pcap with -L. You
+get the idea.
+
+Note that you can do similar things with other tools like tcpdump or
+Wireshark however these commands are very useful when you want to check
+your Snort setup.
+
+The examples above use the default pcap DAQ. Snort supports non-pcap
+interfaces as well via the DAQ (data acquisition) library. Other DAQs
+provide additional functionality such as inline operation and/or higher
+performance. There are even DAQs that support raw file processing (ie
+without packets), socket processing, and plain text packets. To load
+external DAQ libraries and see available DAQs or select a particular DAQ
+use one of these commands:
+
+ $ snort --daq-dir <path> --daq-list
+ $ snort --daq-dir <path> --daq <type>
+
+Be sure to put the --daq-dir option ahead of the --daq-list option or the
+external DAQs won't appear in the list.
+
+To leverage intrusion detection features of Snort you will need to provide
+some configuration details. The next section breaks down what must be
+done.
=== Configuration
-Effective configuration of Snort++ is done via the environment, command
-line, a Lua configruation file, and a rules file.
+Effective configuration of Snort is done via the environment, command
+line, a Lua configuration file, and a set of rules.
-Note that backwards compatibility was sacrificed to obtain new and improved
-functionality. While Snort\++ leverages some of the Snort code base, a lot
-has changed. The configuration of Snort++ is done with Lua, so your old
-conf won't work as is. Rules are still text based but with syntax tweaks,
-so your 2.X rules must be fixed up. However, snort2lua will help you
-convert your conf and rules to the new format.
+Note that backwards compatibility with Snort 2 was sacrificed to obtain
+new and improved functionality. While Snort 3 leverages some of the
+Snort 2 code base, a lot has changed. The configuration of Snort 3 is
+done with Lua, so your old conf won't work as is. Rules are still text
+based but with syntax tweaks, so your 2.X rules must be fixed up. However,
+snort2lua will help you convert your conf and rules to the new format.
==== Environment
LUA_PATH=$install_prefix/include/snort/lua/\?.lua\;\;
-SNORT_LUA_PATH must be set to load auxillary configuration files if you use
+SNORT_LUA_PATH must be set to load auxiliary configuration files if you use
the default snort.lua. For example:
export SNORT_LUA_PATH=$install_prefix/etc/snort
snort --help-config stream
-Snort++ is organized into a collection of builtin and plugin modules.
+Snort is organized into a collection of builtin and plugin modules.
If a module has parameters, it is configured by a Lua table of the same
name. For example, we can see what the active module has to offer with
this command:
==== Rules
-Rules tell Snort how to detect interesting conditions, such as an attack,
-and what to do when the condition is detected. Here is an example rule:
+Rules determine what Snort is looking for. They can be put directly in
+your Lua configuration file with the ips module, on the command line with
+--lua, or in external files. Generally you will have many rules obtained
+from various sources such as Talos and loading external files is the way to
+go so we will summarize that here. Add this to your Lua configuration:
+
+ ips = { include = 'rules.txt' }
+
+to load the external rules file named rules.txt. You can only specify
+one file this way but rules files can include other rules files with the
+include statement. In addition you can load rules like:
+
+ $ sort -c snort.lua -R rules.txt
+
+You can use both approaches together.
+
+==== Converting Your 2.X Configuration
- alert tcp any any -> 192.168.1.1 80 ( msg:"A ha!"; content:"attack"; sid:1; )
+If you have a working 2.X configuration snort2lua makes it easy to get up
+and running with Snort 3. This tool will convert your configuration and/or
+rules files automatically. You will want to clean up the results and
+double check that it is doing exactly what you need.
-The structure is:
+ snort2lua -c snort.conf
- action proto source dir dest ( body )
+The above command will generate snort.lua based on your 2.X configuration.
+For more information and options for more sophisticated use cases, see the
+Snort2Lua section later in the manual.
-Where:
+=== Output
-action - tells Snort what to do when a rule "fires", ie when the signature
-matches. In this case Snort will log the event. It can also do thing like
-block the flow when running inline.
+Snort can produce quite a lot of data. In the following we will summarize
+the key aspects of the core output types. Additional data such as from
+appid is covered later.
-proto - tells Snort what protocol applies. This may be ip, icmp, tcp, udp,
-http, etc.
+==== Basic Statistics
-source - specifies the sending IP address and port, either of which can be
-the keyword any, which is a wildcard.
+At shutdown, Snort will output various counts depending on configuration
+and the traffic processed. Generally, you may see:
-dir - must be either unidirectional as above or bidirectional indicated by
-<>.
+* Packet Statistics - this includes data from the DAQ and decoders such as
+ the number of packets received and number of UDP packets.
-dest - similar to source but indicates the receiving end.
+* Module Statistics - each module tracks activity via a set of peg counts
+ that indicate how many times something was observed or performed. This
+ might include the number of HTTP GET requests processed and the number of
+ TCP reset packets trimmed.
-body - detection and other information contained in parenthesis.
+* File Statistics - look here for a breakdown of file type, bytes,
+ signatures.
-There are many rule options available to construct as sophisticated a
-signature as needed. In this case we are simply looking for the "attack"
-in any TCP packet. A better rule might look like this:
+* Summary Statistics - this includes total runtime for packet processing
+ and the packets per second. Profiling data will appear here as well if
+ configured.
- alert http
- (
- msg:"Gotcha!";
- flow:established, to_server;
- http_uri:"attack";
- sid:2;
- )
+Note that only the non-zero counts are output. Run this to see the
+available counts:
-For details on these and other options, see the reference section.
+ $ snort --help-counts
-==== Converting Your 2.X Configuration
+==== Alerts
-If you have a working 2.X configuration snort2lua makes it easy to get up
-and running with Snort++. This tool will convert your configuration and/or
-rules files automatically. You will want to clean up the results and
-double check that it is doing exactly what you need.
+If you configured rules, you will need to configure alerts to see the
+details of detection events. Use the -A option like this:
- snort2lua -c snort.conf
+ $ snort -c snort.lua -r a.pcap -A cmg
-The above command will generate snort.lua based on your 2.X configuration.
-For more information and options for more sophisticated use cases, see the
-Snort2Lua section later in the manual.
+There are many types of alert outputs possible. Here is a brief list:
+
+* -A cmg is the same as -A fast -d -e and will show information about the
+ alert along with packet headers and payload.
+
+* -A u2 is the same as -A unified2 and will log events and triggering
+ packets in a binary file that you can feed to other tools for post
+ processing. Note that Snort 3 does not provide the raw packets for
+ alerts on PDUs; you will get the actual buffer that alerted.
+
+* -A csv will output various fields in comma separated value format. This
+ is entirely customizable and very useful for pcap analysis.
+
+To see the available alert types, you can run this command:
+
+ $ snort --list-plugins | grep logger
+
+==== Files and Paths
+
+Note that output is specific to each packet thread. If you run 4 packet
+threads with u2 output, you will get 4 different u2 files. The basic
+structure is:
+
+ <logdir>/[<run_prefix>][<id#>][<X>]<name>
+
+where:
+
+* logdir is set with -l and defaults to ./
+
+* run_prefix is set with --run-prefix else not used
+
+* id# is the packet thread number that writes the file; with one packet
+ thread, id# (zero) is omitted without --id-zero
+
+* X is / if you use --id-subdir, else _ if id# is used
+
+* name is based on module name that writes the file
-=== Plugins and Scripts
+Additional considerations:
-There are several plugin types:
+* There is no way to explicitly configure a full path to avoid issues with
+ multiple packet threads.
+
+* All text mode outputs default to stdout
-* Codec - to decode and encode packets
-* Inspector - like the prior preprocessors, for normalization, etc.
-* IpsOption - for detection in Snort++ IPS rules
-* IpsAction - for custom rule actions
-* Logger - for handling events
-* Mpse - for fast pattern matching
-* So - for dynamic rules
+==== Performance Statistics
-Most plugins can be built statically or dynamically. By default they are
-all static. There is no difference in functionality between static or
-dynamic plugins but the dynamic build generates a slightly lighter weight
-binary. Either way you can add dynamic plugins with --plugin-path and
-newer versions will replace older versions, even when built statically.
+Still more data is available beyond the above.
-The power of plugins is that they have a very focused purpose and can be
-created with relative ease. For example, you can extend the rule language
-by writing your own IpsOption and it will plug in and function just like
-existing options. The extra directory has examples of each type of plugin.
+* By configuring the perf_monitor module you can capture a configurable set
+ of peg counts during runtime. This is useful to feed to an external
+ program so you can see what is happening without stopping Snort.
-Some things just need to be tweaked or prototyped quickly. In addition to
-the Lua conf, which is a script that can contain functions to compute
-settings, etc., you can also script Loggers and IpsOptions.
+* The profiler module allows you to track time and space used by module and
+ rules. Use this data to tune your system for best performance. The
+ output will show up under Summary Statistics at shutdown.
-=== Terminology
-
-include::terms.txt[]
-
-=== Usage
-
-include::usage.txt[]
-
=== Build Options
include::building.txt[]
include::options.txt[]
-=== Parameters
-
-include::params.txt[]
-
=== Configuration
include::config.txt[]
=== Module Listing
-// FIXIT-L Either Fix Snort++ output or begin
-// really using these.
-:leveloffset: 1
include::modules.txt[]
-:leveloffset: 0
=== Plugin Listing
include::plugins.txt[]
+=== Bugs
+
+include::bugs.txt[]
+
-One of the major differences between Snort 2.9.X and Snort 3.0 is the
-configuration. Snort 2.9.X configuration files are written in Snort-specific
-syntax while Snort 3.0 configuration files are written in Lua. Snort2Lua is a
-program specifically designed to convert Snort 2.9.X configuration files into
-Lua files that Snort 3.0 can understand.
+One of the major differences between Snort 2 and Snort 3 is the
+configuration. Snort 2 configuration files are written in Snort-specific
+syntax while Snort 3 configuration files are written in Lua. Snort2Lua is
+a program specifically designed to convert Snort 2 configuration files
+into Lua files that Snort 3 can understand.
-Snort2Lua reads your legacy Snort conf file(s) and generates Snort++ Lua
+Snort2Lua reads your legacy Snort conf file(s) and generates Snort 3 Lua
and rules files. When running this program, the only mandatory option is
-to provide Snort2Lua with a Snort configuration file. The default output
-file file is snort.lua, the default error file will be snort.rej, and the
-default rule file is the output file (default is snort.lua). When
+to provide Snort2Lua with a Snort 2 configuration file. The default
+output file file is snort.lua, the default error file will be snort.rej,
+and the default rule file is the output file (default is snort.lua). When
Snort2Lua finishes running, the resulting configuration file can be
successfully run as the Snort3.0 configuration file. The sole exception to
this rule is when Snort2Lua cannot find an included file. If that occurs,
bad. For instance, Snort2Lua will only convert preprocessors that are
currently supported. Therefore, any unsupported preprocessors or
configuration options including DCERP, SIP, and SMTP, will cause an error
-in Snort2Lua since Snort3.0 does not support those preprocessors.
+in Snort2Lua since Snort 3 does not support those preprocessors.
Additionally, any rule options associated with those preprocessors are also
-not supported. Finally, Snort2Lua expects a valid Snort configuration.
+not supported. Finally, Snort2Lua expects a valid Snort 2 configuration.
Therefore, if the configuration is invalid or has questionable syntax,
Snort2Lua may fail to parse the configuration file or create an invalid
-Snort3.0 configuration file.
+Snort 3 configuration file.
There are a also few peculiarities of Snort2Lua that may be confusing to a
first time user. Specifically, aside from an initial configuration file
(which is specified from the command line or as the file in ‘config
-binding’), every file that is included into Snort3.0 must be either a Lua
+binding’), every file that is included into Snort 3 must be either a Lua
file or a rule file; the file cannot contain both rules and Lua syntax.
Therefore, when parsing a file specified with the ‘include’ command,
Snort2Lua will output both a Lua file and a rule file. Additionally, any
pull all of the Lua syntax from every ‘include’ file into the output file.
There are currently three output modes: default, quiet, and differences.
-As expected, quiet mode produces a Snort\++ configuration. All errors
-(aside from Fatal Snort2Lua errors), differences, and comments will omitted
-from the final output file. Default mode will print everything. That mean
-you will be able to see exactly what changes have occurred between Snort and
-Snort++ in addition to the new syntax, the original file's comments, and
-all errors that have occurred. Finally, differences mode will not actually
-output a valid Snort3.0 configuration. Instead, you can see the exact
-options from the input configuration that have changed.
+As expected, quiet mode produces a Snort configuration. All errors (aside
+from Fatal Snort2Lua errors), differences, and comments will omitted from
+the final output file. Default mode will print everything. That mean you
+will be able to see exactly what changes have occurred between Snort 2
+and Snort 3 in addition to the new syntax, the original file's comments,
+and all errors that have occurred. Finally, differences mode will not
+actually output a valid Snort 3 configuration. Instead, you can see the
+exact options from the input configuration that have changed.
:leveloffset: 1
include::snort2lua_cmds.txt[]
=== Known Problems
-* Any Snort ‘string’ which is dependent on a variable will no longer have
+* Any Snort 2 ‘string’ which is dependent on a variable will no longer have
that variable in the Lua string.
* Snort2Lua currently does not handle variables well. First, that means
=== Usage
-Snort2Lua is included in the Snort 3.0 distribution. The Snort2Lua source code
+Snort2Lua is included in the Snort 3 distribution. The Snort2Lua source code
is located in the tools/snort2lua directory. The program is automatically built
and installed.
Translating your configuration
-To run Snort2Lua, the only requirement is a file containing Snort 2.9.X syntax.
+To run Snort2Lua, the only requirement is a file containing Snort 2 syntax.
Assuming your configuration file is named snort.conf, run the command
snort2lua –c snort.conf
Snort2Lua will output a file named snort.lua. Assuming your snort.conf file is
-a valid Snort 2.9.X configuration file, than the resulting snort.lua file will
-always be a valid Snort 3.0 configuration file; any errors that occur are
-because Snort 3.0 currently does not support all of the Snort 2.9.X options.
+a valid Snort 2 configuration file, than the resulting snort.lua file will
+always be a valid Snort 3 configuration file; any errors that occur are
+because Snort 3 currently does not support all of the Snort 2 options.
Every keyword from the Snort configuration can be found in the output file. If
the option or keyword has changed, then a comment containing both the option or
Translating a rule file
Snort2Lua can also accommodate translating individual rule files. Assuming the
-Snort 2.9.X rule file is named snort.rules and you want the new rule file to be
+Snort 2 rule file is named snort.rules and you want the new rule file to be
name updated.rules, run the command
snort2lua –c snort.rules -r updated.rules
Snort2Lua will output a file named updated.rules. That file, updated.rules,
-will always be a valid Snort 3.0 rule file. Any rule that contains unsupported
+will always be a valid Snort 3 rule file. Any rule that contains unsupported
options will be a comment in the output file.
Understanding the Output
that occur when Snort2Lua runs. This is a list of Snort2Lua outputs.
_The console_. Every line that Snort2Lua is unable to translate from the Snort
-2.9.X format to the Snort 3.0 format is considered an error. Upon exiting,
+2.X format to the Snort 3 format is considered an error. Upon exiting,
Snort2Lua will print the number of errors that occurred. Snort2Lua will also
print the name of the error file.
_The output file_. As previously mentioned, Snort2Lua will create a Lua file
-with valid Snort 3.0 syntax. The default Lua file is named snort.lua. This
-file is the equivalent of your main Snort 2.9.X configuration file.
+with valid Snort 3 syntax. The default Lua file is named snort.lua. This
+file is the equivalent of your main Snort 2 configuration file.
_The rule file_. By default, all rules will be printed to the Lua file.
However, if a rule file is specified on the command line, any rules found in
-the Snort 2.9.X configuration will be written to the rule file instead
+the Snort 2 configuration will be written to the rule file instead
_The error file_. By default, the error file is snort.rej. It will only be
created if errors exist. Every error referenced on the command line can be
found in this file. There are two reasons an error can occur.
-* The Snort 2.9.X configuration file has invalid syntax. If Snort 2.9.X cannot
+* The Snort 2 configuration file has invalid syntax. If Snort 2 cannot
parse the configuration file, neither can Snort2Lua. In the example below,
Snort2Lua could not convert the line 'config bad_option'. Since that is not
- valid Snort 2.9.X syntax, this is a syntax error.
+ valid Snort 2 syntax, this is a syntax error.
-* The Snort 2.9.X configuration file contains preprocessors and rule options
- that are not supported in Snort 3.0. If Snort 2.9.X can parse a line that
- Snort2Lua cannot parse, than Snort 3.0 does not support something in the line.
- As Snort 3.0 begins supporting these preprocessors and rule options, Snort2Lua
+* The Snort 2 configuration file contains preprocessors and rule options
+ that are not supported in Snort 3. If Snort 2 can parse a line that
+ Snort2Lua cannot parse, than Snort 3 does not support something in the line.
+ As Snort 3 begins supporting these preprocessors and rule options, Snort2Lua
will also begin translating these lines. One example of such an error is
dcerpc2.
-= Snort++ User Manual
+= Snort 3 User Manual
:author: The Snort Team
:toc:
:toc-placement: manual
include::overview.txt[]
-== Getting Started
+== Concepts
-include::start.txt[]
+This section provides background on essential aspects of Snort's operation.
+
+include::concepts.txt[]
+
+== Tutorial
+
+include::tutorial.txt[]
+
+== Usage
+
+include::usage.txt[]
== Features
-This section explains how to use key features of Snort++.
+This section explains how to use key features of Snort.
include::features.txt[]
include::daq.txt[]
-== Snort++ vs Snort
+== Snort 3 vs Snort 2
include::differences.txt[]
include::snort2lua.txt[]
-== Extending Snort++
+== Extending Snort
include::extending.txt[]
* *hex*: a type of protocol magic that the wizard uses to identify binary
protocols.
-* *inspector*: plugin that processes packets (similar to the legacy Snort
+* *inspector*: plugin that processes packets (similar to the Snort 2
preprocessor)
* *IPS*: intrusion prevention system, like Snort.
-The following pointers will help you get started:
+The section will walk you through building and running Snort. It is not
+exhaustive but, once you master this material, you should be able to figure
+out more advanced usage.
=== Dependencies
export CXX=g++
-=== Run
+=== Running
First set up the environment:
=== Tips
-One of the goals of Snort++ is to make it easier to configure your sensor.
+One of the goals of Snort 3 is to make it easier to configure your sensor.
Here is a summary of tips and tricks you may find useful.
General Use
changing normalizer to Xnormalizer (an unknown symbol) will disable the
normalizer. This can be easier than commenting in some cases.
-* By default, symbols unknown to Snort++ are silently ignored. You can
+* By default, symbols unknown to Snort are silently ignored. You can
generate warnings for them with --warn-unknown. To ignore such symbols,
export them in the environment variable SNORT_IGNORE.
Writing and Loading Rules
-Snort++ rules allow arbitrary whitespace. Multi-line rules make it easier to
+Snort rules allow arbitrary whitespace. Multi-line rules make it easier to
structure your rule for clarity. There are multiple ways to add comments to
your rules:
-* Like Snort, the # character starts a comment to end of line. In addition, all
- lines between #begin and #end are comments.
+* The # character starts a comment to end of line. In addition, all lines
+ between #begin and #end are comments.
* The rem option allows you to write a comment that is conveyed with the rule.
* Set ips.rules or ips.include.
-* Snort 2.X include statements can be used in rules files.
+* include statements can be used in rules files.
* Use -R to load a rules file.
/path-to/libhs.4.0.dylib src/snort
-=== Bugs
-
-include::bugs.txt[]
-
For the following examples "$my_path" is assumed to be the path to the
-Snort++ install directory. Additionally, it is assumed that "$my_path/bin"
+Snort install directory. Additionally, it is assumed that "$my_path/bin"
is in your PATH.
-==== Environment
+=== Environment
LUA_PATH is used directly by Lua to load and run required libraries.
SNORT_LUA_PATH is used by Snort to load supplemental configuration files.
export SNORT_LUA_PATH=$my_path/etc/snort
-==== Help
+=== Help
Print the help summary:
snort --markup --help-options rule
-NOTE: Snort++ stops reading command-line options after the "--help-*" and
+NOTE: Snort stops reading command-line options after the "--help-*" and
"--list-*" options, so any other options should be placed before them.
-==== Sniffing and Logging
+=== Sniffing and Logging
Read a pcap:
snort --pcap-dir /path/to/pcap/dir --pcap-filter '*.pcap' -L dump -l /path/to/log/dir
-==== Configuration
+=== Configuration
Validate a configuration file:
snort -c $my_path/etc/snort/snort.lua --warn-all --pedantic
-Tell Snort++ where to look for additional Lua scripts:
+Tell Snort where to look for additional Lua scripts:
snort --script-path /path/to/script/dir
-==== IDS mode
+=== IDS mode
-Run Snort++ in IDS mode, reading packets from a pcap:
+Run Snort in IDS mode, reading packets from a pcap:
snort -c $my_path/etc/snort/snort.lua -r /path/to/my.pcap
NOTE: The "--lua" option can be specified multiple times.
-Run Snort++ in IDS mode on an entire directory of pcaps, processing each
+Run Snort in IDS mode on an entire directory of pcaps, processing each
input source on a separate thread:
snort -c $my_path/etc/snort/snort.lua --pcap-dir /path/to/pcap/dir \
--pcap-filter '*.pcap' --max-packet-threads 8
-Run Snort++ on 2 interfaces, eth0 and eth1:
+Run Snort on 2 interfaces, eth0 and eth1:
snort -c $my_path/etc/snort/snort.lua -i "eth0 eth1" -z 2 -A cmg
-Run Snort++ inline with the afpacket DAQ:
+Run Snort inline with the afpacket DAQ:
snort -c $my_path/etc/snort/snort.lua --daq afpacket -i "eth0:eth1" \
-A cmg
default to stdout. These options can be combined.
-==== DAQ Alternatives
+=== DAQ Alternatives
Process hext packets from stdin:
--daq-dir $my_path/lib/snort/daqs --daq socket
-==== Logger Alternatives
+=== Logger Alternatives
Dump TCP stream payload in hext mode:
--lua "alert_csv = { fields = 'pkt_num gid sid rev', separator = '\t' }"
-==== Shell
+=== Shell
You must build with --enable-shell to make the command line shell available.
welcome.
-==== Signals
+=== Signals
-NOTE: The following examples assume that Snort++ is currently running and
-
has a process ID of <pid>.
+NOTE: The following examples assume that Snort is currently running and has
+a process ID of <pid>.
Modify and Reload Configuration:
explicitly configuring the binder, default bindings will be generated which
should work for most common cases.
-* Also note that while Snort 2.X bindings can only be configured in the
- default policy, each Snort 3.0 policy can contain a binder leading to an
+* Also note that while Snort 2 bindings can only be configured in the
+ default policy, each Snort 3 policy can contain a binder leading to an
arbitrary hierarchy.
* The entire configuration can be reloaded and hot-swapped during run-time
- via signal or command in both Snort 2.X and 3.0. Ultimately, Snort 3.0
+ via signal or command in both Snort 2 and Snort 3. Ultimately, Snort 3
will support commands to update the binder on the fly, thus enabling
incremental reloads of individual inspectors.
-* Both Snort 2.X and 3.0 support server specific configurations via a hosts
- table (XML in Snort 2.X and Lua in Snort 3.0). The table allows you to
+* Both Snort 2 and Snort 3 support server specific configurations via a hosts
+ table (XML in Snort 2 and Lua in Snort 3). The table allows you to
map network, protocol, and port to a service and policy. This table can
be reloaded and hot-swapped separately from the config file.
projects / thirdparty / snort3.git / commitdiff
