Rule Syntax | uberAgent 7.2.1 (2024)

July 31, 2024

Contributed by:

uberAgent ESA’s Threat Detection rules are part of the configuration. This page documents the rule syntax.

Example

The following example shows a simple rule that is triggered whenever a process is started (EventType = Process.Start). The rule’s query checks if the started process’ name is wmiprvse.exe. If that is the case, the rule matches, and an event with the tag proc-start-wmiservice-child is sent to the backend.

[ThreatDetectionRule]RuleId = 0a1bbfbc-e0d9-4c49-953e-e31c3aa3fc91RuleName = Detect child processes of the WMI serviceEventType = Process.StartAnnotation = {"mitre_attack": ["T1071", "T1071.004"]}Tag = proc-start-wmiservice-childQuery = Parent.Name == "wmiprvse.exe"<!--NeedCopy-->

Rule Stanzas

There can be any number of [ThreatDetectionRule] stanzas, each defining one rule. Rules are processed in the order in which they are defined in the configuration. uberAgent ESA always processes all rules for every activity. This means that multiple events may be generated per activity.

Rule Components

An [ThreatDetectionRule] stanza may contain the following components.

RuleName

Setting name: RuleName
Description: any name to more easily identify a rule. Not used by uberAgent.
Valid values: any string
Default: empty
Required: yes

EventType

Setting name: EventType
Description: the type of event this rule applies to.
Valid values: see the event types page
Default: empty
Required: yes

Annotation

Setting name: Annotation
Description: one or more annotations for the event in JSON format
Valid values:
- Supported in Splunk Enterprise Security: nist, kill_chain_phases, cis20, mitre_attack, or any custom cyber security framework
- Supported in uberAgent ESA: mitre_attack
Default: empty
Required: no

Hive

This setting is only valid for registry events.

Setting name: Hive
Description: a comma-separated list of registry hives that are matched against before evaluating the query. For best performance, only the necessary hives should be specified.
Valid values:
- HKLM, matches HKEY_LOCAL_MACHINE
- HKU, matches HKEY_USERS
- A, matches application hives
- WC, matches App-V packages and UWP apps
- *, matches events in any hive. Note that * has a high performance impact and should be avoided if possible.
Default: empty
Required: only if EventType is a registry event type.

Query

Setting name: Query
Description: a uAQL query string that is matched against the properties of the event. A rule is considered matching if the query returns true.
Valid values: any uAQL query string
Default: empty
Required: yes

RuleId

Setting name: RuleId
Description: a unique id assigned to this rule.
Valid values: any string, e.g.: 7098a059-4191-4a9e-973c-8976d61cddc0
Default: empty
Required: yes

RiskScore

Setting name: RiskScore
Description: a risk score assigned to events matching this rule.
Valid values: any number from 0 to 100. If an invalid value is set, the rule is ignored.
Default: 50
Required: no

VerboseLogging

Setting name: VerboseLogging
Description: if enabled, more detail is added to the log file, e.g., the fully evaluated security descriptor if an SDDL rule is configured.
Valid values: true or false
Default: false
Required: no

Rule Evaluation

Rules are evaluated by running the rule’s query with the event properties as input.

Reusable uAQL Queries

Commonly used queries can be defined as expressions, a functionality that is similar to macros or functions in other languages. This gives you the flexibility to write query code only once and use it multiple times.

Example

The following declares the Threat Detection expression ParentIsMsOffice to identify Microsoft Office as a parent application.

[AddThreatDetectionExpression name=ParentIsMsOffice]Query = istartswith(Parent.Company, "Microsoft") and Parent.Name in ["excel.exe", "msaccess.exe", "onenote.exe", "outlook.exe", "powerpnt.exe", "winword.exe"]<!--NeedCopy-->

The expression ParentIsMsOffice is used in the following Threat Detection rule to identify child processes of Microsoft Office.

[ThreatDetectionRule]Query = ParentIsMsOffice and (Process.Name in ["cmd.exe", "cscript.exe", "wscript.exe", "ftp.exe"] or ProcessIsPowerShell)<!--NeedCopy-->

Please note that expressions must be defined before usage. Ideally, expressions are defined at the top of the configuration file. Also, please make sure not to use reserved keywords as expression names.

Disabling Default Rules

To disable any of the default rules, create a post-processing rule as follows:

[ThreatDetectionRuleExtension RuleId=RULE_ID]Name = Disable the rule with ID RULE_IDQuery = false<!--NeedCopy-->

Example

To disable the rule with the ID 7098a059-4191-4a9e-973c-8976d61cddc0, add the following stanza to any uberAgent configuration file:

[ThreatDetectionRuleExtension RuleId=7098a059-4191-4a9e-973c-8976d61cddc0]Name = Disable the rule with ID 7098a059-4191-4a9e-973c-8976d61cddc0Query = false<!--NeedCopy-->

Handle False Positives with Post-Processing

Consider the following default rule, which, unfortunately, also matches certain Splunk processes:

[ThreatDetectionRule]RuleId = bdc64095-d59a-42a2-8588-71fd9c9d9abcRuleName = Suspicious Unsigned Dbghelp/Dbgcore DLL LoadedEventType = Image.LoadTag = suspicious-unsigned-dbghelp/dbgcore-dll-loadedRiskScore = 75Annotation = {" mitre_attack" : [" T1003.001" ]}Query = ((Image.Path like r" %\\dbghelp.dll" or Image.Path like r" %\\dbgcore.dll" ) and Image.IsSigned == false)<!--NeedCopy-->

To prevent the above rule from matching your Splunk processes, add the following post-processing stanza to any uberAgent configuration file:

[ThreatDetectionRuleExtension RuleId=bdc64095-d59a-42a2-8588-71fd9c9d9abc]Query = Rule.Result and Parent.Name != "Splunkd.exe"<!--NeedCopy-->

The above rule extension does what its name implies: it extends the original rule’s uAQL query with additional statements, which is ideal for adding exclusions.

An important feature of how we’ve set up rule post-processing is its flexibility. Extension sections can be used not just for one rule at a time, but they can also be applied to groups of rules together. For example, a certain extension section could be set up to affect all rules that deal with network events:

[ThreatDetectionRuleExtension EventType=Net.Any]Query = Rule.Result and Parent.Name != "Splunkd.exe"<!--NeedCopy-->