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
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:
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:
|
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:
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
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": ""
}
Request
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.
Use this request body:
{
"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": ""
}
Request
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.
import requests
import json
# Login information
username = "[email protected]"
password = "mypassword"
server = "myserver.com"
port = "443"
data = {
"username": username,
"password": password
}
headers = {"Content-Type": "application/json"}
base_url = "https://" + server + ":" + port
login_url = base_url + "/login.html"
session = requests.session()
login_response = session.post(login_url, data=data, verify=True)
print (login_response.status_code)
print (session.cookies.items())
# Request URL
endpoint_url = "/rest/crimes/unified"
api_url = base_url + endpoint_url
# These are the variables that represent different fields in the request.
malop_id = "11.64804795222430027"
null = None
query = json.dumps({"totalResultLimit":10000,"perGroupLimit":10000,"perFeatureLimit":100,"templateContext":"OVERVIEW","queryPath":[{"requestedType":"MalopProcess","guidList":[malop_id],"result":True,"filters":null}]})
api_headers = {'Content-Type':'application/json'}
api_response = session.request("POST", api_url, data=query, headers=api_headers)
your_response = json.loads(api_response.content)
print(json.dumps(your_response, indent=4, sort_keys=True))
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
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
}
]
}'
Request
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.
Use this request body:
{
"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
}
]
}
Request
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.
import requests
import json
# Login information
username = "[email protected]"
password = "password"
server = "myserver.net"
port = "443"
data = {
"username": username,
"password": password
}
headers = {"Content-Type": "application/json"}
base_url = "https://" + server + ":" + port
login_url = base_url + "/login.html"
session = requests.session()
login_response = session.post(login_url, data=data, verify=True)
print (login_response.status_code)
print (session.cookies.items())
# Request URL
endpoint_url = "/rest/crimes/unified"
api_url = base_url + endpoint_url
# These are the variables that represent different fields in the request.
malop_status = "UNREAD"
malop_status_operator = "NOT_EQUALS"
malop_close_time = 1603191402000
malop_close_time_operator = "GREATER_THAN"
null = None
query = json.dumps({"totalResultLimit":10000,"perGroupLimit":10000,"perFeatureLimit":100,"templateContext":"OVERVIEW","malopManagementFilters":{"malopStatusFilter":{"filterType":malop_status_operator,"malopManagementStatuses":[malop_status]},"malopCloseTimeFilter":{"filterType":malop_close_time_operator,"malopClosedTime":malop_close_time}},"queryPath":[{"requestedType": "MalopProcess","result":True,"filters": null}]})
api_headers = {'Content-Type':'application/json'}
api_response = session.request("POST", api_url, data=query, headers=api_headers)
your_response = json.loads(api_response.content)
print(json.dumps(your_response, indent=4, sort_keys=True))