Skip to main content

Bitdefender B2B Help Center

Sandbox

Sandbox Analyzer API retrieves metadata related to the Sandbox Analyzer instances, images and submissions.

  • getSandboxAnalyzerInstancesList: lists Sandbox Analyzer instances.

  • getImagesList: lists images for a instance.

  • getSubmissionStatus: returns the status of a submission.

  • getDetonationDetails: returns the details of a submission.

API url: https://YOUR-HOSTNAME/api/v1.0/jsonrpc/sandbox

getSandboxAnalyzerInstancesList

This method lists the instances in the Infrastructure menu.

Parameters

Parameter

Type

Optional

Description

page

Number

Yes

The results page. Default value: 1.

perPage

Number

Yes

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

Return value

This method returns an Object containing information regarding the [SandboxAnalyzer] instances. The object has the following structure:

  • page - the current page displayed

  • pagesCount - the total number of available pages

  • perPage - the number of returned items per page

  • items - the list of [SandboxAnalyzer] instances. Each item has the following fields:

    • sandboxId, the ID of the [SandboxAnalyzer] instance.

    • name, the name of the [SandboxAnalyzer] instance.

    • ip, the IP address of the [SandboxAnalyzer] instance.

    • macs, the MAC addresses of the [SandboxAnalyzer] instance.

    • ssid, the Active Directory SID of the [SandboxAnalyzer] instance.

    • detonatedSamples, the overall number of samples analyzed by the [SandboxAnalyzer] instance.

    • diskUsage, the percentage of the disk space that [SandboxAnalyzer] occupies in the datastore.

    • installationStatus, the status of the [SandboxAnalyzer] installation process. It can have one of the following values:

      • 0 - Not installed

      • 1 - Installed

      • 2 - Installing

      • 3 - Installation failed

    • lastSeen, the date of the last synchronization with Control Center.

    • configuredConcurrentDetonations, the number of virtual machines allocated to detonate samples.

    • maximumConcurrentDetonations, the maximum number of virtual machines that the [SandboxAnalyzer] instance can create to detonate samples.

    • submissionUrl, the URL for submitting files for analysis.

  • total - the total number of items

Example

Request:

  {
     "method": "getSandboxAnalyzerInstancesList",
     "params": {
        "page": 1,
        "perPage": 20
     },
     "jsonrpc": "2.0",
     "id": "91d6430d-bfd4-494f-8d4d-4947406d21a7"
  }

Response:

  {
     "id": "91d6430d-bfd4-494f-8d4d-4947406d21a7",
     "jsonrpc": "2.0",
     "result": {
        "page": 1,
        "pagesCount": 1,
        "perPage": 20,
        "total": 1,
        "items": [
           {
               "sandboxId": "5c419e6e26df3d367c49de18",
               "name": "sandbox1",
               "ip": "10.10.20.1",
               "macs": [
                   "00-14-22-01-23-45"
               ],
               "ssid": "",
               "detonatedSamples": 0,
               "diskUsage": 250,
               "installationStatus": 1,
               "lastSeen": "2019-01-18T11:37:50",
               "configuredConcurrentDetonations": 0,
               "maximumConcurrentDetonations": 10,
               "submissionUrl":"https://10.10.20.1:443/api/v1/upload"
           }
        ]
     }
  }

getImagesList

This method lists all images available on a [SandboxAnalyzer] instance.

Parameters

Parameter

Type

Optional

Description

sandboxId

String

No

The ID of the Sandbox Analyzer instance for which the images list will be returned.

page

Number

Yes

The results page number. Default value: 1.

perPage

Number

Yes

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

Return value

This method returns an Object containing information regarding the images. The object has the following structure:

  • page - the current page displayed

  • pagesCount - the total number of available pages

  • perPage - the total number of returned items per page

  • items - the list of images. Each item in the list has the following fields:

    • id, the ID of the image.

    • name, the name of the image.

    • status, the status of the image. It can have one of the following values:

      • 1 - New

      • 2 - Failed

      • 3 - Ready

    • operatingSystem, the operating system of the image.

    • dateAdded, the date on which the image was added.

    • isDefault, a Boolean which has the value True when the image is set as default. False otherwise.

    • actionInProgress, a Boolean which has the value True when there is an action in progress for this image.

  • total - the total number of items

Example

Request:

  {
     "method": "getImagesList",
     "params": {
        "sandboxId": "5c419e6e26df3d367c49de18",
        "page": 1,
        "perPage": 20
     },
     "jsonrpc": "2.0",
     "id": "91d6430d-bfd4-494f-8d4d-4947406d21a7"
  }

Response:

  {
     "id": "91d6430d-bfd4-494f-8d4d-4947406d21a7",
     "jsonrpc": "2.0",
     "result": {
        "page": 1,
        "pagesCount": 1,
        "perPage": 20,
        "total": 1,
        "items": [
           {
               "id": "924cca0d49cc7e350a44502b0bb9026a",
               "name": "image1",
               "status": 1,
               "operatingSystem": "Windows 10",
               "dateAdded": "2019-01-18T09:20:50",
               "isDefault": true,
               "actionInProgress": false
           }
        ]
     }
  }

getSubmissionStatus

Returns the final status of the detonation.

Parameters

Parameter

Type

Optional

Description

submissionId

String

No

The ID of the submission for which the status should be retrieved.

Return value

This method returns an Object containing the status:

  • status - an Integer representing the final status. It can have one of the following values:

    • 1 - completed, if the detonation was successful

    • 2 - pending, if the detonation is currently in progress

    • 3 - failed, if the detonation failed

    • 4 - not supported, if the file cannot be detonated

Example

Request:

  {
     "id": "787b5e36-89a8-4353-88b9-6b7a32e9c87f",
     "jsonrpc": "2.0",
     "method": "getSubmissionStatus",
     "params": {
        "submissionId": "sp02_1547807011_936_e5"
     }
  }

Response:

  {
    "id": "787b5e36-89a8-4353-88b9-6b7a32e9c87f",
    "jsonrpc": "2.0",
    "result": {
      "status": 1
    }
  }

getDetonationDetails

The method returns the details of a submission, including a URL pointing to the HTML report.

Parameters

Parameter

Type

Optional

Description

submissionId

String

No

The ID of the submission for which the detonation details should be retrieved.

Return value

This method returns an Object containing the details of a completed detonation. The object has the following structure:

  • detailsReportUrl - a String containing the URL from where the HTML report is available for download.

  • score - an Integer in the range 0-100 representing the severity of the threat, if any.

  • verdict - an Integer having one of the following values:

    • 0, if clean.

    • 1, if infected.

    • 2, if unsupported.

  • mitreTags - an Array of Objects with the following structure:

    • category a String holding the MITRE category.

    • techniques an Array of Strings holding the MITRE techniques.

Example

Request:

  {
     "id": "787b5e36-89a8-4353-88b9-6b7a32e9c87f",
     "jsonrpc": "2.0",
     "method": "getDetonationDetails",
     "params": {
        "submissionId": "sp02_1547807011_936_e5"
     }
  }

Response:

  {
     "id": "787b5e36-89a8-4353-88b9-6b7a32e9c87f",
     "jsonrpc": "2.0",
     "result": {
        "detailsReportUrl":"https://10.10.20.1:443/api/v1/report?report_id=asd",
        "score": 30,
        "verdict": 0,
        "mitreTags": [
           {
               "category": "Defense Evasion",
               "techniques": [
                  "Modify Registry",
               ]
           },
           {
               "category": "Persistence",
               "techniques": [
                  ".bash_profile and .bashrc",
                  "Account Manipulation",
               ]
           },
        ]
     }
  }
In this section: