Run a Simple Investigation Query

This topic provides a step by step example of how you can use the API to run a simple query. We will search for a number of different items in separate queries:

• Machines running Windows 7

• Shell processes

• Connections to external locations

While the queries are not necessarily searches for malicious behavior or security problems, the process described in this topic shows you how to construct queries for the most common Cybereason Elements.

Step 1: Plan your queries

To create queries that return meaningful results, you must plan your queries carefully:

1. Enumerate in a general way what you want to find, such as computers or processes.

2. Determine the indicators you will use to identify your target, such as a specific operating system. Write an explicit statement of your query.

For detailed documentation on planning and building your queries, see the Hunting and Investigation documentation in the Cybereason core documentation.

For our example queries, we can write the following statements:

1. I want to find machines with the operating system Windows 7.

2. I want to find processes with a product type of Shell.

3. I want to find connections to an external address.

With these statements we can build the queries in the Investigation screen.

Step 2: Build your queries in the Investigation screen

A query in the Investigation screen has two parts:

• Elements are the objects you want to find, or the computing component parts of the your statement.

• Features, or filters, are the indicators that identify the target.

You build these queries:

1. Query 1: I want to find a list of machines with the operating system Windows 7. The Element in the query is Machine and the Feature/filter is OS version is Windows 7.

   

2. Query 2: I want to find processes with a type of SHELL. The Element in the query is Process and the Feature/filter is Product type is Shell

   

3. Query 3: I want to find connections that make connections to an external address. The Element in this query is Connection and the Feature/filter is Is external.

   

Step 3: Run your queries and generate the API request body

To generate the request body for the API request:

1. In Chrome, open Chrome DevTools.

2. In the Cybereason Investigation screen, click Get results.

3. After the query has finished running, select the Network tab in Chrome DevTools, and then select the relevant request.

4. In the Request Payload section in the lower part of the window, copy the entire request payload. You will use this in the request body for API request.

   

Step 4: Build and send the API request

Use the relevant cURL commmand, request body example, or Python script:

All Python examples are formatted for Python version 3.0 and higher, up to the latest Python version. If you are using versions of Python earlier than 3.0, ensure you manually remove parentheses for the print statements in this sample. For example, the print (response.content) statement updates to print response.content.

Query 1: Machines running Windows 7

Use the relevant API request/script depending on your preferred method:

cURLREST API clientPython

curl --request POST \
        --url https://<your server>/rest/visualsearch/query/simple \
        --header 'Content-Type:application/json' \
        --data '{
                  "queryPath": [
                    {
                      "requestedType": "Machine",
                      "filters": [
                        {
                          "facetName": "osVersionType",
                          "values": [
                            "Windows_7"
                          ],
                          "filterType": "Equals"
                        }
                      ]
                    }
                  ],
                  "totalResultLimit": 1000,
                  "perGroupLimit": 100,
                  "perFeatureLimit": 100,
                  "templateContext": "SPECIFIC",
                  "queryTimeout": 120000,
                  "customFields": [
                    "elementDisplayName",
                    "creationTime",
                    "endTime",
                    "commandLine",
                    "productType",
                    "children",
                    "parentProcess",
                    "ownerMachine",
                    "calculatedUser",
                    "imageFile",
                    "loadedModules",
                    "iconBase64",
                    "ransomwareAutoRemediationSuspended",
                    "executionPrevented",
                    "isWhiteListClassification",
                    "matchedWhiteListRuleIds"
                  ]
                }'

Query 2: Product Type is Shell

cURLREST API clientPython

curl --request POST \
  --url https://<your server>/rest/visualsearch/query/simple \
  --header 'Content-Type:application/json' \
  --data '{
            "queryPath":[
                          {
                            "requestedType":"Process",
                            "filters":[
                                        {
                                          "facetName":"productType",
                                          "values":["SHELL"],
                                          "filterType":"Equals"
                                        }
                                      ],
                            "isResult":true
                          }
                        ],
            "totalResultLimit":1000,
            "perGroupLimit":100,
            "perFeatureLimit":100,
            "templateContext":"SPECIFIC",
            "queryTimeout":120000,
            "customFields":[
                              "elementDisplayName",
                              "creationTime",
                              "endTime",
                              "commandLine",
                              "productType",
                              "children",
                              "parentProcess",
                              "ownerMachine",
                              "calculatedUser",
                              "imageFile",
                              "loadedModules",
                              "iconBase64",
                              "ransomwareAutoRemediationSuspended",
                              "executionPrevented",
                              "isWhiteListClassification",
                              "matchedWhiteListRuleIds"
                           ]
          }'

Query 3: Connections to External Address

cURLREST API clientPython

curl --request POST \
  --url https://<your server>/rest/visualsearch/query/simple \
  --header 'Content-Type:application/json' \
  --data '{
            "queryPath":[
                          {
                            "requestedType":"Connection",
                            "filters":[
                                        {
                                          "facetName":"isExternalConnection",
                                          "values":[true]
                                        }
                                      ],
                            "isResult":true
                          }
                         ],
            "totalResultLimit":1000,
            "perGroupLimit":100,
            "perFeatureLimit":100,
            "templateContext":"SPECIFIC",
            "queryTimeout":120000,
            "customFields":[
                            "elementDisplayName",
                            "direction",
                            "ownerMachine",
                            "ownerProcess",
                            "serverPort",
                            "serverAddress",
                            "portType",
                            "aggregatedReceivedBytesCount",
                            "aggregatedTransmittedBytesCount",
                            "remoteAddressCountryName",
                            "dnsQuery",
                            "accessedByMalwareEvidence",
                            "calculatedCreationTime","endTime"
                           ]
          }'

Step 5: Run your request and generate the response

In the command line, REST API client, or IDE, run the command or script that contains the request. After a few seconds, the Cybereason API returns a response.

Step 6: Evaluate the response

The response contains a large number fields. Focus on these fields for meaningful information:

Object Name	Description
simpleValues	Contains separate entries for every feature in the query. (This is the equivalent of adding columns in the Investigation screen.) For each Feature name, such as creationTime, analyze the values in the totalValues field.
elementValues	Contains separate entries for every Element in the query. For each Element name, analyze the values in the elementValues field.
suspicionsMap	Contains a list of Suspicions.
evidenceMap	Contains a list of Evidence.

In the results included in these fields, you may want to analyze the results in a number of different ways:

• Look for values that are unexpected or outside the norm for your organization.

• Look for values that only occur once. Repeated instances of a process or a connection may be normal for your organization, such as the use of a specific application or mail server address by all employees. However, a single instance of something may warrant further analysis on your part.