Filter syntax

Comparison Operators

The filter comparison operators table describes the comparison operators that you can use as part of the filter parameter.

Null values and comparison operators

When the field that you filtered on has a 'null' value, comparison operators behave in the following ways:

• "=", ">", ">=", "<", "<=", "IN", and "BETWEEN" operators always return false.
• "!=", "<>", "^=", "NOT BETWEEN", and "NOT IN" always return true.

The best way to test for null values is to use the "is null" or "is not null" operators.

Logical operators

Use the logical operators OR, AND, and NOT to perform logical operations on subexpressions. The following table provides examples of how to use logical operators in filters.

Specifying JSON fields for comparisons

The following table explains how to specify JSON fields for use with comparison operators in filters.

{
"name": "Proprietary Data",
"element_type": "ALN"
}

{
 "description": "String",
 "duration": {
  "days": 42,
  "hours": 42,
  "minutes": 42,
  "months": 42,
  "seconds": 42.5,
  "years": 42
  }
}

["events","flows","simarc"]

Specifying string and numeric values in filters

When you filter on strings that have values with non-alphanumeric characters, you must wrap the target string in quotation marks. When you filter on numeric values, the numeric values can follow these conditions:

• Start with a leading + or - sign.
• Contain or start with a decimal point.
• Include an exponent by using e notation.

Filtering complex objects by using the CONTAINS operator

You filter complex objects by using the CONTAINS operator. You use the CONTAINS operator to test the contents of lists or maps. On the left side of the operator, is an identifier that is in the standard format, for example x(y(z)). The identifier must refer to an element that is a list, map, or collection. On the right side of the operator is an expression that specifies how the objects in the list must be matched. There are two basic use cases for using the CONTAINS operator:

• The list that is examined contains simple elements like strings or numbers.
• The list contains complex objects.

Lists that contain simple types

For lists that contain simple types such as strings or numbers, the expression is a value of the same type. For single comparisons, no brackets are required.

To request only asset saved searches that have ftp as the string in the filter's value field:

GET /api/asset_model/saved_searches?filter=filters%20contains%20value%20%3D%20ftp

To request assets where interfaces contains the IP address "192.0.2.0":

GET /api/asset_model/assets?filter=interfaces%20contains%20ip_addresses%20contains%20value%20%3D%20%192.0.2.0%22

Lists that contain complex objects

For lists that contain complex objects, the expression is a complete filter expression for the objects within the list. This subfilter expression uses the same syntax as any other filter. You can use any operator in the subfilter to test sublists inside the original list. Identifiers in this expression are relative to the objects in the list that the CONTAINS operator is operating on. In complex subfilter expressions, brackets are required.

To request only assets that have a field value = 14 and the Greater than operator , apply the filter filters contains (value = 14 or operator = "Greater than"). This filter returns the first and the last elements in the list.

GET /api/asset_model/saved_searches?filter=filters%20contains%20(value%20%3D%2014%20and%20operator%20%3D%20%22Greater%20than%22)

To find offenses that contain source addresses that have ID values less than 3 apply the following filter:

GET /api/siem/offenses?filter=source_address_ids%20contains%20(.%3C3)

The LIKE operator

Use the LIKE operator to retrieve partial string matches.

The LIKE operator uses the following format: identifier like "expression". Quotation marks around the expression are mandatory. Single and double quotation marks are supported. The LIKE keyword does case-sensitive matching.

The following wildcard characters are supported. If you use wildcard characters in a string, you must escape them.

GET /path/to/api
[
 {
 "hostname": "server.domain1"
 },
 {
 "hostname": "server.domain2"
 },
 {
 "hostname": "SERVER.domain"
 },
 {
 "hostname": "server.DOMAIN"
 }
]

You can combine the wildcard characters in the same expression. For example, to find servers in domain1 or domain2, use the expression: hostname LIKE "%.domain_".

GET /path/to/api?filter=hostname%20LIKE%20%22%25.domain_%22 
[
 {
 "hostname": "server.domain1"
 },
 {
 "hostname": "server.domain2"
 }
]

Notice that SERVER.domain is not returned, because the underscore (_) has no matching trailing character.

The ILIKE operator

Use the ILIKE operator to retrieve case-insensitive partial string matches.

GET /path/to/api
[
 {
 "hostname": "server.domain1"
 },
 {
 "hostname": "server.domain2"
 },
 {
 "hostname": "SERVER.domain"
 },
 {
 "hostname": "server.DOMAIN"
 }
] 

GET /path/to/api?filter=hostname%20ILIKE%20%22server.domain%22'
[
 {
 "hostname": "SERVER.domain"
 },
 {
 "hostname": "server.DOMAIN"
 }
]