Query Malware Types

Endpoint URL: https://<your server>/rest/malware/query
Endpoint URI: malware/query

Action: POST

Returns details on malware currently in your environment.

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.

            {
              "filters": [
                          {
                            "fieldName": "<field>",
                            "operator": "<operator>",
                            "values": ["<value>"]
                          }
                         ],
              "search": "<value>",
              "sortingFieldName": "<field>",
              "sortDirection": "<sort direction>",
              "limit": "<limit>",
              "offset": "<page number>"
            }

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 response as this may cause unexpected results and affect performance in your environment.


Request Parameters

URL/URI parameters: none

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

Field

Type

Description

filters

Array

An object containing details on how to filter the results.

fieldName

Enum

The type of malware for which to retrieve data. Possible values include:

  • needsAttention

  • type

  • timestamp

  • status

You can add multiple fieldName parameters in this object if you want to filter by multiple criteria. For example, you can add a fieldName parameter for timestamp to limit the time range, add an additional fieldName parameter for type to limit the results to a specific type of malware, and add a third fieldName parameter for status to look results with a specific status.

operator

Enum

The operator to use for the field. Possible values per type include:

If the fieldName parameter is needsAttention:

  • Is

  • Not

If the fieldName parameter is type or status:

  • Equals

  • NotEquals

If the fieldName parameter is timestamp:

  • LessThan

  • LessOrEqualsTo

  • GreaterThan

  • GreaterOrEqualsTo

  • FromTimeOp

values

String

Indicates the value to use with the fieldName parameter.

The values differ depending on whether you are returning Malware marked as Needs Attention or other types of malware:

  • If the fieldName parameter is set to needsAttention, enter true or false.

  • If the fieldName parameter is set to type, use a Malware type, including KnownMalware, UnknownMalware, FilelessMalware, ApplicationControlMalware, or RansomwareMalware.

  • If the fieldName parameter is set to status, use a status type, including Done, Excluded, Detected, Prevented, Remediated, DeleteOnRestart, or Quarantined.

  • If the fieldName parameter is step to timestamp, enter the time (in epoch).

sortingFieldName

String

The field by which to sort the results. Use timestamp

sortDirection

Enum

The direction in which to sort the results. Possible values include ASC or DESC.

limit

Integer

The number of results to include in the response.

offset

Integer

The page in the results on which to start the results. Set to O to receive the beginning of the results.

Response Status Codes

  • 200: Success OK


Response Success Schema

The response contains the following fields:

Field

Type

Description

data

Array

An object containing the data about the malwares.

malwareCountFilters

Array

An object containing the details of the individual filters.

filter

String

The name of the filter specified in the filterName field in the request.

count

Integer

The number of malware items returned for this filter.

totalCount

Integer

The total number of malware instances returned.

status

Enum

The status of the query.

message

String

Any message attached to the query.

Response Failure Schema

None


Important Response Fields

Important information is found in these fields:

  • malwares object: This object contains a list of all malwares that match the filter added in the request.

  • guid: The unique GUID the Cybereason platform uses for this specific malware instance.

  • timestamp: The time (in epoch) when the Cybereason platform detected this malware.

  • name: The name of the process running the malware.

  • type: The type of malware as classified by the Cybereason platform.

  • machineName: The name of the machine on which the Cybereason platform found the malware.

  • status: The detection status of the malware. This should match the Anti-Malware settings you specified for your Cybereason platform.

  • filePath: The path to the file for the malware.


Example: Query all malware that needs attention

Request

curl --request POST \
    --url https://12.34.56.78/rest/malware/query \
    --header 'Content-Type:application/json' \
    --data '{
              "filters": [
                          {
                            "fieldName":"needsAttention",
                            "operator":"Is",
                            "values":[true]
                          }
                         ],
              "sortingFieldName":"timestamp",
              "sortDirection":"DESC",
              "limit":100,
              "offset":0
            }'

Response

