Skip to main content
Sumo Logic

Using CIP Queries in Match Expressions

Learn what CIP search operators and functions you can use in CSE rule expressions.

This topic has information about using a CIP query as the match expression in a CSE rule. CSE supports some, but not all Sumo Logic search operators and options. The sections below describe the CIP search operators and options that CSE supports.

Aliasing limitations

In CIP log search queries, you can turn almost any expression into a field name by adding as <field> at the end. Currently CSE only supports such aliasing for the json operator, described below.

CIP operators supported in CSE

&&

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:

JSONPath Description
. or [] Child operator.
* Wildcard. All objects or elements regardless of their names.

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']

CIP literals supported in CSE

The following CIP literals are supported in CSE:

  • Time-based suffixed literals (millisecond-based. i.e., 1s == 1000)
    • ns (nanosecond)
    • us (microsecond)
    • ms (millisecond)
    • s (second)
    • m (minute)
    • h (hour)
    • d (day)
    • w (week)
  • Base-1000 suffixed literals
    • k or K (1,000)
    • M (1,000,000)
    • G or B (1,000,000,000)
    • T (1,000,000,000,000)
    • P (1,000,000,000,000,000)
  • Base-1024 suffixed literals
    • Ki (1,024)
    • Mi (1,048,576)
    • Gi (1,073,741,824)
    • Ti (1,099,511,627,776)
    • Pi (1,125,899,906,842,624)
  • Escaped double quote are supported
    • For example, "\"foo\"" is the literal "foo"

CIP functions supported in CSE

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”)