Snort 3 User Manual

A simple command line might look like this:

To understand what that does, you can start by just running snort with no arguments by running snort --help. Help for all configuration and rule options is available via a suitable command line. In this case:

-c snort.lua is the main configuration file. This is a Lua script that is executed when loaded.

-R cool.rules contains some detection rules. You can write your own or obtain them from Talos (native 3.0 rules are not yet available from Talos so you must convert them with snort2lua). You can also put your rules directly in your configuration file.

-r some.pcap tells Snort to read network traffic from the given packet capture file. You could instead use -i eth0 to read from a live interface. There many other options available too depending on the DAQ you use.

-A cmg says to output intrusion events in "cmg" format, which has basic header details followed by the payload in hex and text.

Command line options have precedence over Lua configuration files. This can be used to make a custom run keeping all configuration files unchanged:

will override daq.batch_size value.

Notably, you can add to and/or override anything in your configuration file by using the --lua command line option. For example:

will load the built-in decoder and inspector rules. In this case, ips is overwritten with the config you see above. If you just want to change the config given in your configuration file you would do it like this:

The configuration file gives you complete control over how Snort processes packets. Start with the default snort.lua included in the distribution because that contains some key ingredients. Note that most of the configurations look like:

This means enable the stream module using internal defaults. To see what those are, you could run:

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:

This says active is a basic module that has several parameters. For each, you will see:

For example, the active module has a max_responses parameter that takes non-negative integer values and defaults to zero. We can change that in Lua as follows:

or:

If we also wanted to limit retries to at least 5 seconds, we could do:

The following Global Lua Variables are available when Snort is run with a lua config using -c option.

When Snort is run with the --warn-conf-strict option, warnings will be generated for all Lua tables present in the configuration files that do not map to Snort module names. Like with other warnings, these will upgraded to errors when Snort is run in pedantic mode.

To dynamically add exceptions that should bypass this strict validation, two Lua functions are made available to be called during the evaluation of Snort configuration files: snort_whitelist_append() and snort_whitelist_add_prefix(). Each function takes a whitespace-delimited list, the former a list of exact table names and the latter a list of table name prefixes to allow.

Examples: snort_whitelist_append("table1 table2") snort_whitelist_add_prefix("local_ foobar_")

The accumulated contents of the whitelist (both exact and prefix) will be dumped when Snort is run in verbose mode (-v).

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:

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:

You can use both approaches together.

Your configuration file may include other files, either directly via Lua or via various parameters. Snort will find relative includes in the following order:

Some things to keep in mind:

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

At shutdown, Snort will output various counts depending on configuration and the traffic processed. Generally, you may see:

Note that only the non-zero counts are output. Run this to see the available counts:

If you configured rules, you will need to configure alerts to see the details of detection events. Use the -A option like this:

There are many types of alert outputs possible. Here is a brief list:

To see the available alert types, you can run this command:

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:

where:

Additional considerations:

Still more data is available beyond the above.

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.

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.)

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.

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.

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 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 or regex 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.

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 match will automatically be skipped if possible. Note that this differs from Snort 2 which provided the fast_pattern:only option to designate such cases. This is one less thing for the rule writer to worry about.

The following parameters can’t be changed during reload, and require a restart:

In addition, the following scenarios require a restart:

In all of these cases reload will fail with the following message: "reload failed - restart required". The original config will remain in use.

Active response is enabled by configuring one of following IPS action plugins:

When these active responses are not configured the default configuration is used.

Active responses will be performed for reject, react or rewrite IPS rule actions, and response packets are encoded based on the triggering packet. TTL will be set to the value captured at session pickup.

Configure the number of attempts to land a TCP RST within the session’s current window (so that it is accepted by the receiving TCP). This sequence "strafing" is really only useful in passive mode. In inline mode the reset is put straight into the stream in lieu of the triggering packet so strafing is not necessary.

Each attempt (sent in rapid succession) has a different sequence number. Each active response will actually cause this number of TCP resets to be sent. TCP data is multiplied similarly. At most 1 ICMP unreachable is sent, iff attempts > 0.

Device IP will perform network layer injection. It is probably a better choice to specify an interface and avoid kernel routing tables, etc.

dst_mac will change response destination MAC address, if the device is eth0, eth1, eth2 etc. Otherwise, response destination MAC address is derived from packet.

Example:

IPS action reject perform active response to shutdown hostile network session by injecting TCP resets and ICMP unreachable for TCP connections, and ICMP unreachable packets for UDP.

Example:

IPS action react enables sending an HTML page on a session and then resetting it.

The headers used are:

The page to be sent can be read from a file:

or else the default is used:

Note that the file contains the message body only. The headers will be added with an updated value for Content-Length. For HTTP/2 traffic Snort will translate the page to HTTP/2 format.

Limitations for HTTP/2:

When using react, payload injector must be configured as well. Also Snort should be in ips mode, so the rule is triggered on the client packet, and not delayed until the server sends ACK. To achieve this use the default normalizer. It will set normalizer.tcp.ips = true. Example:

React has debug trace functionality. It can be used to get traces in case injection is not successful. To turn it on:

IPS action "rewrite" enables overwrite packet contents based on "replace" option in the rules. Note that using "rewrite" action without "replace" option will raise corresponding rule alert, but will not overwrite the packet payload.

For example:

this rule replaces the first occurrence of "index.php" with "indax.php", and "rewrite" action updates that packet.

Content and replacement are aligned to the right side of the matching content and are limited not by the size of the matching content, but by the boundaries of the packet.

Be aware that after the match there should be enough room left for the "replace" content in the matched packet. If there is not enough space for the "replace" content the rule will not match.

"replace" works for raw packets only. So, TCP data must either fit under the "pkt_data" buffer requirements or one should enable detection on TCP payload before reassembly: search_engine.detect_raw_tcp=true. For example:

The AppId inspector provides an application level view when managing networks by providing the following features:

For proper functioning of the AppId inspector, at a minimum stream flow tracking must be enabled. In addition, to identify TCP-based or UDP-based applications, the appropriate stream inspector must be enabled, e.g. stream_tcp or stream_udp.

In order to identify HTTP-based applications, the HTTP inspector must be enabled. Otherwise, only non-HTTP applications will be identified.

AppId subscribes to the inspection events published by other inspectors, such as the HTTP and SSL inspectors, to gain access to the data needed. It uses that data to help determine the application ID.

AppId subscribes to the events published by SIP and DCE/RPC inspectors to detect applications on expected flows.

The AppId feature can be enabled via configuration. To enable it with the default settings use:

