Installing and Using Cuckoo Malware Analysis Sandbox


In this article we'll explore the Cuckoo Sandbox, an automated malware analysis framework. When installing Cuckoo for the first time, we can quickly determine that it's not all that easy to install Cuckoo [1]. Therefore, to ease the pain we've described the process of how to install Cuckoo on Debian operating system together will all dependencies.

Installing Cuckoo

To install Cuckoo, we must first install all the dependencies, which are described at an official Cuckoo website. Basically we need to run the following commands to install the most basic dependencies needed to run Cuckoo.

# apt-get install python python-sqlalchemy python-bson python-dpkt python-jinja2 python-magic python-pymongo python-gridfs python-libvirt python-bottle python-pefile bridge-utils python-pyrex
# pip install jinja2 pymongo bottle pefile cybox maec django chardet

To sniff packets off the wire, we have to install tcpdump and ensure Cuckoo is able to use it without requiring root permissions.

# apt-get install tcpdump
# setcap cap_net_raw,cap_net_admin=eip /usr/sbin/tcpdump
# getcap /usr/sbin/tcpdump

We might also want to install Yara/Pydeep:

# wget
# tar xvzf ssdeep-2.12.tar.gz
# cd ssdeep-2.12/
# ./configure && make && make install
# git clone
# cd pydeep
# python build
# python install

# wget
# tar xvzf yara-1.7.tar.gz
# cd yara-1.7/
# ./configure && make && make install
# echo "/usr/local/lib" >> /etc/
# ldconfig

# wget
# tar xvzf yara-python-1.7.tar.gz
# cd yara-python-1.7/
# python build
# python install

We can also install Volatility, which requires an additional DiStorm disassembler library. Note that the latest Cuckoo version 1.2 (at the time of this writing) doesn't require DiStorm library, but uses Capstone disassembler library. Nevertheless Volatility still uses DiStorm, which is why we need to install it if we want to use Volatility.

# wget
# unzip
# cd distorm3/
# python build
# python install

# wget
# tar xvzf volatility-2.3.1.tar.g
# cd volatility-2.3.1/
# python build
# python install

At last, it's time to install Cuckoo.

# adduser cuckoo
# usermod -G vboxusers cuckoo
# git clone git://

Installing VirtualBox

To setup a VirtualBox, we must first install appropriate Linux headers and GCC/G++ compiler, which can be done by running the command below. We shouldn't install VirtualBox by simply running “apt-get install virtualbox”, because it often results in installation of an outdated VirtualBox with kernel modules that can't be loaded. To prevent issues with VirtualBox, the best option is to install the kernel headers and then manually download the latest VirtualBox version and install it.

# apt-get install build-essential linux-headers-`uname -r` libvpx1

Next, we have to download the appropriate version of VirtualBox manually from official VirtualBox website.

# wget
# dpkg -i virtualbox-4.3_4.3.18-96516~Debian~wheezy_amd64.deb

Since Cuckoo expects to use the IP address, which belongs to VirtualBox, we must create the networking interface. If the network interface is not present when starting Cuckoo, the program will print a critical error about being unable to bind to and terminate. To create appropriate networking interface, we can execute the following commands.

# VBoxManage hostonlyif create
# ip link set vboxnet0 up
# ip addr add dev vboxnet0

Next we can start Cuckoo normally by running the script as shown below. Note that the script start listening on IP and port 2042.


If we want the vboxnet0 interface to be created at system startup we have to run VBoxManage during system booting, which will automatically create vboxnet* interfaces. Basically, we have to add the “VBoxManage list vms” command to the /etc/rc.local, which will be automatically run on every system startup. Add the following line into the rc.local file before the “exit 0” line.

VBoxManage list vms 2>&1 >> /dev/null

Creating a Virtual Machine

When we've come so far, it's time to create a virtual machine on the same host where Cuckoo is installed. This is required for Cuckoo to be able to start/stop/resume the virtual machine after the malware sample has been executed. Since we're installing Cuckoo in a server environment, which doesn't have GUI interface, it's best if we configure and install the operating system from command-line. We'll be installing a Windows XP SP3 operating system into the virtual machine that will be used by the Cuckoo sandbox.

