Preprocessor Documentation

README.filters

OVERVIEW OF FILTERS

This document describes the detection, rate, and event filtering, introduced in Snort 2.8.5, which control the generation, processing, and logging of events as follows:

  • detection_filter is a new rule option that replaces the current threshold keyword in a rule. It defines a rate which must be exceeded by a source or destination host before a rule can generate an event.

  • rate_filter provides rate based attack prevention by allowing users to configure a new action to take for a specified time when a given rate is exceeded.

  • event_filter is a standalone command which replaces ‘threshold’, which is now obsolete. event_filters reduce the amount of data logged.

  • Events can also be completely suppressed with the standalone suppress command.

Note: this README supercedes README.thresholding which is now deprecated.

DEPRECATED ITEMS

  • detection_filter replaces the existing in-rule threshold, which is now obsolete. Furthermore, the existing threshold when used within a rule was not part of the detection process; it was equivalent to a standalone threshold. To retain the functionality of existing in-rule thresholds, reformat them as standalone event_filters (see below).

  • event_filter replaces the existing standalone threshold, which is now deprecated. Furthermore, even though event_filter is an alias for threshold, which is allowed to appear in a rule (although that use is now also deprecated), event_filter will not be allowed in a rule. Such use will result in a fatal error during initialization.

DETECTION FILTERS

detection_filter is a new rule option that replaces the current threshold keyword in a rule. It defines a rate which must be exceeded by a source or destination host before a rule can generate an event. detection_filter has the following format:

detection_filter: \ track <by_src|by_dst>, \ count , seconds ;

  • Track by_src|by_dst: rate is tracked either by source IP address or destination IP address. This means count is maintained for each unique source IP address or each unique destination IP address.

  • Count c: the maximum number of rule matches in s seconds allowed before the detection filter limit to be exceeded. C must be nonzero.

  • Seconds s: time period over which count is accrued. The value must be nonzero.

Snort evaluates a detection_filter as part of the detection phase, just after pattern matching. At most one detection_filter is permitted per rule.

Example - this rule will fire on every failed login attempt from 10.1.2.100 during one sampling period of 60 seconds, after the first 30 failed login attempts:

drop tcp 10.1.2.100 any > 10.1.1.100 22 ( \ msg:”SSH Brute Force Attempt”; flow:established,to_server; \ content:”SSH”; nocase; offset:0; depth:4; \ detection_filter: track by_src, count 30, seconds 60; \ sid:1000001; rev:1;)

Since potentially many events will be generated, a detection_filter would normally be used in conjunction with an event_filter to reduce the number of logged events.

RATE FILTERS

rate_filter provides rate based attack prevention by allowing users to configure a new action to take for a specified time when a given rate is exceeded. Multiple rate filters can be defined on the same rule, in which case they are evaluated in the order they appear in the configuration file, and the first applicable action is taken.

Rate filters are used as standalone commands (outside any rule) and have the following format:

rate_filter \ gen_id , sig_id , \ track <by_src|by_dst|by_rule>, \ count , seconds , \ new_action alert|drop|pass|log|sdrop|reject, \ timeout , \ apply_to

This format has the following options - all are required except apply_to, which is optional:

  • Track by_src|by_dst|by_rule: rate is tracked either by source IP address, destination IP address, or by rule. This means the match statistics are maintained for each unique source IP address, for each unique destination IP address, or they are aggregated at rule level. For rules related to Stream5 sessions, source and destination means client and server respectively. track by_rule and apply_to may not be used together.

  • Count c: the maximum number of rule matches in s seconds before the rate filter limit to is exceeded. C must be positive.

  • seconds s: the time period over which count is accrued. 0 seconds means count is a total count instead of a specific rate. For example, rate filter may be used to detect if the number of connections to a specific server exceed a specific count. 0 seconds only applies to internal rules (gen_id 135) and other use will produce a fatal error by Snort.

  • new_action <alert|drop|pass|log|sdrop|reject>: new_action replaces rule action with alert|drop| pass|log|sdrop for r (timeout) seconds. Drop, reject and sdrop can be used only when snort is used in inline mode. sdrop and reject are conditionally compiled with #ifdef GIDS.

  • timeout r: revert to the original rule action after r seconds. If r is 0, then rule action is never reverted back. Event filter may be used to manage number of alerts after the rule action is enabled by rate filter.

  • apply_to : restrict the configuration to only to source or destination IP address (indicated by track parameter) determined by

    . track by_rule and apply_to may not be used together. Note that events are generated during the timeout period, even if the rate falls below the configured limit.

event_filters (below) can be used to suppress excessive rate_filter alerts, however, the first new_action event of the timeout period is never suppressed. Such events indicate a change of state that are significant to the user monitoring the network.