To use an AppId as a matching parameter in an IPS rule, use the appids keyword. For example, to block HTTP traffic that contains a specific header:

Alternatively, the HTTP application can be specified in place of tcp instead of using the appids keyword. The AppId inspector will set the service when it is discovered so it can be used in IPS rules like this. Note that this rule also does not specify the IPs or ports which default to any.

It’s possible to specify multiple applications (as many as desired) with the appids keyword. A rule is considered a match if any of the applications on the rule match. Note that this rule does not match specific content which will reduce performance.

Below is a minimal Snort configuration that is sufficient to block flows based on a specific HTTP header:

There are up to four AppIds stored in a session as defined below:

For packets originating from the client, a payloadAppid in a session is matched with all AppIds listed on a rule. Thereafter miscAppId, clientAppId and serviceAppId are matched. Since Alert Events contain one AppId, only the first match is reported. If a rule without an appids option matches, then the most specific appId (in order of payload, misc, client, server) is reported.

The same logic is followed for packets originating from the server with one exception. The order of matching is changed to make serviceAppId come before clientAppId.

The AppId inspector prints application network usage periodically in the snort log directory in unified2 format. File name, time interval for statistic and file rollover are controlled by appId inspection configuration.

Application detectors from Snort team will be delivered in a separate package called the Open Detector Package (ODP) that can be downloaded from snort.org. ODP is a package that contains the following artifacts:

A user can install the ODP package in any directory and configure this directory via the app_detector_dir option in the appid preprocessor configuration. Installing ODP will not modify any subdirectory named custom, where user-created detectors are located.

When installed, ODP will create following sub-directories:

Users can detect new applications by adding detectors in the Lua language. A document will be posted on the Snort Website with details on API. Users can also copy over Snort team provided detectors and modify them. Users can also use the detector creation tool described in the next section.

Users must organize their Lua detectors and libraries by creating the following directory structure, under the ODP installation directory.

The root path is specified by the "app_detector_dir" parameter of the appid section of snort.conf:

So the path to the user-created lua files would be /usr/local/lib/openappid/custom/lua/

None of the directories below /usr/local/lib/openappid/ would be added for you.

Both ODP detectors and user created detectors can be reloaded using the command appid.reload_detectors(). Detectors are expected to be updated in the path appid.app_detector_dir before this command is issued. The command takes no parameters.

For rudimentary Lua detectors, there is a tool provided called appid_detector_builder.sh. This is a simple, menu-driven bash script which creates .lua files in your current directory, based on your choices and on patterns you supply.

When you launch the script, it will prompt for the Application Id that you are giving for your detector. This is free-form ASCII with minor restrictions. The Lua detector file will be named based on your Application Id. If the file name already exists you will be prompted to overwrite it.

You will also be prompted for a description of your detector to be placed in the comments of the Lua source code. This is optional.

You will then be asked a series of questions designed to construct Lua code based on the kind of pattern data, protocol, port(s), etc.

When complete, the Protocol menu will be changed to include the option, "Save Detector". Instead of saving the file and exiting the script, you are allowed to give additional criteria for another pattern which may also be incorporated in the detection scheme. Then either pattern, when matched, will be considered a valid detection.

For example, your first choices might create an HTTP detection pattern of "example.com", and the next set of choices would add the HTTP detection pattern of "example.uk.co" (an equally fictional British counterpart). They would then co-exist in the Lua detector, and either would cause a detection with the name you give for your Application Id.

The resulting .lua file will need to be placed in the directory, "custom/lua", described in the previous section of the README above called "User Created Application Detectors"

This rule option tests a byte field against a specific value (with operator). Capable of testing binary values or converting representative byte strings to their binary equivalent and testing them.

Snort uses the C operators for each of these operators. If the & operator is used, then it would be the same as using

! operator negates the results from the base check. !<oper> is considered as

Note: The bitmask option applies bitwise AND operator on the bytes converted. The result will be right-shifted by the number of bits equal to the number of trailing zeros in the mask. This applies for the other rule options as well.

The byte_jump rule option allows rules to be written for length encoded protocols trivially. By having an option that reads the length of a portion of data, then skips that far forward in the packet, rules can be written that skip over specific portions of length-encoded protocols and perform detection in very specific locations.

The byte_extract keyword is another useful option for writing rules against length-encoded protocols. It reads in some number of bytes from the packet payload and saves it to a variable. These variables can be referenced later in the rule, instead of using hard-coded values.

Perform a mathematical operation on an extracted value and a specified value or existing variable, and store the outcome in a new resulting variable. These resulting variables can be referenced later in the rule, at the same places as byte_extract variables.

The syntax for this rule option is different. The order of the options is critical for the other rule options and can’t be changed. For example, the first option is the number of bytes to extract. Here the name of the option is explicitly written, for example : bytes 2. The order is not important.

The rule options byte_test and byte_jump were written to support writing rules for protocols that have length encoded data. RPC was the protocol that spawned the requirement for these two rule options, as RPC uses simple length based encoding for passing data.

In order to understand why byte test and byte jump are useful, let’s go through an exploit attempt against the sadmind service.

This is the payload of the exploit:

Let’s break this up, describe each of the fields, and figure out how to write a rule to catch this exploit.

There are a few things to note with RPC:

Numbers are written as uint32s, taking four bytes. The number 26 would show up as 0x0000001a.

Strings are written as a uint32 specifying the length of the string, the string, and then null bytes to pad the length of the string to end on a 4-byte boundary. The string bob would show up as 0x00000003626f6200.

The rest of the packet is the request that gets passed to procedure 1 of sadmind.

However, we know the vulnerability is that sadmind trusts the uid coming from the client. sadmind runs any request where the client’s uid is 0 as root. As such, we have decoded enough of the request to write our rule.

First, we need to make sure that our packet is an RPC call.

Then, we need to make sure that our packet is a call to sadmind.

Then, we need to make sure that our packet is a call to the procedure 1, the vulnerable procedure.

Then, we need to make sure that our packet has auth_unix credentials.

We don’t care about the hostname, but we want to skip over it and check a number value after the hostname. This is where byte_test is useful. Starting at the length of the hostname, the data we have is:

We want to read 4 bytes, turn it into a number, and jump that many bytes forward, making sure to account for the padding that RPC requires on strings. If we do that, we are now at:

which happens to be the exact location of the uid, the value we want to check.

In English, we want to read 4 bytes, 36 bytes from the beginning of the packet, and turn those 4 bytes into an integer and jump that many bytes forward, aligning on the 4-byte boundary. To do that in a Snort rule, we use:

