uAQL - uberAgent Query Language (2024)

July 30, 2024

Contributed by:

Overview

The uberAgent Query Language (uAQL) is the language for uberAgent’s powerful Threat Detection and Event Data Filtering queries. Take a look at this blog post for an quick introduction.

uAQL query strings evaluate to either true or false. A simple example: the query Process.Name == "explorer.exe" tests if the current process name is equal to explorer.exe.

Data Types

uAQL is a type-safe language supporting the following data types:

Integer (a number)
Boolean (true or false)
String (a UTF-8 string literal, in other words: text)

Integer

A uAQL integer is a 64-bit signed number. Valid values are in the range between -9223372036854775808 and 9223372036854775807.

Boolean

A uAQL boolean is either true or false. Strings are implicitly converted to false. Integers with the value 1 are implicitly converted to true. All other integers are implicitly converted to false.

String

A uAQL string represents a sequence of characters that are wrapped in double quotes (") or single quotes ('), e.g., "string 1" or 'string 2'. Mixing different types of quotes (e.g., "uberAgent') is not allowed and results in a syntax error.

Character Escaping

Special characters can be specified by escaping them with a prepended backslash (\). This makes it possible to use newlines (\n), tabs (\t), and many other special characters in queries.

As a result, backslashes in paths, etc. need to be escaped, too. A Windows path such as C:\Windows is written in uAQL as "C:\\Windows".

Important: Regular expressions require a second round of escaping. To use the path C:\Windows in a regex, specify it as "C:\\\\Windows".

Raw Strings

To avoid having to write so many backslashes, consider using raw string literals, in other words, strings with character escaping disabled. Raw string literals start with a leading r before the opening quote. The path C:\Windows would be specified as a raw string like this: r"C:\Windows".

Important: regular expressions and the operators like as well as glob still require escaping, even with raw strings. To use the path C:\Windows in a regex or with like or glob, specify it as a raw string literal as r"C:\\Windows".

Character Escaping Examples

The following uAQL queries demonstrate different ways of matching files in uberAgent’s Config cache directory.

Using the icontains operator and a regular string:

Query = icontains(File.Path, "\\vast limits\\uberAgent\\Config cache\\")<!--NeedCopy-->

Using the like operator and a raw string:

Query = File.Path like r"%\\vast limits\\uberAgent\\Config cache\\%"<!--NeedCopy-->

Using the like operator and a regular string:

Query = File.Path like "%\\\\vast limits\\\\uberAgent\\\\Config cache\\\\%"<!--NeedCopy-->

Array

Arrays are special datatypes in uAQL that can hold one or multiple integers, booleans, and strings. An array is defined through square brackets: [Element 1, Element 2, Element n].

Arrays can be used in queries with the in operator. The following example tests if the current process name is equal to one of the elements in the array:

Process.Name in ["uberAgent.exe", "explorer.exe", "cmd.exe"]<!--NeedCopy-->

Operators

uAQL comes with operators for all sorts of logical and binary comparisons.

Operator	Description
`and`, `AND`	Logical AND
`or`, `OR`	Logical OR
`not`, `NOT`	Logical NOT
`==`	Equality. Case-insensitive for strings.
`===`	Equality. Case-sensitive for strings.
`!=`	Inequality. Case-insensitive for strings.
`!==`	Inequality. Case-sensitive for strings.
`<`	Less than.
`<=`	Less than or equal.
`>`	Greater than.
`>=`	Greater than or equal.
`in`, `IN`	Tests if the value on the left-hand side is equal to any element of the array on the right-hand side. Case-sensitive for strings.
`like`, `LIKE`	Pattern matching comparison as in SQL. The following wildcards can be used: The percent sign (`%`) matches zero, one, or many characters, including spaces. The underscore (`_`) matches a single character.
`glob`, `GLOB`	Uses the Unix file globbing syntax for wildcards. Case-sensitive.

Functions

The following functions can be used in uAQL queries:

Function	Description
`strlen(string)`	Returns the length of a string in characters as an integer.
`concat(string, string)`	Concatenates two strings and returns the result.
`lower(string)`	Transforms a string to lowercase and returns the result.
`upper(string)`	Transforms a string to uppercase and returns the result.
`startswith(string, string)`	Returns `true` if the first string starts with the second string, otherwise `false`. Case-sensitive.
`istartswith(string, string)`	Returns `true` if the first string starts with the second string, otherwise `false`. Case-insensitive.
`endswith(string, string)`	Returns `true` if the first string ends with the second string, otherwise `false`. Case-sensitive.
`iendswith(string, string)`	Returns `true` if the first string ends with the second string, otherwise `false`. Case-insensitive.
`contains(string, string)`	Returns `true` if the first string contains the second string, otherwise `false`. Case-sensitive.
`icontains(string, string)`	Returns `true` if the first string contains the second string, otherwise `false`. Case-insensitive.
`join(string array, seperator)`	Returns a concatenated list of all elements from the string array. The seperator can contain 0 to n characters. This function is useful when querying results returned by the registry_read_stringmulti function.
`regex_match(string, string)`	Returns `true` if the first string is matchable against the regular expression in the second string, otherwise `false`. Case-insensitive.
`regex_match_path(string, string)`	Unlike the default `regex_match` this version evaluates paths first. See PATH_REGEX for more details. Case-insensitive.
`registry_read_binary(hive, key, value)`	Reads a binary value from the registry and returns the data as a hexadecimal string (e.g. 0102FCFF). The hive, key and value parameters are strings.
`registry_read_number(hive, key, value)`	Reads a number from the registry. The hive, key and value parameters are strings.
`registry_read_string(hive, key, value)`	Reads a string from the registry. The hive, key and value parameters are strings.
`registry_read_stringmulti(hive, key, value)`	Reads a multi line string from the registry. The hive, key and value parameters are strings.
`get_env(environment variable name)`	Reads and returns the string value of a given environment variable name.
`set(variable name, value)`	Changes the string value of a given variable. Returns true on success, otherwise false.
`seti(variable name, value)`	Changes the integer value of a given variable. Returns true on success, otherwise false.
`setb(variable name, value)`	Changes the boolean value of a given variable. Returns true on success, otherwise false.
`isnull(variable name)`	Returns `true` if the given variable name has a null (undefined) value.
`isnull_or_empty(variable name)`	Returns `true` if the given variable name has a null (undefined) value or if it is an empty string.
`r"string"`	Evaluates a string as raw string, i.e., with character escaping turned off (see above).

Reserved Keywords

All event property names are reserved. Also, operator names including the following keywords are reserved:

Keyword	Description
`true`, `TRUE`, `True`	Boolean `true` constant.
`false`, `FALSE`, `False`	Boolean `false` constant.
`null`, `NULL`, `Null`	Null (undefined) value. E.g. returned by any registry_read_ function which reads data that does not match the expected registry value type.