Obtaining Sandbox Reports Using API

NOTE

Sandbox Report API resources are only accessible to Sandbox subscribers.

Sandbox Report API resources allow you to get a Sandbox Detail Report for any file that was sent for analysis from any organization on Zscaler cloud. Zscaler stores Sandbox Detail Reports for all files that were detonated within Sandbox. Therefore, information such as the threat name, threat score, category, etc. is available within a report. However, the sample file itself and any potentially sensitive information such as screenshots or filenames are removed.

To learn more, see About Sandbox.

Determining your Quota for the Sandbox Report API

NOTE

The resource access quota for retrieving Sandbox Detail Reports is restricted to 3,000 requests per day, with a rate limit of 2/sec and 1,000/hour.

Getting the Sandbox Report API quota allows you to monitor your organization's used, unused, and allocated quota on a daily basis. To determine your quota, send a GET request to /sandbox/report/quota. For example, in Python:

conn.request("GET", "/api/v1/sandbox/report/quota", headers=headers)

Retrieving a Full or Summary Sandbox Detail Report

To get a full (i.e., complete) or summary Sandbox Detail Report, send a GET request to /sandbox/report/{md5Hash} and specify whether the details parameter should be full or summary.

For example, in Python, you would use the following code to get a summary report:

conn.request("GET", "/api/v1/sandbox/report/8350dED6D39DF158E51D6CFBE36FB012?details=summary", headers=headers)

NOTE

GET /sandbox/report/{md5Hash} returns a report only if the MD5 file was analyzed previously. If a report for a requested MD5 does not exist, the request still counts against your quota. To learn more, see Sandbox Report in the API Reference.

A Sandbox Detail Report always provides the following information:

• Status: The summary status of the file analysis, which includes one of the following values:

  • COMPLETED: The file analysis was completed
  • NODYNAMIC: The file analysis was completed, but dynamic analysis was not performed
  • INPROGRESS: The file analysis is in progress
  • NOTFOUND: The MD5 hash was not found

  For example (value COMPLETED):

  "Summary": {
      "Status": "COMPLETED",
      "Category": "SCRIPT",
      "FileType": "CMD",
      "Start Time": 1509567511,
      "Duration": 454557,
      "Analysis": "0",
      "Url": "",
      "TimeUnit": "ms",
      "StartTime": "Nov 1, 2017 1:18:31 PM"
  }

• Category: The summary category of the analyzed file, which includes one of the following values: SCRIPT, PDF, ANDROID, ARCHIVE, JAR, DOCS, FLASH, EXECS, OTHER, or ANY.

  For example (value SCRIPT):

  "Summary": {
      "Status": "COMPLETED",
      "Category": "SCRIPT",
      "FileType": "CMD",
      "Start Time": 1509567511,
      "Duration": 454557,
      "Analysis": "0",
      "Url": "",
      "TimeUnit": "ms",
      "StartTime": "Nov 1, 2017 1:18:31 PM"
  }

• Type: The classification type of the analyzed file, which includes one of the following values: MALICIOUS, SUSPICIOUS, or BENIGN.

  For example (value MALICIOUS):

  "Classification": {
      "Type": "MALICIOUS",
      "Category": "MALWARE_BOTNET",
      "Score": 86,
      "Max Score": 100,
      "DetectedMalware": ""
  }

• Category (Classification): The classification category of the analyzed file, which includes one of the following values: BENIGN, SUSPICIOUS, ADWARE, MALWARE_BOTNET, or ANONYMIZER_P2P.

  For example (value MALWARE_BOTNET):

  "Classification": {
      "Type": "MALICIOUS",
      "Category": "MALWARE_BOTNET",
      "Score": 86,
      "Max Score": 100,
      "DetectedMalware": ""
  }

Example Summary Sandbox Detail Report (Malicious File)

A summary Sandbox Detail Report only includes Summary, Classification, and FileProperties information.