then we want to look for the uid of 0.

Now that we have all the detection capabilities for our rule, let’s put them all together.

The 3rd and fourth string match are right next to each other, so we should combine those patterns. We end up with:

If the sadmind service was vulnerable to a buffer overflow when reading the client’s hostname, instead of reading the length of the hostname and jumping that many bytes forward, we would check the length of the hostname to make sure it is not too large.

To do that, we would read 4 bytes, starting 36 bytes into the packet, turn it into a number, and then make sure it is not too large (let’s say bigger than 200 bytes). In Snort, we do:

Our full rule would be:

In case of using any byte_* option with "string" parameter, the amount of bytes to be extracted from payload can be less than specified by user. This might happen when the buffer has fewer bytes (from the cursor position) than specified in the option.

The --dump-config-text option verifies the configuration and dumps it to stdout in text format. The output contains a config of the main policy and all other included sub-policies.

Example: snort -c snort.lua --dump-config-text

For lists, the index next to the option name designates an element parsing order.

The --dump-config=all command-line option verifies the configuration and dumps it to stdout in JSON format. The output contains a config of the main policy and all other included sub-policies. Snort dumps output in a one-line format.

There is 3rd party tool jq for converting to a pretty printed format.

Example: snort -c snort.lua --dump-config=all | jq .

The --dump-config=top command-line option is similar to --dump-config=all, except it produces dump for the main policy only. It verifies the configuration and dumps the main policy configuration to stdout in JSON format.

Example: snort -c snort.lua --dump-config=top | jq .

The following transports are supported for DCE/RPC: SMB, TCP, and UDP. 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 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 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 functionality is replaced by wizard curses.

A typical dcerpce configuration looks like this:

In this example, it defines smb, tcp and udp inspectors based on port. All the configurations are default.

There are enough important differences between Windows and Samba versions that a target based approach has been implemented. Some important differences:

Because of those differences, each inspector can be configured to different policy. Here are the list of policies supported:

Both SMB inspector and TCP inspector support reassemble. Reassemble threshold specifies a minimum number of bytes in the DCE/RPC desegmentation and defragmentation buffers before creating a reassembly packet to send to the detection engine. This option is useful in inline mode so as to potentially catch an exploit early before full defragmentation is done. A value of 0 s supplied as an argument to this option will, in effect, disable this option. Default is disabled.

SMB inspector is one of the most complex inspectors. In addition to supporting rule options and lots of inspector rule events, it also supports file processing for both SMB version 1, 2, and 3.

dce_tcp inspector supports defragmentation, reassembling, and policy that is similar to SMB.

dce_udp is a very simple inspector that only supports defragmentation

New rule options are supported by enabling the dcerpc2 inspectors:

New modifiers to existing byte_test and byte_jump rule options:

There are two parts of file services: file APIs and file policy. File APIs provides all the file inspection functionalities, such as file type identification, file signature calculation, and file capture. File policy provides users ability to control file services, such as enable/disable/configure file type identification, file signature, or file capture.

In addition to all capabilities from Snort 2, we support customized file policy along with file event log.

A very simple configuration has been included in lua/snort.lua file. A typical file configuration looks like this:

There are 3 steps to enable file processing:

A set of file magic rules is packaged with Snort. They can be located at "lua/file_magic.rules". To use this feature, it is recommended that these pre-packaged rules are used; doing so requires that you include the file in your Snort configuration as such (already in snort.lua):

Example:

The previous two rules define GIF format, because two file magics are different. File magics are specified by content and offset, which look at content at particular file offset to identify the file type. In this case, two magics look at the beginning of the file. You can use character if it is printable or hex value in between "|".

Note that file_meta and a fast-pattern option (content, regex) are required for each file_id rule.

You can enabled file type, file signature, or file capture by configuring file_id. In addition, you can enable trace to see file stream data, file type, and file signature information.

Most importantly, you can configure a file policy that can block/alert some file type or an individual file based on SHA. This allows you build a file blacklist or whitelist.

Example:

In this example, it enables this policy:

File can be captured and stored to log folder. We use SHA as file name instead of actual file name to avoid conflicts. You can capture either all files, some file type, or a particular file based on SHA.

You can enable file capture through this config:

or enable it for some file or file type in your file policy:

The above rule will enable PDF file capture.

File inspect preprocessor also works as a dynamic output plugin for file events. It logs basic information about file. The log file is in the same folder as other log files with name starting with "file.log".

Example:

All file events will be logged in packet time, system time is not logged.

File event example:

HighAvailability (or HA) is a Snort module that provides state coherency between two partner snort instances. It uses SideChannel for messaging.

There can be multiple types of HA within Snort and Snort plugins. HA implements an extensible architecture to enable plugins to subscribe to the base flow HA messaging. These plugins can then include their own messages along with the flow cache HA messages.

HA produces and consumes two type of messages:

The HA module is configured with these items:

The ports item maps to the SideChannel port to use for the HA messaging.

The enabled item controls the overall HA operation.

The items min_age and min_sync are used in the stream HA logic. min_age is the number of milliseconds that a flow must exist in the flow cache before sending HA messages to the partner. min_sync is the minimum time between HA status updates. HA messages for a particular flow will not be sent faster than min_sync. Both are expressed as a number of milliseconds.

HA messages are composed of the base stream information plus any content from additional modules. Modules subscribe HA in order to add message content. The stream HA content is always present in the messages while the ancillary module content is only present when requested via a status change request.

Connectors are a set of modules that are used to exchange message-oriented data among Snort threads and the external world. A typical use-case is HA (High Availability) message exchange. Connectors serve to decouple the message transport from the message creation/consumption. Connectors expose a common API for several forms of message transport.

Connectors are a Snort plugin type.

SideChannel is a Snort module that uses Connectors to implement a messaging infrastructure that is used to communicate between Snort threads and the outside world.

SideChannel adds functionality onto the Connector as:

SideChannel’s are always implement a duplex (bidirectional) messaging model and can map to separate transmit and receive Connectors.

The message handling model leverages the underlying Connector handling. So please refer to the Connector documentation.

SideChannel’s are instantiated by various applications. The SideChannel port numbers are the configuration element used to map SideChannel’s to applications.

The SideChannel configuration mostly serves to map a port number to a Connector or set of connectors. Each port mapping can have at most one transmit plus one receive connector or one duplex connector. Multiple SideChannel’s may be configured and instantiated to support multiple applications.

An example SideChannel configuration along with the corresponding Connector configuration:

You can configure it by adding:

