Package: sandboxapi
A minimal, consistent API for building integrations with malware sandboxes.This library currently supports the following sandbox systems:Cuckoo SandboxFalcon Sandbox(Formerly VxStream)FireEye AX SeriesHatching TriageJoe SandboxOPSWAT SandboxVMRay AnalyzerWildFire SandboxIt provides at least the following methods for each sandbox:is_available(): Check if the sandbox is operable and reachable; returns a booleananalyze(handle, filename): Submit a file for analysis; returns anitem_idcheck(item_id): Check if analysis has completed for a file; returns a booleanreport(item_id,report_format='json'): Retrieve the report for a submitted filescore(report): Parse out and return an integer score from the report objectSome sandbox classes may have additional methods implemented. See inline
documentation for more details.Note that the value returned from thescoremethod 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.InstallationInstall through pip:pip install sandboxapiSupports Python 2.7+.UsageBasic 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 sandoxes
the 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)))Cuckoo SandboxConstructor 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.scoremethod), 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 anunofficial Cuckoo librarywritten by @keithjjones with much
more functionality. For more information on the Cuckoo API, see theCuckoo API
documentation.FireEye AXConstructor 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, theFireEyeAPIclass 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 setlegacy_api=Trueto use the older version.There is some limitedFireEye API documentationon their blog. For more
information on FireEye’s sandbox systems, see theAX Series product page.
FireEye customers have access to more API documentation.Joe SandboxConstructor 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 librarywith much more functionality.
This library is installed as a dependency of sandboxapi, and wrapped by thesandboxapi.joe.JoeSandboxclass.VMRay AnalyzerConstructor 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 SandboxConstructor 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 anofficial Falcon librarywith 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 SandboxConstructor 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 SandboxConstructor signature:OpswatAPI(apikey, profile, verify_ssl=True)Example:OpswatAPI(apikey, 'windows7')OPSWAT sandbox on MetaDefender Cloud. Please create an account onOPSWAT portalto receive a free MetaDefender Cloud apikey.More details in theOPSWAT API documentation.Hatching TriageConstructor 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 cloudand 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
officialTriage API documentation.NotesYou may also be interested inmalsub, a similar project with support for a
number of online analysis services.