Repository files navigation

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

This library currently supports the following sandbox systems:

• Cuckoo Sandbox
• Falcon Sandbox (Formerly VxStream)
• FireEye AX Series
• Hatching Triage
• Joe Sandbox
• MetaDefender Sandbox
• VMRay Analyzer
• WildFire 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 anitem_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 inlinedocumentation for more details.

Note that the value returned from thescore method may be on the range0-10, or 0-100, depending on the sandbox in question, so you should refer tothe specific sandbox's documentation when interpreting this value.

Install through pip:

pip install sandboxapi

Supports Python 2.7+.

Basic usage is as follows:

importsysimporttimeimportpprintfromsandboxapiimportcuckoo# connect to the sandboxsandbox=cuckoo.CuckooAPI('http://192.168.0.20:8090/')# verify connectivityifnotsandbox.is_available():print("sandbox is down, exiting")sys.exit(1)# submit a filewithopen('myfile.exe',"rb")ashandle: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 completewhilenotsandbox.check(file_id):print("not done yet, sleeping 10 seconds...")time.sleep(10)# print the reportprint("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 sandoxesthe same way:

importsysimporttimeimportpprintfromsandboxapiimportcuckoo,fireeye,joe# connect to the sandboxsandboxes= [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)]forsandboxinsandboxes:# verify connectivityifnotsandbox.is_available():print("sandbox is down, exiting")sys.exit(1)# submit a filewithopen('myfile.exe',"rb")ashandle: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 completewhilenotsandbox.check(file_id):print("not done yet, sleeping 10 seconds...")time.sleep(10)# print the reportprint("analysis complete. fetching report...")report=sandbox.report(file_id)pprint.pprint(report)print("Score: {score}".format(score=sandbox.score(report)))

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.xinstallations (though those without a score won't be able to use the.scoremethod), compatible forks like spender-sandbox and CAPE, and the latest 2.xCuckoo releases. If you find a version that doesn't work, let us know.

There is anunofficial Cuckoo library written by @keithjjones with muchmore functionality. For more information on the Cuckoo API, see theCuckoo APIdocumentation.

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, theFireEyeAPI class uses v1.2.0 of the FireEye API, which isavailable on v8.x FireEye AX series appliances. The v1.1.0 API, which isavailable on v7.x appliances, is also supported - just setlegacy_api=Trueto use the older version.

There is some limitedFireEye API documentation on their blog. For moreinformation on FireEye's sandbox systems, see theAX Series product page.FireEye customers have access to more API documentation.

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 anofficial Joe Sandbox library with much more functionality.This library is installed as a dependency of sandboxapi, and wrapped by thesandboxapi.joe.JoeSandbox class.

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.

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 availablein version 8.0.0+ of the Falcon Sandbox.

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

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.

Constructor signature:

MetaDefenderSandboxAPI(api_key, url=None, verify_ssl=True)

Example:

MetaDefenderSandboxAPI('mykey')

MetaDefender Sandbox (previously known as OPSWAT Filescan Sandbox). You can use the Activation Key that you receivedfrom your OPSWAT Sales Representative, and follow the instructions on theOPSWAT Licence Activation page or you can create an API key on theMetaDefender Sandbox Community Site under API Key tab.

More details in theMetaDefender Sandbox API documentation.

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 theTriage public cloud and theprivate Triage instances. Look up the documentation for the right host andapi path for your specific instance.

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

You may also be interested inmalsub, a similar project with support for anumber of online analysis services.