to your snort.lua configuration file. Or you can read about it in the source code under src/service_inspectors/http_inspect.

So why a new HTTP inspector?

For starters it is object-oriented. That’s good for us because we maintain this software. But it should also be really nice for open-source developers. You can make meaningful changes and additions to HTTP processing without having to understand the whole thing. In fact much of the new HTTP inspector’s knowledge of HTTP is centralized in a series of tables where it can be easily reviewed and modified. Many significant changes can be made just by updating these tables.

http_inspect is the first inspector written specifically for the new Snort 3 architecture. This 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 guy) divided it up into IP packets.

http_inspect is free of this burden and can focus exclusively on HTTP. This makes it much simpler, easier to test, and less prone to false positives. It also greatly reduces the opportunity for adversaries to probe the inspector for weak spots by adjusting packet boundaries to disguise bad behavior.

Dealing solely with HTTP messages also opens the door for developing major new features. The http_inspect design supports true stateful processing. Want to ask questions that involve both the client request and the server response? Or different requests in the same session? These things are possible.

http_inspect is taking a very different approach to HTTP header fields. The classic preprocessor divides all the HTTP headers following the start line into cookies and everything else. It normalizes the two pieces using a generic process and puts them in buffers that one can write rules against. There is some limited support for examining individual headers within the inspector but it is very specific.

The new concept is that every header should be normalized in an appropriate and specific way and individually made available for the user to write rules against it. If for example a header is supposed to be a date then normalization means put that date in a standard format.

Currently, there are Legacy and Enhanced Normalizers for JavaScript normalization. Both normalizers are independent and can be configured separately. The Legacy normalizer should be considered deprecated. The Enhanced Normalizer is encouraged to use for JavaScript normalization in the first place as we continue improving functionality and quality. The Enhanced JavaScript Normalizer has to be configured as a separate module:

Refer to JavaScript Normalization section for Enhanced Normalizer specifics.

Configuration can be as simple as adding:

to your snort.lua file. The default configuration provides a thorough inspection and may be all that you need. But there are some options that provide extra features, tweak how things are done, or conserve resources by doing less.

The HTTP CONNECT method is used by a client to establish a tunnel to a destination via an HTTP proxy server. If the connection is successful the server will send a 2XX success response to the client, then proceed to blindly forward traffic between the client and destination. That traffic belongs to a new session between the client and destination and may be of any protocol, so clearly the HTTP inspector will be unable to continue processing traffic following the CONNECT message as if it were just a continuation of the original HTTP/1.1 session.

Therefore upon receiving a success response to a CONNECT request, the HTTP inspector will stop inspecting the session. The next packet will return to the wizard, which will determine the appropriate inspector to continue processing the flow. If the tunneled protocol happens to be HTTP/1.1, the HTTP inspector will again start inspecting the flow, but as an entirely new session.

There is one scenario where the cutover to the wizard will not occur despite a 2XX success response to a CONNECT request. HTTP allows for pipelining, or sending multiple requests without waiting for a response. If the HTTP inspector sees any further traffic from the client after a CONNECT request before it has seen the CONNECT response, it is unclear whether this traffic should be interpreted as a pipelined HTTP request or tunnel traffic sent in anticipation of a success response from the server. Due to this potential evasion tactic, the HTTP inspector will not cut over to the wizard if it sees any early client-to-server traffic, but will continue normal HTTP processing of the flow regardless of the eventual server response.

http_inspect parses HTTP messages into their components and makes them available to the detection engine through rule options. Let’s start with an example:

This rule looks for chocolate in the URI portion of the request message. Specifically, the http_uri rule option is the normalized URI with all the percent encodings removed. It will find chocolate in both:

and

It is also possible to search the unnormalized URI

will match the first message but not the second. If you want to detect someone who is trying to hide his request for chocolate then

will do the trick.

Let’s look at possible ways of writing a rule to match HTTP response messages with the Content-Language header set to "da" (Danish). You could write:

This rule leaves much to be desired. Modern headers are often thousands of bytes and seem to get longer every year. Searching all of the headers consumes a lot of resources. Furthermore this rule is easily evaded:

the extra space before the "da" throws the rule off. Or how about:

By adding a made up second language the attacker has once again thwarted the match.

A better way to write this rule is:

The field option improves performance by narrowing the search to the Content-Language field of the header. Because it uses the header parsing abilities of http_inspect to find the field of interest it will not be thrown off by extra spaces or other languages in the list.

In addition to the headers there are rule options for virtually every part of the HTTP message.

Occasionally one needs a rule that looks for the count of some variable. For example, to alert when a message has more than 100 headers use this rule:

This is a range-based rule. It is matching when the expression in the rule option is true. The general format is "option operator value". To compare for equality, use operator "=". This is the default operator and may be omitted. Both rules below will alert when the message has 100 headers:

Compare for non-equality using operator "!" or "!=", compare for less than using operator "<", compare for greater than using operator ">", compare for less or equal using operator "⇐", and compare for greater or equal using operator ">=".

To alert when a message has strictly more than 100 headers and strictly less than 200 headers use this rule:

This is a range-based rule with an interval. The general format is "option value1 operator value2". Use operator "<>" to match if the option is in the interval excluding the endpoints, or operator "<⇒" to include the endpoints. This rule will alert when a message has 100 headers or more and 200 headers or less:

HTTP inspector is stateful. That means it is aware of a bigger picture than the packet in front of it. It knows what all the pieces of a message are, the dividing lines between one message and the next, which request message triggered which response message, pipelines, and how many messages have been sent over the current connection.

It is possible to write rules that examine both the client request and the server response to it.

This rule looks for white chocolate in a response message body where the URI of the request contained chocolate. Note that this is a "to_client" rule that will alert on and potentially block a server response containing white chocolate, but only if the client URI requested chocolate. If the rule were rewritten "to_server" it would be nonsense and not work. Snort cannot block a client request based on what the server response will be because that has not happened yet.

Response messages do not have a URI so there was only one thing http_uri could have meant in the previous rule. It had to be referring to the request message. Sometimes that is not so clear.

Our search for chocolate has moved from the URI to the message headers. Both the request and response messages have headers—which one are we asking about? Ambiguity is always resolved in favor of looking in the current message which is the response. The first rule is looking for a server response containing chocolate in the headers and white chocolate in the body.

The second rule uses the "request" option to explicitly say that the http_header to be searched is the request header.

Fast patterns are always searched in the current message. Rule options using "request" option can’t be used as fast patterns.

Message body sections can only go through detection at the time they are received. Headers may be combined with later items but the body cannot.