{
  "data": {
      "malwares": [
          {
              "guid": "1568107397.7919062151558828465",
              "timestamp": 1539773402000,
              "name": "dga.exe",
              "type": "KnownMalware",
              "elementType": "File",
              "machineName": "WINTEST-PC",
              "status": "Detected",
              "needsAttention": false,
              "referenceGuid": "1568107397.7919062151558828465",
              "referenceElementType": "File",
              "score": 0,
              "detectionValue": "6d438989ea3f31a41e0f312e466cf417",
              "detectionValueType": "DVT_FILE",
              "malwareDataModel": {
                  "@class": ".BaseFileMalwareDataModel",
                  "type": "KnownMalware",
                  "detectionName": "Trojan.GenericKD.30489158",
                  "filePath": "c:\\users\\dga.exe"
              },
              "schedulerScan": false,
              "id": {
                  "guid": "1568107397.7919062151558828465",
                  "timestamp": 1539773402000,
                  "malwareType": "KnownMalware",
                  "elementType": "File"
              }
          },
          {
              "guid": "1568107397.-726165427183014343",
              "timestamp": 1539772157000,
              "name": "injector2.exe",
              "type": "KnownMalware",
              "elementType": "File",
              "machineName": "WINTEST-PC",
              "status": "Detected",
              "needsAttention": false,
              "referenceGuid": "1568107397.-726165427183014343",
              "referenceElementType": "File",
              "score": 0,
              "detectionValue": "65180e4c3c7d130ef2b65cedd8d47047",
              "detectionValueType": "DVT_FILE",
              "malwareDataModel": {
                  "@class": ".BaseFileMalwareDataModel",
                  "type": "KnownMalware",
                  "detectionName": "Trojan.GenericKD.31253198",
                  "filePath": "c:\\users\\wintest\\desktop\\malop samples\\injector2.exe"
              },
              "schedulerScan": false,
              "id": {
                  "guid": "1568107397.-726165427183014343",
                  "timestamp": 1539772157000,
                  "malwareType": "KnownMalware",
                  "elementType": "File"
              }
          },
      ],
      "totalResults": 25,
      "hasMoreResults": true
  },
  "status": "SUCCESS",
  "message": ""
  }

Example: Query all known malware

Request

curl --request POST \
    --url https://12.34.56.78/rest/malware/query \
    --header 'Content-Type:application/json' \
    --data '{
              "filters":[
                          {
                            "fieldName": "type",
                            "operator": "Equals",
                            "values":["KnownMalware"]
                          },
                          {
                            "fieldName":"needsAttention",
                            "operator":"Is",
                            "values":[false]
                          }
                        ],
              "sortingFieldName":"timestamp",
              "sortDirection":"DESC",
              "limit":25,
              "offset":0
            }'

Response

{
"data": {
    "malwares": [
        {
            "guid": "1568107397.7919062151558828465",
            "timestamp": 1539773402000,
            "name": "dga.exe",
            "type": "KnownMalware",
            "elementType": "File",
            "machineName": "WINTEST-PC",
            "status": "Detected",
            "needsAttention": false,
            "referenceGuid": "1568107397.7919062151558828465",
            "referenceElementType": "File",
            "score": 0,
            "detectionValue": "6d438989ea3f31a41e0f312e466cf417",
            "detectionValueType": "DVT_FILE",
            "malwareDataModel": {
                "@class": ".BaseFileMalwareDataModel",
                "type": "KnownMalware",
                "detectionName": "Trojan.GenericKD.30489158",
                "filePath": "c:\\users\\dga.exe"
            },
            "schedulerScan": false,
            "id": {
                "guid": "1568107397.7919062151558828465",
                "timestamp": 1539773402000,
                "malwareType": "KnownMalware",
                "elementType": "File"
            }
        },
        {
            "guid": "1568107397.-726165427183014343",
            "timestamp": 1539772157000,
            "name": "injector2.exe",
            "type": "KnownMalware",
            "elementType": "File",
            "machineName": "WINTEST-PC",
            "status": "Detected",
            "needsAttention": false,
            "referenceGuid": "1568107397.-726165427183014343",
            "referenceElementType": "File",
            "score": 0,
            "detectionValue": "65180e4c3c7d130ef2b65cedd8d47047",
            "detectionValueType": "DVT_FILE",
            "malwareDataModel": {
                "@class": ".BaseFileMalwareDataModel",
                "type": "KnownMalware",
                "detectionName": "Trojan.GenericKD.31253198",
                "filePath": "c:\\users\\wintest\\desktop\\malop samples\\injector2.exe"
            },
            "schedulerScan": false,
            "id": {
                "guid": "1568107397.-726165427183014343",
                "timestamp": 1539772157000,
                "malwareType": "KnownMalware",
                "elementType": "File"
            }
        },
    ],
    "totalResults": 25,
    "hasMoreResults": true
},
"status": "SUCCESS",
"message": ""
}

