Requirements ¶

Before proceeding to installing and configuring Cuckoo, you’ll need to install some required software packages and libraries.
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 .
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.