Sandbox

Overview

The Sandbox API allows you to submit files for in-depth analysis within a secure, cloud-based sandbox environment. This Symantec technology meticulously examines file behavior, leveraging machine learning to identify malicious attributes. By correlating findings with the extensive Symantec Global Intelligence Network, it delivers a reliable verdict on whether a file is malicious.

Use Cases

The Sandbox API enables you to:

  • Easily upload suspicious files or submit already uploaded sha256 hashes for sandboxed execution and examination.
  • Obtain a clear verdict (e.g., MALWARE, CLEAN, SUSPICIOUS) based on the analysis.
  • Receive comprehensive reports including static analysis findings and a summary of the file’s behavior during dynamic execution.

Requirements

  • Enterprise EDR product
  • All API calls require an API key with appropriate permissions

Resources

Authentication

For more details see the Carbon Black Cloud API Access Guide.


Carbon Black Cloud Managed Identity and Authentication
Customize your access to the Carbon Black Cloud APIs with Role-Based Access Control; All APIs and Services authenticate via API Keys. To access the data in Carbon Black Cloud via API, you must set up a key with the correct permissions for the calls you want to make and pass it in the HTTP Headers.

Environment
Available on majority of environments; Use the Carbon Black Cloud Console URL, as described here.

API Route
Replace the {cbc-hostname} and {org_key} with the URL of your Environment and the org_key for your specific Org.
  • {cbc-hostname}/ubs/v1/orgs/{org_key}/binary_analysis/{sha256}
  • {cbc-hostname}/ubs/v1/orgs/{org_key}/sandbox_executions/{execution_id}
  • {cbc-hostname}/ubs/v1/orgs/{org_key}/sandbox_executions
  • {cbc-hostname}/ubs/v1/orgs/{org_key}/binary_analysis/{sha256}/sandbox_report

Access Level
Before you create your API Key, you need to create a "Custom" Access Level including each category:
  • Unified Binary Store > Sandbox > ubs.org.sandbox, allow permission to READ, CREATE

API Key
When creating your API Key, use the Access Level Type of "Custom" and select the Access Level you created. Details on constructing and passing the API Key in your requests are available here.


API Calls

Get Binary Analysis

Get the binary analysis summary for a given sha256


API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud ubs.org.sandbox READ Majority of environments

Request 
GET {cbc-hostname}/ubs/v1/orgs/{org_key}/binary_analysis/{sha256}


Response Codes

Code Description Content-Type Content
200 Binary Analysis Found application/json See example below
404 Not Found No Content

Examples

Request 
GET https://defense.conferdeploy.net/ubs/v1/orgs/ABCD1234/binary_analysis/bef9dbed290af17cf3f30cc43fc0a94cdadc540f171c25df1363b2e852d0a042
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Response Body 
{
    "sha256": "bef9dbed290af17cf3f30cc43fc0a94cdadc540f171c25df1363b2e852d0a042",
    "status": "COMPLETE",
    "verdict": "CLEAN",
    "last_analyzed": "2025-05-20T18:37:09.029033Z"
}
To download or review the Carbon Black Cloud Postman collection, click here.

Get Sandbox Report

Get the full sandbox report for a given sha256


API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud ubs.org.sandbox READ Majority of environments

Request 
GET {cbc-hostname}/ubs/v1/orgs/{org_key}/binary_analysis/{sha256}/sandbox_report

Response Codes

Code Description Content-Type Content
200 Sandbox Report Found application/json SandboxReportResponse
404 Not Found No Content

Examples