Example: Query all known malware after a certain time

Request

curl --request POST \
    --url https://12.34.56.78/rest/malware/query \
    --header 'Content-Type:application/json' \
    --data '{
              "filters":[
                          {
                            "fieldName": "type",
                            "operator": "Equals",
                            "values":["KnownMalware"]
                          },
                          {
                            "fieldName":"needsAttention",
                            "operator":"Is",
                            "values":[false]
                          },
                          {
                            "fieldName":"timestamp",
                            "operator":"GreaterThan",
                            "values":[1582206286000]
                          }
                        ],
              "sortingFieldName":"timestamp",
              "sortDirection":"DESC",
              "limit":25,
              "offset":0
            }'

Response

{
"data": {
    "malwares": [
        {
            "guid": "1568107397.7919062151558828465",
            "timestamp": 1539773402000,
            "name": "dga.exe",
            "type": "KnownMalware",
            "elementType": "File",
            "machineName": "WINTEST-PC",
            "status": "Detected",
            "needsAttention": false,
            "referenceGuid": "1568107397.7919062151558828465",
            "referenceElementType": "File",
            "score": 0,
            "detectionValue": "6d438989ea3f31a41e0f312e466cf417",
            "detectionValueType": "DVT_FILE",
            "malwareDataModel": {
                "@class": ".BaseFileMalwareDataModel",
                "type": "KnownMalware",
                "detectionName": "Trojan.GenericKD.30489158",
                "filePath": "c:\\users\\dga.exe"
            },
            "schedulerScan": false,
            "id": {
                "guid": "1568107397.7919062151558828465",
                "timestamp": 1539773402000,
                "malwareType": "KnownMalware",
                "elementType": "File"
            }
        },
        {
            "guid": "1568107397.-726165427183014343",
            "timestamp": 1539772157000,
            "name": "injector2.exe",
            "type": "KnownMalware",
            "elementType": "File",
            "machineName": "WINTEST-PC",
            "status": "Detected",
            "needsAttention": false,
            "referenceGuid": "1568107397.-726165427183014343",
            "referenceElementType": "File",
            "score": 0,
            "detectionValue": "65180e4c3c7d130ef2b65cedd8d47047",
            "detectionValueType": "DVT_FILE",
            "malwareDataModel": {
                "@class": ".BaseFileMalwareDataModel",
                "type": "KnownMalware",
                "detectionName": "Trojan.GenericKD.31253198",
                "filePath": "c:\\users\\wintest\\desktop\\malop samples\\injector2.exe"
            },
            "schedulerScan": false,
            "id": {
                "guid": "1568107397.-726165427183014343",
                "timestamp": 1539772157000,
                "malwareType": "KnownMalware",
                "elementType": "File"
            }
        },
    ],
    "totalResults": 25,
    "hasMoreResults": true
},
"status": "SUCCESS",
"message": ""
}

Example: Query all known malware with a status of Done

Request

curl --request POST \
    --url https://12.34.56.78/rest/malware/query \
    --header 'Content-Type:application/json' \
    --data '{
              "filters":[
                          {
                            "fieldName": "type",
                            "operator": "Equals",
                            "values":["KnownMalware"]
                          },
                          {
                            "fieldName":"needsAttention",
                            "operator":"Is",
                            "values":[false]
                          },
                          {
                            "fieldName":"status",
                            "operator":"Equals",
                            "values":["Done"]
                          }
                        ],
              "sortingFieldName":"timestamp",
              "sortDirection":"DESC",
              "limit":25,
              "offset":0
            }'

