sandboxapi¶

A minimal, consistent API for building integrations with malware sandboxes.

This library currently supports the following sandbox systems:

It provides at least the following methods for each sandbox:

is_available(): Check if the sandbox is operable and reachable; returns a boolean
analyze(handle, filename): Submit a file for analysis; returns an item_id
check(item_id): Check if analysis has completed for a file; returns a boolean
report(item_id, report_format='json'): Retrieve the report for a submitted file
score(report): Parse out and return an integer score from the report object

Some sandbox classes may have additional methods implemented. See inline documentation for more details.

Note that the value returned from the score method may be on the range 0-10, or 0-100, depending on the sandbox in question, so you should refer to the specific sandbox’s documentation when interpreting this value.

Installation¶

Install through pip:

pip install sandboxapi

Supports Python 2.7+.

Usage¶

Basic usage is as follows:

import sys
import time
import pprint

from sandboxapi import cuckoo

# connect to the sandbox
sandbox = cuckoo.CuckooAPI('http://192.168.0.20:8090/')

# verify connectivity
if not sandbox.is_available():
    print("sandbox is down, exiting")
    sys.exit(1)

# submit a file
with open('myfile.exe', "rb") as handle:
    file_id = sandbox.analyze(handle, 'myfile.exe')
    print("file {f} submitted for analysis, id {i}".format(f=filename, i=file_id))

# wait for the analysis to complete
while not sandbox.check(file_id):
    print("not done yet, sleeping 10 seconds...")
    time.sleep(10)

# print the report
print("analysis complete. fetching report...")
report = sandbox.report(file_id)
pprint.pprint(report)
print("Score: {score}".format(score=sandbox.score(report)))

Since the library provides a consistent API, you can treat all sandoxes the same way:

import sys
import time
import pprint

from sandboxapi import cuckoo, fireeye, joe

# connect to the sandbox
sandboxes = [
    cuckoo.CuckooAPI('http://192.168.0.20:8090/'),
    fireeye.FireEyeAPI('myusername', 'mypassword', 'https://192.168.0.21', 'winxp-sp3'),
    joe.JoeAPI('mykey', 'https://jbxcloud.joesecurity.org/api', True)
]

for sandbox in sandboxes:
    # verify connectivity
    if not sandbox.is_available():
        print("sandbox is down, exiting")
        sys.exit(1)

    # submit a file
    with open('myfile.exe', "rb") as handle:
        file_id = sandbox.analyze(handle, 'myfile.exe')
        print("file {f} submitted for analysis, id {i}".format(f=filename, i=file_id))

    # wait for the analysis to complete
    while not sandbox.check(file_id):
        print("not done yet, sleeping 10 seconds...")
        time.sleep(10)

    # print the report
    print("analysis complete. fetching report...")
    report = sandbox.report(file_id)
    pprint.pprint(report)
    print("Score: {score}".format(score=sandbox.score(report)))

Cuckoo Sandbox¶

Constructor signature:

CuckooAPI(url, verify_ssl=False)

Example:

CuckooAPI('http://192.168.0.20:8090/')

This library attempts to support any Cuckoo-like API, including older 1.x installations (though those without a score won’t be able to use the .score method), compatible forks like spender-sandbox and CAPE, and the latest 2.x Cuckoo releases. If you find a version that doesn’t work, let us know.

There is an unofficial Cuckoo library written by @keithjjones with much more functionality. For more information on the Cuckoo API, see the Cuckoo API documentation.

FireEye AX¶

Constructor signature:

FireEyeAPI(username, password, url, profile, legacy_api=False, verify_ssl=True)

Example:

FireEyeAPI('myusername', 'mypassword', 'https://192.168.0.20', 'winxp-sp3')

By default, the FireEyeAPI class uses v1.2.0 of the FireEye API, which is available on v8.x FireEye AX series appliances. The v1.1.0 API, which is available on v7.x appliances, is also supported - just set legacy_api=True to use the older version.

There is some limited FireEye API documentation on their blog. For more information on FireEye’s sandbox systems, see the AX Series product page. FireEye customers have access to more API documentation.

Joe Sandbox¶

Constructor signature:

