Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

 

Filter Syntax

 

To limit the results that are returned in an API retrieval request (HTTP GET), most JSA API endpoints that return lists of resources support the filter parameter.

The filter parameter syntax is consistent for all endpoints that support it. Refer to the documentation for the endpoint to determine whether the filter parameter applies to it. Any limitations for the filter syntax are included in that endpoint's description. Query parameters must be double URL encoded before they are sent.

Comparison Operators

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

Table 1: Filter Comparison Operators

Operator

Description

Example Filter Syntax

=

Equality between the identifier and the specified value returned.

To find offenses where status=CLOSED, use the following syntax:

GET /api/siem/offenses?filter=status%3DCLOSED

>

Identifier is greater than the specified value.

To find offenses where credibility > 3, use the following syntax:

/api/siem/offenses?filter=credibility%20%3E%203

<

Identifier is less than the specified value.

To find offenses where magnitude < 9, use the following syntax:

/api/siem/offenses?filter=magnitude%20%3C%209

<=

Identifier is less than or equal to the specified value.

To find offenses where id <= 1004, use the following syntax:

/api/asset_model/properties?filter=id%20%3C%3D%201004

>=

Identifier is greater than or equal to the specified value.

To find offenses where scanProfileId >= 3, use the following syntax:

/api/scanner/scanprofiles?filter=scanProfileId%

20%3E%3D%203

!=,

<>,

^=

Identifier is not equal to the specified value.

The following examples filter all IDs that are not equal to 5:

/api/siem/offenses?filter=id%20!%3D%205

/api/siem/offenses?filter=id%20%3C%3E%205

/api/siem/offenses?filter=id%20%5E%3D%205

in

Identifier is equal to at least one of the specified values in the list.

Syntax: id in (1001,1111,1200):

Example: /api/asset_model/assets?filter=

id%20in%20(1001%2C1111%2C1200)

not in

Identifier is not equal to any of the specified values in the list.

Syntax: id not in (1001,1002,1003):

Example: /api/asset_model/saved_searches?

filter=id%20not%20in%20(14%2C20

%2C1003)

between … and ...

Identifier is between two specified values.

Syntax: id between 0 and 3:

Example: /api/siem/offenses?filter=id%20between%200%20and%203

not between … and …

Identifier is not between two specified values.

Syntax: id not between 30 and 31:

Example: /api/siem/offenses?filter=id%20not%20between

%2030%20and%2031

is null

Identifier is null.

Syntax: assigned_to is null

Example: /api/siem/offenses?filter=assigned_to%20is%20null

is not null

Identifier is not null.

Syntax: assigned_to is not null

Example: /api/siem/offenses?filter=assigned_to%20is%20not%20null

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.

Operator

Description

Example

or

Performs a logical OR operation on the two subexpressions. The subexpressions might be comparison nodes or other logical nodes.

assigned_to is not null OR id = 111:

/api/siem/offenses?filter=assigned_to%20is%20not%20null

%20or%20id%20%3D%20111

and

Performs a logical AND operation on the two subexpressions. The subexpressions might be comparison nodes or other logical nodes.

assigned_to is not null AND id = 111:

/api/siem/offenses?filter=assigned_to%20is%20not%20null

%20and%20id%20%3D%20111

not

Performs a logical NOT operation on the subexpression.

protected =true and not id in (111,112,113)

/api/siem/offenses?filter=protected%20%3D%20true%20and

%20not%20id%20in%20(111%2C112%2C113)

Specifying JSON Fields for Comparisons

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

JSON field example

Description

Example

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

When you apply a filter to a field directly in the object that is returned, the field is specified by name.

name = "Proprietary Data"

GET /api/reference_data/sets?filter=name%20

%3D%20%22Proprietary%20Data%22

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

When you apply a filter to a field nested inside a sub object use brackets to specify the inner field.

duration(days) >= 20

GET/api/scanner/scanprofiles?filter=

duration(days)%20%3E%3D%201

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

For simple JSON types where no field label exists, such as strings, numbers, or Boolean, use the . operator.

.= events

GET /api/ariel/databases?filter=.%3D%20events

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%20

    contains%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%20

    contains%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.

Wildcard character

Description

%

Matches a string of zero or more characters

_

Matches any single character

For example, consider an API that returns the following collection of data:

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_".

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.

The ILIKE operator is similar to the LIKE operator, but is case-insensitive. For example, consider an API that returns the following collection of data:

Filter with the expression hostname ILIKE "server.domain" produces the following collection of data: