July 30, 2024
Contributed by:
C
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
.
- If yes, the query yields
true
- If no, the query yields
false
Data Types
uAQL is a type-safe language supporting the following data types:
- Integer (a number)
- Boolean (
true
orfalse
) - 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. |