Skip to main content

getQuarantineItemsList

This method retrieves the list of quarantined items available for a company.

An item can be a file or an Microsoft Exchange object.

Services

This method requires you to place the {service} name in the API URL. The allowed services are:

  • computers, for "Computers and Virtual Machines"

  • exchange, for "Security for Exchange"

For example, the request URL for the exchange service is:

https://YOUR-HOSTNAME/api/v1.0/jsonrpc/quarantine/exchange

Parameters

Parameter

Type

Optional

Description

companyId

String

Yes

The ID of the company for which the quarantine items are retrieved.

Default value: the company the API key used to make the request belongs to.

If this parameter is not included in the request, the response will display all the quarantined items within the company the API key used to make the request belongs to.

endpointId

String

Yes

The ID of the computer for which you want to retrieve the quarantined items.

If this parameter is not included in the request, the method returns the items quarantined in the entire network.

page

Number

Yes

The results page. The default value is 1.

perPage

Number

Yes

The number of items displayed in a page. The upper limit is 100 items per page. Default value is 30 items per page.

filters

Object

Yes

The filters to be used when querying the quarantine items list. For information regarding the available filters and how to use them, refer to Available Filters.

Available Filters

You can use the filters parameter to query the quarantine by certain properties.

The query result is a list of quarantine items that match ALL selected filters.

These are the available filtering options:

Field

Type

Description

threatName

String

Filters the quarantined items by threat name.

This filter is available for computers and exchange services.

startDate

String

Filters the items that were quarantined after the specified date.

The format for startDate is in ISO 8601.

This filter is available for computers and exchange services.

endDate

String

Filters the items that were quarantined before the specified date.

The format for endDate is in ISO 8601.

This filter is available for computers and exchange services.

filePath

String

Filters the quarantined items by file path.

This filter is available for computers service.

ip

String

Filters the quarantine items by IP address.

This filter is available for computers service.

actionStatus

Integer

Filters the quarantine items by action status.

The available values for actionStatus are:

  • 0 - None

  • 1 - Pending remove

  • 2 - Pending restore

  • 3 - Remove failed

  • 4 - Restore failed

If the service is exchange, then the following will also be valid action statuses:

  • 16 - Pending Save

  • 17 - Failed Save

This filter is available for computers and exchange services.

Important

  • The fields threatName, filePath and ip work with partial matching.

    The filter returns the items which are exact match or start with the specified value. To use the specified value as a suffix, use the asterisk symbol (*).

    For example:

    If filePath is C:\temp, the API returns all items originating from this folder, including sub-folders.

    If filePath is *myfile.exe, then the API returns a list of all myfile.exe files from anywhere on the system.

  • The Exchange filters require a valid license key for .

Return value

This method returns an Array containing objects with the quarantined items. Each entry in the array has the following structure:

  • page - the current displayed page

  • pagesCount - the total number of available pages

  • perPage - the total number of returned items per page

  • total - the total number of items

  • items - the list of quarantined items. Each entry in the list has the following fields:

    • id, the ID of the quarantined item,

    • quarantinedOn, the date and time when the object was quarantined,

    • actionStatus, the status of the action taken on the quarantined file: (0 - None; 1 - Pending remove; 2 - Pending restore; 3 - Remove failed; 4 - Restore failed; 16 - Pending save; 17 - Failed save) ,

    • endpointId, the ID of the endpoint on which the threat was detected,

    • endpointName, the name of endpoint on which the threat was detected,

    • endpointIP, the IP of endpoint on which the threat was detected,

    • canBeRestored, has the value True if the restore operation is allowed, False otherwise,

    • companyId, the company ID,

    • details, more information related to the quarantined item. For information regarding the content of the details member, refer to Contents of detailsContents of details.

Contents of details

For the Computers and Virtual Machines service, the details field has this structure:

Field name

Data type

Description

filePath

String