First we have to create the new XML virtual machine definition file by using createvm command. The command takes a required --name argument specifying the name of the virtual machine. The --register option is used to register the created XML of the VM with the VirtualBox installation.


Afterwards add 256MB of RAM to the virtual machine, disables ACPI, marks DVD as the first booting option, defines host-only networking interface and declares the operation system to be Windows XP.


Next, we have to create the VDI storage, which will be attacked to the previously created virtual machine. The storage of 10GB stored in /srv/vms/ directory can be created by using the createhd command.


To actually attach the VDI image to the virtual machine, the following commands need to be executed.


We might also need the Windows installation iso to the virtual machine, so we'll be able to install the operating system.


Once the iso has been added, we can start the virtual machine by using the startvm command.


At this point, the VirtualBox should be listening for incoming RDP connections on port 3389. If that isn't the case, we probably forgot to install VirtualBox Extension Pack, which can be installed with the extpack command presented below. Note that Oracle Extension Pack is required to be installed on the host in order for VRDP to work.

# wget
# VBoxManage extpack install Oracle_VM_VirtualBox_Extension_Pack-4.3.18-96516.vbox-extpack

After restarting the virtual machine with VboxHeadless, we can observe an additional comment letting us know that VirtualBox is now listening on port 3389 for incoming RDP connections.


We can connect to the host server on port 3389 with rdesktop RDP client after which we'll be presented with the installation procedure as seen below.


We should install the operating system normally by following all the steps, which are normal steps required when installing Windows operating system. When the Windows XP operating system is installed, it should look like presented below.


Now is the time to install the Cuckoo python agent inside the virtual machine. Since we have host-only networking enabled, we can't connect to the internet inside the virtual machine and download the packages we require. We can temporarily add a secondary NAT network interface card and download all the required packages.


After adding a secondary network interface, we'll have access to the internet. Now we have to configure the virtual machine appropriately.

1. Install Python: we have to visit the and download Python, which is a mandatory component when wanting to use Cuckoo guest analyzer. Additionally, we can also install the PIL Python library used for taking screenshots of the Windows desktop during the analysis.

2. Disable Auto Updates: in the Control Panel, we can click on the Automatic Updates and disable it not to interfere with the malware analysis.


3. Disable Windows Firewall: in the Control Panel, we can click on the Windows Firewall and disable it not to interfere with the malware analysis.


4. Additional Software Components: depending on the type of malware we'll be analyzing, we might also install other software components into the virtual machine, like Adobe Reader, Microsoft Office, etc.

5. Installing the Agent: Cuckoo has an agent that runs inside the guest virtual machine and handles the communication and data transfer between guest and host. To start the agent, we need to copy agent/ to the guest VM and run it, which will start the XMLRPC server listening for incoming connections on port 8000.


Since we want to start automatically at startup, we can add the "HKLMSOFTWAREMicrosoftWindowsCurrentVersionRunAgent" registry key with a value “”.


6. Removing NIC: when we've downloaded and installed everything needed by the virtual machine, we have to remove the NAT network interface we've previously added. Basically we have to poweroff the virtual machine, remote the secondary NIC and restart the VM, which can be done by using the commands presented below.


7. Taking a Snapshot: if we restart the guest VM at this point, the VM will automatically call the script to start listening on port 8080. Since that requirement has been satisfied, we can take a snapshot of the virtual machine, which will save the state of the virtual machine. After that we can shut it down and restore it again. By using snapshots we can save the state of the system before infecting it with malicious malware sample. After the analysis is done, we can simply revert the changes by restoring from the snapshot.


The virtual machine is now ready to be used by Cuckoo Sandbox to analyze malware samples. In this section of the article we have only configured the virtual machine without looking at the Cuckoo Sandbox. Therefore, it's imperative that we configure Cuckoo appropriately in order for it to be able to use the configured virtual machine.

Configuring Cuckoo

