Cuckoo Sandbox Book¶

Using a Sandbox¶

Before starting installing, configuring and using Cuckoo you should take some time to think on what you want to achieve with it and how.

Some questions you should ask yourself:

• What kind of files do I want to analyze?
• Which volumes of analysis do I want to be able to handle?
• Which platform do I want to use to run my analysis on?
• What kind of information I want about the file?

The creation of the isolated environment (the virtual machine) is probably the most critical and important part of a sandbox deployment: it should be done carefully and with proper planning.

Before getting hands on the virtualization product of your choice, you should already have a design plan that defines:

• Which operating system, language and patching level to use.
• Which softwares to install and which versions (particularly important when analyzing exploits).

Consider that automated malware analysis is not deterministic and its success might depend on a trillion of factors: you are trying to make a malware run in a virtualized system as it would do on a native one, which could be tricky to achieve and could not always succeed. Your goal should be both to create a system able to handle all the requirements you need as well as try to make it as realistic as possible.

For example you could consider leaving some intentional traces of normal usage, such as browsing history, cookies, documents, images etc. If a malware is designed to operate, manipulate or steal such files you’ll be able to notice it.

Virtualized operating systems usually carry a lot of traces with them that makes them very easily detectable. Even if you shouldn’t overestimate this problem, you might want to take care of this and try to hide as many virtualization traces as possible. There is a lot of literature on Internet regarding virtualization detection techniques and countermeasures.

Once you finished designing and preparing the prototype of system you want, you can proceed creating it and deploying it. You will be always in time to change things or slightly fix them, but remember that good planning at the beginning always means less troubles in the long run.

Some History¶

Cuckoo Sandbox started as a Google Summer of Code project in 2010 within The Honeynet Project. It was originally designed and developed by Claudio “nex” Guarnieri, who still mantains it and coordinates all efforts from joined developers and contributors.

After initial work during the summer 2010, the first beta release was published on Feb. 5th 2011, when Cuckoo was publicly announced and distributed for the first time.

In March 2011, Cuckoo has been selected again as a supported project during Google Summer of Code 2011 with The Honeynet Project, during which Dario Fernandes joined the project and extended its functionalities.

On November 2nd 2011 Cuckoo the release of its 0.2 version to the public as the first real stable release.

On late November 2011 Alessandro “jekil” Tanasi joined the team expanding Cuckoo’s processing and reporting functionalities.

On December 2011 Cuckoo v0.3 gets released and quickly hitting release 0.3.2 in early February.

In late January 2012 we opened Malwr.com, a free and public running Cuckoo Sandbox instance provided with a full fledged interface through which people can submit files to be analysed and get results back.

Use Cases¶

Cuckoo is designed to be used both as a standalone application as well as to be integrated in larger frameworks, thanks to its submission and processing automation capabilities.

It can be used to analyze:

• Generic Windows executables
• DLL files
• PDF documents
• Microsoft Office documents
• URLs
• PHP scripts
• Almost everything else

Thanks to its scripting and customization capabilities there’s basically no limit to what you can achieve with Cuckoo, for example automating malware unpacking or automating the dump of configuration files and web-injects from banking trojans.

For more information on customizing Cuckoo, see the Customization chapter.

Architecture¶

Cuckoo Sandbox consists of a central management software which handles sample execution and analysis.

Each analysis is launched in a fresh and isolated virtual machine. Cuckoo’s infrastructure is composed by an Host machine (the management software) and a number of Guest machines (virtual machines for analysis).

The Host runs the core component of the sandbox that manages the whole analysis and execution process, while the Guests are the isolated environments where the malwares get actually safely executed and analyzed.

The following picture explains Cuckoo’s architecture:

Although recommended setup is GNU/Linux (Ubuntu preferrably) as host and Windows XP Service Pack 3 as guest, Cuckoo proved to work smoothly also on Mac OS X as host and Windows Vista and Windows 7 as guests.

Obtaining Cuckoo¶

Cuckoo can be downloaded from the official website, where the stable and packaged releases are distributed, or can be cloned from our official git repository.

Warning

While being more updated, including new features and bugfixes, the version available in the git repository should be considered an under development stage. Therefore its stability is not guaranteed and it most likely lacks updated documentation.

Submission Utility¶

The easiest way to submit an analysis is to use the provided submit.py command-line utility. It currently has the following options available:

Usage: submit.py [options] filepath

Options:
  -h, --help            show this help message and exit
  -t TIMEOUT, --timeout=TIMEOUT
                        Specify analysis execution time limit
  -p PACKAGE, --package=PACKAGE
                        Specify custom analysis package name
  -r PRIORITY, --priority=PRIORITY
                        Specify an analysis priority expressed in integer
  -c CUSTOM, --custom=CUSTOM
                        Specify any custom value to be passed to postprocessing
  -d, --download        Specify if the target is an URL to be downloaded
  -u, --url             Specify if the target is an URL to be analyzed
  -m MACHINE, --machine=MACHINE
                        Specify a virtual machine you want to specifically use for this analysis

The concept of analysis packages will be dealt later in this documentation (at Analysis Packages). Following are some usage examples:

Example: submit a local binary:

$ python submit.py /path/to/binary

Example: submit a local binary and specify an higher priority:

$ python submit.py /path/to/binary --priority 5

Example: submit a local binary and specify a custom analysis timeout of 60 seconds:

$ python submit.py /path/to/binary --timeout 60

Example: submit a local binary and specify a custom analysis package:

$ python submit.py /path/to/binary --package <name of package>

Example: submit an URL to be downloaded locally and analyzed:

$ python submit.py --download http://www.website.tld/file.exe

Example: submit an URL to be analyzed within Internet Explorer:

$ python submit.py --url http://maliciousurl.tld/exploit.php

Example: submit a local binary to be run on virtual machine cuckoo1:

$ python submit.py /path/to/binary --machine cuckoo1

Interact with SQLite¶

Cuckoo is designed to be easily integrated in larger solutions and to be fully automated. In order to automate analysis submission or to provide a different interface rather than the command-line (for instance a web interface), you can directly interact with the SQLite database located at db/cuckoo.db.

The database contains the table queue which is defined as the following schema:

1 2 3 4 5 6 7 8 9 10 11 12 13 14

CREATE TABLE queue ( id INTEGER PRIMARY KEY, md5 TEXT DEFAULT NULL, target TEXT NOT NULL, timeout INTEGER DEFAULT NULL, priority INTEGER DEFAULT 0, added_on DATE DEFAULT CURRENT_TIMESTAMP, completed_on DATE DEFAULT NULL, package TEXT DEFAULT NULL, lock INTEGER DEFAULT 0, status INTEGER DEFAULT 0, custom TEXT DEFAULT NULL, vm_id TEXT DEFAULT NULL );

Following are the details on the fields:

• id: it’s the numeric ID also used to name the results folder of the analysis.
• md5: it’s the MD5 hash of the target file.
• target: it’s the path pointing to the file to analyze.
• timeout: it’s the analysis timeout, if none has been specified the field is set to NULL.
• priority: it’s the analysis priority, if none has been specified the field is set to NULL.
• added_on: it’s the timestamp of when the analysis request was added.
• completed_on: it’s the timestamp of when the analysis has been completed.
• package: it’s the name of the analysis package to be used, if non has been specified the field is set to NULL.
• lock: it’s field internally used by Cuckoo to lock pending analysis.
• status: it’s a numeric field representing the status of the analysis (0 = not completed, 1 = completed successfully, 2 = failed).
• custom: it’s a custom user-defined text that can be used for synchronization between submission and post-analysis processing.
• vm_id: it’s the ID (as defined in cuckoo.conf) of a virtual machine the user specifically wants to use for the analysis.

Cuckoo Python Functions¶

In case you want to write your own Python submission script, you can use the add_task() function provided by Cuckoo, which has the following prototype:

def add_task(self, target, md5 = None, timeout = None, package = None, priority = None, custom = None, vm_id = None)

Following is a usage example:

1 2 3 4 5

#!/usr/bin/python from cuckoo.core.db import CuckooDatabase db = CuckooDatabase() db.add_task("/path/to/binary")

analysis.conf¶

analysis.conf is a configuration file automatically generated by Cuckoo to specify some parameters to the guest component (analyzer). It’s generally not relevant for an end-users as it’s exclusively used internally by Cuckoo.

analysis.log¶

analysis.log is a log file generated by Cuckoo analyzer and that keeps track of analysis execution and might report errors occurred during the analysis.

dump.pcap¶

dump.pcap is the trace dump containing all the network activity generated by the virtual machine during the malware execution.

additional/¶

The additional/ directory can be used to drop any kind of additional file or data which is not generated by the malware. For example memory dumps, dumped configs or anything else you might want to store during an analysis.

files/¶

The files/ directory contains all files created or deleted by the malware and that were successfully dumped by Cuckoo.

logs/¶

The logs/ directory contains the raw CSV-like logs generated by the monitored processes and that contains the concrete behavioral tracing results.

reports/¶

The reports/ directory contains the abstract analysis reports generated automatically by Cuckoo. The number and the format of such reports depends on the the configuration explained in the Configuration chapter.

shots/¶

The shots/ directory contains the screenshots of Windows desktop taken during the analysis execution.

Start the Web Server¶

The web server has following options:

Usage: web.py [options]

Options:
  -h, --help            show this help message and exit
  -t HOST, --host=HOST  Specify the host to bind the server on (default localhost)
  -p PORT, --port=PORT  Specify the port to bind the server on (default 8080)

In order to start it, just launch:

$ python web.py

You should see displayed:

Starting web server on localhost:8080

You can change the host and the port on which to bind the web server by specifying them with the appropriate options.

Recent Analysis¶

If you now open your browser and go to http://localhost:8080/ you will see Cuckoo’s index page, which includes a list of the 30 most recent analysis and a web form through which you can search for analysis by MD5 hash.

By filling the form and submitting it you’ll be prompted with search results. By clicking on the MD5 of one of the analysis, you’ll be prompted with the report for that specific analysis.

Search for MD5¶

After submitting a valid MD5 in the search form, you’ll be prompted with all the analysis performed on the file matching that hash.

View Report¶

When requesting the report of a specific analysis, the web server will returns you the appropriate HTML report. Please notice that if in your Cuckoo Setup you disabled the generation of HTML reports (see Configuration), a 404 error will be returned.

Getting started¶

As first example we’ll take a look at the default package for analyzing generic Windows executables (located at shares/setup/packages/exe.py):

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43

import os import sys sys.path.append("\\\\VBOXSVR\\setup\\lib\\") from cuckoo.execute import cuckoo_execute from cuckoo.monitor import cuckoo_monitor # The package main function "cuckoo_run" should follow a fixed structure in # order for Cuckoo to correctly handle it and its results. def cuckoo_run(target_path): # Every analysis package can retrieve a list of multiple process IDs it # might have generated. All processes added to this list will be added to # the monitored list, and Cuckoo will wait for all of the to complete their # execution before ending the analysis. pids = [] # The following functions are used to launch a process with the simplified # "cuckoo_execute" function. This function takes as arguments (in specific # order): # - a path to the executable to launch # - arguments to be passed on execution # - a boolean value to specify if the process have to be created in # suspended mode or not (it's recommended to set it to True if the # process is supposed to be injected and monitored). suspended = True (pid, h_thread) = cuckoo_execute(target_path, None, suspended) # The function "cuckoo_monitor" invoke the DLL injection and resume the # process if it was suspended. It needs the process id and the main thread # handle returned by "cuckoo_execute" and the same boolean value to tell it # if it needs to resume the process. cuckoo_monitor(pid, h_thread, suspended) # Append all the process IDs you want to the list, and return the list. pids.append(pid) return pids def cuckoo_check(): return True def cuckoo_finish(): return True

Let’s walk through the given code.

At line 1 and 2 we import the os and sys Python modules. At line 4 we append “\\VBOXSVR\setup\lib\” to Python’s modules paths list: this will allow us to invoke Cuckoo’s modules directly from the shared folder.

Then we can see that three functions are defined:

• cuckoo_run()
• cuckoo_check()
• cuckoo_finish()

In the given example the package just executes the binary located at target_path in suspended mode and instructs Cuckoo to inject the process and start monitoring it.

A slightly more complex example is the PDF analysis package (located at shares/setup/packages/pdf.py):

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26