Request 
GET https://defense.conferdeploy.net/ubs/v1/orgs/ABCD1234/binary_analysis/bef9dbed290af17cf3f30cc43fc0a94cdadc540f171c25df1363b2e852d0a042/sandbox_report
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Response Body 
{
    "report": {
        "verdict": "CLEAN",
        "verdictType": "FULL_ANALYSIS",
        "executionMetadata": {
            "sampleName": "bef9dbed290af17cf3f30cc43fc0a94cdadc540f171c25df1363b2e852d0a042",
            "fileType": "application/x-dosexec",
            "fileSize": 213920,
            "sha256": "bef9dbed290af17cf3f30cc43fc0a94cdadc540f171c25df1363b2e852d0a042"
        },
        "staticAnalysisMetadata": {
            "status": "AVAILABLE",
            "staticRules": [
                {
                    "uuid": "7bcc5190-715e-4f04-8a4e-7ed895b2f0af",
                    "severity": "LOW_RISK",
                    "desc": "Submitted file has a high good reputation",
                    "sha256": [
                        "bef9dbed290af17cf3f30cc43fc0a94cdadc540f171c25df1363b2e852d0a042"
                    ]
                },
                {
                    "uuid": "79392242-ec03-4892-a5f3-cecc0c5580cc",
                    "severity": "LOW_RISK",
                    "desc": "Signature on the file is trusted",
                    "sha256": [
                        "bef9dbed290af17cf3f30cc43fc0a94cdadc540f171c25df1363b2e852d0a042"
                    ]
                }
            ],
            "staticEvents": [
                {
                    "sha256": "bef9dbed290af17cf3f30cc43fc0a94cdadc540f171c25df1363b2e852d0a042",
                    "reputationData": {
                        "band": 8,
                        "text": "Symantec trusts the file"
                    },
                    "detectionData": null,
                    "urlData": null
                }
            ]
        },
        "executionSummary": {
            "status": "AVAILABLE",
            "sha256": "bef9dbed290af17cf3f30cc43fc0a94cdadc540f171c25df1363b2e852d0a042",
            "fileType": "application/x-dosexec",
            "rules": [
                {
                    "uuid": "e8470d03-50b8-420a-9500-72bc62509632",
                    "severity": "LOW_RISK",
                    "desc": "A registry key was opened",
                    "eventIds": [
                        "acfd6e12-2a4d-4329-b568-58330f10515f",
                        "3ca252a9-a4e6-462e-b817-2be4ff278798"
                    ]
                }
            ],
            "filteredEvents": [
                {
                    "id": "9ded1a83-a63f-4bd5-a00e-7826682aceaf",
                    "generatedTimeInMs": "1747762988375",
                    "summary": "[38] dns.msftncsi.com",
                    "icdEventId": 42,
                    "icdEventDesc": "URL Reputation",
                    "icdActivityId": 4,
                    "icdActivityDesc": "Logged"
                },
                {
                    "id": "83aaf398-73ec-416a-97b9-0c8d2ac97367",
                    "generatedTimeInMs": "1747762988375",
                    "summary": "[38] dns.msftncsi.com",
                    "icdEventId": 42,
                    "icdEventDesc": "URL Reputation",
                    "icdActivityId": 4,
                    "icdActivityDesc": "Logged"
                },
                {
                    "id": "acfd6e12-2a4d-4329-b568-58330f10515f",
                    "generatedTimeInMs": "1747765938995",
                    "summary": "HKEY_LOCAL_MACHINE\\System\\CurrentControlSet\\Control\\SafeBoot\\Option\\",
                    "icdEventId": 8005,
                    "icdEventDesc": "Registry Key Activity",
                    "icdActivityId": 3,
                    "icdActivityDesc": "Opened"
                },
                {
                    "id": "3ca252a9-a4e6-462e-b817-2be4ff278798",
                    "generatedTimeInMs": "1747765939009",
                    "summary": "HKEY_USERS\\S-1-5-21-1839595590-1967928825-12345678-1234\\Control Panel\\Desktop\\MuiCached\\MachineLanguageConfiguration\\",
                    "icdEventId": 8005,
                    "icdEventDesc": "Registry Key Activity",
                    "icdActivityId": 3,
                    "icdActivityDesc": "Opened"
                },
                {
                    "id": "087ad845-8a62-4460-8ba9-b1a539a02946",
                    "generatedTimeInMs": "1747765939042",
                    "summary": "[9144] c:\\bef9dbed290af17cf3f30cc43fc0a94cdadc540f171c25df1363b2e852d0a042.exe",
                    "icdEventId": 8001,
                    "icdEventDesc": "Process Activity",
                    "icdActivityId": 2,
                    "icdActivityDesc": "Terminated"
                },
                {
                    "id": "9236c73b-af38-475d-8d96-1977d2f926ba",
                    "generatedTimeInMs": "1747765939946",
                    "summary": "[90] wpad.midas.local",
                    "icdEventId": 42,
                    "icdEventDesc": "URL Reputation",
                    "icdActivityId": 4,
                    "icdActivityDesc": "Logged"
                },
                {
                    "id": "30cbf7dd-6fc4-4ba6-8b5e-20c6bd4227b0",
                    "generatedTimeInMs": "1747765939946",
                    "summary": "[90] wpad.midas.local",
                    "icdEventId": 42,
                    "icdEventDesc": "URL Reputation",
                    "icdActivityId": 4,
                    "icdActivityDesc": "Logged"
                }
            ],
            "executionArtifacts": {
                "pcap": {
                    "artifact": {
                        "uri": "https://example-integration-infra-analysis-results.s3.amazonaws.com/sandbox-reports/<truncated>",
                        "expiryTimeInMs": "1747855782416",
                        "fileType": "application/vnd.tcpdump.pcap"
                    },
                    "status": "AVAILABLE"
                },
                "screenShots": {
                    "artifact": {
                        "uri": "https://example-integration-infra-analysis-results.s3.amazonaws.com/sandbox-reports/<truncated>",
                        "expiryTimeInMs": "1747855782417",
                        "fileType": "image/png"
                    },
                    "status": "AVAILABLE"
                },
                "sepTraces": {
                    "status": null,
                    "artifact": null
                }
            }
        }
    }
}
To download or review the Carbon Black Cloud Postman collection, click here.

