Query Language Reference

The general syntax is a logical expression followed by an "order by" clause.

Search Expression syntax

Expression syntax

Specifies the search condition for the query's results.

Expression syntax

There are 3 logical operators: not, and, or.

The precedence level of operation is: 'not' > 'and' > 'or', with 'not' being evaluated first and 'or' evaluated last. Expressions can also be nested using parenthesis.

For logical comparisons, the following operators are available: '==' (equals), '!=' (different), '<' (less than), '>' (greater than), '>=' (greater than or equal), '<=' (less than or equal).

"in" operator

The operator 'in' will evaluate to true if the variable is equal to any of the elements in the list.

This will return all requests made by "admin" and "example_user":

username in ("admin", "example_user")

Which is equivalent to:

username == "admin" or username == "example_user"

"contains" operator

The contains operator is used for variables that stores lists of things. The following query will return all requests that applied both "rule_a" and "rule_b" rules:

rules contains ("rule_a", "rule_b")

This operator only supports lists, and lists can only be compared using this operator.

Order By syntax

The "order by" clause sorts the results by one or more fields.

Order By syntax

Examples

order by timestamp

order by timestamp asc

order by timestamp desc, ip asc

scanned == true order by timestamp desc

Valid fields

The following fields can be used in place of "VARIABLE_NAME" in all expressions:

Name	Type	Description
timestamp	DateTime	Date/time the request happened
instanceId	Text	Id of the shield instance that processed this request
apps	Text Array	List of apps that matched to this rule
hostname	Text	Hostname of the http server for this request
contentType	Text	Content type of the request
username	Text	User that made this request
userGroup	Text	Comma separated list of user groups
ip	Ip	User Ip address
ipLocation	Text	User country detected through the ip address
device	Text	User device description
rules	Text Array	List of rules matched to the request
detectedDataTypes	Text Array	List of data types detected on this request
scanned	Bool	`true` if the request was scanned
detected	Bool	`true` if the request was detected
obfuscated	Bool	`true` if the request was obfuscated

Field Types

Each field has a type that can be DateTime, Text, Text Array, Ip or bool. Text and bool are straightforward and can be compared using: the comparison operators (like == or >) and the in operator. The other types are detailed as follows:

DateTime

A datetime can be compared using the same comparison operators as Text, but must follow a specific format. The simplest format to define a specific date is in the format YYYY-MM-DD, where YYYY is the year, MM the month and DD the day. The following query returns all requests that happen after 2022-01-01 at 00:00:

timestamp >= "2022-01-01"

To refer to a specific date and time, use the rfc 3339 string. The query below is equivalent to the one above:

timestamp >= "2022-01-01T00:00:00Z"

Relative dates can also be used. In the query below, requests that happened the last 10 days are returned:

timestamp >= '-10d'

Examples

Request happened within the last 10 days
```
timestamp >= '-10d'
```
Request happened within the last 10 hours
```
timestamp >= '-10h'
```
Request happened within the last 10 minutes
```
timestamp >= '-10m'
```
Request happened within the last 10 days and 5 hours
```
timestamp >= '-10d 5h'
```

Ip

Ip addresses should be in the ipv4 octet format (as in "192.167.14.2").

Examples

Returns all requests made by "192.167.14.2"
```
ip == "192.167.14.2"
```
Returns all requests made by the subnet at "192.168.x.x"
```
ip >= "192.168.0.0" && ip <= "192.168.255.255"
```

Text Arrays

These type contains a list, and can only be compared with the "contains" operator.

Examples

All requests that both "rule_a" and "rule_b" matched.
```
rules contains ("rule_a", "rule_b")
```

Examples

Request happened at or later than '2021-01-01'
```
timestamp >= '2021-01-01'
```
Request happened at or after '2021-01-01' and was scanned
```
timestamp >= '2021-01-01' and scanned == true
```

Request happened at or after '2021-01-01' and was obfuscted or detected

timestamp >= '2021-01-01' and (scanned == true or detected == true)

Note that this is different from:

timestamp >= '2021-01-01' and scanned == true or detected == true

Which due to operator precedence, is interpreted as:

(timestamp >= '2021-01-01' and scanned == true) or detected == true

Request that happened at '2021-01-01'

timestamp >= '2021-01-01' and timestamp <= '2021-01-02'

Scanned requests, sorted by timestamp
```
scanned == true order by timestamp
```
All requests in which credit cards and domains were detected, sorted by ascending timestamp
```
detectedDatatypes contains ("CREDIT_CARD","DOMAIN") order by timestamp asc
```