Customize Details in the Query Response
In this tutorial, we will explain, step-by-step, how to customize the Features that display for each results instance in the response body for an investigation query run with the API.
For the purposes of this tutorial, you will run a query to find processes downloaded from the internet.
You must have the Analyst L1, Analyst L2, or Analyst L3 to run these requests.
When running investigation queries, for the target Element of the query, you can add custom Features related to the target Element about which you want to see information. As a result, you can see a wide variety of details about a process, machine, user, and so forth (depending on the Element you choose as the target Element). You update the request body with the related fields.
Add Features in the customFields object
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
Ensure that the method 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.
Navigate to the section to add your request body. In Postman, for example, this is the Body tab.
In the request body edit area, enter an open and closed bracket {}. This is the standard syntax for JSON.
Inside the brackets, add this request body:
{ "queryPath": [ { "requestedType": "Process", "filters": [ { "facetName": "isDownloadedFromInternet", "values": [ true, ], "filterType": "Equals" } ], "isResult": "true", } ], "templateContext": "SPECIFIC", "totalResultLimit": "1000", "perGroupLimit": "100", "perFeatureLimit": "100", "queryTimeout": "120000", "customFields": [ "<value>", "<value>", "<value>" ] }
For your target Element, you can add related Features about which to return details in the customFields object. Depending on the target Element, you can add any Feature for that Element. In this example the target Element is the Process Element (since the isResult key for the Process Element is set to true), so you can add any Feature related to the Process Element.
For the full list of Features available for an Element, see Query Elements and Features.
In the request body, in the customFields object, replace each respective <value> placeholder with the following Features:
elementDisplayName
calculatedName
commandLine
parentProcessName
Make sure that each Feature has quotes and is separated by a comma character.
{ "queryPath": [ { "requestedType": "Process", "filters": [ { "facetName": "isDownloadedFromInternet", "values": [ true, ], "filterType": "Equals" } ], "isResult": "true", } ], "templateContext": "SPECIFIC", "totalResultLimit": "1000", "perGroupLimit": "100", "perFeatureLimit": "100", "queryTimeout": "120000", "customFields": [ "**elementDisplayName**", "**calculatedName**", "**commandLine**", "**parentProcessName**" ] }
In your client machine, run the request.
View Features in the results
After you run the query, you will receive a response with the standard keys and values:
{
"data": {
"resultIdToElementDataMap": {
"-2046359355.-446319856563366924": {
"simpleValues": {
"elementDisplayName": {
"totalValues": 1,
"values": [
"vnc02.exe"
]
},
"calculatedName": {
"totalValues": 1,
"values": [
"vnc02.exe"
]
},
"commandLine": {
"totalValues": 1,
"values": [
"\"vnc02.exe\""
]
},
"parentProcessName": {
"totalValues": 1,
"values": ["cmd.exe"]
}
},
"elementValues": {
"calculatedUser": {
"totalValues": 1,
"elementValues": [
{
"elementType": "User",
"guid": "0.-6313743191401684913",
"name": "mydomain\\mark",
"hasSuspicions": false,
"hasMalops": false
}
],
"totalSuspicious": 0,
"totalMalicious": 0
},
"parentProcess": {
"totalValues": 1,
"elementValues": [
{
"elementType": "Process",
"guid": "-2046359355.-7870067516287985870",
"name": "cmd.exe",
"hasSuspicions": false,
"hasMalops": false
}
],
"totalSuspicious": 0,
"totalMalicious": 0
}
},
"suspicions": {
"blackListFileSuspicion": 1512300804528
},
"filterData": {
"sortInGroupValue": "-2046359355.-446319856563366924",
"groupByValue": "ransomfreetest.exe"
},
"isMalicious": true,
"suspicionCount": 1,
"guidString": "-2046359355.-446319856563366924",
"labelsIds": null,
"malopPriority": null
}
},
"suspicionsMap": {
"dualExtensionSuspicion": {
"potentialEvidence": [
"dualExtensionNameEvidence",
"hiddenFileExtensionEvidence",
"rightToLeftFileExtensionEvidence",
"masqueradingAsMovieEvidence"
],
"firstTimestamp": 1516033781024,
"totalSuspicions": 1
},
"blackListModuleSuspicion": {
"potentialEvidence": [
"blackListModuleEvidence"
],
"firstTimestamp": 1512314218832,
"totalSuspicions": 1
},
"ransomwareByCanaryFilesSuspicion": {
"potentialEvidence": [
"ransomwareByCanaryFilesEvidence"
],
"firstTimestamp": 1512313571594,
"totalSuspicions": 1
},
"connectingToBadReputationAddressSuspicion": {
"potentialEvidence": [
"hasMaliciousConnectionEvidence"
],
"firstTimestamp": 1516033781024,
"totalSuspicions": 1
}
},
"evidenceMap": {},
"totalPossibleResults": 13,
"queryLimits": {
"totalResultLimit": 1000,
"perGroupLimit": 100,
"perFeatureLimit": 100,
"groupingFeature": {
"elementInstanceType": "Process",
"featureName": "imageFileHash"
},
"sortInGroupFeature": null
},
"queryTerminated": false,
"pathResultCounts": [
{
"featureDescriptor": {
"elementInstanceType": "Process",
"featureName": null
},
"count": 13
}
]
},
"status": "SUCCESS",
"message": ""
}
In the response body, in the simpleValues object for each results instance, you will see the names of the Features you added in the response. In this example, in the simpleValues object, you can see the commandLine, calculatedName, elementDisplayName, and parentProcessName Features you added in the request, in addition to the values for each results instance for each of these Features.
Next steps
Now that you understand how to customize the response details, update your requests to see relevant details to help you get more out of each investigation query.