{"id":420,"date":"2016-05-04T07:22:53","date_gmt":"2016-05-04T07:22:53","guid":{"rendered":"http:\/\/www.adlice.com\/?p=420"},"modified":"2022-12-21T10:37:03","modified_gmt":"2022-12-21T10:37:03","slug":"cuckoo-sandbox-customization","status":"publish","type":"post","link":"https:\/\/www.adlice.com\/es\/cuckoo-sandbox-customization\/","title":{"rendered":"Cuckoo Sandbox Customization"},"content":{"rendered":"\n

Cuckoo Sandbox is a neat open source project <\/strong>used by many people around the world to test malware into a secure environment<\/strong>, to understand how they work and what they do. Cuckoo is written in a modular way<\/strong>, with python language. It’s really easy to customize, and this is what I’m going to show you here.<\/p>\n\n\n\n


Cuckoo Sandbox<\/h2>\n\n\n\n

You can download and install Cuckoo Sandbox here<\/strong><\/a>, and here’s a tutorial on how to configure it<\/strong><\/a>. We will not cover the installation of cuckoo itself because the guide is really well done.<\/p>\n\n\n\n


Customization, the idea<\/h2>\n\n\n\n

Let’s study a real example<\/strong> that we’ve done for our own purpose, here at Adlice Labs. We wanted an easy way to test for malware removal<\/strong> with our software, RogueKiller<\/strong><\/a>. The idea is to get a removal report for malware that we send to the sandbox, let’s take a look.<\/p>\n\n\n\n

The Cuckoo team made a guide for customization as well<\/strong><\/a>, this will be our reference.
In our templates below, for consistency all our file modules will be named “custom.py”. Just adapt to your case.<\/strong><\/p>\n\n\n\n


Auxiliary (guest) module<\/h2>\n\n\n\n

The auxiliary guest modules are located into \/analyzer\/windows\/modules\/auxiliary.<\/strong>
They are executed before the malware, on the guest machine<\/strong>. Therefore they can be useful to log some initial state machine information.<\/p>\n\n\n\n

import logging\nimport json\n\nfrom lib.common.abstracts import Auxiliary\nfrom lib.common.results import NetlogFile\n\nlog = logging.getLogger(__name__)\n\nclass Custom(Auxiliary):\n    \"\"\"Gather custom data\"\"\"\n\n    def __init__(self, options={}, analyzer=None):\n        Auxiliary.__init__(self, options, analyzer)\n\n    def start(self):\n        log.info(\"Starting my Custom auxiliary module\")\n        nf = NetlogFile(\"logs\/initial.json\")\n        nf.send(json.dumps(['foo', {'bar': ('baz', None, 1.0, 2, False)}]))<\/code><\/pre>\n\n\n\n

As a result, a initial.json file is created into \/logs.<\/p>\n\n\n\n

Package module<\/h2>\n\n\n\n
The package modules are located into \/analyzer\/windows\/modules\/packages.<\/strong>
They are responsible for executing and injecting the malware<\/strong> for analysis, they are executed on the guest<\/strong>.
You can define different execution routines, depending on the type<\/strong> of malware (exe, swf, pdf, …)
I have implemented the finish method to make some post execution actions, we will see later for a concrete example of this.<\/p>\n\n\n\n
import os\nimport shlex\nimport json\nimport logging\n\nfrom lib.common.abstracts import Package\nfrom lib.common.results import NetlogFile\n\nlog = logging.getLogger(\"analyzer\")\n\nclass CustomExe(Package):\n    \"\"\"Custom analysis package.\"\"\"\n\n    def start(self, path):\n        args = self.options.get(\"arguments\", \"\")\n\n        name, ext = os.path.splitext(path)\n        if not ext:\n            new_path = name + \".exe\"\n            os.rename(path, new_path)\n            path = new_path\n\n        return self.execute(path, args=shlex.split(args))\n\n    # Post execution\n    def finish(self):\n        nf = NetlogFile(\"logs\/post.json\")\n        nf.send(json.dumps(['foo', {'bar': ('baz', None, 1.0, 2, False)}]))\n        return True\n<\/code><\/pre>\n\n\n\n

As a result, a post.json file is created into \/logs.<\/p>\n\n\n\n

Processing module<\/h2>\n\n\n\n
The processing modules are located into \/modules\/processing.<\/strong>
They are executed on the host<\/strong>, to append data generated by the modules above into the global container<\/strong><\/a>. That way, the data will be available by all the next modules for processing and reporting.<\/p>\n\n\n\n
To enable a new processing module, you need to add that section into \/conf\/processing.conf<\/strong>.<\/p>\n\n\n\n
[custom]\nenabled = yes<\/code><\/pre>\n\n\n\n
import os\nimport json\n\nfrom lib.cuckoo.common.abstracts import Processing\nfrom lib.cuckoo.common.exceptions import CuckooProcessingError\n\nclass Custom(Processing):\n    \"\"\"Analysis custom information.\"\"\"\n\n    def run(self):\n        \"\"\"Run debug analysis.\n        @return: debug information dict.\n        \"\"\"\n        self.key = \"custom\"\n        data = {}\n        try:\n          #initial\n          custom_log = os.path.join(self.logs_path, \"initial.json\")\n          with open(custom_log) as json_file:          \n            data[\"initial\"] = json.load(json_file)\n        except Exception, e:\n          raise CuckooProcessingError(str(e))\n\n        try:\n          #post\n          custom_log = os.path.join(self.logs_path, \"post.json\")\n          with open(custom_log) as json_file:          \n            data[\"post\"] = json.load(json_file)\n        except Exception, e:\n          raise CuckooProcessingError(str(e))\n\n        return data<\/code><\/pre>\n\n\n\n

As a result, data from initial.json and post.json are appended into the global container. If the Json reporting module (builtin) is enabled, you will retrieve their content into it, under the “custom” key.<\/p>\n\n\n\n

Reporting module<\/h2>\n\n\n\n
The reporting modules are located into \/modules\/reporting.<\/strong>
They are executed on the host<\/strong>, to translate data from the global container<\/strong><\/a> into a different format. It could be a HTML page, json file, even a PDF<\/strong> or something else.<\/p>\n\n\n\n
To enable a new reporting module, you need to add that section into \/conf\/reporting.conf<\/strong>.<\/p>\n\n\n\n
[custom]\nenabled = yes\n\ufeff<\/code><\/pre>\n\n\n\n
import os\nimport json\nimport codecs\n\nfrom lib.cuckoo.common.abstracts import Report\nfrom lib.cuckoo.common.exceptions import CuckooReportError\n\nclass Custom(Report):\n    \"\"\"Saves custom results in JSON format.\"\"\"   \n    def run(self, results):\n        \"\"\"Writes report.\n        @param results: Cuckoo results dict.\n        @raise CuckooReportError: if fails to write report.\n        \"\"\"\n\n        try:\n            path = os.path.join(self.reports_path, \"custom.json\")\n\n            with codecs.open(path, \"w\", \"utf-8\") as report:\n                json.dump(results[\"custom\"], report, sort_keys=False, indent=4)\n        except (UnicodeError, TypeError, IOError) as e:\n            raise CuckooReportError(\"Failed to generate JSON report: %s\" % e)\n\n\ufeff<\/code><\/pre>\n\n\n\n

As a result, data from initial.json and post.json that was stored in the global container is returning back to a single “custom.json” file. But we could have easily done a HTML, a PDF or something else.<\/p>\n\n\n\n

Concrete use case: Removal report<\/h2>\n\n\n\n
The idea is to get a removal report <\/strong>for a malware with a given anti-malware scanner, RogueKiller<\/strong><\/a>.
To do so, we will use a new package module, for which we will write a finish routine that runs and inject our antimalware<\/strong>:<\/p>\n\n\n\n
import os\nimport shlex\nimport json\nimport logging\nimport urllib2\nimport tempfile\n\nfrom lib.common.abstracts import Package\nfrom lib.common.results import upload_to_host\nfrom lib.api.process import Process\nfrom lib.common.defines import KERNEL32\n\nlog = logging.getLogger(\"analyzer\")\n\nclass ExeWithRemoval(Package):\n    \"\"\"Custom analysis package.\"\"\"\n\n    def start(self, path):\n        args = self.options.get(\"arguments\", \"\")\n\n        name, ext = os.path.splitext(path)\n        if not ext:\n            new_path = name + \".exe\"\n            os.rename(path, new_path)\n            path = new_path\n\n        return self.execute(path, args=shlex.split(args))\n\n    # Post execution\n    def finish(self):\n        try: \n          #download\n          response = urllib2.urlopen(\"http:\/\/link_to_roguekillercmd.exe\")\n          f = tempfile.NamedTemporaryFile(delete=False)           \n          data = response.read()   \n          f.write(data)\n           \n          #rename\n          path = f.name + \".exe\"          \n          f.close()\n          os.rename(f.name, path)\n          log.info(\"Downloaded remover program to %s\", path)\n\n          #execute\n          args = \"-scan -dont_ask -params \\\"-autoremove\\\"\"\n          pid  = self.execute(path, args=shlex.split(args))\n          log.info(\"Executing remover program with args: %s\", args)\n\n          #wait for end\n          while Process(pid=pid).is_alive():\n              KERNEL32.Sleep(1000)\t\t\t  \n\t\t  \n          #upload report\n          upload_to_host(\"C:\/path_to_my_report.json\", \"logs\/removal.json\")\n\n          log.info(\"Executed remover program with args: %s\", args)\n        except Exception, e:\n          log.exception(\"Error while loading the remover program\")\n\n        return True\n<\/code><\/pre>\n\n\n\n

After the analysis is done, finish() is called. In this method we download in a temporary file our anti-malware<\/strong> (in CLI version), then we run it under cuckoo injection<\/strong>.
Once the report is generated we upload it back to the host to attach it to our analysis. Then the cuckoo report is generated and we can compare what the malware did, and what the anti-malware was able to catch and remove<\/strong>. Simple as that!<\/p>\n\n\n\n
In our example below, the malware was a fake putty binary, notice the RogueKillerCMD scanner<\/strong><\/a> running.<\/p>\n\n\n\n
\"cuckoo1\"<\/a><\/figure>\n\n\n\n
\"cuckoo2\"<\/a><\/figure>\n\n\n\n
\"cuckoo3\"<\/a><\/figure>\n\n\n\n

Links<\/h2>\n\n\n\n