The sub-options "with_header", "with_body" and "with_trailer" are deprecated, and no longer required when mixing the different sections.

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 supports several new features with the goal of improving the performance of HTTP requests, notably the ability to multiplex many requests over a single TCP connection, HTTP header compression, and server push.

HTTP/2 is a perfect fit for the new Snort 3 PDU-based inspection architecture. The HTTP/2 inspector parses and strips the HTTP/2 protocol framing and outputs HTTP/1.1 messages, exactly what http_inspect wants to input. The HTTP/2 traffic then undergoes the same processing as regular HTTP/1.1 traffic discussed above. So if you haven’t already, take a look at the HTTP Inspector section; those features also apply to HTTP/2 traffic.

You can configure the HTTP/2 inspector with the default configuration by adding:

to your snort.lua configuration file. Since processing HTTP/2 traffic relies on the HTTP inspector, http_inspect must also be configured. Keep in mind that the http_inspect configuration will also impact HTTP/2 traffic.

Since HTTP/2 traffic is processed through the HTTP inspector, all of the rule options discussed above are also available for HTTP/2 traffic. To smooth the transition to inspecting HTTP/2, rules that specify service:http will be treated as if they also specify service:http2. Thus:

is understood to mean:

Thus it will alert on "/foo" in the URI for both HTTP/1 and HTTP/2 traffic.

The reverse is not true. "service: http2" without http will match on HTTP/2 flows but not HTTP/1 flows.

This feature makes it easy to add HTTP/2 inspection without modifying large numbers of existing rules. New rules should explicitly specify "service http,http2;" if that is the desired behavior. Eventually support for http implies http2 may be deprecated and removed.

IEC 60870-5-104 (iec104) is a protocol distributed by the International Electrotechnical Commission (IEC) that provides a standardized method of sending telecontrol messages between central stations and outstations, typically running on TCP port 2404.

It is used in combination with the companion specifications in the IEC 60870-5 family, most notably IEC 60870-5-101, to provide reliable transport via TCP/IP.

An iec104 Application Protocol Data Unit (APDU) consists of one of three Application Protocol Control Information (APCI) structures, each beginning with the start byte 0x68. In the case of an Information Transfer APCI, an Application Service Data Unit (ASDU) follows the APCI.

The iec104 inspector decodes the iec104 protocol and provides rule options to access certain protocol fields and data content. This allows the user to write rules for iec104 packets without decoding the protocol.

iec104 messages can be normalized to either combine a message spread across multiple frames, or to split apart multiple messages within one frame. No manual configuration is necessary to leverage this functionality.

A typical iec104 configuration looks like this:

In this example, the tcp inspector is defined based on port. All configurations are default.

Debug logging can be enabled with the following additional configuration:

New rule options are supported by enabling the iec104 inspector:

You can configure it by adding:

to your snort.lua configuration file. Or you can read about it in the source code under src/js_norm.

Having js_norm module configured and ips option js_data in the rules automatically enables Enhanced Normalizer.

The Enhanced Normalizer can normalize JavaScript embedded in HTML (inline scripts), in separate .js files (external scripts), and JavaScript embedded in PDF files sent over HTTP/1, HTTP/2, SMTP, IMAP and POP3 protocols. It supports scripts over multiple PDUs. It is a stateful JavaScript whitespace and identifiers normalizer. Normalizer concatenates string literals whenever it’s possible to do. This also works with any other normalizations that result in string literals. All JavaScript identifier names, except those from the ignore lists, will be substituted with unified names in the following format: var_0000 → var_ffff. The Normalizer tries to expand escaped text, so it will appear in a readable form in the output. When such text is a parameter of an unescape function, the entire function call will be replaced by the unescaped string. Moreover, Normalizer validates the syntax concerning ECMA-262 Standard, including scope tracking and restrictions for script elements. JavaScript, embedded in PDF files, has to be decompressed before normalization. For that, decompress_pdf = true option has to be set in configuration of appropriate service inspectors.

Check with the following options for more configurations: bytes_depth, identifier_depth, max_tmpl_nest, max_bracket_depth, max_scope_depth, ident_ignore, prop_ignore.

Enhanced normalizer is the preferred option for writing new JavaScript related rules, though legacy normalizer (part of http_inspect) is still available to support old rules.

Configuration can be as simple as adding:

to your snort.lua file. The default configuration provides a thorough normalization and may be all that you need, but there are some options that provide extra features, tweak how things are done, or conserve resources by doing less.

Also, there are default lists of ignored identifiers and object properties provided. To get a complete default configuration, use default_js_norm from $SNORT_LUA_PATH/snort_defaults.lua by adding:

to your snort.lua file.

Enhanced JavaScript Normalizer implements JIT approach. Actual normalization takes place only when js_data option is evaluated. This option is also used as a buffer selector for normalized JavaScript data.

Enhanced JavaScript Normalizer follows JIT approach, which requires rules with js_data IPS option to be executed. This can lead to missed data when js_data option is not evaluated for some packets, e.g. if there is a non-js_data fast pattern. In this case, when fast pattern doesn’t match, JavaScript normalization is skipped for the current PDU. If later js_data IPS rule matches again, a missed normalization context is detected and 154:8 built-in alert is raised. Further normalization is not possible for the script. For example:

When a user needs help to sort out things going on inside Enhanced JavaScript Normalizer, Trace module becomes handy.

Messages for the enhanced JavaScript Normalizer follow (more verbosity available in debug build):

IEC 61850 is a family of protocols, including MMS, distributed by the International Electrotechnical Commission (IEC) that provide a standardized method of sending service messages between various manufacturing and process control devices, typically running on TCP port 102.

It is used in combination with various parts of the OSI model, most notably the TPKT, COTP, Session, Presentation, and ACSE layers, to provide reliable transport via TCP/IP.

The MMS inspector decodes the OSI layers encapsulating the MMS protocol and provides rule writers access to certain protocol fields and data content through rule options. This allows the user to write rules for MMS messages without decoding the protocol.

MMS messages can be sent in a variety of ways including multiple PDUs within one TCP packet, one PDU split across multiple TCP packets, or a combination of the two. It is the aim of the MMS service inspector to normalize the traffic such that only complete MMS messages are presented to the user. No manual configuration other than enabling the MMS service inspector is necessary to leverage this functionality.

A typical MMS configuration looks like this:

In this example, the mms inspector is defined based on patterns known to be consistent with MMS messages.

New rule options are supported by enabling the MMS inspector:

The Snort performance monitor is the built-in utility for monitoring system and traffic statistics. All statistics are separated by processing thread. perf_monitor supports several trackers for monitoring such data:

The base tracker is used to gather running statistics about Snort and its running modules. All Snort modules gather, at the very least, counters for the number of packets reaching it. Most supplement these counts with those for domain specific functions, such as http_inspect’s number of GET requests seen.

Statistics are gathered live and can be reported at regular intervals. The stats reported correspond only to the interval in question and are reset at the beginning of each interval.

These are the same counts displayed when Snort shuts down, only sorted amongst the discrete intervals in which they occurred.

Base differs from prior implementations in Snort in that all stats gathered are only raw counts, allowing the data to be evaluated as needed. Additionally, base is entirely pluggable. Data from new Snort plugins can be added to the existing stats either automatically or, if specified, by name and function.

All plugins and counters can be enabled or disabled individually, allowing for only the data that is actually desired instead of overly verbose performance logs.

To enable everything:

To enable everything within a module:

To enable specific counts within modules:

Note: Event stats from prior Snorts are now located within base statistics.

Flow tracks statistics regarding traffic and L3/L4 protocol distributions. This data can be used to build a profile of traffic for inspector tuning and for identifying where Snort may be stressed.

To enable:

FlowIP provides statistics for individual hosts within a network. This data can be used for identifying communication habits, such as generating large or small amounts of data, opening a small or large number of sessions, and tendency to send smaller or larger IP packets.

To enable:

This tracker monitors the CPU and wall time spent by a given processing thread.

To enable:

Performance monitor allows statistics to be output in a few formats. Along with human readable text (as seen at shutdown) and csv formats, a JSON format format is also available.

POP and IMAP inspectors examine data traffic and find POP and IMAP commands and responses. The inspectors also identify the command, header, body sections and extract the MIME attachments and decode it appropriately. The pop and imap also identify and whitelist the pop and imap traffic.

POP inspector and IMAP inspector offer same set of configuration options for MIME decoding depth. These depths range from 0 to 65535 bytes. Setting the value to 0 ("do none") turns the feature off. Alternatively the value -1 means an unlimited amount of data should be decoded. If you do not specify the default value is -1 (unlimited).

The depth limits apply per attachment. They are:

This module is designed to detect the first phase in a network attack: Reconnaissance. In the Reconnaissance phase, an attacker determines what types of network protocols or services a host supports. This is the traditional place where a portscan takes place. This phase assumes the attacking host has no prior knowledge of what protocols or services are supported by the target, otherwise this phase would not be necessary.

As the attacker has no beforehand knowledge of its intended target, most queries sent by the attacker will be negative (meaning that the services are closed). In the nature of legitimate network communications, negative responses from hosts are rare, and rarer still are multiple negative responses within a given amount of time. Our primary objective in detecting portscans is to detect and track these negative responses.

One of the most common portscanning tools in use today is Nmap. Nmap encompasses many, if not all, of the current portscanning techniques. Portscan was designed to be able to detect the different types of scans Nmap can produce.

The following are a list of the types of Nmap scans Portscan will currently alert for.

These alerts are for one to one portscans, which are the traditional types of scans; one host scans multiple ports on another host. Most of the port queries will be negative, since most hosts have relatively few services available.

Decoy portscans are much like regular, only the attacker has spoofed source address inter-mixed with the real scanning address. This tactic helps hide the true identity of the attacker.

These are many to one portscans. Distributed portscans occur when multiple hosts query one host for open services. This is used to evade an IDS and obfuscate command and control hosts.

These alerts are for one to many portsweeps. One host scans a single port on multiple hosts. This usually occurs when a new exploit comes out and the attacker is looking for a specific service.

"Filtered" alerts indicate that there were no network errors (ICMP unreachables or TCP RSTs) or responses on closed ports have been suppressed. It’s also a good indicator on whether the alert is just a very active legitimate host. Active hosts, such as NATs, can trigger these alerts because they can send out many connection attempts within a very small amount of time. A filtered alert may go off before responses from the remote hosts are received.

Portscan only generates one alert for each host pair in question during the time window. On TCP scan alerts, Portscan will also display any open ports that were scanned. On TCP sweep alerts however, Portscan will only track open ports after the alert has been triggered. Open port events are not individual alerts, but tags based off the original scan alert.

There are 3 default scan levels that can be set.

Each of these default levels have separate options that can be edited to alter the scan sensitivity levels (scans, rejects, nets or ports)

Example:

The example above would change each of the individual settings to 1.

NOTE:The default levels for scans, rejects, nets and ports can be seen in the snort_defaults.lua file.

The counts can be seen in the alert outputs (-Acmg shown below):

"Low" alerts are only generated on error packets sent from the target host, and because of the nature of error responses, this setting should see very few false positives. However, this setting will never trigger a Filtered Scan alert because of a lack of error responses. This setting is based on a static time window of 60 seconds, after which this window is reset.

"Medium" alerts track Connection Counts, and so will generate Filtered Scan alerts. This setting may false positive on active hosts (NATs, proxies, DNS caches, etc), so the user may need to deploy the use of Ignore directives to properly tune this directive.

"High" alerts continuously track hosts on a network using a time window to evaluate portscan statistics for that host. A "High" setting will catch some slow scans because of the continuous monitoring, but is very sensitive to active hosts. This most definitely will require the user to tune Portscan.

The most important aspect in detecting portscans is tuning the detection engine for your network(s). Here are some tuning tips:

Use the watch_ip, ignore_scanners, and ignore_scanned options. It’s important to correctly set these options. The watch_ip option is easy to understand. The analyst should set this option to the list of CIDR blocks and IPs that they want to watch. If no watch_ip is defined, Portscan will watch all network traffic. The ignore_scanners and ignore_scanned options come into play in weeding out legitimate hosts that are very active on your network. Some of the most common examples are NAT IPs, DNS cache servers, syslog servers, and nfs servers. Portscan may not generate false positives for these types of hosts, but be aware when first tuning Portscan for these IPs. Depending on the type of alert that the host generates, the analyst will know which to ignore it as. If the host is generating portsweep events, then add it to the ignore_scanners option. If the host is generating portscan alerts (and is the host that is being scanned), add it to the ignore_scanned option.

Filtered scan alerts are much more prone to false positives. When determining false positives, the alert type is very important. Most of the false positives that Portscan may generate are of the filtered scan alert type. So be much more suspicious of filtered portscans. Many times this just indicates that a host was very active during the time period in question. If the host continually generates these types of alerts, add it to the ignore_scanners list or use a lower sensitivity level.

