Add Filters to a Request
As you construct queries with the API, you add filters to focus the search queries and find meaningful results. You can add any of these filter types for a given aspect of the query provided the Element supports the filter type.
In this topic:
Feature filters
When you build any query with the API, you must add a Feature filter to define the match criteria for an Element. If you do not add a Feature filter, the platform returns all instances of the selected Element, which can cause your environment to run very slowly.
Note
Adding a Feature filter in the request body is the same as selecting a Filter item in the Investigation screen.
When you add a Feature filter, you specify the Feature name by which to search and the values of the Feature for which to search. For example, if you add a Feature looking for a specific process name, the platform returns results with that process name. If you add multiple values for the search, Cybereason returns a match if the Feature contains any of the specific values.
For an Element, you can apply multiple filters. If you use more than one filter, an Element matches the criteria if the Element matches all of the defined filters.
The Feature filter in the request body is in the filters object.
The filters object contains the following fields:
Field |
Type |
Description |
|---|---|---|
facetName |
String |
The name of the Feature by which to filter. |
values |
List |
Values for the specific Feature by which to match when filtering the elements. Multiple values are allowed for non-Boolean features only. |
filterType |
Enum |
The search operator to apply to the filter. Valid values depend on the data type by which you are searching. |
For a list of available Features for each Element, see Query Elements and Features.
Example: Search for processes containing Chrome in the process name
In this case, the query returns a list of processes with the string Chrome, including chrome.exe, updater_chrome.exe, and so forth.
{
"queryPath": [
{
"requestedType": "Process",
"filters": [
{
"facetName": "elementDisplayName",
"values": [
"chrome"
]
}
],
"result": true
}
],
"queryLimits": {
"groupingFeature": {
"elementInstanceType": "Process",
"featureName": "elementDisplayName"
}
},
"totalResultLimit": 100,
"perGroupLimit": "100"
}
Example: Find machines running Windows 7 or Windows Vista
{
"queryPath": [
{
"requestedType": "Machine",
"filters": [
{
"facetName": "osVersionType",
"values": [
"Windows 7",
"Windows Vista"
]
}
],
"result": true
}
],
"queryLimits": {
"groupingFeature": {
"elementInstanceType": "Process",
"featureName": "elementDisplayName"
}
},
"totalResultLimit": 10000,
"perGroupLimit": 100,
"perFeatureLimit": 100
}
Example: Find machines with sensors in a sensor group (SOC Federation customers only)
{
"queryPath": [
{
"requestedType": "Machine",
"filters": [
{
"facetName": "group",
"filterType": "MatchesToken",
"values": [
"00000000-0000-0000-0000-000000000000",
"dab276af-b309-4170-85ed-0dd0ac6e0d2b"
]
}
],
"isResult": true
}
],
"totalResultLimit": 100,
"perGroupLimit": 100,
"perFeatureLimit": 100,
"templateContext": "SPECIFIC",
"queryTimeout": 120000,
"customFields": [
"group",
"osVersionType",
"platformArchitecture",
"uptime",
"isActiveProbeConnected",
"lastSeenTimeStamp",
"timeStampSinceLastConnectionTime",
"activeUsers",
"mountPoints",
"processes",
"services",
"elementDisplayName"
]
}
GUID filter
In addition, you can narrow your query by using Globally Unique Identifiers (GUIDs) for Elements. Each Element instance in the Cybereason platform has a special GUID which helps the Cybereason platform uniquely identify the item (process, file, and so forth).
Using GUIDs is helpful to focus on specific instance of an Element. For example, narrow down the search for specific machines or users, restrict results to a specific process instance or file, and so forth.
If you use multiple GUIDs in a filter, an Element matches the filter if its GUID matches any of the GUIDs used.
To filter by guids, add a guidList object parallel to the selected Element (the requestedType field).
Example: Filter the results by GUID
{
"queryPath": [
{
"requestedType": "Process",
"guidList": [
"983065095.904703596071019631",
"2005065441.250733381259028001",
"764229295.-8576675221926498235"
],
"result": true
}
]
}
Time filters
In addition, you can narrow your search to retrieve results from a given time frame.
To search by time, add a timeRange object to the request body:
{
"queryPath": [
{
"requestedType": "<Element>",
"filters": [
{
"facetName": "<Feature name>",
"values": [
"<value>"
]
}
]
"timeRange": {
"startFeatureId": "creationTime",
"startTime": 1427921395986,
"endTime": 1448390195518
},
"isResult": true
}
],
"templateContext": "<value>",
"totalResultLimit": "1000",
"perGroupLimit": "100",
"perFeatureLimit": "100",
"queryTimeout": "12000",
"customFields": [
"<value>",
"<value>",
"<value>"
]
}
In the timeRange object, you add the folloiwng keys:
startFeatureId or endFeatureId: The time-based Feature for the Element. The relevant time-based Features differ depending on the Element.
startTime: The beginning time (in epoch)
endTime: The end time (in epoch)
Example: Search for processes created during a certain time frame
This example searches for processes created in a certain time frame. In this case, the query returns all the processes created between April 1, 2015 and November 24, 2015.
{
"queryPath": [
{
"requestedType": "Process",
"timeRange": {
"startFeatureId": "creationTime",
"startTime": 1427921395986,
"endTime": 1448390195518
},
"result": true
}
],
"queryLimits": {
"groupingFeature": {
"elementInstanceType": "Process",
"featureName": "elementDisplayName"
}
}
}