Response

{
"data": {
    "malwares": [
        {
            "guid": "1568107397.7919062151558828465",
            "timestamp": 1539773402000,
            "name": "dga.exe",
            "type": "KnownMalware",
            "elementType": "File",
            "machineName": "WINTEST-PC",
            "status": "Detected",
            "needsAttention": false,
            "referenceGuid": "1568107397.7919062151558828465",
            "referenceElementType": "File",
            "score": 0,
            "detectionValue": "6d438989ea3f31a41e0f312e466cf417",
            "detectionValueType": "DVT_FILE",
            "malwareDataModel": {
                "@class": ".BaseFileMalwareDataModel",
                "type": "KnownMalware",
                "detectionName": "Trojan.GenericKD.30489158",
                "filePath": "c:\\users\\dga.exe"
            },
            "schedulerScan": false,
            "id": {
                "guid": "1568107397.7919062151558828465",
                "timestamp": 1539773402000,
                "malwareType": "KnownMalware",
                "elementType": "File"
            }
        },
        {
            "guid": "1568107397.-726165427183014343",
            "timestamp": 1539772157000,
            "name": "injector2.exe",
            "type": "KnownMalware",
            "elementType": "File",
            "machineName": "WINTEST-PC",
            "status": "Detected",
            "needsAttention": false,
            "referenceGuid": "1568107397.-726165427183014343",
            "referenceElementType": "File",
            "score": 0,
            "detectionValue": "65180e4c3c7d130ef2b65cedd8d47047",
            "detectionValueType": "DVT_FILE",
            "malwareDataModel": {
                "@class": ".BaseFileMalwareDataModel",
                "type": "KnownMalware",
                "detectionName": "Trojan.GenericKD.31253198",
                "filePath": "c:\\users\\wintest\\desktop\\malop samples\\injector2.exe"
            },
            "schedulerScan": false,
            "id": {
                "guid": "1568107397.-726165427183014343",
                "timestamp": 1539772157000,
                "malwareType": "KnownMalware",
                "elementType": "File"
            }
        },
    ],
    "totalResults": 25,
    "hasMoreResults": true
},
"status": "SUCCESS",
"message": ""
}

Example: Query malware in a time range

Request

curl --request POST \
    --url https://12.34.56.78/rest/malware/query \
    --header 'Content-Type:application/json' \
    --data '{
                "sortingFieldName": "timestamp",
                "sortDirection": "DESC",
                "limit": 25,
                "offset": 0,
                "filters": [
                                      {
                                        "fieldName":"timestamp",
                                        "operator":"GreaterThan",
                                        "values":[1665007364000]
                                      },
                                      {
                                        "fieldName":"timestamp",
                                        "operator":"LessThan",
                                        "values":[1665110780000]
                                      }

                ]
            }'

Response