Create Sandbox Execution

Trigger a sandbox execution by specifying an existing binary in the Carbon Black Cloud or upload your own binary.


API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud ubs.org.sandbox READ Majority of environments

Request 
POST {cbc-hostname}/ubs/v1/orgs/{org_key}/sandbox_executions

Request Body

{
  "sha256": <string>"
}


Body Schema

Application/JSON

Field Definition Data Type Values
sha256 The sha256 for a binary previously uploaded to the Carbon Black Cloud string

Response Codes

Code Description Content-Type Content
200 Execution triggered successfully application/json Execution
400 Execution Creation Error No Content
413 File is too large text/html
415 Unsupported Media Type No Content
429 Too many requests No Content

Examples

Request 
POST https://defense.conferdeploy.net/ubs/v1/orgs/ABCD1234/sandbox_executions
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
{
  "sha256": "bef9dbed290af17cf3f30cc43fc0a94cdadc540f171c25df1363b2e852d0a042"
}
Response Body 
{
    "id": "0176ba23-7908-40b6-a001-e014c1b4d44c",
    "sha256": "bef9dbed290af17cf3f30cc43fc0a94cdadc540f171c25df1363b2e852d0a042",
    "status": "IN_PROGRESS",
    "last_submitted": "2025-05-21T18:37:44.923027014Z",
    "file_name": "microsoftedgeupdate.exe",
    "submitter": "example",
    "verdict": null,
    "last_analyzed": null
}
To download or review the Carbon Black Cloud Postman collection, click here.

Get Sandbox Executions

Get the history of all sandbox executions for an org


API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud ubs.org.sandbox READ Majority of environments

Request 
GET {cbc-hostname}/ubs/v1/orgs/{org_key}/sandbox_executions

Query Parameter

Parameter Required Description Values Default
start No Row to start from when retrieving results 0
rows No Number of rows to retrieve 10
sort_field No Field to sort results by
sort_order No Direction to sort by ASC, DESC