Make use of the Priority Count, Connection Count, IP Count, Port Count, IP range, and Port range to determine false positives. The portscan alert details are vital in determining the scope of a portscan and also the confidence of the portscan. In the future, we hope to automate much of this analysis in assigning a scope level and confidence level, but for now the user must manually do this. The easiest way to determine false positives is through simple ratio estimations. The following is a list of ratios to estimate and the associated values that indicate a legitimate scan and not a false positive.

Connection Count / IP Count: This ratio indicates an estimated average of connections per IP. For portscans, this ratio should be high, the higher the better. For portsweeps, this ratio should be low.

Port Count / IP Count: This ratio indicates an estimated average of ports connected to per IP. For portscans, this ratio should be high and indicates that the scanned host’s ports were connected to by fewer IPs. For portsweeps, this ratio should be low, indicating that the scanning host connected to few ports but on many hosts.

Connection Count / Port Count: This ratio indicates an estimated average of connections per port. For portscans, this ratio should be low. This indicates that each connection was to a different port. For portsweeps, this ratio should be high. This indicates that there were many connections to the same port.

The reason that Priority Count is not included, is because the priority count is included in the connection count and the above comparisons take that into consideration. The Priority Count play an important role in tuning because the higher the priority count the more likely it is a real portscan or portsweep (unless the host is firewalled).

If all else fails, lower the sensitivity level. If none of these other tuning techniques work or the analyst doesn’t have the time for tuning, lower the sensitivity level. You get the best protection the higher the sensitivity level, but it’s also important that the portscan detection engine generates alerts that the analyst will find informative. The low sensitivity level only generates alerts based on error responses. These responses indicate a portscan and the alerts generated by the low sensitivity level are highly accurate and require the least tuning. The low sensitivity level does not catch filtered scans, since these are more prone to false positives.

The sd_pattern rule option is powered by the open source Hyperscan library from Intel. It provides a regex grammar which is mostly PCRE compatible. To learn more about Hyperscan see https://intel.github.io/hyperscan/dev-reference/

Snort provides sd_pattern as IPS rule option with no additional inspector overhead. The Rule option takes the following syntax.

Complete Snort IPS rules with built-in sensitive data patterns.

Let’s try them on the next traffic.

Printout of alert_cmg logger for this would be obfuscated.

But obfuscation doesn’t work for custom patterns.

Example of a rule with a custom pattern.

Traffic.

Printout of alert_cmg logger for this would not be obfuscated.

Threshold values are applied per packet.

So, traffic like this.

Doesn’t match a rule like this.

The SMTP inspector examines SMTP connections looking for commands and responses. It also identifies the command, header and body sections, TLS data and extracts the MIME attachments. This inspector also identifies and whitelists the SMTP traffic.

SMTP inspector logs the filename, email addresses, attachment names when configured.

SMTP command lines can be normalized to remove extraneous spaces. TLS-encrypted traffic can be ignored, which improves performance. In addition, plain-text mail data can be ignored for an additional performance boost.

The configuration options are described below:

ayt_attack_thresh number

Detect and alert on consecutive are you there [AYT] commands beyond the threshold number specified. This addresses a few specific vulnerabilities relating to bsd-based implementations of telnet.

The trace module is responsible for configuring traces and supports the following parameters:

The following lines, added in snort.lua, will enable trace messages for detection and codec modules. The messages will be printed to syslog if the packet filtering constraints match. Messages will be in extended format, including timestamp and n-tuple packet info at the beginning of each trace message.

The trace module supports config reloading. Also, it’s possible to set or clear modules traces and packet filter constraints via the control channel command.

The trace module has the modules option - a table with trace configuration for specific modules. The following lines placed in snort.lua will enable trace messages for detection, codec and wizard modules:

The detection and snort modules are currently the only modules to support multiple trace options. Others have only the default all option, which will enable or disable all traces in a given module. It’s available for multi-option modules also and works as a global switcher:

Also, it’s possible to enable or disable traces for all modules with a top-level all option.

The following configuration states that:

The full list of available trace parameters is placed into the "Basic Modules.trace" chapter.

Each option must be assigned an integer value between 0 and 255 to specify a level of verbosity for that option:

Tracing is disabled by default (verbosity level equals 0). The verbosity level is treated as a threshold, so specifying a higher value will result in all messages with a lower level being printed as well. For example:

There is a capability to filter traces by the packet constraints. The trace module has the constraints option - a table with filtering configuration that will be applied to all trace messages that include a packet. Filtering is done on a flow that packet is related. By default filtering is disabled.

Available constraints options:

The following lines placed in snort.lua will enable all trace messages for detection filtered by ip_proto, dst_ip, src_port and dst_port:

To create constraints that will never successfully match, set the match parameter to false. This is useful for situations where one is relying on external packet filtering from the DAQ module, or for preventing all trace messages in the context of a packet. The following is an example of such configuration:

There is a capability to configure the output method for trace messages. The trace module has the output option with two acceptable values:

By default, the output method will be set based on the Snort run mode. Normally it will use stdout, but if -D (daemon mode) and/or -M (alert-syslog mode) are set, it will instead use syslog.

Example - set output method as syslog:

In snort.lua, the following lines were added:

As a result, each trace message will be printed into syslog (the Snort run-mode will be ignored).

There is a capability to configure module trace options and packet constraints via the control channel command by using a Snort shell. In order to enable shell, Snort has to be configured and built with --enable-shell.

The trace control channel command is a way how to configure module trace options and/or packet filter constraints directly during Snort run and without reloading the entire config.

Control channel also allow adjusting trace output format by setting ntuple and timestamp switchers.

After entering the Snort shell, there are two commands available for the trace module:

Also, it’s possible to omit tables in the trace.set() command:

Each tracing message has a standard format:

The stdout logger also prints thread type and thread instance ID at the beginning of each trace message in a colon-separated manner.

The capital letter at the beginning of the trace message indicates the thread type.

Possible thread types: C – main (control) thread P – packet thread O – other thread

Setting the option - ntuple allows you to change the trace message format, expanding it with information about the processed packet.

It will be added at the beginning, right after the thread type and instance ID, in the following format:

Where:

Those info can be displayed only for IP packets. Port defaults to zero if a packet doesn’t have it.

The timestamp option extends output format by logging the message time in the next format:

Where:

The detection engine is responsible for rule evaluation. Turning on the trace for it can help with debugging new rules.

The relevant options for detection are as follow:

Buffer print is useful, but in case the buffer is very big can be too verbose. Choose between verbosity levels 1, 5, or no buffer trace accordingly.

