{"id":13530012,"url":"https://github.com/InQuest/sandboxapi","last_synced_at":"2025-04-01T17:31:41.662Z","repository":{"id":56474411,"uuid":"117734039","full_name":"InQuest/sandboxapi","owner":"InQuest","description":"Minimal, consistent Python API for building integrations with malware sandboxes.","archived":false,"fork":false,"pushed_at":"2024-01-31T18:25:07.000Z","size":743,"stargazers_count":131,"open_issues_count":0,"forks_count":39,"subscribers_count":21,"default_branch":"master","last_synced_at":"2024-05-07T18:00:05.957Z","etag":null,"topics":["api-client","automated-analysis","library","malware-analysis","python","sandbox"],"latest_commit_sha":null,"homepage":"https://inquest.readthedocs.io/projects/sandboxapi/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/InQuest.png","metadata":{"files":{"readme":"README.rst","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-01-16T19:54:33.000Z","updated_at":"2024-06-21T17:53:43.456Z","dependencies_parsed_at":"2023-02-06T10:01:00.037Z","dependency_job_id":"a486a3a8-dd1f-49fa-bada-d09149a15e33","html_url":"https://github.com/InQuest/sandboxapi","commit_stats":null,"previous_names":["inquest/python-sandboxapi"],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/InQuest%2Fsandboxapi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/InQuest%2Fsandboxapi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/InQuest%2Fsandboxapi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/InQuest%2Fsandboxapi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/InQuest","download_url":"https://codeload.github.com/InQuest/sandboxapi/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246680328,"owners_count":20816677,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api-client","automated-analysis","library","malware-analysis","python","sandbox"],"created_at":"2024-08-01T07:00:42.134Z","updated_at":"2025-04-01T17:31:40.944Z","avatar_url":"https://github.com/InQuest.png","language":"Python","funding_links":[],"categories":["Automation and Convention"],"sub_categories":["Code libraries and bindings"],"readme":"sandboxapi\n==========\n\n.. image:: https://inquest.net/images/inquest-badge.svg\n    :target: https://inquest.net/\n    :alt: Developed by InQuest\n.. image:: https://github.com/InQuest/sandboxapi/workflows/sandboxapi/badge.svg?branch=master\n    :target: https://github.com/InQuest/sandboxapi/actions\n    :alt: Build Status (GitHub Workflow)\n.. image:: https://readthedocs.org/projects/sandboxapi/badge/?version=latest\n    :target: https://inquest.readthedocs.io/projects/sandboxapi/en/latest/?badge=latest\n    :alt: Documentation Status\n.. image:: http://img.shields.io/pypi/v/sandboxapi.svg\n    :target: https://pypi.python.org/pypi/sandboxapi\n    :alt: PyPi Version\n\nA minimal, consistent API for building integrations with malware sandboxes.\n\nThis library currently supports the following sandbox systems:\n\n* `Cuckoo Sandbox`_\n* `Falcon Sandbox`_ (Formerly VxStream)\n* `FireEye AX Series`_\n* `Hatching Triage`_\n* `Joe Sandbox`_\n* `MetaDefender Sandbox`_\n* `VMRay Analyzer`_\n* `WildFire Sandbox`_\n\nIt provides at least the following methods for each sandbox:\n\n* ``is_available()``: Check if the sandbox is operable and reachable; returns a boolean\n* ``analyze(handle, filename)``: Submit a file for analysis; returns an ``item_id``\n* ``check(item_id)``: Check if analysis has completed for a file; returns a boolean\n* ``report(item_id, report_format='json')``: Retrieve the report for a submitted file\n* ``score(report)``: Parse out and return an integer score from the report object\n\nSome sandbox classes may have additional methods implemented. See inline\ndocumentation for more details.\n\nNote that the value returned from the ``score`` method may be on the range\n0-10, or 0-100, depending on the sandbox in question, so you should refer to\nthe specific sandbox's documentation when interpreting this value.\n\nInstallation\n------------\n\nInstall through pip::\n\n    pip install sandboxapi\n\nSupports Python 2.7+.\n\nUsage\n-----\n\nBasic usage is as follows:\n\n.. code-block:: python\n\n    import sys\n    import time\n    import pprint\n\n    from sandboxapi import cuckoo\n\n    # connect to the sandbox\n    sandbox = cuckoo.CuckooAPI('http://192.168.0.20:8090/')\n\n    # verify connectivity\n    if not sandbox.is_available():\n        print(\"sandbox is down, exiting\")\n        sys.exit(1)\n\n    # submit a file\n    with open('myfile.exe', \"rb\") as handle:\n        file_id = sandbox.analyze(handle, 'myfile.exe')\n        print(\"file {f} submitted for analysis, id {i}\".format(f=filename, i=file_id))\n\n    # wait for the analysis to complete\n    while not sandbox.check(file_id):\n        print(\"not done yet, sleeping 10 seconds...\")\n        time.sleep(10)\n\n    # print the report\n    print(\"analysis complete. fetching report...\")\n    report = sandbox.report(file_id)\n    pprint.pprint(report)\n    print(\"Score: {score}\".format(score=sandbox.score(report)))\n\nSince the library provides a consistent API, you can treat all sandoxes\nthe same way:\n\n.. code-block:: python\n\n    import sys\n    import time\n    import pprint\n\n    from sandboxapi import cuckoo, fireeye, joe\n\n    # connect to the sandbox\n    sandboxes = [\n        cuckoo.CuckooAPI('http://192.168.0.20:8090/'),\n        fireeye.FireEyeAPI('myusername', 'mypassword', 'https://192.168.0.21', 'winxp-sp3'),\n        joe.JoeAPI('mykey', 'https://jbxcloud.joesecurity.org/api', True)\n    ]\n\n    for sandbox in sandboxes:\n        # verify connectivity\n        if not sandbox.is_available():\n            print(\"sandbox is down, exiting\")\n            sys.exit(1)\n\n        # submit a file\n        with open('myfile.exe', \"rb\") as handle:\n            file_id = sandbox.analyze(handle, 'myfile.exe')\n            print(\"file {f} submitted for analysis, id {i}\".format(f=filename, i=file_id))\n\n        # wait for the analysis to complete\n        while not sandbox.check(file_id):\n            print(\"not done yet, sleeping 10 seconds...\")\n            time.sleep(10)\n\n        # print the report\n        print(\"analysis complete. fetching report...\")\n        report = sandbox.report(file_id)\n        pprint.pprint(report)\n        print(\"Score: {score}\".format(score=sandbox.score(report)))\n\nCuckoo Sandbox\n~~~~~~~~~~~~~~\n\nConstructor signature::\n\n    CuckooAPI(url, verify_ssl=False)\n\nExample::\n\n    CuckooAPI('http://192.168.0.20:8090/')\n\nThis library attempts to support any Cuckoo-like API, including older 1.x\ninstallations (though those without a score won't be able to use the ``.score``\nmethod), compatible forks like spender-sandbox and CAPE, and the latest 2.x\nCuckoo releases. If you find a version that doesn't work, let us know.\n\nThere is an `unofficial Cuckoo library`_ written by @keithjjones with much\nmore functionality. For more information on the Cuckoo API, see the `Cuckoo API\ndocumentation`_.\n\nFireEye AX\n~~~~~~~~~~\n\nConstructor signature::\n\n    FireEyeAPI(username, password, url, profile, legacy_api=False, verify_ssl=True)\n\nExample::\n\n    FireEyeAPI('myusername', 'mypassword', 'https://192.168.0.20', 'winxp-sp3')\n\nBy default, the ``FireEyeAPI`` class uses v1.2.0 of the FireEye API, which is\navailable on v8.x FireEye AX series appliances. The v1.1.0 API, which is\navailable on v7.x appliances, is also supported - just set ``legacy_api=True``\nto use the older version.\n\nThere is some limited `FireEye API documentation`_ on their blog. For more\ninformation on FireEye's sandbox systems, see the `AX Series product page`_.\nFireEye customers have access to more API documentation.\n\nJoe Sandbox\n~~~~~~~~~~~\n\nConstructor signature::\n\n    JoeAPI(apikey, apiurl, accept_tac, timeout=None, verify_ssl=True, retries=3)\n\nExample::\n\n    JoeAPI('mykey', 'https://jbxcloud.joesecurity.org/api', True)\n\nThere is an `official Joe Sandbox library`_ with much more functionality.\nThis library is installed as a dependency of sandboxapi, and wrapped by the\n``sandboxapi.joe.JoeSandbox`` class.\n\nVMRay Analyzer\n~~~~~~~~~~~~~~\n\nConstructor signature::\n\n    VMRayAPI(api_key, url='https://cloud.vmray.com', verify_ssl=True)\n\nExample::\n\n    VMRayAPI('mykey')\n\nVMRay customers have access to a Python library with much more functionality.\nCheck your VMRay documentation for more details.\n\nFalcon Sandbox\n~~~~~~~~~~~~~~\n\nConstructor signature::\n\n    FalconAPI(key, url='https://www.reverse.it/api/v2', env=100)\n\nExample::\n\n    FalconAPI('mykey')\n\nThis class only supports version 2.0+ of the Falcon API, which is available\nin version 8.0.0+ of the Falcon Sandbox.\n\nThere is an `official Falcon library`_ with much more functionality, that\nsupports the current and older versions of the Falcon API. Note that the\nofficial library only supports Python 3.4+.\n\n\nWildFire Sandbox\n~~~~~~~~~~~~~~~~\n\nConstructor signature::\n\n    WildFireAPI(api_key, url='https://wildfire.paloaltonetworks.com/publicapi')\n\nExample::\n\n    WildFireAPI('mykey')\n\nCurrently, only the WildFire cloud sandbox is supported and not the WildFire appliance.\n\n\nMetaDefender Sandbox\n~~~~~~~~~~~~~~~~~~~~\n\nConstructor signature::\n\n    MetaDefenderSandboxAPI(api_key, url=None, verify_ssl=True)\n\nExample::\n\n    MetaDefenderSandboxAPI('mykey')\n\nMetaDefender Sandbox (previously known as OPSWAT Filescan Sandbox). You can use the Activation Key that you received \nfrom your OPSWAT Sales Representative, and follow the instructions on the \n`OPSWAT Licence Activation`_ page or you can create an API key on the \n`MetaDefender Sandbox Community Site`_ under API Key tab.\n\nMore details in the `MetaDefender Sandbox API documentation`_.\n\n\nHatching Triage\n~~~~~~~~~~~~~~~~\n\nConstructor signature::\n\n    TriageAPI(api_key, url='https://api.tria.ge', api_path='/v0')\n\nExample::\n\n    TriageAPI(\"ApiKeyHere\")\n\nYou're able to use this class with both the `Triage public cloud`_ and the\nprivate Triage instances. Look up the documentation for the right host and\napi path for your specific instance.\n\nFor more information on what is returned from the API you can look up the\nofficial `Triage API documentation`_.\n\n\nNotes\n-----\n\nYou may also be interested in `malsub`_, a similar project with support for a\nnumber of online analysis services.\n\n\n.. _Cuckoo Sandbox: https://www.cuckoosandbox.org/\n.. _Fireeye AX Series: https://www.fireeye.com/products/malware-analysis.html\n.. _Joe Sandbox: https://www.joesecurity.org/\n.. _MetaDefender Sandbox: https://docs.opswat.com/filescan\n.. _VMRay Analyzer: https://www.vmray.com/\n.. _Falcon Sandbox: https://www.falcon-sandbox.com/\n.. _WildFire Sandbox: https://www.paloaltonetworks.com/products/secure-the-network/wildfire\n.. _Hatching Triage: https://tria.ge/\n.. _unofficial Cuckoo library: https://github.com/keithjjones/cuckoo-api\n.. _Cuckoo API documentation: https://cuckoo.sh/docs/usage/api.html\n.. _FireEye API documentation: https://www.fireeye.com/blog/products-and-services/2015/12/restful_apis_thatdo.html\n.. _AX Series product page: https://www.fireeye.com/products/malware-analysis.html\n.. _official Joe Sandbox library: https://github.com/joesecurity/joesandboxcloudapi\n.. _official Falcon library: https://github.com/PayloadSecurity/VxAPI\n.. _OPSWAT Licence Activation: https://docs.opswat.com/filescan/installation/license-activation\n.. _MetaDefender Sandbox Community Site: https://www.filescan.io/users/profile?active=apikeyinfo\n.. _MetaDefender Sandbox API documentation: https://docs.opswat.com/filescan/metadefender-sandbox-api-reference-v1\n.. _malsub: https://github.com/diogo-fernan/malsub\n.. _Triage public cloud: https://tria.ge/\n.. _Triage API documentation: https://tria.ge/docs/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FInQuest%2Fsandboxapi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FInQuest%2Fsandboxapi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FInQuest%2Fsandboxapi/lists"}