import os import sys sys.path.append("\\\\VBOXSVR\\setup\\lib\\") from cuckoo.execute import cuckoo_execute from cuckoo.monitor import cuckoo_monitor def cuckoo_run(target_path): pids = [] # Customize this Path with the correct one on your Windows setup. adobe_reader = "C:\\Program Files\\Adobe\\Reader 9.0\\Reader\\AcroRd32.exe" suspended = True (pid, h_thread) = cuckoo_execute(adobe_reader, "\"%s\"" % target_path, suspended) cuckoo_monitor(pid, h_thread, suspended) pids.append(pid) return pids def cuckoo_check(): return True def cuckoo_finish(): return True

In this example we have the same structure, with the only difference being that instead of executing the file at target_path, it executes Adobe Reader with target_path as argument. In this way it basically instructs Cuckoo to monitor what Adobe Reader is doing while opening the given PDF file. As you understand, this opens a large spectrum of possibilities on what Cuckoo can be used for.

Cuckoo Modules¶

As you noticed in the packages examples, Cuckoo provides some custom functions that facilitates some complex Windows actions.

These functions are defined in some Python modules that Cuckoo provide by default. You can use any of these modules in your analysis packages.

Following is a list of available modules and the contained functions.

Retrieving details on a file¶

The first thing you might be interested in, is retrieving some details on the binary you just analyzed. For this purpose there’s a dedicated class called File provided by the module cuckoo.processing.file. It takes the path to a file as argument and invoking process() retrieves a dictionary containing some static details. You can actually use this clan on any file you want, perhaps also on dropped files.

Following is an example usage and output:

>>> import pprint
>>> from cuckoo.processing.file import File
>>> details = File("analysis/1/malware.exe").process()
>>> pprint.pprint(details)
{'crc32': '76652E7B',
 'md5': '9b2de8b062a5538d2a126ba93835d1e9',
 'name': 'malware.exe',
 'sha1': 'f3b2025f64aaec787b1009223927b78b1677b92a',
 'sha256': '676a818365c573e236245e8182db87ba1bc021c5d8ee7443b9f673f26e7fd7d1',
 'sha512': '807142b3141bddbf5b2c2be78ff755433fca67b3f78ea7c5f7e74001614097a2bf439d90fa6ab415e736c59829be40d8c220f60117478e1a1ee372a97faa8fcb',
 'size': 194560,
 'ssdeep': '3072:J9GgqeRehDMVYQKSGJhJX11o0wojolTmXJmfEaQHNo8+PZ7ya4aMi4ry0zxLbnJG:J9JqeohDMODSGFX11o0wo0AJ4+a82Z7U',
 'type': 'PE32 executable for MS Windows (GUI) Intel 80386 32-bit'}

Processing behavioral analysis results¶

As you read in Analysis Results, Cuckoo generates some csv-like raw logs for every process it monitored. These logs contains all the win32 API calls that Cuckoo was able to intercept while tracking the processes. In order to make the information contained there more accessible, you can use the BehaviorAnalysis class provided by the module cuckoo.processing.analysis.

This class takes the path to the logs files as argument and, by calling its function process(), it will return a dictionary containing the behavioral results in a structured format.

Following is an example usage and output:

>>> import pprint
>>> from cuckoo.processing.analysis import BehaviorAnalysis
>>> results = BehaviorAnalysis("analysis/1/logs/").process()
>>> pprint.pprint(results)
[{'calls': [{'api': 'LoadLibraryA',
             'arguments': [{'name': 'lpFileName', 'value': 'KERNEL32.DLL'}],
             'repeated': 0,
             'return': '0x7c800000',
             'status': 'SUCCESS',
             'timestamp': '20111219100536.679'},

            [...]

            {'api': 'VirtualAllocEx',
             'arguments': [{'name': 'th32ProcessID', 'value': '764'},
                           {'name': 'szExeFile', 'value': 'binary.exe'},
                           {'name': 'lpAddress', 'value': '0x00000000'},
                           {'name': 'dwSize', 'value': '4826'},
                           {'name': 'flAllocationType',
                            'value': '0x00003000'},
                           {'name': 'flProtect', 'value': '0x00000040'}],
             'repeated': 0,
             'return': '0x00150000',
             'status': 'SUCCESS',
             'timestamp': '20111219100536.679'},
            {'api': 'CreateFileW',
             'arguments': [{'name': 'lpFileName',
                            'value': 'C:\\WINDOWS\\system32\\svchost.exe'},
                           {'name': 'dwDesiredAccess',
                            'value': 'GENERIC_READ'}],
             'repeated': 1,
             'return': '0x000000b4',
             'status': 'SUCCESS',
             'timestamp': '20111219100546.734'},
            {'api': 'CreateProcessA',
             'arguments': [{'name': 'lpApplicationName',
                            'value': '(null)'},
                           {'name': 'lpCommandLine',
                            'value': 'svchost.exe'}],
             'repeated': 0,
             'return': '1548',
             'status': 'SUCCESS',
             'timestamp': '20111219100546.734'},
            {'api': 'VirtualAllocEx',
             'arguments': [{'name': 'th32ProcessID', 'value': '1548'},
                           {'name': 'szExeFile', 'value': 'svchost.exe'},
                           {'name': 'lpAddress', 'value': '0x00000000'},
                           {'name': 'dwSize', 'value': '0'},
                           {'name': 'flAllocationType',
                            'value': '0x00003000'},
                           {'name': 'flProtect', 'value': '0x00000040'}],
             'repeated': 0,
             'return': '',
             'status': 'FAILURE',
             'timestamp': '20111219100546.734'},
            {'api': 'ExitProcess',
             'arguments': [{'name': 'uExitCode', 'value': '0x00000000'}],
             'repeated': 0,
             'return': '',
             'status': '',
             'timestamp': '20111219100546.744'}],
  'first_seen': '20111219100536.679',
  'process_id': '764',
  'process_name': 'binary.exe'}]