JoeAPI(apikey, apiurl, accept_tac, timeout=None, verify_ssl=True, retries=3)

Example:

JoeAPI('mykey', 'https://jbxcloud.joesecurity.org/api', True)

There is an official Joe Sandbox library with much more functionality. This library is installed as a dependency of sandboxapi, and wrapped by the sandboxapi.joe.JoeSandbox class.

VMRay Analyzer¶

Constructor signature:

VMRayAPI(api_key, url='https://cloud.vmray.com', verify_ssl=True)

Example:

VMRayAPI('mykey')

VMRay customers have access to a Python library with much more functionality. Check your VMRay documentation for more details.

Falcon Sandbox¶

Constructor signature:

FalconAPI(key, url='https://www.reverse.it/api/v2', env=100)

Example:

FalconAPI('mykey')

This class only supports version 2.0+ of the Falcon API, which is available in version 8.0.0+ of the Falcon Sandbox.

There is an official Falcon library with much more functionality, that supports the current and older versions of the Falcon API. Note that the official library only supports Python 3.4+.

WildFire Sandbox¶

Constructor signature:

WildFireAPI(api_key, url='https://wildfire.paloaltonetworks.com/publicapi')

Example:

WildFireAPI('mykey')

Currently, only the WildFire cloud sandbox is supported and not the WildFire appliance.

OPSWAT Sandbox¶

Constructor signature:

OpswatAPI(apikey, profile, verify_ssl=True)

Example:

OpswatAPI(apikey, 'windows7')

OPSWAT sandbox on MetaDefender Cloud. Please create an account on OPSWAT portal to receive a free MetaDefender Cloud apikey.

More details in the OPSWAT API documentation.

Hatching Triage¶

Constructor signature:

TriageAPI(api_key, url='https://api.tria.ge', api_path='/v0')

Example:

TriageAPI("ApiKeyHere")

You’re able to use this class with both the Triage public cloud and the private Triage instances. Look up the documentation for the right host and api path for your specific instance.

For more information on what is returned from the API you can look up the official Triage API documentation.

Notes¶

You may also be interested in malsub, a similar project with support for a number of online analysis services.

Module Documentation¶

API documentation for sandbox classes.

class sandboxapi.SandboxAPI(*args, **kwargs)¶

Bases: object

Sandbox API wrapper base class.

analyses()¶

Retrieve a list of analyzed samples.

Return type:	list
Returns:	List of objects referencing each analyzed file.

analyze(handle, filename)¶

Submit a file for analysis.

Parameters:	handle (File handle) – Handle to file to upload for analysis. filename (str) – File name.
Return type:	str
Returns:	Item ID as a string

check(item_id)¶

Check if an analysis is complete

Parameters:	item_id (int \| str) – item_id to check.
Return type:	bool
Returns:	Boolean indicating if a report is done or not.

delete(item_id)¶

Delete the reports associated with the given item_id.

Parameters:	item_id (int \| str) – Report ID to delete.
Return type:	bool
Returns:	True on success, False otherwise.

is_available()¶

Determine if the Sandbox API servers are alive or in maintenance mode.

Return type:	bool
Returns:	True if service is available, False otherwise.

queue_size()¶

Determine sandbox queue length

Return type:	int
Returns:	Number of submissions in sandbox queue.

report(item_id, report_format='json')¶

Retrieves the specified report for the analyzed item, referenced by item_id.

Parameters:	item_id (int \| str) – Item ID
Return type:	dict
Returns:	Dictionary representing the JSON parsed data or raw, for other formats / JSON parsing failure.

exception sandboxapi.SandboxError¶

Bases: exceptions.Exception

Custom exception class to be raised by known errors in SandboxAPI and its subclasses, and caught where this library is used.

Cuckoo Sandbox¶

class sandboxapi.cuckoo.CuckooAPI(url, port=8090, api_path='/', verify_ssl=False, **kwargs)¶

Bases: sandboxapi.SandboxAPI

Cuckoo Sandbox API wrapper.

analyses()¶

Retrieve a list of analyzed samples.

Return type:	list
Returns:	List of objects referencing each analyzed file.

analyze(handle, filename)¶

Submit a file for analysis.

