Get Details on a Specific AI Hunt Malop

Endpoint URL: https://<your server>/rest/crimes/unified
Endpoint URI: crimes/unified

Action: POST

Returns details on a specific AI Hunt MalOp.

Note

You can use this endpoint to retrieve a list of all AI Hunt MalOps. However, Cybereason recommends you use the /rest/detection/inbox endpoint to ensure you retrieve all MalOps. For details, see Retrieve All MalOps.

This endpoint retrieves MalOps based on the MalopProcess Element or the MalopLogonSession Element. To retrieve a list of all MalOps in the environment, send this request once using “MalopProcess” as the requestType in the request body, and a second time using “MalopLogonSession” as the requestType.

Note

Ensure that you have logged into the Cybereason platform. For details, see Log in with the API.

Request Headers

You must add an Content-Type:application/json header with the request.

Note

If you are using cURL, add the authorization cookie details or the path to the file with cookie details with every request.

Request Body

Input: JSON

Download JSON syntax file

Depending on your browser settings, this linked file may open in a separate tab instead of downloading directly to your machine. If this happens, use the Save As option in your browser to save the file locally.

When using this API endpoint, you should send the request twice. In this request body, the first request uses the MalopProcess Element. The second request uses the MalopLogonSession Element.

Note

When sending this request, there may be a delay in returning a response, depending on how much data and activity is in your system. Ensure you do not send this request multiple times while waiting for a response as this may cause unexpected results and performance issues in your environment.

            {
              "totalResultLimit": 10000,
              "perGroupLimit": 10000,
              "perFeatureLimit": 100,
              "templateContext": "OVERVIEW",
              "creationTime":"<time in epoch>",
              "malopLastUpdateTime":"<time in epoch>",
              "malopManagementFilters" : {
                                          "malopStatusFilter":{
                                                                "filterType":"<operator>",
                                                                "malopManagementStatuses": ["<status>"]
                                                              },
                                          "malopCloseTimeFilter":{
                                              "filterType":"<operator>",
                                              "malopClosedTime": "<time in epoch>"
                                          }
                                         },
              "queryPath": [
                {
                  "requestedType": "MalopProcess",
                  "guidList":["guid IDs for Malops"],
                  "result": true,
                  "filters": null
                }
              ]
            }

Request Parameters

URL/URI parameters: none

Request Body Parameters: Use the following available fields in the request. Required parameters are noted in bold.

Field	Type	Description
totalResultlimit	Integer	The total number of results to return. Ensure you make the limit a reasonable number to maximize server performance and avoid system overload.
perGroupLimit	Integer	The number of items to return per Malop group. As this number does not affect the response, we suggest you leave it at the default of 10000.
perFeatureLimit	Integer	The number of items to return per Feature. As this number does not affect the response, we suggest you leave it at the default of 100.
templateContext	Enum	The level of detail to provide in the response. Set this parameter to DETAILS to return the relevant information for a Malop. You should not modify this value as it will cause unexpected behavior in your response.
creationTime	Time stamp	The time (in epoch) when the Malop was created.
malopLastUpdateTime	Time stamp	The time (in epoch) when the Malop was last updated.
malopManagementFilters	Array	An object containing the filter for the Malop status or for the Malop close time. This object is available for versions 20.2.61 and later versions.
malopStatusFilter	Array	An array containing the filters for retrieving Malops based on the Malop status. This object is available for versions 20.2.61 and later versions.
malopManagementStatuses	Enum	The status for the Malop. Possible values include: UNREAD OPEN REOPEN CLOSED FP TODO ACTIVE This field is available for versions 20.2.61 and later versions.
malopCloseTimeFilter	Array	An array containing the filters for retrieving Malops based on the time an analyst closed a Malop. This object is available for versions 20.2.61 and later versions.
malopClosedTime	Integer	A timestamp (in epoch) when a Malop was closed. This field is available for versions 20.2.61 and later versions.
queryPath	Array	An object containing details on the requested Element.
requestedType	String	The type for the Element. Set the value of this parameter to Malop Process or MalopLogonSession. You should send one with request with the value of this parameter set to MalopProcess and a second request with the value set to MalopLogonSession.
result	Boolean	Indicates whether this Element is the Element on which to return the results. Set the value of this parameter to true.
filters	String	Possible filters to use for the Malop Process Element. Set the value of this parameter to null unless you are using time filters.
facetName	String	The time-based Feature to use for a filter. Use one of the following: creationTime for the time when a Malop was created malopLastUpdateTime for the time when the Malop was last updated
filterType	Enum	The operator to use for the time period. See Apply Operators in Filters for a list of supported operators for integer-type values.
guidList	Array	The list of AI Hunt Malop GUIDs for which to return details. Add the GUIDs of the Malops on which to search, wrapped in double quotes. For a list of multiple Malops, add commas between each item.

