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
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.
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.
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
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.
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.
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
SWIG is present on the system one may install
M2Crypto as follows:
$ sudo pip install m2crypto==0.24.0
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
$ 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
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
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.