Requirements¶

Installing Python libraries (on Ubuntu/Debian-based distributions)¶

The Cuckoo host components is completely written in Python, therefore it is required to have an appropriate version of Python installed. At this point we only fully support Python 2.7. Older version of Python and Python 3 versions are not supported by us (although Python 3 support is on our TODO list with a low priority).

The following software packages from the apt repositories are required to get Cuckoo to install and run properly:

$ sudo apt-get install python python-pip python-dev libffi-dev libssl-dev
$ sudo apt-get install python-virtualenv python-setuptools
$ sudo apt-get install libjpeg-dev zlib1g-dev swig

In order to use the Django-based Web Interface, MongoDB is required:

$ sudo apt-get install mongodb

In order to use PostgreSQL as database (our recommendation), PostgreSQL will have to be installed as well:

$ sudo apt-get install postgresql libpq-dev

Pydeep is an optional plugin that can be installed manually. A Link is provided for convenience: * pydeep install - note: the libfuzzy-dev package is required for

pydeep but at the time of writing, was not listed in the official documentation.

If you want to use KVM as machinery module you will have to install KVM:

$ sudo apt-get install qemu-kvm libvirt-bin ubuntu-vm-builder bridge-utils python-libvirt

If you want to use XenServer you’ll have to install the XenAPI Python package:

$ sudo pip install XenAPI

If you want to use the mitm auxiliary module (to intercept SSL/TLS generated traffic), you need to install mitmproxy. Please refer to its website for installation instructions. Please note that the latest version of mitmproxy requires Python 3.6 or higher and therefore it’s required to install it within a separate virtualenv to isolate it and its requirements from Cuckoo’s Python 2.7 environment. After installing mitmproxy in a separate virtualenv, include its binary path in the Cuckoo configuration, e.g., /tmp/mitmproxy3/bin/mitmdump if the virtualenv is /tmp/mitmproxy3.

Installing Python libraries (on Mac OS X)¶

This is mostly the same as the installation on Ubuntu/Debian, except that we’ll be using the brew package manager. Install all the required dependencies as follows (this list is WIP):

$ brew install libmagic cairo pango openssl

In addition to that you’ll also want to expose the openssl header files in the standard GCC/Clang include directory, so that yara-python may compile successfully. This can be done as follows:

$ cd /usr/local/include
$ ln -s ../opt/openssl/include/openssl .

Installing Python libraries (on Windows 7)¶

To be documented.

Virtualization Software¶

Cuckoo Sandbox supports most Virtualization Software solutions. As you will see throughout the documentation, Cuckoo has been setup to remain as modular as possible and in case integration with a piece of software is missing this could be easily added.

For the sake of this guide we will assume that you have VirtualBox installed (which is the default), but this does not affect the execution and general configuration of the sandbox.

You are completely responsible for the choice, configuration, and execution of your virtualization software. Please read our extensive documentation and FAQ before reaching out to us with questions on how to set Cuckoo up.

Assuming you decide to go for VirtualBox, you can get the proper package for your distribution at the official download page. Please find following the commands to install the latest version of VirtualBox on your Ubuntu LTS machine. Note that Cuckoo supports VirtualBox 4.3, 5.0, 5.1, and 5.2:

$ echo deb http://download.virtualbox.org/virtualbox/debian xenial contrib | sudo tee -a /etc/apt/sources.list.d/virtualbox.list
$ wget -q https://www.virtualbox.org/download/oracle_vbox_2016.asc -O- | sudo apt-key add -
$ sudo apt-get update
$ sudo apt-get install virtualbox-5.2

For more information on VirtualBox, please refer to the official documentation.

Installing tcpdump¶

In order to dump the network activity performed by the malware during execution, you’ll need a network sniffer properly configured to capture the traffic and dump it to a file.

By default Cuckoo adopts tcpdump, the prominent open source solution.

Install it on Ubuntu:

$ sudo apt-get install tcpdump apparmor-utils
$ sudo aa-disable /usr/sbin/tcpdump

Note that the AppArmor profile disabling (the aa-disable command) is only required when using the default CWD directory as AppArmor would otherwise prevent the creation of the actual PCAP files (see also Permission denied for tcpdump).

For Linux platforms with AppArmor disabled (e.g., Debian) the following command will suffice to install tcpdump:

$ sudo apt-get install tcpdump

Tcpdump requires root privileges, but since you don’t want Cuckoo to run as root you’ll have to set specific Linux capabilities to the binary:

$ sudo groupadd pcap
$ sudo usermod -a -G pcap cuckoo
$ sudo chgrp pcap /usr/sbin/tcpdump
$ sudo setcap cap_net_raw,cap_net_admin=eip /usr/sbin/tcpdump

You can verify the results of the last command with:

$ getcap /usr/sbin/tcpdump
/usr/sbin/tcpdump = cap_net_admin,cap_net_raw+eip

If you don’t have setcap installed you can get it with:

$ sudo apt-get install libcap2-bin

Or otherwise (not recommended) do:

$ sudo chmod +s /usr/sbin/tcpdump

Please keep in mind that even the setcap method is not perfectly safe (due to potential security vulnerabilities) if the system has other users which are potentially untrusted. We recommend to run Cuckoo on a dedicated system or a trusted environment where the privileged tcpdump execution is contained otherwise.

Installing Volatility¶

Volatility is an optional tool to do forensic analysis on memory dumps. In combination with Cuckoo, it can automatically provide additional visibility into deep modifications in the operating system as well as detect the presence of rootkit technology that escaped the monitoring domain of Cuckoo’s analyzer.

In order to function properly, Cuckoo requires at least version 2.3 of Volatility, but recommends the latest version, Volatility 2.5. You can download it from their official repository.

See the volatility documentation for detailed instructions on how to install it.

Installing M2Crypto¶

Currently the M2Crypto library is only supported when SWIG has been installed. On Ubuntu/Debian-like systems this may be done as follows:

$ sudo apt-get install swig

If SWIG is present on the system one may install M2Crypto as follows:

$ sudo pip install m2crypto==0.24.0

Installing guacd¶

guacd is an optional service that provides the translation layer for RDP, VNC, and SSH for the remote control functionality in the Cuckoo web interface.

Without it, remote control won’t work. Versions 0.9.9 and up will work, but we recommend installing the latest version. On an Ubuntu 17.04 machine the following command will install version 0.9.9-2:

$ sudo apt install libguac-client-rdp0 libguac-client-vnc0 libguac-client-ssh0 guacd

If you only want RDP support you can skip the installation of the libguac-client-vnc0 and libguac-client-ssh0 packages.

If you are using an older distribution or you just want to use the latest version (our recommendation), the following will build the latest version (0.9.14) from source:

$ sudo apt -y install libcairo2-dev libjpeg-turbo8-dev libpng-dev libossp-uuid-dev libfreerdp-dev
$ mkdir /tmp/guac-build && cd /tmp/guac-build
$ wget https://www.apache.org/dist/guacamole/0.9.14/source/guacamole-server-0.9.14.tar.gz
$ tar xvf guacamole-server-0.9.14.tar.gz && cd guacamole-server-0.9.14
$ ./configure --with-init-dir=/etc/init.d
$ make && sudo make install && cd ..
$ sudo ldconfig
$ sudo /etc/init.d/guacd start

When installing from source, make sure you don’t have another version of any of the libguac- libraries installed from your package manager or you might experience issues due to incompatibilities which can crash guacd.

Note that the VirtualBox Extension Pack must also be installed to take advantage of the Cuckoo Control functionality exposed by Guacamole.