Response Status Codes

This request can return the following status codes:

• 200: Success OK

Response Success Schema

For each Malop, the details are returned in an object identified by the MalOp ID. This is the GUID for the MalOp, such as 11.5133381726858807240.

In the details returned for a MalOp, each Feature contains the following fields:

• totalvalues: An integer value. This is the total number of items for a particular feature of the Malop.

• values: A string value. The value for that particular feature of the Malop which provides the details Cybereason used to determine the MalOp.

Each MalOp also contains the following objects and their relevant fields:

simpleValues Object

elementValues Object

filterData Object

The end of the response includes a status field with a value SUCCESS or PARTIAL_SUCCESS.

Response Failure Schema

The response returns no data and reports the status field as one of the following:

• FAILURE

• NO_SERVERS_CONFIGURED

• QUERY_LIMIT_CROSSED

• TIMEOUT_ERROR

Important Response Fields

Important information is found in these fields:

• <malop GUID>: This integer value (which usually begins with 11) represents the unique MalOp ID the Cybereason platform assigns to this particular MalOp. You may need this identifier to filter other requests by the specific MalOp.

• simpleValues object: The general information about the Malop. In the object, view the name of the Features to see general information about the Malop.

• decisionFeature: The Feature used as the key aspect that caused the Cybereason platform to generate a MalOp.

• malopStartTime: The time (in epoch) that the Cybereason platform detected the activity listed in the MalOp and generated a MalOp.

• detectionType: The type of MalOp.

• rootCauseElementTypes: The type of Element on which the Cybereason platform generated a MalOp. The value of this field is either Process or Logon Session.

• rootCauseElementNames: The name of the item identified as the root cause of the MalOp. This value is the name collected by the sensor for the process (for example, explorer.exe) or the name of the logon session.

• malopLastUpdateTime: The timestamp (in epoch) when the Cybereason platforom last updated the MalOp.

• rootCauseElementHashes: The hash value for the item identified as the root cause of the MalOp.

• managementStatus: The current status of the MalOp.

• elementValues: This object contains general information about Elements related to the MalOp. This includes details on related machines, users, and connections (when they exist).

• affectedUsers/affectedMachines: This object contains the details on related machines and users. View the guid and name fields in these objects to see details on the related machines and users.

• *suspicionsMap: An object containing details on the suspicions connected to this MalOp.

• evidenceMap: An object containing details on Evidence connected to this MalOp.

Example: Retrieve MalOp details for a specific AI Hunt MalOp

CURLREST API ClientPython

Request

curl --request POST \
  --url https://12.34.56.78/rest/crimes/unified \
  --header 'Content-Type:application/json' \
  --data '{
            "totalResultLimit":10000,
            "perGroupLimit":10000,
            "perFeatureLimit":100,
            "templateContext":"OVERVIEW",
            "queryPath":[
                          {
                            "requestedType":"MalopProcess",
                            "guidList":["11.64804795222430027"],
                            "result":true,"filters":null
                          }
                        ]
          }'

Response

