Apply Operators in Filters
When you add Feature filters in the request body for a query, you must also add a search operator for each Feature. You add the operator in the filtertype key in the filters object in the request body.
For details on how to build the request body, see Build a Query Request.
The operators you can use differ according to the Feature’s value type (string, enum, Boolean, or integer). For example, when you search for a machine of a specific name - a string value - the available operators include ContainsIgnoreCase and Equals, among others.
You define the search operators in the filterType field of the filters object of a request.
String Operators
Due to the way Cybereason queries data from the data retention feature’s database, some query operators for strings are different than those used when data retention is not enabled. The following operators are available for string Features:
Operator |
Description |
---|---|
ContainsIgnoreCase |
Returns results for items in which the search string appears, even as only part of the complete string. This operator is not case sensitive. For example, if you want to search for a certain hash value but you only have a partial string, you use this operator. |
Equals |
Returns results for items that are an exact match to the search string. This operator is not case sensitive. For example, if you want to search for a specific process name (such as process associated with known malware) or search for a certain hash value but you may not have the correct format with correct capitalization, use this operator. |
NotContainsIgnoreCase |
Returns results for items that do not contain the search string. This operator is not case sensitive. If you want to exclude certain values, such as a specific hash value, but you want to use a partial string, use this operator. |
NotEquals |
Returns results for items that are not an exact match to the search string. This operator is not case sensitive. For example, isearch for a certain hash value, but you are not sure that you have the correct format with correct capitalization, use this operator. |
Note
The ContainsIgnoreCase and NotContainsIgnoreCase operators (in versions 19.0+ and earlier) use considerably more resources and can slow query performance. In addition, the MatchesToken operator returns results faster than the MatchesWildcard operator.
Cybereason is gradually migrating customers to the new Data Platform architecture that involves minor changes, including updates to string operators. If you are using the architecture, the following string operators are available:
Operator |
Description |
---|---|
ContainsIgnoreCase |
Returns results for items in which the search string appears, even as only part of the complete string. This operator is not case sensitive. For example, if you want to search for a certain hash value but you only have a partial string, you use this operator. If your Cybereason environment uses the new Data Platform infrastructure, this operator is available from version 22.1.22X and later. |
Equals |
Returns results for items that are an exact match to the search string. This operator is not case sensitive. For example, if you want to search for the name of a process that is associated with known malware, or for a certain hash value, but you are not sure about the format or capitalization in the name or hash value, use this operator. |
NotEquals |
Returns results for items that are not an exact match to the search string. This operator is not case sensitive. For example, if you want to exclude the exact name of a process, or search for a specific hash value, but you are not sure about the format or capitalization in the name or hash value, use this operator. |
MatchesToken |
Returns results that contain the token in the search string. For example, for a selected Feature, Cybereason breaks the results into tokens. If you have a pattern c://ps//memlick//bla210.exe, the platform breaks this string into tokens, such as but not limited to these examples:
As a result, if you use a value of exe or memlick//bla201.exe for the query, the Cybereason platform returns c://ps//memlick//bla210.exe as one of the results. |
MatchesWildCard |
Searches for wildcards in the prefix and suffix of the string. If no wildcard is present, the system will automatically add a wildcard to the end of the string. For example, a search for ‘ab’ will be translated to ‘ab*’. You can use these wildcards:
This operator is available in versions earlier than 22.1.22X. |
NotContainsIgnoreCase |
Returns results for items that do not contain the search string. This operator is not case sensitive. If you want to exclude certain values, such as a specific hash value, but you want to use a partial string, use this operator. If your Cybereason environment uses the new Data Platform infrastructure, this operator is available from version 22.1.22X and later. |
NotMatchesToken |
Returns results that do not contain the words in the search string. |
NotMatchesWildCard |
Allows you to add a wildcard (*) at the beginning or end of a string to search for items that do not contain the specified string. If no wildcard is present, the system will automatically add a wildcard to the end of the string. For example, a search for ‘ab’ will be translated to ‘ab*’. You do not need to include the escape character () when using the wildcard (*). This operator is available in versions earlier than 22.1.22X. |
Enum Operators
The following operators are available for enum-type Features:
Operator |
Description |
---|---|
Equals |
Default value. Returns results for items that are an exact match to the value in the Enum list. |
Not Equals |
Returns results for all items that are not an exact match to the value in the list. IMPORTANT: This also returns items for which the value is null. |
ContainsIgnoreCase |
Returns results for items in which the search string appears, even as only part of the complete string. This operator is not case sensitive. For example, use this operator if you want to search for a specific hash value but you only have a partial string. This operator is available from versions 20.2.281 and 21.1.101 and later. |
NotContainsIgnoreCase |
Returns results for items that do not contain the search string. This operator is not case sensitive. For example, use this operator if you want to exclude certain values, such as a specific hash value but with a partial string. This operator is available from versions 20.2.281 and 21.1.101 and later. |
MatchesWildcard |
Returns results that match the pattern in the search string, including wildcard characters. You can use these wildcards:
You can also use the slash character as an escape character. This operator is available from versions 20.2.281 and 21.1.101 and later if you are using the newer data infrastructure. |
NotMatchesWildcard |
Returns results that do not match the pattern in the search string, including wildcard characters. This operator is available from versions 20.2.281 and 21.1.101 and later if you are using the newer data infrastructure. |
Boolean Operators
The following operators are available for for boolean Features:
Operator |
Description |
---|---|
Equals |
Default value. Returns results for items whose value are an exact match to the value used for the Boolean. |
NotEquals |
Returns results for all whose value is not an exact match to the boolean value. IMPORTANT: This also returns items for which the value is NULL. |
Numeric (Integer) Operators
The following operators are available for integer-type Features:
Note
When sending numeric queries with the API, all units are in KB.
Operator |
Description |
---|---|
Equals |
Default value. Returns results for items where the number is an exact match to the numeric value of the query. For example, all password that were reset in the last n days. |
NotEquals |
Returns results for items that where the number is not an exact match to the numeric value in the query. For example passwords that were not reset in the last n days. |
LessThan |
Returns results for items that are less than the numeric value in the query. For example, files small than X MB. |
LessOrEqualsTo |
Returns results for items that are less than or an exact match to the numeric value in the query. |
GreaterThan |
Returns results for items that are greater than the numeric value in the query. For example, files larger than X MB. |
GreaterOrEqualsTo |
Returns results for items that are greater than or an exact match to the numeric value in the query. |
Between |
Returns results for items that are between two values, including the two values. For example, process with between 2 and 5 children will return all processes that have at least and no more than 5 children. |
Collections Operators
The following operators are available for Features of type Collection:
Operator |
Description |
---|---|
Equals |
Returns results that are an exact match to the number of items contained in the collection. |
NotEquals |
Returns results that are not an exact match to the number of items contained in the collection. |
LessThan |
Returns results where the number of items contained in the collection is less than the value specified in the query. |
LessOrEqualsTo |
Returns results where the number of items contained in the collection is less than or an exact match to the value specified in the query. |
GreaterThan |
Returns results where the number of items contained in the collection is greater than the items specified in the query. |
GreaterOrEqualsTo |
Returns results where the number of items contained in the collection is greater than or an exact match to the value specified in the query. |
Between |
Returns results for collections that have the number of items between the two values, including two values. |
Includes |
Returns results when an item in the collection contains the search string as part of the complete string. |
NotIncludes |
Returns results when an item in the collection doos not include the search string. |