Documentation

Contents
Contents
Contents
Contents

uAQL – uberAgent Query Language

Overview

The uberAgent Query Language (uAQL) is the language for uberAgent’s powerful Activity Monitoring and Event Data Filtering queries.

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.

  1. If yes, the query yields true
  2. If no, the query yields false

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 using the operators like as well as glob still requires 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".

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
== 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.
not in, NOT IN Tests if the value on the left-hand side is inequal to all elements 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.
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.
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.

Leave a Reply

Your email address will not be published. Required fields are marked *