Cuckoo Sandbox

The Cuckoo Sandbox is an open source software for automatic analysis of suspicious files. It uses custom components that monitor the behavior of malicious processes while they are running in an isolated environment.

This manual describes the installation of the Cuckoo Sandbox and its modules. Since setting up the sanbdox can sometimes cause a lot of difficulties I have found some useful workarounds for my issues, which I would like to publish here. The manual is strongly based on the official documentation of the Cuckoo Sandbox. Nevertheless some changes have been made, some passages have been shortened or extended to fit the host system.

The Official Documentation can be found at

The basic architecture of the system used for this is as follows:

Image Cuckoo-Machine-Architecture

1. Host system requirements

The following describes the requirements for installing Cuckoo on the system.

My configuration of the system is as follows:

  • VMWare ESXi
  • Debian 10.0 Buster
  • 8GB Ram
  • At least 200GB memory
  • Virtualbox 6.0
  • Cuckoo Sandbox v2.0.7

It is important to provide the machine enough memory (min. 200GB), because the host system will be extended by multiple virtual analysis systems in the next steps.

For this reason it is also absolutely necessary to make the following setting on the host system, enabling nested virtualization. Nested virtualization can be activated in the CPU settings as shown in the following screenshot.

Image Nested virtualization

If the described requirements are met, the installation of cuckoo can be started.

2. Cuckoo and VMCloak installation

Unfortunately Cuckoo does not yet work as a standalone product. For this reason, the installation requires several software packages to be installed. In the following all necessary packages for the startup of Cuckoo and the tool Vmcloak will be installed.

Bring the system up to date:

sudo apt-get update 
sudo apt-get upgrade -y 
sudo apt-get dist-upgrade -y 
sudo apt-get autoremove -y 

Installation of Python libraries which are necessary for VMCloak and Cuckoo:

sudo apt-get install python3 python3-pip python-dev libffi-dev libssl-dev -y 
sudo apt-get install libjpeg-dev zlib1g-dev swig -y
sudo apt-get install python3-virtualenv -y

Adding the user Cuckoo:
For security reasons, malware analysis is performed on a low privileged user (cuckoo).

sudo adduser cuckoo

Installation of the required database:

sudo apt-get install mongodb -y

Installation and configuration of TCP-Dump as a tool for network analysis:

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

Installation of Virtualbox:

sudo apt-get install virtualbox -y

Add the Cuckoo user to groups:

sudo usermod -a -G vboxusers cuckoo
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

Create a virtual environment:

sudo su cuckoo
virtualenv -p python2.7 ~/cuckoo
. ~/cuckoo/bin/activate
# The virtual environment can be left with the command exit.

Install Cuckoo and VMCloak within the virtual cuckoo environment:

pip install -U cuckoo vmcloak
cuckoo init
cuckoo community --force

3. Creation of the Base-Virtual Machine

The previously installed tool Vmcloak is used to create virtual machines. This tool enables an automatic generation of analysis systems.

For this purpose, an ISO file is required, which is then written to a mount accessible to the user Cuckoo.

Windows7 system:

Download Windows ISO file

sudo wget

Directory Mounting

sudo mkdir /mnt/win7
sudo chown cuckoo:cuckoo /mnt/win7
sudo mount -o ro,loop win7ultimate.iso /mnt/win7

Creation of the base virtual machine For the automatic generation of the analysis system, you must first switch to the virtual environment.

. ~/cuckoo/bin/activate

Configuring VirtualBox Host-Only Network Adapter


Creating the default virtual machine
The Default VM serves as a basis for the creation of future virtual analysis machines. Thus, future VMs do not have to be created first, but can be simply cloned from the base VM quickly.
The syntax is as follows:

vmcloak init <os flag> <vmname> <options>
vmcloak init --verbose --win7x64 win7x64Base --cpus 2 --ramsize 2048

Windows10 system:

It is important to note that at the time of writing the document, current versions of Windows are not supported. For this reason, an older version of Windows should be used to create the system.

Windows can be obtained from the following website:

In my case the following Windows 10 version is used:
Windows 10, Version 1809 – Redstone 5

Image win10-Version-Cuckoo

The setup of the Windows10 machine can be started in the same way as the creation of the Win7 machine with the following command.

vmcloak init --win10x64 win10x64base --cpus 2 --ramsize 2048 --serial-key XXXXX-XXXXX-XXXXX-XXXXX-XXXXX --product pro--ramsize 2048

Once Vmcloak has finished creating the base VM, the next step is to clone the Base-VM to any number of analysis VMs. As mentioned before, the Base-VM is not used to analyze malware, but is used to clone additional analysis machines. The cloned systems are used for the analysis of malware, which ensures that a “pure” base system is available at all times.

4. Creation of analysis systems

The preferred way to add a new analysis machine to the Cuckoo Sandbox is cloning. This ensures that the default configurations such as the agent and network parameters are applied appropriately. This allows a fast and uncomplicated start of a new analysis system.

Cloning of a machine using Vmcloak
The Vmcloack tool is used to clone a VM. The syntax for cloning a virtual disk image (VDI) from an existing one is as follows:

vmcloak clone presentVDI newVDI

Image cloneVM This command creates a .vdi file under the /home/cuckoo/.vmcloak/image directory.

5. Software installation on analysis systems

The installation of additional software on the analysis systems is not necessary. However, in order to simulate the system environment of a user as realistically as possible, it is highly recommended. Malware often works/spreads in dependence of third party software. For this reason, standard software applications such as office products, readers and browsers are installed. Additionally, parameters such as activation of macros in Office products can be used to make the system even more vulnerable to malware.

A software package can be installed using the following syntax:

vmcloak install <image name> <package>

Image vmcloak_list

A specific version or serial key can be selected by:

package.version=X or package.serialkey=X. 

If no version was selected, the latest version will be selected.

I will install some basic software packages:

vmcloak install win10x64Cuckoo1 adobe9 wic pillow java7

Image vmcloak_install

If you now want to install Office 2007, assuming that a valid serial key are available, you can do this as follows:

vmcloak install win10x64Cuckoo1 office2007 \office2007.isopath=/path/to/a.iso \office2007.serialkey=XXX-XXX

If the installation using Vmcloak does not work, you should mount the installation ISO in the virtual machine drive as a workaround.

The following steps are required:

  1. Start the virtual machine from the VirtualBox GUI.
  2. Select the path to the software ISO file under the tab Devices > Optical Drives > Select Image Image mount_ISO
  3. Go through the graphic installation of the software as usual.

6. Creation of Snapshots

After creating the analysis system, a snapshot of the analysis system has to be created. The syntax for creating snapshots is as follows:

Vmcloack snapshot <Machine name> <Snapshot name> <Static IP assignment
vmcloak snapshot win7x64cuckoo Snap1

Image snap

After executing the command, the analysis system should be displayed in Virtualbox. If this is the case and no error message is displayed, the following section (6.1 Workarund Multi-attach) can be skipped.

6.1 Workaround for the error message “Cannot Multi-attatch media”

If the following error occurs Cannot change type for medium: the media type “Multiattach”, this section provides a workaround. If the snapshot was created without causing problems, this section can be skipped.

Image multiattatch

The following steps are necessary for the workaround:

Create a temporary “Throw-Away” machine

Image throw_AwayVM

When selecting the disk image, select the Analysis VM.

Image selectVM

Open the virtual media manager in VirtualBox:

Image mediaManager

Select disk image of the previously created Throw_away VM in Media Manager:

Image selectThrowAway

Set Disk-Type to Multi-attach: Under the Properties tab in the Type -> Select Multi-attach selection, click Apply.

Image vm_properties

Since the virtual disk image now has the multi-attach flag set, we can add it to VirtualBox as a snapshot using Vmcloak as described in the previous section. To do so execute the following command:

vmcloak snapshot win7x64cuckoo cuckoo1

Afterwards the throw_away VM can be deleted.

7. Updating configuration files

The following describes which changes must be made to configuration files to get the Cuckoo Sandbox up and running. If new systems have been added, an update of the configuration file “virtualbox.conf” is necessary. The configuration file is located under the directory:


New machines can be added manually using the editor or alternatively automated by the following command combination:

while read -r vm ip; do cuckoo machine --add $vm $ip; done < <(vmcloak list vms)

8. Additional features

1. Remote control

By adding guacamole it is possible to remotely control the analysis systems and interact with the malware. A really cool feature that is definitely worth checking out.

2. Moloch

Moloch is used to save network traffic caused by malware in standard PCAP format. Via a web interface the outgoing and incoming connections can be viewed, downloaded and analyzed quickly.

3. Viper and Misp integration

The MISP Threat Exchange Platform is a free and open source software that supports the exchange of threat information, including cyber security indicators. If you are not familiar with the projects Viper and Misp you should definitely have a look at them. Both can be easily integrated into cuckoo. The necessary steps can be found in the Cuckoo documentation.

4. My Start-Script

For starting all necessary services of the Cuckoo sandbox I have written a script which is executed as a cronjob when the system boots. I have put it on GitHub for all interested. Please note that you have to make changes to the ports and services if you want to use it.

If you have come this far, i wish you a lot of fun with your brand new sandbox. Don’t forget to check out the additional modules and extensions of the Cuckoo sandbox.