{
    "data": {
        "resultIdToElementDataMap": {
            "11.64804795222430027": {
                "simpleValues": {
                    "hasRansomwareSuspendedProcesses": {
                        "totalValues": 1,
                        "values": [
                            "false"
                        ]
                    },
                    "decisionFeature": {
                        "totalValues": 1,
                        "values": [
                            "Process.malwareByHashReputation(Malop decision)"
                        ]
                    },
                    "rootCauseElementCompanyProduct": {
                        "totalValues": 1,
                        "values": [
                            " : Microsoft@ Windows@ Operating System"
                        ]
                    },
                    "malopStartTime": {
                        "totalValues": 1,
                        "values": [
                            "1526060754034"
                        ]
                    },
                    "detectionType": {
                        "totalValues": 1,
                        "values": [
                            "KNOWN_MALWARE"
                        ]
                    },
                    "malopActivityTypes": {
                        "totalValues": 1,
                        "values": [
                            "MALICIOUS_INFECTION"
                        ]
                    },
                    "elementDisplayName": {
                        "totalValues": 1,
                        "values": [
                            "MALICIOUS_INFECTION"
                        ]
                    },
                    "creationTime": {
                        "totalValues": 1,
                        "values": [
                            "1560841924148"
                        ]
                    },
                    "isBlocked": {
                        "totalValues": 1,
                        "values": [
                            "false"
                        ]
                    },
                    "rootCauseElementTypes": {
                        "totalValues": 1,
                        "values": [
                            "File"
                        ]
                    },
                    "rootCauseElementNames": {
                        "totalValues": 1,
                        "values": [
                            "taskhost.exe"
                        ]
                    },
                    "malopLastUpdateTime": {
                        "totalValues": 1,
                        "values": [
                            "1560841924148"
                        ]
                    },
                    "allRansomwareProcessesSuspended": {
                        "totalValues": 1,
                        "values": [
                            "false"
                        ]
                    },
                    "rootCauseElementHashes": {
                        "totalValues": 1,
                        "values": [
                            "5b6cac9374bf1d9cfb3fd1f9889bb665af1e3ce3"
                        ]
                    },
                    "managementStatus": {
                        "totalValues": 1,
                        "values": [
                            "OPEN"
                        ]
                    },
                    "closeTime": {
                        "totalValues": 1,
                        "values": [
                            null
                        ]
                    },
                    "closerName": {
                        "totalValues": 1,
                        "values": [
                            null
                        ]
                    },
                    "customClassification": {
                        "totalValues": 1,
                        "values": [
                            "None"
                        ]
                    }
                },
                "elementValues": {
                    "primaryRootCauseElements": {
                        "totalValues": 1,
                        "elementValues": [
                            {
                                "elementType": "File",
                                "guid": "-1815202414.876556071966300277",
                                "name": "taskhost.exe",
                                "hasSuspicions": true,
                                "hasMalops": false
                            }
                        ],
                        "totalSuspicious": 1,
                        "totalMalicious": 0,
                        "guessedTotal": 0
                    },
                    "affectedUsers": {
                        "totalValues": 1,
                        "elementValues": [
                            {
                                "elementType": "User",
                                "guid": "0.933183153144438077",
                                "name": "aep-s1-v50\\admin",
                                "hasSuspicions": false,
                                "hasMalops": false
                            }
                        ],
                        "totalSuspicious": 0,
                        "totalMalicious": 0,
                        "guessedTotal": 0
                    },
                    "affectedMachines": {
                        "totalValues": 1,
                        "elementValues": [
                            {
                                "elementType": "Machine",
                                "guid": "-1815202414.1198775089551518743",
                                "name": "AEP-S1-V50",
                                "hasSuspicions": false,
                                "hasMalops": false
                            }
                        ],
                        "totalSuspicious": 0,
                        "totalMalicious": 0,
                        "guessedTotal": 0
                    }
                },
                "suspicions": null,
                "filterData": {
                    "sortInGroupValue": "11.64804795222430027",
                    "groupByValue": "MalopProcessRuntime:11.64804795222430027 "
                },
                "isMalicious": false,
                "suspicionCount": 0,
                "guidString": "11.64804795222430027",
                "labelsIds": [],
                "malopPriority": null,
                "suspect": false,
                "malicious": false
            }
        },
        "suspicionsMap": {},
        "evidenceMap": {},
        "totalPossibleResults": 1,
        "guessedPossibleResults": 0,
        "queryLimits": {
            "totalResultLimit": 10000,
            "perGroupLimit": 10000,
            "perFeatureLimit": 100,
            "groupingFeature": {
                "elementInstanceType": "MalopProcess",
                "featureName": "self"
            },
            "sortInGroupFeature": null
        },
        "queryTerminated": false,
        "pathResultCounts": [
            {
                "featureDescriptor": {
                    "elementInstanceType": "MalopProcess",
                    "featureName": null
                },
                "count": 1
            }
        ]
    },
    "status": "SUCCESS",
    "message": ""
}

Example: Get a list of MalOps by status

CURLREST API ClientPython

Request

curl --request POST \
  --url https://12.34.56.78/rest/crimes/unified \
  --header 'Content-Type:application/json' \
  --data '{
           "totalResultLimit":10000,
           "perGroupLimit":10000,
           "perFeatureLimit":100,
           "templateContext":"OVERVIEW",
           "malopManagementFilters" : {
                                        "malopStatusFilter":{
                                            "filterType":"NOT_EQUALS",
                                            "malopManagementStatuses": ["UNREAD"]
                                        },
                                        "malopCloseTimeFilter":{
                                            "filterType":"GREATER_THAN",
                                            "malopClosedTime": 1603191402000
                                        }
                                      },
           "queryPath":[
                          {
                            "requestedType": "MalopProcess",
                            "result": true,
                            "filters": null
                          }
                         ]
          }'