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 is still the main developer 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 hits 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.

In March 2012 Cuckoo Sandbox wins the first round of the Magnificent7 program organized by Rapid7.

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 extremely modular design.

It can be used to analyze:

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

Thanks to its modularity and powerful scripting capabilities, there’s not limit to what you can achieve with Cuckoo.

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 process, while the Guests are the isolated environments where the malwares get actually safely executed and analyzed.

The following picture explains Cuckoo’s main 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 [-h] [--package PACKAGE] [--timeout TIMEOUT]
                 [--options OPTIONS] [--priority PRIORITY] [--machine MACHINE]
                 [--platform PLATFORM]
                 path

positional arguments:
  path                 Path to the file or folder to analyze

optional arguments:
  -h, --help           show this help message and exit
  --package PACKAGE    Specify an analysis package
  --timeout TIMEOUT    Specify an analysis timeout
  --options OPTIONS    Specify options for the analysis package (e.g.
                       "name=value,name2=value2")
  --priority PRIORITY  Specify a priority for the analysis represented by an
                       integer
  --machine MACHINE    Specify the identifier of a machine you want to use
  --platform PLATFORM  Specify the operating system platform you want to use
                       (windows/darwin/linux)

If you specify a directory as path, all the files contained in it will be submitted for 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:

$ ./utils/submit.py /path/to/binary

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

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

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

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

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

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

Example: submit a local binary and specify a custom analysis package and some options (in this case a command line argument for the malware):

$ ./utils/submit.py --package exe --options arguments=--dosomething /path/to/binary.exe

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

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

Example: submit a local binary to be run on a Windows machine:

$ ./utils/submit.py --platform windows /path/to/binary

Web Utility¶

Cuckoo provides a very basic web utility that you can use to submit files to be analyzed.

You can find the script at path utils/web.py and you can start it with:

$ python utils/web.py

By default it will create a webserver on localhost and port 8080. Open your browser at http://localhost:8080 and it will prompt you a simple form that allows you to upload a file, specify some options (with the same format as the submit.py utility) and submit it.

In the Browse section you can track the status of pending, failed and succeeded analyses and, when available, you’ll be prompted a link to view the HTML report.

Note

This is by no means supposed to be a full fledged web interface: it’s a very simple utility that we put together to allow users to simply upload files and consumes the generated HTML report. Despite being incorporated and rendered dynamically, the results displayed are nothing else than the report.html file, therefore it is supposed to be independent from the utility.

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 tasks which is defined as the following schema:

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

CREATE TABLE tasks ( id INTEGER PRIMARY KEY, md5 TEXT DEFAULT NULL, file_path TEXT NOT NULL, timeout INTEGER DEFAULT NULL, priority INTEGER DEFAULT 0, custom TEXT DEFAULT NULL, machine TEXT DEFAULT NULL, package TEXT DEFAULT NULL, options TEXT DEFAULT NULL, platform TEXT DEFAULT NULL, added_on DATE DEFAULT CURRENT_TIMESTAMP, completed_on DATE DEFAULT NULL, lock INTEGER DEFAULT 0, status INTEGER DEFAULT 0 );

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.
• file_path: 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.
• custom: it’s a custom user-defined text that can be used for synchronization between submission and post-analysis processing.
• machine: it’s the ID of a virtual machine the user specifically wants to use for the analysis.
• package: it’s the name of the analysis package to be used, if non has been specified the field is set to NULL.
• options: it’s a comma-separated list of options to pass to the analysis package.
• platform: it’s the operating system platform to use for this analysis.
• 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.
• 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 = failed, 2 = succeeded).

Cuckoo Python Functions¶

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

def add(self,
        file_path,
        md5=None,
        timeout=None,
        package=None,
        options=None,
        priority=None,
        custom=None,
        machine=None,
        platform=None):

Following is a usage example:

1 2 3 4 5

#!/usr/bin/env python from lib.cuckoo.core.database import Database db = Database() db.add("/path/to/binary")