rule_vars is useful when the rule is using ips rule options vars.

In snort.lua, the following lines were added:

The pcap has a single packet with payload:

Evaluated on rules:

The output:

Turning on decode trace will print out information about the packets decoded protocols. Can be useful in case of tunneling.

Example for a icmpv4-in-ipv6 packet:

In snort.lua, the following line was added:

The output:

There is a capability to track which inspectors evaluate a packet, and how much time the inspector consumes doing so. These trace messages could be enabled by the Snort module trace options:

Example for a single packet with payload:

In snort.lua, the following lines were added:

The output:

In snort.lua, the following lines were added:

The processed traffic was next:

The output:

The trace messages for two last packets (numbers 5 and 6) weren’t printed.

In snort.lua, the following lines were added:

The processed traffic was next:

After 1 packet, entering shell and pass the trace.set() command as follows:

The output (not full, only descriptive lines):

The new configuration was applied. decode:all:1 messages aren’t filtered because they don’t include a packet (a packet isn’t well-formed at the point when the message is printing).

There are more trace options supported by detection:

The rest support only 1 option, and can be turned on by adding all = 1 to their table in trace lua config.

When turned on prints a message in case inspection is stopped on a flow. Example for output:

Other modules that support trace have messages as seemed fit to the developer. Some are for corner cases, others for complex data structures.

Wizard supports 3 kinds of patterns:

Each kind of pattern has its own purpose and features. It should be noted that the types of patterns are evaluated exactly in the order in which they are described above. Thus, if some data matches a hex, it will not be processed by spells and curses.

The depth of search for a pattern in the data can be configured using the max_search_depth option

TCP packets form a flow, so wizard checks all data in the flow for a match. If no pattern matches and max_search_depth is reached, the flow is abandoned by wizard.

UDP packets form a "meta-flow" based on the addresses and ports of the packets. However, unlike TCP processing, for UDP wizard only looks at the first arriving packet from the meta-flow. If no pattern matches that packet or wizard’s max_search_depth is reached, the meta-flow is abandoned by wizard.

Spell is a text based pattern. The best area of usage - text protocols: http, smtp, sip, etc. Spells are:

In order to match any sequence of characters in pattern, you should use "*" (glob) symbol in pattern.

To escape "*" symbol, put "**" in the pattern.

Spells are configured as a Lua array, each element of which can contain following options:

Hexes can be used to match binary protocols: dnp3, http2, ssl, etc. Hexes use hexadecimal representation of the data for pattern matching.

Wildcard in hex pattern is a placeholder for exactly one occurrence of any hexadecimal digit and denoted by the symbol "?".

Hexes are configured in the same way as spells and have an identical set of options.

Curses are internal algorithms of service identification. They are implemented as state machines in C++ code and can have their own unique state information stored on the flow.

A list of available services can be obtained using snort --help-config wizard | grep curses.

The following is the equivalent of the above command line DAQ configuration in Lua form:

The daq.snaplen property was included for completeness and may be omitted if the default value is acceptable.

Like briefly mentioned above, a DAQ configuration consists of a base DAQ module and zero or more wrapper DAQ modules. DAQ wrapper modules provide additional functionality layered on top of the base module in a decorator pattern. For example, the Dump DAQ module will capture all passed or injected packets and save them to a PCAP savefile. This can be layered on top of something like the PCAP DAQ module to assess which packets are making it through Snort without being dropped and what actions Snort has taken that involved sending new or modified packets out onto the network (e.g., TCP reset packets and TCP normalizations).

To configure a DAQ module stack from the command line, the --daq option must be given multiple times with the base module specified first followed by the wrapper modules in the desired order (building up the stack). Each --daq option changes which module is being configured by subsequent --daq-var and --daq mode options.

When configuring the same sort of stack in Lua, everything lives in the daq.modules[] property. daq.modules[] is an array of module configurations pushed onto the stack from top to bottom. Each module configuration must contain the name of the DAQ module. Additionally, it may contain an array of variables (daq.modules[].variables[]) and/or an operational mode (daq.modules[].mode).

If only wrapper modules were specified, Snort will default to implicitly configuring a base module with the name pcap in read-file mode. This is a convenience to mimic the previous behavior when selecting something like the old Dump DAQ module that may be removed in the future.

For any particularly complicated setup, it is recommended that one configure via a Lua configuration file rather than using the command line options.

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 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 the ability to retrieve a DAQ_UsrHdr_t structure via ioctl. DAQ_UsrHdr_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.

Packets from the socket DAQ module are handled by Snort’s stream_user module, which must be configured in the Snort configuration.

To use the socket DAQ, start Snort like this:

The file module provides the ability to process files directly without having to extract them from pcaps. Use the file module with Snort’s stream_file to get file type identification and signature services. The usual IPS detection and logging, etc. is also available.

You can process all the files in a directory recursively using 8 threads with these Snort options:

The hext module generates packets suitable for processing by Snort from hex/plain text. Raw packets include full headers and are processed normally. Otherwise the packets contain only payload and are accompanied with flow information (4-tuple) suitable for processing by stream_user.

The first character of the line determines it’s purpose:

The available commands are:

Client and server are determined as follows. $packet → client indicates to the client (from server) and $packet → server indicates a packet to the server (from client). $packet followed by a 4-tuple uses the heuristic that the client is the side with the greater port number.

The default client and server are 192.168.1.1 12345 and 10.1.2.3 80 respectively. $packet commands with a 4-tuple do not change client and server set with the other $packet commands.

$packet commands should be followed by packet data, which may contain any combination of hex and strings. Data for a packet ends with the next command or a blank line. Data after a blank line will start another packet with the same tuple as the prior one.

$sof and $eof commands generate Start of Flow and End of Flow metapackets respectively. They are followed by a definition of a DAQ_FlowStats_t data structure which will be fed into Snort via the metadata callback.

Strings may contain the following escape sequences:

Format your input carefully; there is minimal error checking and little tolerance for arbitrary whitespace. You can use Snort’s -L hext option to generate hext input from a pcap.

The hext DAQ also supports a raw mode which is activated by setting the data link type. For example, you can input full ethernet packets with --daq-var dlt=1 (Data link types are defined in the DAQ include sfbpf_dlt.h.) Combine that with the hext logger in raw mode for a quick (and dirty) way to edit pcaps. With --lua "log_hext = { raw = true }", the hext logger will dump the full packet in a way that can be read by the hext DAQ in raw mode. Here is an example:

A comment indicating packet number and size precedes each packet dump. Note that the commands are not applicable in raw mode and have no effect.