Response Codes

Code Description Content-Type Content
200 OK application/json See example below

Examples

Request 
GET https://defense.conferdeploy.net/ubs/v1/orgs/ABCD1234/sandbox_executions
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Response Body 
{
    "results": [
        {
            "id": "0176ba23-7908-40b6-a001-e014c1b4d44c",
            "sha256": "bef9dbed290af17cf3f30cc43fc0a94cdadc540f171c25df1363b2e852d0a042",
            "status": "IN_PROGRESS",
            "last_submitted": "2025-05-21T18:37:44.923027Z",
            "file_name": "microsoftedgeupdate.exe",
            "submitter": "example",
            "verdict": null,
            "last_analyzed": null
        },
        {
            "id": "61b19b59-6329-4545-9296-65f257f6cc37",
            "sha256": "774459214dfd435d37baa2cd43c034e3ea771d0a638979c09832fcad25effc4e",
            "status": "COMPLETE",
            "last_submitted": "2025-05-20T20:09:47.396656Z",
            "file_name": "backgroundtaskhost.exe",
            "submitter": "example2",
            "verdict": null,
            "last_analyzed": "2025-05-20T14:34:30.746020Z"
        },
        {
            "id": "00fb1900-542c-4d53-a139-aae0a60ad90b",
            "sha256": "eb71ea69dd19f728ab9240565e8c7efb59821e19e3788e289301e1e74940c208",
            "status": "COMPLETE",
            "last_submitted": "2025-05-20T18:49:26.188597Z",
            "file_name": "cmd.exe",
            "submitter": "example2",
            "verdict": "CLEAN",
            "last_analyzed": "2025-05-20T18:51:07.650818Z"
        }
    ],
    "num_available": 3
}
To download or review the Carbon Black Cloud Postman collection, click here.

Get Execution by ID

Get the details for a specific sandbox execution


API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud ubs.org.sandbox READ Majority of environments

Request 
GET {cbc-hostname}/ubs/v1/orgs/{org_key}/sandbox_executions/{execution_id}

Response Codes

Code Description Content-Type Content
200 Execution Found application/json Execution
404 Not Found No Content

Examples

Request 
GET https://defense.conferdeploy.net/ubs/v1/orgs/ABCD1234/sandbox_executions/0176ba23-7908-40b6-a001-e014c1b4d44c
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Response Body 
{
    "id": "0176ba23-7908-40b6-a001-e014c1b4d44c",
    "sha256": "bef9dbed290af17cf3f30cc43fc0a94cdadc540f171c25df1363b2e852d0a042",
    "status": "COMPLETE",
    "last_submitted": "2025-05-21T18:37:44.923027Z",
    "file_name": "microsoftedgeupdate.exe",
    "submitter": "8H9KH636JG",
    "verdict": "CLEAN",
    "last_analyzed": "2025-05-21T18:39:26.638294Z"
}
To download or review the Carbon Black Cloud Postman collection, click here.

Field Definitions

Execution

Field Definition Data Type Values
id Unique identifier for the execution. string
status Current status of the sandbox execution. string IN_PROGRESS, ERROR, COMPLETE
last_submitted Timestamp of the last submission for this execution. ISO8601 timestamp
file_name Name of the file submitted for execution. string
submitter Identifier of the entity that submitted the execution. string
verdict Verdict of the analysis. string MALWARE, CLEAN, SUSPICIOUS
last_analyzed Timestamp of when the analysis was last completed. ISO8601 timestamp

SandboxReportResponse

Field Definition Data Type Values
report The sandbox report SandboxReport Schema

SandboxReport