The configuration file conf/virtualbox.conf contains settings for the VirtualBox virtualization backend Cuckoo will use. The picture below presents all configuration options, where comments and empty lines have been removed. The mode specifies the VirtualBox mode under which we want to run virtual machine: basically we need to choose between gui, sdl or headless; when installing on a remote system without X server we have to use headless mode. The path variable specifies the absolute path to the VBoxManage program, while the machines directive defines a comma-separated list of available virtual machines to be used. Since we've installed only the “WindowsXPSP3” virtual machine that is the only one listed. Afterwards, each of the virtual machines has it's own configuration section presented as “[WindowsXPSP3]”, which contains different configuration variables. The label contains the name of the virtual machines as specified in VirtualBox configuration. The platform defines the operating system of the virtual machine, which can be windows, darwin or linux. The ip defines the IP address of the virtual machine, which must be reachable by the host, otherwise the analysis will fail.


At this point we should also verify whether the host has access to the guest virtual machine. First we can run ipconfig in cmd.exe to verify whether the virtual machine has correct IP address as specified in the virtualbox.conf configuration file.


From the host we should connect to the IP on port 8000 where is listening for incoming connections. If the connection succeeds, it means the host can successfully communicate with the guest virtual machine by using the Cuckoo Agent. On the picture below we can see that the connection is working, but the server responds with error message, which is normal, since it doesn't speak HTTP protocol. What's important is the fact that communication is working, which clearly states that host can use the virtual machine for analysis.


Now is a good time to restart to see whether the virtual machine has been successfully detected. On the picture below, we can see that virtualbox virtual machine manager has need successfully used to load 1 virtual machine and Cuckoo is waiting for analysis tasks.


Additionally, Cuckoo has configuration files in conf/ directory, which are presented and described in the table below.

Configuration File Description

Auxiliary modules, which run concurrently to malware analysis. The following options are most commonly used:

  • [sniffer] enabled: enables or disables the use of an external tcpdump sniffer.
  • [sniffer] interface: specifies the interface on which tcpdump should monitor network traffic.

General Cuckoo settings and analysis options. The following options are most commonly used:

  • [cuckoo] machinery: defines the machinery module used to interact with virtual machines, which depends on the backend virtualization software we’re using.
  • [cuckoo] memory_dump: enables the creation of memory dump before shutting down the virtual machine; this currently works only in VirtualBox/KVM.
  • [resultserver] ip: the IP used by the analysis virtual machines to send logs and reports to. This IP address should be accessible from the analysis virtual machines.
  • [resultserver] port: the PORT number where the result server will listen for incoming connections from analysis virtual machines.
  • [database] connection: specifies the database used by Cuckoo to keep track of submissions, samples and execution.
esx.conf Options for ESX virtualization software.
kvm.conf Options for KVM virtualization software.

Options for volatility configuration. The following options are most commonly used:

  • [basic] guest_profile: a predefined profile that will be used with volatility to analyze memory dump, which saves time when identifying it. Since we’re using Windows XP SP3 for analysis, we can set this option to WinXPSP3x86.
  • [basic] delete_memdump: whether or not the memory dump will be deleted after the analysis.
  • [plugin] enabled: whether to enable or disable the plugin.
  • [plugin] filter: enable or disable known clean data from the resulting report.
physical.conf Options for defining physical machines to use for analysis.

Options for enabling, disabling and configuring processing modules. Each of the processing modules has an enable option accepting arguments ‘yes|no’, which enable or disable the module, but can also have other configuration parameters. We can enable all of the modules if we want them to process the malware sample. The modules are the following:

  • analysisinfo
  • behavior
  • debug
  • dropped
  • memory
  • network
  • procmemory
  • static
  • strings
  • targetinfo
  • virustotal

Configuration options for reporting the analysis results, which can be dumped in various formats. The following reporting modules are supported, which accept the enabled parameter that can be set to ‘yes|no’ to enable|disable the generation of such report.

  • jsondump
  • reporthtml
  • mmdef
  • maec40
  • mongodb

