Sandbox

To submit files or URLs to the ThreatStream hosted Sandbox.

Request

/api/v1/submit/new/

HTTP Method: POST

Attributes: See the table below

Request Attributes

Attribute	Type	Description
file_has_password	boolean	When using Anomali Sandbox, Joe Sandbox or Polyswarm to detonate a file, set this attribute to `true` if the file is password protected. You must specify the password using the `file_password` attribute. Note: File passwords are supported only for .zip files on Polyswarm.
file_password	string	When detonating a password protected file on Anomali Sandbox, Joe Sandbox or Polyswarm, use this attribute to specify the value of the password. You must set `file_has_password` to `true` if using this attribute.
import_indicators	boolean	To initiate an import job for observables discovered during detonation, set this value to `true`. Default: `true`
is_qrcode (Polyswarm Only)	boolen	To analyze URLs embedded in the QR codes of the file that is being submitted to detonation, set `is_qrcode` to `true`.
classification	string	Classification of the Sandbox submission—public or private.
notes	string	A comma-separated list that provides additional details for imported observables. This information is displayed in the Tag column of the ThreatStream UI. For example, "Credential-Exposure,compromised_email".
polyswarm_scan (Polyswarm Only)	boolean	To submit a URL or file artifact for a Polyswarm scan, set `polyswarm_scan` to `true`.
platform	string	Platform on which the submitted URL or file will be detonated. Note: This attribute is required for Joe Sandbox detonations. Do not specify this value for VMRay detonations. The following platforms are supported: For organizations using Anomali Sandbox (Joe Sandbox via ThreatStream):`ANDROID9.0`, `MACOSXVM`, `LINUX` (Ubuntu 16.04), `WINDOWS10x64`, `WINDOWS7`, `WINDOWS7x64OFFICE2010`. Note: The `Android9.0` platform is supported only for file detonations. For organizations using Joe Sandbox via an individual subscription:`ANDROID9.0`, `MACOSXVM`, `LINUX` (Ubuntu 16.04), `WINDOWS10x64`, `WINDOWS7`, `WINDOWS7x64OFFICE2010`. Note: The `Android9.0` platform is supported only for file detonations. For organizations using Polyswarm: `cape_windows10pro`, `triage_android11x64`, `triage_ubuntu22x64`, `triage_windows10x64`. Multiple platforms can be specified in a single request as a comma-separated string. Note: When using Polyswarm, multiple platforms can be specified in a single request as a comma-separated string. You can obtain a list of supported platforms by making this API call: `curl -XGET'https://api.threatstream.com/api/v1/submit/parameters/' -H 'Authorization: apikey <username>:<api_key>'`
url OR file	string	Specify the URL that you want to detonate. OR Specify the file that you want to detonate. Include the full path to the file.
circles	string	ID of the trusted circle to which the Sandbox data should be associated. If you want to specify multiple trusted circles, enter the list of comma-separated IDs. To find the ID of a trusted circle, locate the trusted circle using ThreatStream UI and click on its name. The URL displayed in the address bar shows the ID. For example, `https://ui.threatstream.com/search?circles=13`.
use_anomali_sandbox	boolean	If you want to use the Anomali Sandbox for detonation, set this attribute to `true`. Note: By default, Anomali offers 2 free detonations per day.
use_premium_sandbox	boolean	If you want to use the Joe Sandbox service for detonation, set this attribute to `true`. Notes: You must have an active Joe Sandbox integration on ThreatStream in order to use the Joe Sandbox service.
use_polyswarm_sandbox	boolean	If you want to use the Polyswarm sandbox service for detonation, set this attribute to `true`. Note: You must have an active Polyswarm integration on ThreatStream in order to use the Polyswarm sandbox service.
use_vmray_sandbox	boolean	If you want to use the VMRay sandbox service for detonation, set this attribute to `true`. Note: You must have an active VMRay integration on ThreatStream in order to use the VMRay sandbox service.
vmray_max_jobs	integer	Specify the number of detonations you want VMRay to perform for the submission. If you specify a number greater than 1, VMRay performs the detonations on different platforms. A Sandbox Report is created on ThreatStream for each detonation that returns results. Note: Specify a value for this attribute only if `use_vmray_sandbox` is set to `true`.

Response

The response contains the following attributes.

Attribute	Description
success	Whether the submission was successful or not. Possible values: true, false
reports status detail	Provides a report of the denotation. The following specifics are contained in the report: End point that provides the detonation status End point where the detonation report is located

Attribute

Description

success

Whether the submission was successful or not. Possible values: true, false

