Using CIP Queries in Match Expressions

&&

A logic AND operator, equivalent to AND in CSE rules syntax. 

|| 

A logical OR, equivalent to OR in CSE rules syntax. 

==

Returns “true” if the two expressions are equal. The two expressions must be the same type, and must be a type that can be used in an equality comparison. For complex types such as array and struct, the data types of fields must be orderable.

Syntax:

expr1 == expr2 

! 

A logical NOT operator.

if

Evaluates a condition as either true or false, with values assigned for each outcome. It is a shorthand way to express an if-else condition. On the basis of the test, the entire expression returns value_if_true if the condition is true, else value_if_false if the condition is false. The two sub-expressions (value_if_true and value_if_false) must have the same type.

You can nest the if operator.

Syntax: 

if(condition, value_if_true, value_if_false)

Examples:

| if(status_code matches "5*", 1, 0) as serverError

Here is an example of nesting the if operator.

| if(severity >= 10, "Critical", if(severity >= 5, "Moderate", "Low"))

matches

Can be used to match a string to a wildcard pattern or an RE2 compliant regex. The operator returns a boolean value; the operator can be used with where or if operators.

Syntax:

• where <string expression> matches <pattern>
• where <string expression> matches /<regex>/
• where !(<string expression> matches <pattern>)

Examples: 

• where foo matches "*bar*" (This example is equivalent to foo LIKE '%bar%' in the CSE rules syntax.)
• where foo matches /.*bar.*/ (This example is equivalent to foo RLIKE '.*bar.*' in the CSE rules syntax.)

json

Extracts values from JSON logs with selected JSONPath expressions. See Supported JSONPath syntax elements below.

You can use the json operator allows to extract:

• Single, top-level fields
• Multiple fields
• Nested keys
• Keys in arrays

Syntax:

| json field=<field_name> "<name_or_key>"[, "<name_or_key>", ...] [as <field> ...]

Supported JSONPath syntax elements:

Syntax notes:

• In CIP, you can use the json operator without specifying a field to parse, in which case the operation is performed against the _raw field. CSE does not have a _raw field, so if you are going to use a query with the json operator in CSE, you must use the syntax above. An alias is required.
• The pipe character before the first json clause is optional.
• You can use multiple json clauses in a query.
• You can use only one where clause per query.
• CSE doesn’t support all of the json operator syntax options that CIP does, but you can do things like:
  • | json field=fields "foo.bar['baz']" as nestedKey
  • | json field=fields "foo[0]" as indexKey
  • json field=fields "foo[*]" as asteriskKey
    Works for arrays, not maps.
  • | json field=fields "['foo.bar']" as topLevelKey
    This is a top-level key named `foo.bar`.

Examples:

| json field=fields "foo" as alias
| where toInt(alias) > 5

| json field=fields "packetsSent" as packets_sent
| json field=fields "packetsReceived" as packets_received
| where toInt(packets_sent) != toInt(packets_received)

The second query shown above is equivalent to the following CSE syntax. 

int(fields['packetsSent']) != int(fields['packetsReceived']

asciiToHex 

Casts an ASCII string to a hexadecimal string. This is equivalent to toHex in the CSE rules syntax.

Syntax: 

• asciiToHex(<ascii_string>)
• asciiToHex(<ascii_field>)

base64Decode 

Casts a base64 string to an ASCII string, encoded as UTF-8. This is equivalent to fromBase64 in the CSE rules syntax.

Syntax: 

base64Decode("<string>")
base64Decode(<string_field>)

base64Encode 

Takes an ASCII string and converts it to a base64 string. This is equivalent to toBase64 in the CSE rules syntax.

Syntax:

base64Encode("<string>")
base64Encode(<string_field>)

contains

Compares string values of two fields and returns a boolean result based on whether the second field's value exists in the first.

Syntax:

contains(<field1>, <field2>)

floor

Rounds down to the largest previous integer value. Returns the largest integer not greater than x. This is equivalent to int in the CSE rules syntax.

Syntax:

floor(<x>)

Examples: 

• floor(1.5) as v
  Sets v to the value “1”
• floor(-1.5) as v 
  Sets v to the value “-2”

hexToAscii 

Converts a hexadecimal string to an ASCII string. This is equivalent to fromHex in the CSE rules syntax.

Syntax: 

• hexToAscii(<hexadecimal_field>)
• hexToAscii("<hexadecimal string>")

isBlank

Checks to see if a string contains text. Specifically, it checks to see if a character sequence is whitespace, empty (""), or null. It takes a single parameter and returns a boolean value: “true” if the variable is blank, or “false” if the variable contains a value other than whitespace, empty, or null.

Syntax:

isBlank(string)

isEmpty

Checks to see if a string contains no characters or whitespace, and returns a boolean value: “true” if the string contains no characters or whitespace, or “false” otherwise.

Syntax:

isEmpty(string)

isNull

Checks to see if a string is null, and returns a boolean value: “true” if the string is null, or “false” if the string is not null.

Syntax:

isNull(string)

isNumeric

Checks whether a string is a valid Java number. 

Valid numbers include hexadecimals marked with the 0x or 0X qualifier, octal numbers, scientific notation and numbers marked with a type qualifier, like 123L.

Syntax:

isNumeric("<string>")
isNumeric(<string_field>)

jsonArrayContains 

Returns “true” if a specified field contains a particular value. This is equivalent to array_contains in the CSE rules syntax.

Syntax:

jsonArrayContains(field, “value”)

Example: 

| where jsonArrayContains(field, “vuln_scanner”)

jsonArraySize 

Returns the length of a string. Returns -1 if null. This is equivalent to size in the CSE rules syntax.

Syntax: 

jsonArraySize(field) > value

Example: 

| where jsonArraySize(field) > 5

num

Casts string data to a number.

Syntax: 

num(string)

number

Casts string data to a number.

Syntax: 

number()

toDouble

Casts string data to the double data type.

Syntax: 

toDouble(<field>)

toFloat 

Casts a string to a floating point number. This is equivalent to float in the CSE rules syntax.

Syntax:

float(<field>)

toInt 

Casts a string to an integer This is equivalent to int in the CSE rules syntax.

Syntax:

int (<field>)

toLong

Casts string data to the long data type.

Syntax: 

toLong(<field>)

toLowerCase 

Converts a string to all lower case letters. This is equivalent to lower in the CSE rules syntax.

Syntax:

toLowerCase(<string>)

toUpperCase 

Converts a string to all uppercase letters. This is equivalent to upper in the CSE rules syntax.

Syntax:

toUpperCase(<string>)

where

Filters results based on the value of a boolean expression.  

Syntax:

... | where <boolean expression>

Example:

| where jsonArrayContains(field, “vuln_scanner”)