analysis.conf¶

This is a configuration file automatically generated by Cuckoo to instruct its analyzer some details about the current analysis. It’s generally of no interest for the end-user, as it’s exclusively used internally by the sandbox.

analysis.log¶

This is a log file generated by the analyzer and that contains a trace of the analysis execution inside the guest environment. It will report the creation of processes, files and eventual error occurred during the execution.

dump.pcap¶

This is the network dump generated by tcpdump or any other corresponding network sniffer.

files/¶

This directory contains all the files the malware operated on and that Cuckoo was able to dump.

logs/¶

This directory contains all the raw logs generated by Cuckoo’s process monitoring They are named <process id>.csv and contain the monitored API calls in chronological order represented in a csv-like format.

reports/¶

This directory contains all the reports generated by Cuckoo as explained in the Configuration chapter.

shots/¶

This directory contains all the screenshots of the guest’s desktop taken during the malware execution.

Cleanup utility¶

If you want to delete all history, analysis, data and begin again from the first task you need clean.sh utility.

To clean your setup, run:

$ cd utils
$ sh clean.sh

Submission Utility¶

Submits sample to analysis. This tool is already described in Submit an analysis.

Web Utility¶

Cuckoo’s web interface. This tool is already described in Submit an analysis.

Test Report Utility¶

Run the reporting engine (run all reports) on an already available analysis folder, in order to not re-run the analysis if you want to re-generate the reports for it. This is used mainly in debugging and developing Cuckoo. For example if you want run again the report engine for analysis number 1:

$ cd utils
$ python testreport.py ../storage/analyses/1/

Test Signature Utility¶

Run the signature engine (checks all signatures) on an already available analysis folder and see possible matches. This is used mainly in debugging and developing Cuckoo and testing new signatures. For example if you want run again the singature engine for analysis number 1:

$ cd utils
$ python testsignatures.py ../storage/analyses/1/

Community Download Utility¶

This utility downloads signatures from Cuckoo Community Repository and installs specific additional modules in your local setup and for example update id with all the latest available signatures. Following are the usage options:

$ cd utils
$ python community.py
You need to enable some category!

usage: community.py [-h] [-a] [-s] [-f] [-w]

optional arguments:
  -h, --help        show this help message and exit
  -a, --all         Download everything
  -s, --signatures  Download Cuckoo signatures
  -f, --force       Install files without confirmation
  -w, --rewrite     Rewrite existing files

Example: install all available signatures:

$ ./utils/community.py --signatures --force

Configuration¶

Every machine manager module should come with a dedicated configuration file located in conf/<machine manager name>.conf. For example for modules/kvm.py we have a conf/kvm.conf.

The configuration file should follow the default structure:

[kvm]
# Specify a comma-separated list of available machines to be used. For each
# specified ID you have to define a dedicated section containing the details
# on the respective machine. (E.g. cuckoo1,cuckoo2,cuckoo3)
machines = cuckoo1

[cuckoo1]
# Specify the label name of the current machine as specified in your
# libvirt configuration.
label = cuckoo1

# Specify the operating system platform used by current machine
# [windows/darwin/linux].
platform = windows

# Specify the IP address of the current machine. Make sure that the IP address
# is valid and that the host machine is able to reach it. If not, the analysis
# will fail.
ip = 192.168.122.105

A main section called [<name of the module>] with a machines field containing a comma-separated list of machines IDs.

For each machine you should specify a label, a platform and it’s ip.

These fields are required by Cuckoo in order to use the already embedded initialize() function that generates the list of available machines.

If you plan to change the configuration structure you should override the initialize() function (inside your own module, no need to modify Cuckoo’s core code). You can find it’s original code in the MachineManager abstract inside lib/cuckoo/common/abstracts.py.

Getting started¶