Options for VirtualBox virtualization software. The following options are most commonly used:

  • [virtualbox] mode: specifies the mode in which VirtualBox will operate. For remote servers that don’t have a GUI interface, this is most often set to headless.
  • [virtualbox] path: an absolute path to the VboxManage binary.
  • [virtualbox] machines: a comma-separated list of virtual machines that will be used for malware analysis.
  • [vmname] label: the name of the existing virtual machine.
  • [vmname] platform: the operating system installed in the virtual machine.
vmware.conf Options for VMware virtualization software.

A problem that often occurs when using Cuckoo with VirtualBox is presented below, which states that analysis virtual machine was not able to access the resultserver's IP. The problem is the “[resultserver] ip” directive in cuckoo.conf, which must specify the IP address of the host interface the guest is connected to.


To resolve the problem, we need to ensure the guest virtual machine can access the specified IP address on the configured port. An example of successfully connecting to the can be seen on the picture below, where the connection was established, but no data was received.


This verifies that virtual machine can access the result server. In case of VirtualBox, we must ensure the networking interface used by the guest virtual machine is up prior to starting Cuckoo, otherwise such error will be displayed in stdout. To ensure the interface is up, we can manually start and stop the virtual machine prior to running Cuckoo.


Analyzing Malware Samples

Now it would be a good time to submit a malware sample to Cuckoo for analysis. There are multiple ways a malware sample can be submitted to Cuckoo for analysis and are presented below.

Creating a Malicious Malware Sample

Let's first create a malicious sample with msfpayload to analyze. The malicious sample can be generated with the command below, which generates a meterpreter.exe binary executable ready to be run on Winows operating system.


We should also create the meter.rc script that will automatically start a Meterpreter handler to listen for incoming Meterpreter connections. The script should be invoked with “msfconsole -r meter.rc” command, which will start up the listener.


We should also start meterpreter.exe program from a Windows operating system to confirm that it's working as expected and can connect back to the handler. Once we've confirmed the program is working it's time to submit it to Cuckoo for analysis.

Using Command Line Interface

The commands below are first creating a new directory to hold malware samples /srv/malware/, after which the meterpreter.exe malware is moved to that directory. At last the is called with various parameters to analyze the malware sample on Windows platform on WindowsXPSP3 virtual machine.


Every configuration option of the util can be seen below and is presented for completeness.


Using Web Interface

To start a web interface, we have to run the utils/ utility, which will start listening on port 8080.


To start the web interface, all we need to do is run, but we can optionally make it bind to an arbitrary port by using the --port argument. Afterwards, we can connect to the 8080 port with a web browser, which will display a Cuckoo web interface as shown below. We can choose the meterpreter.exe file and submit it for analysis the same way as we did with the script.


Once the analysis is complete, we can see the results in a web interface. One of the most most interesting details is the “File Details” section of the report presented below, where we can see the filename, file size and a lot of other useful stuff, like whether the meterpreter sample is detected by Yara or PEiD.


Alternatively, we should rather use Apache to server the Cuckoo webpage, which we can do by creating the /etc/apache2/sites-enabled/cuckoo and using the following configuration directives. The WSGIScriptAlias maps a URL to a filesystem location and marks the target as a WSGI script: whenever we request the http://analyzemalware/ in our web browser, the server will run the WSGI application defined in script. The WSGIDaemonProcess specifies the distrint daemon process for applications, which can be run under a different usernams as Apache. The rest of the options in VirtualHost directive should be self-explanatory.

<VirtualHost *:443>
ServerName analyzemalware
WSGIDaemonProcess web user=cuckoo group=cuckoo processes=1 threads=5
WSGIScriptAlias / /srv/cuckoo/web/web/
<Directory /srv/cuckoo/web/web/>
AllowOverride All
Order deny,allow
Allow from all
Alias /static /srv/cuckoo/web/static
<Directory /srv/cuckoo/web/static>
AllowOverride All
Order deny,allow
Allow from all
ErrorLog /var/log/cuckoo/web-error.log
CustomLog /var/log/cuckoo/web-access.log combined
LogLevel warn
ServerSignature Off