Field Definition Data Type Values
verdict The overall verdict of the sandbox analysis. string MALWARE, CLEAN, SUSPICIOUS
verdictType The type of analysis that led to the verdict. string FULL_ANALYSIS, INTELLIGENCE
executionMetadata Metadata related to the execution of the sample. ExecutionMetadata Schema
staticAnalysisMetadata Metadata from the static analysis of the sample. StaticAnalysisMetadata Schema
executionSummary A summary of the dynamic execution analysis. ExecutionSummary Schema

ExecutionMetadata

Field Definition Data Type Values
sampleName The name of the sample file. string
fileType The MIME type of the sample file. string
fileSize The size of the sample file in bytes. integer
sha256 The SHA256 hash of the sample file. string

StaticAnalysisMetadata

Field Definition Data Type Values
staticRules A list of static analysis rules that were triggered. list Schema
staticEvents A list of events observed during static analysis. list Schema

StaticRule

Field Definition Data Type Values
uuid Unique identifier for the static rule. string
desc Description of the static rule. string
sha256 SHA256 hash(es) associated with the rule trigger. list
severity Severity level of the triggered rule. string MALICIOUS, SUSPICIOUS, LOW_RISK

StaticEvent

Field Definition Data Type Values
sha256 SHA256 hash of the file associated with this static event. string
reputationData Reputation information related to the static event. ReputationData Schema
detectionData Detection information related to the static event. DetectionData Schema
urlData URL information related to the static event. array Schema

ReputationData

Field Definition Data Type Values
band Numerical reputation score or band. integer
text Textual description of the reputation. string

DetectionData

Field Definition Data Type Values
threatNames A list of names for identified threats. array

UrlData

Field Definition Data Type Values
url The URL observed. string
urlCategory Category information for the URL. array 
{
  "id": 0,
  "name": "<string>"
}
detected Indicates if the URL was detected as part of the analysis. boolean true, false

ExecutionSummary

Field Definition Data Type Values
status Status of the execution summary. string AVAILABLE, NOT_GENERATED, ERROR
sha256 SHA256 hash of the executed file. string
fileType MIME type of the executed file. string
rules Rules triggered during dynamic execution. Rule Schema
filteredEvents A list of filtered events from the dynamic execution. array Schema
executionArtifacts Artifacts generated during execution. executionArtifact Schema

Rule

Field Definition Data Type Values
uuid Unique identifier for the rule. string
desc Description of the rule. string
severity Severity level of the rule. string MALICIOUS, SUSPICIOUS, LOW_RISK
eventIds List of event IDs associated with this rule. array

FilteredEvent

Field Definition Data Type Values
id Unique identifier for the filtered event. string
generatedTimeInMs Timestamp when the event was generated, in milliseconds. integer
summary A summary of the event. string
icdEventId ICD (Integrated Cyber Defense) event ID. integer
icdEventDesc Description of the ICD event. string
icdActivityId ICD activity ID. integer
icdActivityDesc Description of the ICD activity. string

ExecutionArtifact

Field Definition Data Type Values
pcap Network traffic capture (PCAP) artifact. PcapArtifact Schema
screenShots Screenshots taken during execution. ScreenShotArtifact Schema
sepTraces SEP (Symantec Endpoint Protection) traces. SepTraceArtifact Schema

Artifact

Field Definition Data Type Values
uri URI to download the artifact. string
expiryTimeInMs Timestamp when the download URI expires, in milliseconds. integer
fileType MIME type of the artifact. string

PcapArtifact

Field Definition Data Type Values
artifact Details of the PCAP artifact. Artifact Schema
status Status of the PCAP artifact generation. string AVAILABLE, NOT_GENERATED, ERROR

ScreenShotArtifact

Field Definition Data Type Values
artifact Details of the screenshot artifact. Artifact Schema
status Status of the screenshot artifact generation. string AVAILABLE, NOT_GENERATED, ERROR

SepTraceArtifact

Field Definition Data Type Values
artifact Details of the SEP trace artifact. Artifact Schema
status Status of the SEP trace artifact generation. string AVAILABLE, NOT_GENERATED, ERROR

Last modified on October 15, 2025