As an example we’ll take a look at the default package for analyzing generic Windows executables (located at analyzer/windows/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

from lib.common.abstracts import Package from lib.api.process import Process class Exe(Package): """EXE analysis package.""" def start(self, path): p = Process() if "arguments" in self.options: p.execute(path=path, args=self.options["arguments"], suspended=True) else: p.execute(path=path, suspended=True) p.inject() p.resume() return p.pid def check(self): return True def finish(self): return True

Let’s walk through the code.

At line 1 we import the parent class Package, all analysis packages must inherit this abstract class otherwise Cuckoo won’t be able to load them. At line 2 we import the class Process, which is an API module provided by Cuckoo’s Windows analyzer for accessing several process-related features.

At line 4 we define our class.

At line 7 we define the start() function, at line 20 the check() function and at line 23 the finish() function. These three functions are required as they are used for customizing the package’s operations at three different stages of the analysis.

In this case we just create a Process instance, check if the user specified any arguments as option and launch the malware located at path, which then gets injected and resumed.

def check(self):
    if os.path.exists("C:\\config.bin"):
        return False
    else:
        return True

Options¶

Every package have automatically access to a dictionary containing all user-specified options (see Submit an analysis).

Such options are made available in the attribute self.options. For example let’s assume that the user specified the following string at submission:

foo=1,bar=2

The analysis package selected will have access to these values:

from lib.common.abstracts import Package

class Example(Package):

    def start(self, path):
        foo = self.options["foo"]
        bar = self.options["bar"]

    def check():
        return True

    def finish():
        return True

These options can be used for anything you might need to configure inside your package.

Process API¶

The Process class provides access to different process-related features and functions. You can import it in your analysis packages with:

from lib.api.process import Process

You then initialize an instance with:

p = Process()

In case you want to open an existing process instead of creating a new one, you can specify multiple arguments:

• pid: PID of the process you want to operate on.
• h_process: handle of a process you want to operate on.
• thread_id: thread ID of a process you want to operate on.
• h_thread: handle of the thread of a process you want to operate on.

This class implements several methods that you can use in your own scripts.

p = Process(pid=1234)
p.open()
handle = p.h_process

p = Process(pid=1234)
code = p.exit_code()

p = Process(pid=1234)
if p.is_alive():
    print("Still running!")

p = Process()
p.execute(path="C:\\WINDOWS\\system32\\calc.exe", args="Something", suspended=True)

p = Process()
p.execute(path="C:\\WINDOWS\\system32\\calc.exe", args="Something", suspended=True)
p.resume()

p = Process(pid=1234)
if p.terminate():
    print("Process terminated!")
else:
    print("Could not terminate the process!")

p = Process()
p.execute(path="C:\\WINDOWS\\system32\\calc.exe", args="Something", suspended=True)
p.inject()
p.resume()

p = Process(pid=1234)
p.dump_memory()

Global Container¶

After an analysis is completed, Cuckoo will invoke all the processing modules available in the modules/processing/ directory.

Every module will then be initialized and executed and the data returned will be appended in a data structure that we’ll call global container.

This container is simply just a big Python dictionary that contains all the abstracted results produced by all the modules sorted by their defined keys.

Cuckoo is already provided with a default set of modules which will generate a standard global container. It’s important for the existing reporting modules (HTML report etc.) that these default modules are not modified, otherwise the resulting global container structure would change and the reporting modules wouldn’t be able to recognize it and extract the information used to build the final report.

Following is a JSON-like representation of a default global container:

{
    "info": {
        "started": <timestamp>,
        "ended": <timestamp>,
        "duration": <duration in seconds>,
        "version": <version of Cuckoo>
    },
    "signatures": [
        {
            "severity": <severity level>,
            "description": <signature description>
            "alert": <boolean value>,
            "references": [<any reference link>],
            "data": [<any contextual data>],
            "name": <signature name>
        }
    ],
    "behavior": {
        "processes": [
            {
                "parent_id": <parent PID>,
                "process_name": <process name>,
                "process_id": <PID>,
                "first_seen": <timestamp when the process was first seen>,
                "calls": [
                    {
                        "category": <API function category>,
                        "status": <SUCCESS or FAILURE>,
                        "return": <any returned value>,
                        "timestamp": <timestamp of the call>,
                        "repeated": <how many times it was repeated consecutively>,
                        "api": <API function>,
                        "arguments": [
                            {
                                "name": <argument name>,
                                "value": <argument value>
                            }
                        ]
                    },
                    <...>
                ],
                <...>
            }
        ],
        "processtree": [
            {
                "pid": <PID>,
                "name": <process name>,
                "children": [<recursive child entries>]
            }
        ],
        "summary": {
            "files": [<list of files accessed>],
            "keys": [<list of registry keys accessed>],
            "mutexes": [<list of mutexes accessed>]
        }
    },
    "static": {<static analysis if available for the file type>},
    "dropped": [
        {
            "size": <file size>,
            "sha1": <SHA1 hash>,
            "name": <file name>,
            "type": <file type>,
            "crc32": <CRC32 hash>,
            "ssdeep": <Ssdeep hash>,
            "sha256": <SHA256 hash>,
            "sha512": <SHA512 hash>,
            "md5": <MD5 hash>
        },
        <...>
    ],
    "file": {
        "size": <file size>,
        "sha1": <SHA1 hash>,
        "name": <file name>,
        "type": <file type>,
        "crc32": <CRC32 hash>,
        "ssdeep": <Ssdeep hash>,
        "sha256": <SHA256 hash>,
        "sha512": <SHA512 hash>,
        "md5": <MD5 hash>
    },
    "debug": {
        "log": <content of analysis.log>
    },
    "network": {
        "http": [
            {
                "body": <request body>,
                "uri": <request URI>,
                "method": <request method>,
                "host": <host name>,
                "version": <HTTP version>,
                "path": <path of the request>,
                "data": <dump of whole request>,
                "port": <port>
            },
            <...>
        ],
        "udp": [
            {
                "dport": <destination port>,
                "src": <source IP>,
                "dst": <destination IP>,
                "sport": <source port>
            },
            <...>
        ],
        "hosts": [<list of involved IP addresses>],
        "dns": [
            {
                "ip": <IP address>,
                "hostname": <domain name>
            },
        ],
        "tcp": [
            {
                "dport": <destination port>,
                "src": <source IP>,
                "dst": <destination IP>,
                "sport": <source port>
            },
            <...>
        ]
    }
}

Every processing module added will end up with a dedicated dictionary entry in this data structure.

Getting started¶

All processing modules are and should be placed in modules/processing/. In this directory you will find a set of default modules that are used to produce the traditional Cuckoo analysis reports.

A basic processing module could look like:

1 2 3 4 5 6 7 8

from lib.cuckoo.common.abstracts import Processing class MyModule(Processing): def run(self): self.key = "file" data = do_something() return data

Every processing module should contain:

• A class inheriting Processing.
• A run() function.
• A self.key attribute defining the name to be used as a subcontainer for the returned data.
• A set of data (list, dictionary or string etc.) that will be appended to the global container.

You can also specify an order value, which allows you to run the available processing modules in an ordered sequence. By default all modules are set with an order value of 1 and are executed in alphabetical order.

If you want to change this value your module would look like:

1 2 3 4 5 6 7 8 9

from lib.cuckoo.common.abstracts import Processing class MyModule(Processing): order = 2 def run(self): self.key = "file" data = do_something() return data

The processing modules are provided with some attributes that can be used to access the raw results for the given analysis:

• self.analysis_path: path to the folder containing the results (e.g. storage/analysis/1)
• self.log_path: path to the analysis.log file.
• self.conf_path: path to the analysis.conf file.
• self.file_path: path to the analyzed file.
• self.dropped_path: path to the folder containing the dropped files.
• self.logs_path: path to the folder containing the raw behavioral logs.
• self.shots_path: path to the folder containing the screenshots.
• self.pcap_path: path to the network pcap dump.

Example¶

A good example to understand better the mechanics behind this is the Yara module. Yara is a tool and library used to match user’s defined signatures containing static binary patterns against the analyzed file.

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

import os import logging try: import yara HAVE_YARA = True except ImportError: HAVE_YARA = False from lib.cuckoo.common.constants import CUCKOO_ROOT from lib.cuckoo.common.abstracts import Processing log = logging.getLogger(__name__) class YaraSignatures(Processing): """Yara signature processing.""" def run(self): """Run Yara processing. @return: hash with matches. """ self.key = "yara" matches = [] if HAVE_YARA: try: rules = yara.compile(filepath=os.path.join(CUCKOO_ROOT, "data", "yara", "index.yar")) for match in rules.match(self.file_path): matches.append({"name" : match.rule, "meta" : match.meta}) except yara.Error as e: log.warning("Unable to match Yara signatures: %s" % e[1]) else: log.warning("Yara is not installed, skip") return matches

As you can see in line #22 we defined the key name for the module. Next in the run() function we compile the signatures file and match every signature against the file located at self.file_path. The matched signatures are appended in the matches dictionary which is then returned and that will be included in the global container under the section “yara”.

Getting started¶

Creation of signatures is a very simple process and requires just a decent understanding of Python programming.

All signatures are and should be located in modules/signatures/.

A basic example signature is the following:

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

from lib.cuckoo.common.abstracts import Signature class CreatesExe(Signature): name = "creates_exe" description = "Creates a Windows executable on the filesystem" severity = 2 def run(self, results): for file_name in results["behavior"]["summary"]["files"]: if file_name.endswith(".exe"): self.data.append({"file_name" : file_name}) return True return False

As you can see the structure is very simple and similar to the other modules types we’ve seen so far.

You need to declare your class inheriting Signature, for which you can define some generic attributes:

• name: an identifier for the signature.
• description: a brief description of what the signature represents.
• severity: a number identifying the severity of the events matched (generally between 1 and 3).
• authors: a list of people who authored the signature.
• references: a list of references (URLs) to give context to the signature.
• enable: if set to False the signature will be skipped.
• alert: if set to True can be used to specify that the signature should be reported (perhaps by a dedicated reporting module)

The run() function takes the previously generated global container (see Processing Modules) and performs some checks against it.

In the given example it just walks through all the accessed files in the summary and checks if there is anything ending with ”.exe”: in that case it will return True, meaning that the signature was matched. Otherwise return False.

In case the signature gets matched, a new entry in the “signatures” section will be added to the global container like following:

"signatures": [
    {
        "severity": 2,
        "description": "Creates a Windows executable on the filesystem",
        "alert": false,
        "references": [],
        "data": [
            {
                "file_name": "C:\\d.exe"
            }
        ],
        "name": "creates_exe"
    }
],

Getting Started¶

All reporting modules are and should be placed inside the directory modules/reporting/.

Every module should also have a dedicated section in the file conf/reporting.conf, for example if you create a module module/reporting/foobar.py you will have to append the following section to conf/reporting.conf:

[foobar]
enabled = on

Every additional option you add to your section will be available to your reporting module in the self.options dictionary.

Following is an example of a working JSON reporting module:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20

import os import json from lib.cuckoo.common.abstracts import Report from lib.cuckoo.common.exceptions import CuckooReportError class JsonDump(Report): """Saves analysis results in JSON format.""" def run(self, results): """Writes report. @param results: Cuckoo results dict. @raise CuckooReportError: if fails to write report. """ try: report = open(os.path.join(self.reports_path, "report.json"), "w") report.write(json.dumps(results, sort_keys=False, indent=4)) report.close() except (TypeError, IOError) as e: raise CuckooReportError("Failed to generate JSON report: %s" % e)

This code is very simple, it basically just receives the global container produced by the processing modules, converts it into JSON and writes it to a file.

There are few requirements for writing a valid reporting module:

• Declare your class inheriting Report.
• Have a run() function performing the main operations.
• Try to catch most exceptions and raise CuckooReportError to notify the issue.

All reporting modules have access to some attributes:

• self.analysis_path: path to the folder containing the raw analysis results (e.g. storage/analyses/1/)
• self.reports_path: path to the folder where the reports should be written (e.g. storage/analyses/1/reports/)
• self.options: a dictionary containing all the options specified in the report’s configuration section in conf/reporting.conf.

Git branches¶

Cuckoo Sandbox source code is available in our official git repository. You’ll find multiple branches which are used for different stages of our development lifecycle.

• Development: This is where our developers commit their ongoing work for the upcoming releases. As a development branch, this can be really unstable and sometimes even broken and not usable. Users are discouraged to adopt this branch, this is aimed only to developers or guys with a deep knowledge into our technologies.
• Testing: When work on development branch is in a usable state and some new features or fixes are completed, the development branch in merged into testing. This is the branch where users can get a taste of the next release. If you want to be always up-to-date this branch is for you.
• Stable: When unstable branch is widely tested and bugs free and if all planned features has been completed, a new stable version will be released and available here.

Release Versioning¶

Cuckoo releases are named using three numbers separated by dots, such as 1.2.3, where the first number is the release, the second number is the major version, the third number is the bugfix version. The testing stage from git ends with “-beta” and development stage with “-dev”.

Warning

If you are using a “beta” or “dev” stage, please consider that it’s not meant to be an official release, therefore we don’t guarantee its functioning and we don’t generally provide support. If you think you encountered a bug there, make sure that the nature of the problem is not related to your own misconfiguration and collect all the details to be notified to our developers. Make sure to specify which exact version you are using, eventually with your current git commit id.

Ticketing system¶

We use a ticketing system to track all Cuckoo’s developments, bugs and features. Official tracking system is public available, if you want to contribute to Cuckoo please take a look to it before reporting bugs or asking for new features.

Contribute¶

To submit your patch just create a Pull Request from yuor GitHub fork. If you don’t now how to create a Pull Request take a look to GitHub help.

Formatting¶

# Copyright (C) 2010-2012 Cuckoo Sandbox Developers.
# This file is part of Cuckoo Sandbox - http://www.cuckoosandbox.org
# See the file 'docs/LICENSE' for copying permission.

class MyClass:
    """Doing something."""

    def __init__(self):
        """Initialize"""
        pass

    def do_it(self, what):
        """Do it.
        @param what: do what.
        """
        pass

from lib import a, b, c

from lib import a
from lib import b
from lib import c

from lib import a, b, c

from lib import *

import logging
log = logging.getLogger(__name__)

print("foo")

print "foo"

if "bar" in foo:
    do_something(foo["bar"])

Exceptions¶

Custom exceptions must be defined in the lib/cuckoo/common/exceptions.py file or in the local module if the exception should not be global.

Following is current Cuckoo’s exceptions chain:

.-- CuckooCriticalError
|   |-- CuckooStartupError
|   |-- CuckooDatabaseError
|   |-- CuckooMachineError
|   `-- CuckooDependencyError
|-- CuckooOperationalError
|   |-- CuckooAnalysisError
|   |-- CuckooProcessingError
|   `-- CuckooReportError
`-- CuckooGuestError

Beware that the use of CuckooCriticalError and its child exceptions will cause Cuckoo to terminate.

try:
    foo()
except Exception as e:
    bar()

try:
    foo()
except Exception, something:
    bar()

Documentation¶

All code must be documented in docstring format, see PEP 257 – Docstring Conventions. Additional comments may be added in logical blocks will be results hard to understand.

Automated testing¶

We belive in automated testing to provide high quality code and avoid dumb bugs. When possible, all code must be committed with proper unit tests. Particular attention must be placed when fixing bugs: it’s good practice to write unit tests to reproduce the bug. All unit tests and fixtures are placed in the tests folder in the cuckoo root. We adopt Nose as unit testing framework.