This topic has information about CSE Aggregation rules and how to write them.
Aggregation rules: purpose and use case
This section describes the purpose of Aggregation rules, and gives an example of how you would use one. If you’re ready to jump in and configure a rule, see Create an Aggregation rule below.
An Aggregation rule is useful when you want to fire a Signal based multiple conditions—up to six—being met over a period of time.
As an example, suppose you want to fire a Signal when the ratio of failed to successful HTTP requests is too high—75% or more. You can use an Aggregation rule to calculate the percentage of failed requests, and configure the rule to fire a signal when the request failure rate is 75% or higher.
The table below summarizes the rule configuration. Each row corresponds to an element of the sentence-style configuration UI for the If Triggered settings for an Aggregation rule.
|Configuration setting||What it does|
|When Records matching the expression
||Filters the Records to which the rule will be applied: only Records that contain a non-null http_response_statusCode field.|
||Specifies the field by which aggregation results will be grouped: device_ip|
||Specifies the duration across which Records will be evaluated.|
|Defines an aggregation named “good”, which counts the number of Records encountered during the within duration in which the
|Defines an aggregation named “bad”, which counts the number of Records encountered during the within duration in which the
|that match the following condition
||Specifies the condition for firing a Signal based on the results of the “good” and “bad” aggregation: more than 75% percent of requests failed during the within duration,|
The screenshot below shows the If Triggered configuration for the example rule in the Rules Editor.
Create an Aggregation rule
- Select Rules from the Content menu.
- Click Create.
- Click the Aggregation tile.
- Name. At the top of the Rules Editor, enter a name for the rule. Signals fired by the rule will have the same name as the rule.
Configure “If Triggered” settings
On the left side of the Rules Editor, in the If Triggered section, you configure a filter that determines the Records to which the rule will be applied, and the conditions under which you want the rule to fire a Signal. Here’s the UI before any entries have been made:
- When Records matching the expression. Enter one or more boolean expressions to filter the Records you want to apply the rule to. For example:
- grouped by. Specify the Record field or fields by which aggregation results will be grouped. Note that when you define the On Entity field for the rule (in Configure “Then Create a Signal” settings below), the field you choose will automatically appear here. If you want to aggregate on other fields, you can select them from the selector list.
- Within. Select the length of time across which the rule is applied. The options range from 5 minutes to 5 days.
- have aggregations. To define an aggregation:
- Name. Give the aggregation a brief, meaningful name. You’ll reference the aggregation by its name in the trigger condition for the rule.
- Function. Select an aggregation function:
- Expression. Enter an expression to filter the Records to be aggregated. For example, the following expression results in the aggregation being applied to Record whose
http_response_statusCodefield is greater than 201.
http_response_statusCode > 201
- To define another aggregation, click Add Aggregation and repeat the previous three steps.
- that match the following condition. Enter one or more boolean expressions, based on the results of the configured aggregations, which when true will cause the rule to fire a Signal. For example, given the following expression, a rule will fire a Signal when the sum of
Aggregation-2is greater than 5.
Aggregation-1 + Aggregation-2 > 5
Configure “Then Create a Signal” settings
On the right side of the Rules Editor, in the Then Create a Signal section, you configure details of the Signals that your rule will fire. Here’s the UI before any entries have been made:
- On Entity. Use the pull-down list to select one or more Entity fields. (Entity fields are fields that contain an IP address, hostname, or username. When the rule is triggered it will fire a Signal on each of the entity fields you select.
- with the description. Enter a description for the Signal. The Signal description should be a good indication of what the rule looks for.
- with the stage. Select the MITRE ATT&CK stage that best describes the behavior the rule is looking for, for example, “initial access” or “execution”.
- with a severity of. Severity is an estimate of the criticality of the detected activity, from 1 (lowest) to 10 (highest). There are two ways to specify Severity.
- with a constant severity. Choose constant, and select a severity level.
- with a dynamic severity. Use dynamic if you want to base the severity level on a value of a field in the Record. Select a field from the list.
- with tags. If desired, you can add metadata tags to your rule. Tags are useful for adding context to items like Rules, Insights, Signals, Entities. You can also search for and filter items by tag. For more information, see Using Tags with Insights, Signals, Entities, and Rules.
Save this rule as a prototype. Click this checkbox to save the rule as a prototype, so that Signals created by the rule won’t be used to generate Insights.
Make your rule a prototype (optional)
If you are not sure that your rule is ready for prime time, you can save it as a prototype. A prototype rule generates Signals, but those Signals won't contribute to Insights. (Signals generated by a prototype rule do not increment the rule's On Entity entity's Activity Score.) Running the rule as a prototype for a while allows you to determine whether the rule is too noisy and fires too many Signals.
To make the rule a prototype, click the box next to Save this rule as a prototype. When you are satisfied with the rule's behavior you can uncheck the box.
Click Submit to save the rule.