sandboxapi 1.1.0

A minimal, consistent API for building integrations with malware sandboxes

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

• VMRay Analyzer

• Falcon Sandbox (Formerly VxStream)

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.6+.

Usage

Basic usage is as follows:

import sys
import time
import pprint

from sandboxapi import cuckoo

# connect to the sandbox
sandbox = cuckoo.CuckooAPI('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, '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

Constructor signature:

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

Example:

CuckooAPI('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:

FireEyeAPI(username, password, url, profile)

Example:

FireEyeAPI('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:

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

Constructor signature:

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

Example:

VMRayAPI('mykey')

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

Falcon

Constructor signature:

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

Example:

FalconAPI('mykey', 'mysecret')

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

Notes

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