Chapter 24: Threshold Rules

Home Prev	cOS Stream 4.00.03 Administration Guide	Next

Overview

The objective of the threshold rules feature is to provide a means of reacting to abnormal flow activity. An example of such activity might be an internal host becoming infected with a virus so that it repeatedly opens new flows to external IP addresses.

Alternatively, an external network device might try to open excessive numbers of flows to some protected resource. (A "flow" in this context refers to any type of connections, such as TCP, UDP or ICMP, which is being tracked by the system's state-engine).

Threshold Rule Object Structure

The object structure used with threshold rules is as follows:

ThresholdRules

This is a predefined top level object. Only one exists and its only purpose is to be a parent to one or more ThresholdRule objects.
ThresholdRule

Multiple of these can be added to the ThresholdRules object as children. This object defines the filter that targets specific traffic. The filter includes source/destination network/interface plus the service.
ThresholdSet

Multiple of these can be added to a ThresholdRule object as children. This object defines an action to be taken when all the set's associated ThresholdDefinitions objects trigger, as well as the logging performed when they do.
ThresholdDefinition

Multiple of these can be added to a ThresholdSet as children. Each defines either a level of concurrent flows or rate of new flow establishment as a trigger. The action of the parent ThresholdSet is only applied when all of its child ThresholdDefinition objects are triggered.

ThresholdRule Properties

A ThresholdRule object is a child of the single predefined ThresholdRules object and has the properties listed below to filter the targeted traffic:

SourceInterface
SourceNetwork
DestinationInterface
SourceNetwork
Service

This filtering combination of source/destination network/interface and service is common to other rules, such as IPRule objects.

ThresholdSet Properties

A ThresholdSet object is a child of a ThresholdRule object and has the following key properties:

Action

This is the response of the rule when the limit is exceeded. The options are:
1. None - Leave the flow intact but generate a log event message.
2. Drop - Drop the triggering flow.
3. RandomDrop - Drop triggering flows randomly using the Probability property.
4. Blacklist - Add the source IP to the system blacklist. It will stay on the blacklist for the number of seconds specified by the Timeout property. The blacklisting action will be ignored for IPs on the system whitelist.
  
  When the blacklist is listed with the blacklist CLI command, the name of this set's parent ThresholdRule will be displayed in the Rule column for entries added by this action.

ActionLog

This decides if logging is to be done or not. The possible values are:
1. ObeyRule - This is the default value. Logging is decided by the logging setting on the associated IP rule.
2. NeverLog - No logging is done.
3. AlwaysLog - Logging is always done.

ActionLogSeverity

This is the log severity with which log messages will be sent to log receivers.

Probability

If the Action property is set to RandomDrop, this is an integer value that specifies the percentage of flows that will be dropped.

Timeout

This property is only used if the Action is set to Blacklist and must be specified if the action is set to this. It specifies the time in seconds that the source IP will remain on the blacklist.

If the value is specified as 0 then the source IP will remain on the blacklist until the system is restarted or if the IP is removed manually from the blacklist using the blacklist CLI command. The blacklist command is described further in Section 25.1, Blacklisting.

ThresholdDefinition Properties

One or more ThresholdDefinition objects are children of a ThresholdSet object and the threshold limit(s) that must be triggered before the parent ThresholdSet action is applied.

The key properties for this object are the following:

Type

The rule can be specified to limit either one of the following:
1. FlowRate - The number of new flows opened per second.
2. ConcurrentFlows - The total number of concurrent flows.

Limit

This is the numerical maximum threshold for the Type.

This setting takes an integer value with a minimum of 1 and an upper limit of 2 billion.

	Note: Limit can optionally have a unit specified
The property Limit can optionally be specified with a unit of measurement. Any of the following unit notations can be used: K - Thousands (examples: 2K, 2.5K, 900K) M - Millions (examples: 5M, 2.25M). G - Billions (examples: 3G, 4.125G). As shown in the above examples, the numeric value used can be integer or decimal. Also, different units cannot be mixed in a single value.

Note: Limit can optionally have a unit specified

The property Limit can optionally be specified with a unit of measurement. Any of the following unit notations can be used:

K - Thousands (examples: 2K, 2.5K, 900K)
M - Millions (examples: 5M, 2.25M).
G - Billions (examples: 3G, 4.125G).

As shown in the above examples, the numeric value used can be integer or decimal. Also, different units cannot be mixed in a single value.

Interval

This is the number of seconds during which all the limits of the Type are added together to get a sum. If this sum exceeds the Limit then triggering is ready but is still subject to the Duration property, which is explained next.

This setting can take time values between 1 second and any value. The default value is 1 second.

Duration

Once the sum of the Type exceeds the Limit value within the Interval number of seconds, another sum is calculated during the subsequent Duration number of seconds. If this sum also exceeds the Limit during this subsequent period then the threshold will now be triggered.

Following triggering, the summing of values begins again within the next Interval number of seconds, and the process repeats.

This value has no maximum limit. The default value is 0.

	Note: Time values must be specified with a unit notation
Both the above time properties Interval and Duration must be specified with their units of measurement, unless the value is zero. Any of the following unit notations can be used: s - Seconds (examples: 2s, 2.5s, 1000s) m - Minutes (examples: 5m, 2.25m). h - Hours (examples: 3h, 4.125h). d - Days (examples: 1d, 3.5d). This can only be used with Duration. As shown in the above examples, the numeric value used can be integer or decimal. Also, different units cannot be mixed in a single time value.

Note: Time values must be specified with a unit notation

Both the above time properties Interval and Duration must be specified with their units of measurement, unless the value is zero. Any of the following unit notations can be used:

s - Seconds (examples: 2s, 2.5s, 1000s)
m - Minutes (examples: 5m, 2.25m).
h - Hours (examples: 3h, 4.125h).
d - Days (examples: 1d, 3.5d). This can only be used with Duration.

As shown in the above examples, the numeric value used can be integer or decimal. Also, different units cannot be mixed in a single time value.

Grouping

The thresholds can be applied by grouping meaning that flows from a single grouping are considered together when calculating if a threshold has been exceeded. For example, if the Grouping property is set to SourceIP, then by default all the traffic from a single source IP address is added together when calculating if a threshold has been exceeded. However, this behavior can be altered using the Scope property (see below).
1. None - no grouping.
2. SourceIP.
3. SourceNetwork.
4. SourceInterface.
5. DestinationIP.
6. DestinationNetwork.
7. DestinationInterface.
Note grouping by interface is usually used with VLANs and VPN.

GroupingIP4NetworkSize

Used if the Grouping property is specified as SourceNetwork or DestinationNetwork. This is the size of the IPv4 network, specified as an integer. The default value is 16.

GroupingIP6NetworkSize

Used if the Grouping property is specified as SourceSubnet or DestinationSubnet. This is the size of the IPv6 network, specified as an integer. The default value is 64.

Scope

This specifies how the Grouping property is applied. It can have one the following values:
1. Group (the default)
  
  This setting applies the limit separately to each group. For example, with a total flow limit of 100 and 7 active groups then the effective limit is 100 flows for each group.
  
  Similarly, for a limit on flow setup rate, each group applies the limit separately from other groups.
2. Shared
  
  For a limit on the total number of flows, this setting applies the limit across all groups by dividing the total limit by the number of groups. For example, if the limit is 100 flows and there are 7 active groups then the limit becomes 14 flows per group.
  
  If the number of groups exceed the number of flows then cOS Stream will allocate the available flows on a randomized basis with the probability of allocation depending on the number of active groups and the flow limit.
  
  When the limit is on the rate of flow setup, all groups share the limit.

ThresholdLog

When enabled (the default), log messages are generated for each time this object triggers and when it stops triggering.

ThresholdLogSeverity

The severity of the log messages generated. The default severity is Default.

Triggering Multiple Actions

If one or more ThresholdSet objects trigger at the same time then the following rules apply to decide which action has priority:

If the Action property of the ThresholdSet objects has differing values then the following priority is used (where number 1 is the highest priority):
1. Drop.
2. RandomDrop.
3. None.
If the Action property of the ThresholdSet objects is the same value then the ordering of the ThresholdSet objects determines which one is used. The first ThresholdSet object found is used and the others are ignored.

Example 24.1. Creating a Threshold Rule

This example creates threshold rules that are applied to HTTP traffic passing between the if1 and if2 interface. Once the number of concurrent flows reaches 1000, subsequent new flows will be dropped.

Command-Line Interface

Change the current CLI context to be the threshold rule set:

System:/> cc ThresholdRules
System:/ThresholdRules>

Add a new ThresholdRule object:

System:/ThresholdRules> add ThresholdRule
			SourceNetwork=if1_net
			SourceInterface=if1
			DestinationNetwork=if2_net
			DestinationInterface=if2
			Service=http
			Name=my_rule

Change the CLI context to be the new ThresholdRule object:

System:/ThresholdRules> cc ThresholdRule my_rule

Note that the object could have been referred to by its name my_rule or its position in the set of rules, as shown below:

System:/ThresholdRules> cc ThresholdRule 1

Add a new ThresholdSet object:

System:/ThresholdRules/ThresholdRule/1(my_rule)> add ThresholdSet
			Action=Drop
			Name=my_set

Change the CLI context to be the new ThresholdSet object:

System:/ThresholdRules/ThresholdRule/1(my_rule)> cc ThresholdSet my_set

Add a new ThresholdDefinition object:

System:/ThresholdRules/ThresholdRule/1(my_rule)/ThresholdSet/1(my_set)> 
			add ThresholdDefinition
			Type=ConcurrentFlows
			Limit=1000
			Name=my_def

To return to the parent CLI context use the cc.. command:

System:/ThresholdRules/ThresholdRule/1(my_rule)/ThresholdSet/1(my_set)> 
			cc..
System:/ThresholdRules/ThresholdRule/1(my_rule)>

To return to the default top-level CLI context use the cc command:

System:/ThresholdRules/ThresholdRule/1(my_rule)/ThresholdSet/1(my_set)> cc
System:/>

Advanced Settings for Threshold Rules

The threshold rules subsystem has the following associated global setting which is a property of the MiscSettings object:

MaxThresholdMemUsage

This is the maximum percentage of system memory that the threshold subsystem can use. The default value is 10. This value may need to be increased when large numbers of flows trigger the subsystem.

If large numbers of the log event Random group replacement are generated during normal operation then increasing memory could reduce this problem. Note that a denial-of-service attack could also result in large quantities of this log message being generated.