Example 1 - allow a maximum of 100 connection attempts per second from any one IP address, and block further connection attempts from that IP address for 10 seconds:

rate_filter \ gen_id 135, sig_id 1, \ track by_src, \ count 100, seconds 1, \ new_action drop, timeout 10

Example 2 - allow a maximum of 100 successful simultaneous connections from any one IP address, and block further connections from that IP address for 10 seconds:

rate_filter \ gen_id 135, sig_id 2, \ track by_src, \ count 100, seconds 0, \ new_action drop, timeout 10

EVENT FILTERS

In Snort 2.8.5, a new command event_filter was added with the following format. It functions the same as the global threshold command does in Snort 2.8.4 and earlier, except that it is not permitted within a rule.

event_filter \ gen_id , sig_id , \ type <limit|threshold|both>, \ track <by_src|by_dst>, \ count , seconds

This format supports the following options - all are required:

  • gen_id, sig_id: specify generator and signature ids of an associated rule. A sig_id of 0 will apply to all sig_ids for the given gen_id. If both gen_id and sig_id are zero, the event_filter applies to all events. Only one event_filter may be defined for a given gen_id, sig_id.

  • type <limit|threshold|both>: type limit alerts on the 1st m events during the time interval, then ignores events for the rest of the time interval. Type threshold alerts every m times we see this event during the time interval. Type both alerts once per time interval after seeing m occurrences of the event, then ignores any additional events during the time interval.

  • track by_src|by_dst: rate is tracked either by source IP address, or destination IP address. This means count is maintained at either by unique source IP addresses, or unique destination IP addresses.

  • count c: number of rule matching in s seconds that will cause event filter limit to exceed. C must be nonzero value. A count of -1 disables the event filter and can be used to override the global event_filter.

  • seconds s: time period over which count is accrued. S must be nonzero value.

Example 1 - rule event_filter - limit to logging 1 event per 60 seconds:

event_filter \ gen_id 1, sig_id 1851, \ type limit, track by_src, \ count 1, seconds 60

Example 2 - rule event_filter - limit to logging every 3rd event:

event_filter \ gen_id 1, sig_id 1852, type threshold, track by_src, \ count 3, seconds 60

Example 3 - rule event_filter - limit to logging just 1 event per 60 seconds, but only if we exceed 30 events in 60 seconds:

event_filter \ gen_id 1, sig_id 1853, \ type both, track by_src, \ count 30, seconds 60

Example 4 - global event_filter - limit to logging 1 event per 60 seconds per IP triggering each rule:

event_filter \ gen_id 1, sig_id 0, \ type limit, track by_src, \ count 1, seconds 60

Example 5 - global event_filter - limit to logging 1 event per 60 seconds per IP triggering each rule for each event generator:

event_filter \ gen_id 0, sig_id 0, \ type limit, track by_src, \ count 1, seconds 60

EVENT SUPPRESSION

Suppression commands are standalone commands that reference generators and SIDs and IP addresses via an IP list. This allows a rule to be completely suppressed, or suppressed when the causative traffic is going to or coming from a specific IP or group of IP addresses.

The suppress command has these formats:

suppress \ gen_id , sig_id

suppress \ gen_id , sig_id , \ track by_src|by_dst, \ ip

  • gen_id, sig_id: specify generator and signature ids of an associated rule. A sig_id of 0 will apply to all sig_ids for the given gen_id. If both gen_id and sig_id are zero, the event_filter applies to all events. Multiple suppress commands may be defined for a given gen_id !=0, sig_id != 0.

  • track by_src|by_dst: rate is tracked either by source IP address or destination IP address. This means count is maintained for each unique source or destination IP address. If ip is provided, track must be provided as well.

  • ip : restrict the suppression to only source or destination IP addresses (indicated by track parameter) determined by . If track is provided, ip must be provided as well.

Example 1 - suppress this event completely:

suppress \ gen_id 1, sig_id 1852

Example 2 - suppress this event from this IP:

suppress \ gen_id 1, sig_id 1852, \ track by_src, ip 10.1.1.54

Example 3 - suppress this event to this CIDR block:

suppress \ gen_id 1, sig_id 1852, \ track by_dst, ip 10.1.1.0/24

MEMORY CAPS

Memory caps can be configured for maximum storage of run-time data (excludes configuration) as follows:

config rate_filter: memcap config event_filter: memcap

If the rate_filter reaches its memcap, it will recycle memory by releasing the oldest tracker and using that memory for a new tracker. The event_filter works the same way.

The default in both cases is 1048576 bytes (1MB). (Internally, global event_ filters (sig_id = 0) are tracked separately from local event_filters (sig_id != 0) and the memcap limit is applied to each group separately, yielding 2*memcap total for event_filter.)