Path to the infected or suspicious file on the endpoint it wasdetected on

For Security for Exchange service, the details field has this structure:

Field name

Data type

Description

detectionPoint

Integer

The level where the detection took place. Possible values:

  • 0 - transport

  • 1 - mailbox

  • 2 - folder

  • 3 - on demand

itemType

Integer

The quarantined object type. Possible values:

  • 0 - attachement

  • 1 - email

threatStatus

String

The status of the object when scan is complete. The status shows if an email is spam or contains unwanted content, or if an attachment is malware infected, suspect of being infected, unwanted or unscannable. Possible values are:

  • 0 - spam

  • 1 - suspected

  • 2 - infected

  • 3 - attachement detection

  • 4 - content detection

  • 5 - unscannable

email

Object

  • senderIP, a String containing the sender's IP address

  • senderEmail, a String consisting in the sender's email address, as it appears in the email header fieldFrom

  • subject, a String with the subject of the quarantined email

  • recipients, an Array with the recipients, as they appear in the email header fields To and Cc

  • realRecipients, an Array containing the email addresses of the intended recipients

Example

Request:

     {
         "params": {
             "companyId": "55896b87b7894d0f367b23c6",
             "endpointId": "5d36c255f23f730fa91944e2",
             "page": 2,
             "perPage": 1,
             "filters": {
                 "threatName": "Virus 0",
                 "actionStatus": 1,
                 "startDate": "2019-07-28T11:31:28",
                 "endDate": "2019-08-16T11:31:16",
                 "filePath": "c:\\Virus0\\virus0.exe"
             }
         },
         "jsonrpc": "2.0",
         "method": "getQuarantineItemsList",
         "id": "5399c9b5-0b46-45e4-81aa-889952433d86"
     }  

Response:

  This response example is for computers service:
     {
         "id": "5399c9b5-0b46-45e4-81aa-889952433d86",
         "jsonrpc": "2.0",
         "result": {
             "total": 2,
             "page": 2,
             "perPage": 1,
             "pagesCount": 2,
             "items": [
                 {
                     "id": "5d3968e0f23f730ecb0f68c2",
                     "quarantinedOn": "2019-07-28T11:31:28",
                     "actionStatus": 1,
                     "companyId": "55896b87b7894d0f367b23c6",
                     "endpointId": "5d36c255f23f730fa91944e2",
                     "endpointName": "Computer 1",
                     "endpointIP": "156.133.37.181",
                     "canBeRestored": false,
                     "canBeRemoved": false,
                     "threatName": "Virus 0",
                     "details": {
                         "filePath": "c:\\Virus0\\virus0.exe"
                     }
                 }
             ]
         }
     }  
This response example is for exchange service:
     {
         "id":"5399c9b5-0b46-45e4-81aa-889952433d86",
         "jsonrpc":"2.0",
         "result": {
              page: 2,
              pagesCount: 10,
              perPage: 1,
              total: 10
              items[{
                   "id": "5b7d219bb1a43d170b7b23ee",
                   "quarantinedOn": "2019-08-01T07:15:20",
                   "actionStatus": 1,
                   "endpointId": "5d36c255f23f730fa91944e2",
                   "endpointName": "Computer 1",
                   "endpointIP": "57.238.160.118",
                   "endpointAvailable": true,
                   "threatName": "Virus 0",
                   "companyId": "55896b87b7894d0f367b23c6",
                   "details": {
                       "threatStatus": 4,
                       "itemType" : 0,
                       "detectionPoint": 1,
                       "email": { 
                           "senderIP": "185.36.136.238",
                           "senderEmail": "[email protected]",
                           "subject":
                         "Test subject_5b7d2128b1a43da20c7b23c6",
                           "recipients": [
                              "[email protected]", "
                              [email protected]",
                           ]
                           "realRecipients": [
                              "[email protected]", "
                              [email protected]"
                          ]
                       }
                   }
               }]
          }
     }