Run an Advanced Investigation Query
In this tutorial, we will explain, step-by-step, how to run a more advanced investigation query (with more than one Element) and related Features.
Before you read and follow the steps in this tutorial, we recommend you do the Run a Simple Investigation Query tutorial.
For this tutorial, you are going to use the scenario of finding machines that have processes downloaded from the Internet:
You must have the Analyst L1, Analyst L2, or Analyst L3 role to perform this request.
When performing investigations, you may need to use multiple Elements to learn more. For example, you may want to find machines with a certain type of process, or users that opened processes, and so forth. In cases such as this, you can also use the Cybereason API to create a query with mutliple Elements.
In this topic:
Build the first Element
Note
The request body is the same regardless of how you run the request (such as a cURL command, in a REST API client, or Python script).
In your REST API client, open a new tab/file.
In the relevant field, enter the URL for the request:
https://<your server address>/rest/visualsearch/query/simple
For example, in Postman, you enter the URL here:
Ensure that the method for the request is set to POST. (This may be the default for your REST API client, but if not, ensure that you select it.)
For the Headers, in the Key column, add a Content-Type header.
In the Value column, add the value application/json.
For example, in Postman, your header will look like this:
Navigate to the section to add your request body. In Postman, for example, this is in the Body tab.
In the Body tab, ensure that you ahve set your client editor to enable you to add raw JSON content. In Postman, for example, ensure that Raw is selected.
In the request body edit area, enter an open and closed bracket {}. This is the standard syntax for JSON.
Inside the brackets, add this template request body:
{ "queryPath":[ { "requestedType":"<First Element name>", "filters":[], "connectionFeature": { "elementInstanceType":"<Element for Feature>", "featureName":"<Connection Feature>" }, "isResult":true }, { "requestedType":"<Second Element name>", "filters":[ { "facetName":"<Feature filter>", "values":["value"] } ] } ], "totalResultLimit":1000, "perGroupLimit":100, "perFeatureLimit":100, "templateContext":"SPECIFIC", "queryTimeout":120000, "customFields":[ "osVersionType", "platformArchitecture", "uptime", "isActiveProbeConnected", "lastSeenTimeStamp", "timeStampSinceLastConnectionTime", "activeUsers", "mountPoints", "processes", "services", "elementDisplayName" ] }
In the sample query you saw above, the first Element in the query was a Machine Element. Therefore, we need to add the API name for the Machine Element for the value of the first requestedType key. In the API, the name for the Machine Element is Machine.
In the request body, in the queryPath object, for the first requestedType key, update the <First Element value> placeholder value to Machine:
{ "queryPath":[ { "requestedType":"**Machine**", "filters":[], "connectionFeature": { "elementInstanceType":"<Element for Feature>", "featureName":"<Connection Feature>" }, "isResult":true }, { "requestedType":"<Second Element name>", "filters":[ { "facetName":"<Feature filter>", "values":["value"] } ] } ], "totalResultLimit":1000, "perGroupLimit":100, "perFeatureLimit":100, "templateContext":"SPECIFIC", "queryTimeout":120000, "customFields":[ "osVersionType", "platformArchitecture", "uptime", "isActiveProbeConnected", "lastSeenTimeStamp", "timeStampSinceLastConnectionTime", "activeUsers", "mountPoints", "processes", "services", "elementDisplayName" ] }
Normally, for each Element in a query, you need to add a Feature. However, in the sample query you saw above, there are no filters applied for the Machine Element.
In the queryPath object, for the filters objecct for the first requestedType key (with the value Machine), leave the filters object empty as it is in the template response.
Add the details to connect Elements
When you connect Elements in the Cybereason API, you must add details on the Feature that connects the Elements.
For most Elements in the Cybereason platform’s data model, these Elements connect to other Elements. These connections are made by Features in one Element that are actually references to data from another Element. For example, for processes, you can se the machine on which a process runs (represented by the ownerMachine Feature on the Process Element), or connections that the process made (represented by the connections Feature for the Process Element).
When you create the request body, you need to define the Feature that connects the Elements in the query.
In the example query for this tutorial, you are connecting a Machine Element to a Process Element. You will use the processes Feature (which is a collection of all processes on a machine) to connect the Machine Element to the Process Element.
For a list of those Features which connect Elements, see Use Multiple Elements in a Query.
In the request body, in the queryPath object, find the connectionFeature object. This object contains the information on how the Elements connect.
In the connectionFeature object, in the elementInstanceType key, update the <Element for Feature> placeholder value to Machine.
{ "queryPath":[ { "requestedType":"Machine", "filters":[], "connectionFeature": { "elementInstanceType":"**Machine**", "featureName":"<Connection Feature>" }, "isResult":true }, { "requestedType":"<Second Element name>", "filters":[ { "facetName":"<Feature filter>", "values":["value"] } ] } ], "totalResultLimit":1000, "perGroupLimit":100, "perFeatureLimit":100, "templateContext":"SPECIFIC", "queryTimeout":120000, "customFields":[ "osVersionType", "platformArchitecture", "uptime", "isActiveProbeConnected", "lastSeenTimeStamp", "timeStampSinceLastConnectionTime", "activeUsers", "mountPoints", "processes", "services", "elementDisplayName" ] }
Since the processess Feature connects the Machine Element and the Process Element, you must also add this information into the request body.
Below the elementInstanceType key, for the featureName key, update the <Connection Feature> placeholder value to processess.
{ "queryPath":[ { "requestedType":"Machine", "filters":[], "connectionFeature": { "elementInstanceType":"Machine", "featureName":"**processes**" }, "isResult":true }, { "requestedType":"<Second Element name>", "filters":[ { "facetName":"<Feature filter>", "values":["value"] } ] } ], "totalResultLimit":1000, "perGroupLimit":100, "perFeatureLimit":100, "templateContext":"SPECIFIC", "queryTimeout":120000, "customFields":[ "osVersionType", "platformArchitecture", "uptime", "isActiveProbeConnected", "lastSeenTimeStamp", "timeStampSinceLastConnectionTime", "activeUsers", "mountPoints", "processes", "services", "elementDisplayName" ] }
Note
Since you want to return details about machines, not processes, you will see that the isResult key is set for the Machine Element (the first requestedType key in the request body). If you use the Process Element as the target Element, you would add the isResult key there.
Add the second Element
After you add the connection information for both Elements, you must also add another Element to the query. In the sample query for this tutorial, the second Element is the Process Element (which has a name of Process in the API).
In the request body, in the queryPath object, find the second requestedType Key.
For the requestedType key, update the update of the <second Element name> placeholder value to Process:
{ "queryPath":[ { "requestedType":"Machine", "filters":[], "connectionFeature": { "elementInstanceType":"Machine", "featureName":"processes" }, "isResult":true }, { "requestedType":"**Process**", "filters":[ { "facetName":"<Feature filter>", "values":["value"] } ] } ], "totalResultLimit":1000, "perGroupLimit":100, "perFeatureLimit":100, "templateContext":"SPECIFIC", "queryTimeout":120000, "customFields":[ "osVersionType", "platformArchitecture", "uptime", "isActiveProbeConnected", "lastSeenTimeStamp", "timeStampSinceLastConnectionTime", "activeUsers", "mountPoints", "processes", "services", "elementDisplayName" ] }
For the second Element, you will use a filter Feature, since you are looking for processes downloaded from the internet (which has the name isDownloadedFromInternet in the API).
In the queryPath object, below the second queryPath key, in the filters object, for the facetName key, update the <Feature filter> placeholder value to isDownloadedFromInternet.
{ "queryPath":[ { "requestedType":"Machine", "filters":[], "connectionFeature": { "elementInstanceType":"Machine", "featureName":"processes" }, "isResult":true }, { "requestedType":"Process", "filters":[ { "facetName":"**isDownloadedFromInternet**", "values":["value"] } ] } ], "totalResultLimit":1000, "perGroupLimit":100, "perFeatureLimit":100, "templateContext":"SPECIFIC", "queryTimeout":120000, "customFields":[ "osVersionType", "platformArchitecture", "uptime", "isActiveProbeConnected", "lastSeenTimeStamp", "timeStampSinceLastConnectionTime", "activeUsers", "mountPoints", "processes", "services", "elementDisplayName" ] }
Below the facetName key, for the values array, update the <value> placeholder value to true (without quotes).
You use this value because the isDownloadedFromInternet Feature is a boolean type, and requires a true or false value.
{ "queryPath":[ { "requestedType":"Machine", "filters":[], "connectionFeature": { "elementInstanceType":"Machine", "featureName":"processes" }, "isResult":true }, { "requestedType":"Process", "filters":[ { "facetName":"isDownloadedFromInternet", "values":[true] } ] } ], "totalResultLimit":1000, "perGroupLimit":100, "perFeatureLimit":100, "templateContext":"SPECIFIC", "queryTimeout":120000, "customFields":[ "osVersionType", "platformArchitecture", "uptime", "isActiveProbeConnected", "lastSeenTimeStamp", "timeStampSinceLastConnectionTime", "activeUsers", "mountPoints", "processes", "services", "elementDisplayName" ] }
Leave the values for the other keys as they are in the template syntax. These are the default values.
In your client machine, run the request.
The response will contain a list of machines on which there are processes downloaded from the internet.
Next steps
Now that you understand how to create queries that use multiple Elements, you will be able to add multi-Element queries to your automation scripts to run these queries on a regular basis.