Parameters:	handle (File handle) – Handle to file to upload for analysis. filename (str) – File name.
Return type:	str
Returns:	Task ID as a string

check(item_id)¶

Check if an analysis is complete

Parameters:	item_id (int) – task_id to check.
Return type:	bool
Returns:	Boolean indicating if a report is done or not.

delete(item_id)¶

Delete the reports associated with the given item_id.

Parameters:	item_id (int) – Report ID to delete.
Return type:	bool
Returns:	True on success, False otherwise.

is_available()¶

Determine if the Cuckoo Sandbox API servers are alive or in maintenance mode.

Return type:	bool
Returns:	True if service is available, False otherwise.

queue_size()¶

Determine Cuckoo sandbox queue length

There isn’t a built in way to do this like with Joe

Return type:	int
Returns:	Number of submissions in sandbox queue.

report(item_id, report_format='json')¶

Retrieves the specified report for the analyzed item, referenced by item_id.

Available formats include: json, html, all, dropped, package_files.

Parameters:	item_id (int) – Task ID number report_format (str) – Return format
Return type:	dict
Returns:	Dictionary representing the JSON parsed data or raw, for other formats / JSON parsing failure.

score(report)¶: Pass in the report from self.report(), get back an int.

Falcon Sandbox¶

class sandboxapi.falcon.FalconAPI(key, url=None, env=100, **kwargs)¶

Bases: sandboxapi.SandboxAPI

Falcon Sandbox API wrapper.

analyze(handle, filename)¶

Submit a file for analysis.

Parameters:	handle (File handle) – Handle to file to upload for analysis. filename (str) – File name.
Return type:	str
Returns:	File hash as a string

check(item_id)¶

Check if an analysis is complete.

Parameters:	item_id (str) – Job ID to check.
Return type:	bool
Returns:	Boolean indicating if a report is done or not.

full_report(item_id, report_format='json')¶: Retrieves a more detailed report

is_available()¶

Determine if the Falcon API server is alive.

Return type:	bool
Returns:	True if service is available, False otherwise.

queue_size()¶

Determine Falcon sandbox queue length

Return type:	str
Returns:	Details on the queue size.

report(item_id, report_format='json')¶

Retrieves the specified report for the analyzed item, referenced by item_id.

Available formats include: json, html.

Parameters:	item_id (str) – File ID number report_format (str) – Return format
Return type:	dict
Returns:	Dictionary representing the JSON parsed data or raw, for other formats / JSON parsing failure.

score(report)¶: Pass in the report from self.report(), get back an int 0-10.

FireEye AX¶

class sandboxapi.fireeye.FireEyeAPI(username, password, url, profile, legacy_api=False, verify_ssl=True, **kwargs)¶

Bases: sandboxapi.SandboxAPI

FireEye Sandbox API wrapper.

analyze(handle, filename)¶

Submit a file for analysis.

Parameters:	handle (File handle) – Handle to file to upload for analysis. filename (str) – File name.
Return type:	str
Returns:	File ID as a string

check(item_id)¶

Check if an analysis is complete.

Parameters:	item_id (str) – File ID to check.
Return type:	bool
Returns:	Boolean indicating if a report is done or not.

is_available()¶

Determine if the FireEye API server is alive.

Return type:	bool
Returns:	True if service is available, False otherwise.

logout()¶: The FireEye AX has a limit of 100 concurrent sessions, so be sure to logout

report(item_id, report_format='json')¶

Retrieves the specified report for the analyzed item, referenced by item_id.

Available formats include: json.

Parameters:	item_id (str) – File ID number report_format (str) – Return format
Return type:	dict
Returns:	Dictionary representing the JSON parsed data or raw, for other formats / JSON parsing failure.

score(report)¶: Pass in the report from self.report(), get back an int.

sandboxapi.fireeye.fireeye_loop(fireeye, filename)¶

Joe Sandbox¶

class sandboxapi.joe.JoeAPI(apikey, apiurl, accept_tac, timeout=None, verify_ssl=True, retries=3, chunked=False, **kwargs)¶

Bases: sandboxapi.SandboxAPI

Joe Sandbox API wrapper.

This class is actually just a convenience wrapper around jbxapi.JoeSandbox.