# ssL
SSLEngine on
SSLCertificateFile /etc/ssl/certs/ssl-cert-snakeoil.pem
SSLCertificateKeyFile /etc/ssl/private/ssl-cert-snakeoil.key

When restarting Apache web server and visiting the Cuckoo web address as specified in the configuration file, the Cuckoo web interface will be shown.

Running Cuckoo as Normal User

After we've configured and tested everything, we should run Cuckoo as normal cuckoo user without root privileges: we should never be executing malware as root, because malware can somehow break out of the virtualization environment and execute code under the user virtualization software is running. First we have to transform the previously created virtual machine to cuckoo user's home directory /home/cuckoo/ and register it with the cuckoo user. We should also run the registervm command with VboxManage, which will tell VirtualBox about the previously created virtual machine. We have to run commands presented below:


After that we can execute ./ normally as shown on the picture below, which will be able to import the previously created virtual machine without any problems.


We can also verify that Cuckoo is actually running under the cuckoo username, which is shown below.


Cuckoo Analysis Packages

Cuckoo contains multiple analysis packages, which guide Cuckoo's analyzer when conducting the analysis. The analysis packages are contained in the analyzer/windows/modules/packages/ directory and are presented in the table below.

Cuckoo analysis packages
Cuckoo Analysis Package Description
applet Used to analyze Java applets.
bin Used to analyze binary data.
cpl Used to analyze control panel applets.
dll Used to analyze dynamically linked libraries.
doc Used to analyze Microsoft Word documents.
exe Used to analyze Windows executables.
generic Used to analyze generic samples.
html Used to analyze HTML code.
ie Used to analyze Internet Explorer process when opening an URL.
jar Used to analyze Java JAR files.
pdf Used to analyze PDF documents.
ppt Used to analyze PPT documents.
ps1 Used to analyze powershell files.
python Used to analyze python files.
vbs Used to analyze VBScripts files.
xls Used to analyze XSL documents.
zip Used to analyze ZIP archives.

The analysis packages are basically just modules that tell Cuckoo how the uploaded files need to be tested. For executable files, the looks like presented below, where the arguments parameter is taken from request and added to the program name.


From the code snippet above, we can see that start() function basically calls the execute() function, which is part of the Package class defined in the ./analyzer/windows/lib/common/ Python file.


We can take a look at the self.options.get function calls to determine which arguments it accepts. The argument free is used to enable behavior logs, the arguments argument is used to specify command-line arguments to be passed to the malware sample. The procmemdump enables the memory dump of actively monitored process, while the dll specifies the name of the optional DLL that will be injected into the process instead of cuckoomon.dll.

To use a specific package, we should choose it when submitting a new malware sample for analysis.

Analyzing the Cuckoo's DLL Injection

Cuckoo injects the cuckoomon.dll DLL library into the process by using the inject() function defined in analyzer/windows/lib/api/


Cuckoo will then try to inject the DLL into the process by using the following functions: VirtualAllocEx, WriteProcessMemory, CreateEventA and CreateRemoteThread.

  • VirtualAllocEx


  • WriteProcessMemory


  • QueueUserAPC


  • CreateEventA


  • CreateRemoteThread


If we look at the code, we can see those are standard Win32 API functions that can be used to allocate memory inside another process, write a DLL into the allocated memory and create a new thread in the remote process which executes the injected DLL. Therefore, code execution inside an arbitrary remote process can be done by simply calling a few functions and passing a DLL, which will get executed.


In this article we've taken a look at Cuckoo malware analyst sandbox. We've approached the problem from the beginning and first installed and configured Cuckoo from scratch. Then we've setup a virtual machine running Windows XP, which will be used to run malware samples.

Since there are a myriad of malware samples being distributed around the Internet every day, it's important to analyze them quickly and efficiently and this is where Cuckoo comes in. Since Cuckoo is open-source anybody can install it for free and most importantly contribute new features that possibly make malware analysis more reliable.

I urge you to try and install Cuckoo, since the process is quite easy and if anything is unclear don't forget to comment below.


[1] Cuckoo Installation,