uberAgent

Rule Syntax

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.

[ActivityMonitoringRule]
RuleId = 0a1bbfbc-e0d9-4c49-953e-e31c3aa3fc91
RuleName = Detect child processes of the WMI service
EventType = Process.Start
Annotation = {"mitre_attack": ["T1071", "T1071.004"]}
Tag = proc-start-wmiservice-child
Query = Parent.Name == "wmiprvse.exe"
<!--NeedCopy-->

Rule Stanzas

There can be any number of [ActivityMonitoringRule] 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 [ActivityMonitoringRule] 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

registry events.

This setting is only valid for registry events.

  • Setting name: Hive
  • Description: a comma-separated list of registry hives that will be 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

Tag

  • Setting name: Tag
  • Description: a tag assigned to events matching this rule.
  • Valid values: any string
  • Default: empty
  • Required: yes

RuleId

  • Setting name: RuleId
  • Description: an 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
  • Default: 50
  • Required: no

VerboseLogging

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

Rule Evaluation

Rules are evaluated by evaluating a rule’s query with the properties of an event that occurred.

Reusable uAQL Queries

Threat Detection can store common queries in expressions that can then be used in other queries. 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.

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

[ActivityMonitoringRule]
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.

Disable default shipped rules

Rules can be filtered by their RuleId setting. This gives the flexibility to disable certain rules without merging changes in configuration files during updates. The RuleId field is unique and persistent over uberAgent releases.

The stanza ActivityMonitoringRule_Filter defines a deny list to ignore certain rules by their id.

[ActivityMonitoringRule_Filter]
7098a059-4191-4a9e-973c-8976d61cddc0 = uberAgent_denylist
d5b4d0b7-1bfe-4a6b-9664-7b321bfa4094 = uberAgent_denylist
21791409-7892-4122-9441-066955ee01b5 = uberAgent_denylist
<!--NeedCopy-->
Rule Syntax