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.

Release files for sandboxapi 1.7.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for sandboxapi 1.7.1
File	Size	Uploaded
sandboxapi-1.7.1.tar.gz	25.1 kB	Jan 6, 2023	Details

Built distribution (wheel)

Table of built distributions (wheels) for sandboxapi 1.7.1
File	Interpreter	ABI	Platform	Reset
sandboxapi-1.7.1-py3-none-any.whl 32.1 kB Jan 6, 2023	Python 3	none	any	Details

Total release size: 57.2 kB

Release files / sandboxapi-1.7.1.tar.gz

Download URL	sandboxapi-1.7.1.tar.gz
Size	25.1 kB
Tags	Source
SHA-256 checksum How to use checksums	`ed7c8cdb96d42296a04d434206731f576950dcd72886b6fae1980896632ab171`
BLAKE2b-256 checksum How to use checksums	`00c66c17e802fe00150fe2666ccc6c5f82ed9970e5ef05b49604af4f6df8dd76`
Upload date	Jan 6, 2023
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/4.0.2 CPython/3.10.6`

Release files / sandboxapi-1.7.1-py3-none-any.whl

Download URL	sandboxapi-1.7.1-py3-none-any.whl
Size	32.1 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`02f64028fc140715fac509267e2f4fbc7456c6061d75aec4d7e7172ae7d2291e`
BLAKE2b-256 checksum How to use checksums	`582aef67d50d53ac986de2a923764f79d2054ef693e2e085bc3fc10df6272295`
Upload date	Jan 6, 2023
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/4.0.2 CPython/3.10.6`