{
    "Summary": {
        "Summary": {
            "Status": "COMPLETED",
            "Category": "EXECS",
            "FileType": "DLL",
            "StartTime": 1522111841,
            "Duration": 481690
        },
        "Classification": {
            "Type": "MALICIOUS",
            "Category": "MALWARE_BOTNET",
            "Score": 82,
            "DetectedMalware": "Win32/TrojanDownloader.Banload.TNJ trojan"
        },
        "FileProperties": {
            "FileType": "DLL",
            "FileSize": 2358272,
            "MD5": "b3b13c2fe5710507612106cb11ceced3",
            "SHA1": "6f30404f8b30812758acc06455bc95348c86f9f2",
            "Sha256": "c77ab4c60b73c8f8135d54162813ab7c63432058f17ff00754d5fd547c22db76",
            "Issuer": "",
            "DigitalCerificate": "",
            "SSDeep": "49152:mQU0HSp/RcGuBLe/PESBbFVZ86MfBWPvGZxnBGVV3NcKRLFcTOJP:mQUn6LsPQp6vkoiKt",
            "RootCA": ""
        }
    }
}

Example Full Sandbox Detail Report (Malicious File)

A full Sandbox Detail Report includes the same information as in a summary report, and also includes System Summary, Networking, and other information specific to the analyzed file.

{
    "Full Details": {
        "Summary": {
            "Status": "COMPLETED",
            "Category": "SCRIPT",
            "FileType": "CMD",
            "Start Time": 1509567511,
            "Duration": 454557,
            "Analysis": "0",
            "Url": "",
            "TimeUnit": "ms",
            "StartTime": "Nov 1, 2017 1:18:31 PM"
        },
        "Classification": {
            "Type": "MALICIOUS",
            "Category": "MALWARE_BOTNET",
            "Score": 86,
            "Max Score": 100,
            "DetectedMalware": ""
        },
        "File Properties": {
            "File Type": "CMD",
            "File Size": 9810,
            "MD5": "8350ded6d39df158e51d6cfbe36fb012",
            "SHA1": "f4dd1d176975c70ba8963ebc654a78a6e345cfb6",
            "Sha256": "aff2d40828597fbf482753bec73cc9fc2714484262258875cc23c7d5a7372cee",
            "Issuer": "",
            "Digital Cerificate": "",
            "SSDeep": "192:+cgNT7Zj4tvl2Drc+gEakjqBT1W431lXXH1TR8J:InZjevl2Drc+gEakmBT44rXVR8J",
            "RootCA": ""
        },
        "System Summary": [
            {
                "Risk": "LOW",
                "Signature": "Allocates memory within range which is reserved for system DLLs",
                "Signature Sources": [
                    "76E70000 page execute and read and write",
                    "76F90000 page execute and read and write"
                ]
            },
            {
                "Risk": "LOW",
                "Signature": "Creates files inside the user directory",
                "Signature Sources": [
                    "C:\\Users\\win_7_64bit\\Desktop\\WlanTraces"
                ]
            }
        ],
        "Networking": [
            {
                "Risk": "MODERATE",
                "Signature": "Uses ipconfig to modify the Windows network settings",
                "Signature Sources": [
                    "C:\\Windows\\SysWOW64\\ipconfig.exe "
                ]
            },
            {
                "Risk": "HIGH",
                "Signature": "Uses netsh to modify the Windows network and firewall settings",
                "Signature Sources": [
                    "C:\\Windows\\SysWOW64\\netsh.exe "
                ]
            }
        ],
        "Persistence": [
            {
                "Risk": "MODERATE",
                "Signature": "Creates or modifies Windows services",
                "Signature Sources": [
                    "HKEY_LOCAL_MACHINE\\SYSTEM\\ControlSet001\\services\\IKEEXT\\Parameters"
                ]
            },
            {
                "Risk": "HIGH",
                "Signature": "Modifies security policies related information",
                "Signature Sources": [
                    "HKEY_LOCAL_MACHINE\\SYSTEM\\ControlSet001\\Control\\Lsa\\Kerberos\\Parameters KerbDebugLevel"
                ]
            }
        ]
    }
}