uAQL - uberAgent Query Language
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 (
trueorfalse) -
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\\")
Using the
like operator and a raw string:
Query = File.Path like r"%\\vast limits\\uberAgent\\Config cache\\%"
Using the
like operator and a regular string:
Query = File.Path like "%\\\\vast limits\\\\uberAgent\\\\Config cache\\\\%"
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"]
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. |