{
"data": {
    "malwares": [
        {
            "guid": "1568107397.7919062151558828465",
            "timestamp": 1539773402000,
            "name": "dga.exe",
            "type": "KnownMalware",
            "elementType": "File",
            "machineName": "WINTEST-PC",
            "status": "Detected",
            "needsAttention": false,
            "referenceGuid": "1568107397.7919062151558828465",
            "referenceElementType": "File",
            "score": 0,
            "detectionValue": "6d438989ea3f31a41e0f312e466cf417",
            "detectionValueType": "DVT_FILE",
            "malwareDataModel": {
                "@class": ".BaseFileMalwareDataModel",
                "type": "KnownMalware",
                "detectionName": "Trojan.GenericKD.30489158",
                "filePath": "c:\\users\\dga.exe"
            },
            "schedulerScan": false,
            "id": {
                "guid": "1568107397.7919062151558828465",
                "timestamp": 1539773402000,
                "malwareType": "KnownMalware",
                "elementType": "File"
            }
        },
        {
            "guid": "1568107397.-726165427183014343",
            "timestamp": 1539772157000,
            "name": "injector2.exe",
            "type": "KnownMalware",
            "elementType": "File",
            "machineName": "WINTEST-PC",
            "status": "Detected",
            "needsAttention": false,
            "referenceGuid": "1568107397.-726165427183014343",
            "referenceElementType": "File",
            "score": 0,
            "detectionValue": "65180e4c3c7d130ef2b65cedd8d47047",
            "detectionValueType": "DVT_FILE",
            "malwareDataModel": {
                "@class": ".BaseFileMalwareDataModel",
                "type": "KnownMalware",
                "detectionName": "Trojan.GenericKD.31253198",
                "filePath": "c:\\users\\wintest\\desktop\\malop samples\\injector2.exe"
            },
            "schedulerScan": false,
            "id": {
                "guid": "1568107397.-726165427183014343",
                "timestamp": 1539772157000,
                "malwareType": "KnownMalware",
                "elementType": "File"
            }
        },
    ],
    "totalResults": 25,
    "hasMoreResults": true
},
"status": "SUCCESS",
"message": ""
}

Example: Query all known malware with a status of Done

Request

curl --request POST \
    --url https://12.34.56.78/rest/malware/query \
    --header 'Content-Type:application/json' \
    --data '{
              "filters":[
                          {
                            "fieldName": "type",
                            "operator": "Equals",
                            "values":["KnownMalware"]
                          },
                          {
                            "fieldName":"needsAttention",
                            "operator":"Is",
                            "values":[false]
                          },
                          {
                            "fieldName":"status",
                            "operator":"Equals",
                            "values":["Done"]
                          }
                        ],
              "sortingFieldName":"timestamp",
              "sortDirection":"DESC",
              "limit":25,
              "offset":0
            }'

Response

{
"data": {
    "malwares": [
        {
            "guid": "1568107397.7919062151558828465",
            "timestamp": 1539773402000,
            "name": "dga.exe",
            "type": "KnownMalware",
            "elementType": "File",
            "machineName": "WINTEST-PC",
            "status": "Detected",
            "needsAttention": false,
            "referenceGuid": "1568107397.7919062151558828465",
            "referenceElementType": "File",
            "score": 0,
            "detectionValue": "6d438989ea3f31a41e0f312e466cf417",
            "detectionValueType": "DVT_FILE",
            "malwareDataModel": {
                "@class": ".BaseFileMalwareDataModel",
                "type": "KnownMalware",
                "detectionName": "Trojan.GenericKD.30489158",
                "filePath": "c:\\users\\dga.exe"
            },
            "schedulerScan": false,
            "id": {
                "guid": "1568107397.7919062151558828465",
                "timestamp": 1539773402000,
                "malwareType": "KnownMalware",
                "elementType": "File"
            }
        },
        {
            "guid": "1568107397.-726165427183014343",
            "timestamp": 1539772157000,
            "name": "injector2.exe",
            "type": "KnownMalware",
            "elementType": "File",
            "machineName": "WINTEST-PC",
            "status": "Detected",
            "needsAttention": false,
            "referenceGuid": "1568107397.-726165427183014343",
            "referenceElementType": "File",
            "score": 0,
            "detectionValue": "65180e4c3c7d130ef2b65cedd8d47047",
            "detectionValueType": "DVT_FILE",
            "malwareDataModel": {
                "@class": ".BaseFileMalwareDataModel",
                "type": "KnownMalware",
                "detectionName": "Trojan.GenericKD.31253198",
                "filePath": "c:\\users\\wintest\\desktop\\malop samples\\injector2.exe"
            },
            "schedulerScan": false,
            "id": {
                "guid": "1568107397.-726165427183014343",
                "timestamp": 1539772157000,
                "malwareType": "KnownMalware",
                "elementType": "File"
            }
        },
    ],
    "totalResults": 25,
    "hasMoreResults": true
},
"status": "SUCCESS",
"message": ""
}