sandboxapi

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

This library currently supports the following sandbox systems:

• Cuckoo Sandbox
• FireEye AX Series
• Joe Sandbox
• VxStream Sandbox

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 a file_id
• check(file_id): Check if analysis has completed for a file; returns a boolean
• report(file_id, report_format='json'): Retrieve the report for a submitted file

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

Installation

Install through pip:

pip install sandboxapi

Supports Python 2.6+.

Usage

Basic usage is as follows:

import sys
import time
import pprint

import sandboxapi

# connect to the sandbox
sandbox = sandboxapi.cuckoo.CuckooSandbox('192.168.0.20')

# 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, filename)
    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...")
pprint.pprint(sandbox.report(file_id))

Cuckoo

Constructor signature:

CuckooSandbox(host, port=8090, api_path='/', verify_ssl=False)

Example:

CuckooSandbox('192.168.0.20')

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

Constructor signature:

FireEyeSandbox(username, password, url, profile)

Example:

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

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

Joe

Constructor signature:

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

Example:

JoeSandbox('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.

VxStream

Constructor signature:

VxStreamSandbox(key, secret, url='https://www.reverse.it', env=100)

Example:

VxStreamSandbox('mykey', 'mysecret')

There is an official VxStream library with much more functionality, that only supports Python 3.4+.