reports

status
detail

Provides a report of the denotation. The following specifics are contained in the report:

End point that provides the detonation status
End point where the detonation report is located

Response Example:

Copy

{
"success": true,
"reports":{
"WINDOWS7":{
"status":"/api/v1/submit/188/",
"detail":"/api/v1/submit/188/report/"
}
}
}

Detonating Archive Files

You can use the Sandbox API to detonate archive files in a Sandbox. Files within the archive are detonated individually. Therefore, Anomali recommends adding a tag (using the notes attribute) to your sandbox submission when detonating archive files. After detonation, you can use the tag to locate all the detonated files in a request to the /api/v1/submit/search API.

The following Sandbox Search request returns a list of detonated files for a submission tagged with archive_detonation_2025-02-15:

Copy

curl 'https://api.threatstream.com/api/v1/submit/search/?q=archive_detonation_2025-02-15' -H 'Authorization: apikey <username>:<api_key>'

See Sandbox Search for more information on the Sandbox Search API.

Examples

Note: If you plan on cutting and pasting the following examples, be sure to remove any spaces that are introduced in places where lines wrap in the document.

To submit a URL to the Anomali Sandbox:

Copy

curl -XPOST 'https://api.threatstream.com/api/v1/submit/new/' -F classification=private  -F platform=WINDOWS7 -F use_anomali_sandbox=true -F url="http://preppybeach.cl/wp-includes/images/ipad/"  -H 'Authorization: apikey <username>:<api_key>'

To submit an archive file to the Anomali Sandbox:

Copy

curl -XPOST 'https://api.threatstream.com/api/v1/submit/new/' -F classification=private  -F platform=WINDOWS7 -F file="@/Users/jdoe/Downloads/archive.zip" -F notes=archive_detonation_2025-04-21 -F use_anomali_sandbox=true -H 'Authorization: apikey <username>:<api_key>'

To submit a file to the Polyswarm sandbox service:

Copy

curl -XPOST 'https://api.threatstream.com/api/v1/submit/new/'  -F classification=private  -F platform=WINDOWS7 -F file="@/Users/jdoe/Downloads/structure.csv" -F use_polyswarm_sandbox=true -H 'Authorization: apikey <username>:<api_key>'

To submit a URL to the Joe Sandbox service:

Copy

curl -XPOST 'https://api.threatstream.com/api/v1/submit/new/' -F classification=private  -F platform=WINDOWS7 -F url="http://preppybeach.cl/wp-includes/images/ipad/" -F use_premium_sandbox=true -F notes="Credential-Exposure,compromised_email" -H 'Authorization: apikey <username>:<api_key>'

To submit a password protected file whose password is "infected" to the Joe Sandbox service:

Copy

curl -XPOST 'https://api.threatstream.com/api/v1/submit/new/' -F classification=private  -F platform=WINDOWS7 -F file="@/Users/jdoe/Downloads/ts_logo.png" -F file_has_password=true -F file_password=infected -F use_premium_sandbox=true -H 'Authorization: apikey <username>:<api_key>'

To submit a URL to the VMRay sandbox service:

Copy

curl -XPOST 'https://api.threatstream.com/api/v1/submit/new/' -F use_vmray_sandbox=true -F vmray_max_jobs=3 -F classification=private -F url="http://preppybeach.cl/wp-includes/images/ipad/" -F notes="Credential-Exposure,compromised_email" -H 'Authorization: apikey <username>:<api_key>'

To submit a file to the VMRay sandbox service:

Copy

curl -XPOST 'https://api.threatstream.com/api/v1/submit/new/' -F use_vmray_sandbox=true -F vmray_max_jobs=3 -F file="@/Users/jdoe/Downloads/ts_logo.png" -F notes="Credential-Exposure,compromised_email" -H 'Authorization: apikey <username>:<api_key>'

Sandbox Search

To search for submissions your organization has made to the ThreatStream sandbox.

Request

/api/v1/submit/search/

HTTP Method: GET

Attributes: See the table below

Request Attribute

Attribute	Type	Description
q	string	Value of the keyword you want to query. Specifying a value for this attribute queries the following fields: vendor platform status result notes (tags)

Attribute

Type

Description

string

Value of the keyword you want to query. Specifying a value for this attribute queries the following fields:

vendor
platform
status
result
notes (tags)

Example

To search for sandbox detonations using a keyword:

Copy

curl 'https://api.threatstream.com/api/v1/submit/search/?q=<keyword>' -H 'Authorization: apikey <username>:<api_key>'