analyze(handle, filename)¶

Submit a file for analysis.

Parameters:	handle (File handle) – Handle to file to upload for analysis. filename (str) – File name.
Return type:	str
Returns:	Task ID as a string

check(item_id)¶

Check if an analysis is complete.

Parameters:	item_id (str) – File ID to check.
Return type:	bool
Returns:	Boolean indicating if a report is done or not.

is_available()¶

Determine if the Joe Sandbox API server is alive.

Return type:	bool
Returns:	True if service is available, False otherwise.

report(item_id, report_format='json')¶

Retrieves the specified report for the analyzed item, referenced by item_id.

For available report formats, see online Joe Sandbox documentation.

Parameters:	item_id (str) – File ID number report_format (str) – Return format
Return type:	dict
Returns:	Dictionary representing the JSON parsed data or raw, for other formats / JSON parsing failure.

score(report)¶: Pass in the report from self.report(), get back an int.

VMRay Analyzer¶

class sandboxapi.vmray.VMRayAPI(api_key, url=None, verify_ssl=True, **kwargs)¶

Bases: sandboxapi.SandboxAPI

VMRay Sandbox API wrapper.

analyze(handle, filename)¶

Submit a file for analysis.

Parameters:	handle (File handle) – Handle to file to upload for analysis. filename (str) – File name.
Return type:	str
Returns:	File ID as a string

check(item_id)¶

Check if an analysis is complete.

Parameters:	item_id (str) – File ID to check.
Return type:	bool
Returns:	Boolean indicating if a report is done or not.

is_available()¶

Determine if the VMRay API server is alive.

Return type:	bool
Returns:	True if service is available, False otherwise.

report(item_id, report_format='json')¶

Retrieves the specified report for the analyzed item, referenced by item_id.

Available formats include: json.

Parameters:	item_id (str) – File ID number report_format (str) – Return format
Return type:	dict
Returns:	Dictionary representing the JSON parsed data or raw, for other formats / JSON parsing failure.

score(report)¶: Pass in the report from self.report(), get back an int 0-100

sandboxapi.vmray.vmray_loop(vmray, filename)¶

WildFire Sandbox¶

class sandboxapi.wildfire.WildFireAPI(api_key='', url='', verify_ssl=True, **kwargs)¶

Bases: sandboxapi.SandboxAPI

WildFire Sandbox API wrapper.

analyze(handle, filename)¶

Submit a file for analysis.

Parameters:	handle (BytesIO) – File handle filename (str) – File name
Return type:	str
Returns:	File ID as a string

check(item_id)¶

Check if an analysis is complete.

Parameters:	item_id (str) – The hash of the file to check.
Return type:	bool
Returns:	True if the report is ready, otherwise False.

decode(response)¶

Convert a xml response to a python dictionary.

Parameters:	response (requests.Response) – A Response object with xml content.
Return type:	dict
Returns:	The xml content converted to a dictionary.

is_available()¶

Checks to see if the WildFire sandbox is up and running.

Return type:	bool
Returns:	True if the WildFire sandbox is responding, otherwise False.

WildFire doesn’t have an explicit endpoint for checking the sandbox status, so this is kind of a hack.

report(item_id, report_format='json')¶

Retrieves the specified report for the analyzed item, referenced by item_id.

Parameters:	item_id (str) – The hash of the file. report_format (str) – Return format.
Return type:	dic
Returns:	Dictionary representing the JSON parsed data.

score()¶

Get the threat score for the submitted sample.

Return type:	int
Returns:	The assigned threat score.

sandboxapi

Table of Contents

Related Topics

Other Projects

Useful Links

Stay Informed

sandboxapi¶

Installation¶

Usage¶

Cuckoo Sandbox¶

FireEye AX¶

Joe Sandbox¶

VMRay Analyzer¶

Falcon Sandbox¶

WildFire Sandbox¶

OPSWAT Sandbox¶

Hatching Triage¶

Notes¶

Module Documentation¶

Cuckoo Sandbox¶

Falcon Sandbox¶

FireEye AX¶

Joe Sandbox¶

VMRay Analyzer¶

WildFire Sandbox¶

Indices and tables¶