Using the normalized data generated by BehaviorAnalysis class, you can even generate a tree with the ProcessTree class which orders the monitored processes recursively.

Following is an example usage and output:

>>> import pprint
>>> from cuckoo.processing.analysis import BehaviorAnalysis, ProcessTree
>>> results = BehaviorAnalysis("analysis/2/logs/").process()
>>> tree = ProcessTree(results).process()
>>> pprint.pprint(tree)
[{'children': [{'children': [], 'name': 'kadef.exe', 'pid': 788},
               {'children': [], 'name': 'cmd.exe', 'pid': 1764}],
  'name': 'malware.exe',
  'pid': 1488}]

In the same way, using the normalized results, you can generate a summary with the BehaviorSummary class which contains key values currently including accessed files, accessed registry keys and accessed mutexes.

Following is an example usage and output:

>>> import pprint
>>> from cuckoo.processing.analysis import BehaviorAnalysis, BehaviorSummary
>>> results = BehaviorAnalysis("analysis/1/logs/").process()
>>> summary = BehaviorSummary(results).process()
>>> pprint.pprint(summary)
{'files': ['\\\\.\\PIPE\\lsarpc',
           'C:\\WINDOWS\\',
           '\\\\.\\MountPointManager',
           'C:\\debug.txt',
           'C:\\1d8f4af4e7bcec0c3a3cec09c23a64b1.exe',
           'C:\\Documents and Settings\\User\\Application Data\\Pywou\\ikxi.exe',
           'C:\\Documents and Settings\\User\\Application Data\\Leydav\\idyr.fud',
           'C:\\Documents and Settings\\User\\Application Data',
           'C:\\Documents and Settings\\User\\Application Data\\Pywou',
           'C:\\Documents and Settings\\User\\Application Data\\Leydav',
           'C:\\DOCUME~1\\Me\\LOCALS~1\\Temp\\tmpc8bd469a.bat',
           'C:\\WINDOWS\\system32\\cmd.exe'],
 'keys': ['HKEY_LOCAL_MACHINE\\\\Software\\Policies\\Microsoft\\Windows\\Safer\\CodeIdentifiers',
          '0x000000dc\\\\Software\\Policies\\Microsoft\\Windows\\Safer\\CodeIdentifiers',
          'HKEY_LOCAL_MACHINE\\\\Software\\Microsoft\\Command Processor',
          'HKEY_CURRENT_USER\\\\Software\\Microsoft\\Command Processor'],
 'mutexes': ['{8EEEA37C-5CEF-11DD-9810-2A4256D89593}',
             'Global\\{502CC696-1792-D22B-3DCD-DB4062D1CF32}',
             'Local\\{C19386EC-57E8-4394-3DCD-DB4062D1CF32}',
             'ShimCacheMutex',
             'Local\\{EA35E3DD-32D9-6832-3DCD-DB4062D1CF32}',
             'Global\\{0C34F9D1-28D5-8E33-4ED7-02E811CB169A}',
             'Global\\{0C34F9D1-28D5-8E33-42D5-02E81DC9169A}',
             'Global\\{0C34F9D1-28D5-8E33-02D5-02E85DC9169A}']}

Processing network traffic¶

In the exact same way as you can process behavioral results, you can also process network traffic from the PCAP file using the Pcap class available from cuckoo.processing.pcap.

At current stage it retrieves a dictionary with all the information on DNS and HTTP requests as well as all UDP and TCP packets.

Following is an example usage and output:

>>> import pprint
>>> from cuckoo.processing.pcap import Pcap
>>> network = Pcap("analysis/3/dump.pcap").process()
>>> pprint.pprint(network)
{'dns': [{'hostname': 'www.google.com', 'ip': '74.125.127.104'}],
 'http': [{'body': '',
           'data': 'GET / HTTP/1.1\r\nHost: www.google.com\r\nUser-Agent: Mozilla/5.0 (Windows NT 5.1; rv:6.0.2) Gecko/20100101 Firefox/6.0.2\r\nAccept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8\r\nAccept-Language: en-us,en;q=0.5\r\nAccept-Encoding: gzip, deflate\r\nAccept-Charset: ISO-8859-1,utf-8;q=0.7,*;q=0.7\r\nConnection: keep-alive\r\n\r\n',
           'host': 'www.google.com',
           'method': 'GET',
           'path': '/',
           'port': 80,
           'uri': 'http://www.google.com/',
           'user-agent': 'Mozilla/5.0 (Windows NT 5.1; rv:6.0.2) Gecko/20100101 Firefox/6.0.2',
           'version': '1.1'}],
 'tcp': [{'dport': 80,
          'dst': '74.125.127.104',
          'sport': 1214,
          'src': '10.0.2.15'}],
 'udp': [{'dport': 67,
          'dst': '255.255.255.255',
          'sport': 68,
          'src': '0.0.0.0'}]}

Putting all together¶

If you don’t want to bother invoking all the necessary classes but just want a comprehensive (and huge) dictionary containing everything you need, you can simply use the CuckooDict class provided by the module cuckoo.processing.data, just like the default package do.

Following is an example usage and output:

>>> import pprint
>>> from cuckoo.processing.data import CuckooDict
>>> analysis = CuckooDict("analysis/2/").process()
>>> pprint.pprint(analysis)
{'behavior': {'processes': [<results provided by class BehaviorAnalysis>],
              'processtree': [<results provided by class ProcessTree>],
              'summary': [<results provided by class BehaviorSummary]},
 'debug': {'log': '<content of analysis.log file>'},
 'dropped': [<results provided by class File on all dropped files>],
 'file': {<results provided by class File on the analyzed file>},
 'info': {'duration': '165 seconds',
          'ended': '2012-01-31 23:03:15',
          'started': '2012-01-31 23:01:09',
          'version': 'v0.3.2'},
 'network': {<results provided by class Pcap>},
 'static': {<results provided by class static analysis classes}.
 'screenshots': {<screenshots taken during analysis>}}

The output has been stripped out of results.

Built-in Reports¶

Writing your own reporting module¶

As said, reporting tasks are handled by the ReportProcessor class: it loads all reporting modules from cuckoo/reporting/tasks folder, checks if they are enabled in the configuration file and then execute them.

If you want to write your own reporting module you have to:

• Create a Python file inside the reporting module folder (cuckoo/reporting/tasks), e.g. foo.py.

• Append an option inside the reporting configuration file (reporting.conf) with the lowercase name of the file and enable it, like following:

  foo = on
  

• Inside your Python script you have to implement the BaseObserver interface in a class named “Report”. When new analysis results are available, Cuckoo calls your update() method passing the analysis results as a parameter.

A sample custom reporting module would look like following:

1 2 3 4 5 6 7 8

from cuckoo.reporting.observers import BaseObserver class Report(BaseObserver): def update(self, results): # Here you get analysis results as parameter. # Now do your stuff. print "My report!"

Whatever operation you might want to run, remember to place it inside the update() method or invoke it from there, so that Cuckoo will be able to execute it when needed.

The BaseObserver will check for reports folder and puts that path in self.report_path, you can use this variable if you need the reports folder path writing your custom report to disk.