Cuckoo – ESXi

Cuckoo is a sandbox for automated Malware Analysis. The idea of a malware sandbox is to have a collection of virtual machines that you can setup up, run malware and when your finished reset to a clean state so you can start again without mixing samples.

Cuckoo takes it one step further and generates reports based on Dynamic and some static behaviours the malware exhibited while it was in the sandbox.

This installation process is specifically to install Cuckoo Sandbox in to an ESXi environment. Before i start its important to note that this will NOT work on the free version of ESXi. The API is not enabled as part of the free license.

The Analysis machines I create are not network connected and instead use inetsim to emulate internet access.

For the most part the Cuckoo Guides provided by Cuckoo are great and if your doing a standard install this should be enough to get you going. There are several steps missing from these guides if your installing in to ESXi.

The Host OS is an Ubuntu Server 14.04 Virtual Machine running on the ESXi. For my network i have given the VM 3 Network Interfaces. The configuration of these is covered in the Network Section.

Update the OS

sudo apt-get update
sudo apt-get upgrade


Core Dependencies

Grab our core dependencies. This is all one long line, make sure you copy to the end.

sudo apt-get install python-sqlalchemy python-bson python-dpkt python-jinja2 python-magic python-pymongo python-gridfs python-libvirt python-bottle python-pefile python-chardet python-django libgeoip-dev libjpeg-dev


Optional Elements

These steps install Yara and SSDeep. They are optional but there’s no reason not to add them.

sudo apt-get install build-essential python-dev python-pip git automake libtool Must be 2x or greater

tar zxf v3.1.0.tar.gz
cd yara-3.1.0/
sudo make install

Now lets do the python bindings.

cd yara-python/
sudo python install

grab the latest version and away we go. Tested with version 2.11.1

tar zxf ssdeep-2.11.1.tar.gz
cd ssdeep-2.11.1/
./configure && make
sudo make install

Lets install the python bindings to go with it.

sudo pip install pydeep

Network Components.

Getting the network configuration correct is one of the most important aspects, if Cuckoo cant speak to the analysis machines then nothing is going to work.

As i mentioned earlier i have 3 network cards on my Cuckoo Controller as detailed here.

eth0 – This connects to my home environment and allows me to access the Cuckoo Interface. It is statically assigned to my network.

eth1 – Connects to the Host Only Network in Promiscuous mode.

eth2 – Connects to a Host Only Network with all the Analysis VMs. It is statically assigned to my network.

The following is my /etc/network/interfaces

# This file describes the network interfaces available on your system
# and how to activate them. For more information, see interfaces(5).

# The loopback network interface
auto lo
iface lo inet loopback

# The primary network interface
auto eth0
iface eth0 inet static

# The Monitor network interface
auto eth1
iface eth1 inet manual
   up ip address add 0/0 dev $IFACE
   up ip link set $IFACE up
   up ip link set $IFACE promisc on
down ip link set $IFACE promisc off
down ip link set $IFACE down

# The Analysis network interface
auto eth2
iface eth2 inet static

The final step is to add a line to /etc/rc.local to ensure our nic enters promisc mode on reboot.

# By default this script does nothing.
ifconfig eth1 up
ifconfig eth1 promisc
exit 0

Enable non root access to tcpdump with the following command.

sudo setcap cap_net_raw,cap_net_admin=eip /usr/sbin/tcpdump

Libvert – ESXi

This is the major missing point from the Cuckoo Docs, we need to build libvert and tell it to include ESXi support.

sudo apt-get install libpciaccess-dev libnl-dev pkg-config libxml2-dev libgnutls-dev libdevmapper-dev libcurl4-gnutls-dev
tar zxf libvirt-1.2.7.tar.gz libvirt-1.3.4
cd libvirt-1.2.7/
./configure --with-esx=yes
sudo make install

That should complete with no errors.


Cuckoo is capable of running multiple analysis tasks concurrently, this is not supported if your using the default SQLite Database options. We are going to install MySql to add this support.

sudo apt-get install mysql-server
sudo apt-get install python-mysqldb
sudo mysql_install_db
sudo mysql_secure_installation


Say no to changing the root password and YES to all other questions.

mysql -u root -p
GRANT ALL ON cuckoo.* TO 'cuckoo'@'localhost' IDENTIFIED BY 'newpassword';


Now lets grab the latest version of cuckoo

git clone

Before we can run cuckoo we need to make the configuration changes for our environment.


Line 20  machinery = esx

Line 62  ip =

Line 82  resolve_dns = on # Change as suits your needs.

Line 91 connection = mysql://cuckoo:newpassword@localhost/cuckoo # The same password you created in the mysql setup.


line 11 interface = eth1


Find [mongodb] and set

enabled = yes


This config file is where we declare all our analysis Virtual Machines that cuckoo can use. The configuration of these Analysis machines is detailed later on.

The main section is where we setup our connection these are the details for the ESXi host NOT the cuckoo controller.

dsn = esx://
username = username_goes_here
password = password_goes_here

machines = analysis1

The machines line is a , seperated list of machines that are available for cuckoo to use. Each machine listed here must have its own config section.

The config sections contain a lot of comments to help you understand the sections. Here is an example of the relevant fields with the comments removed.

machines = Win7Adobe9, Win7Adobe10, Win7Adobe11
label = Win7_1
platform = windows
snapshot = SnapShotName
ip =
tags = Win7,Office07,Adobe9.1

label = Win7_2
platform = windows
snapshot = SnapShotName
ip =
tags = Win7,Office07,Adobe10.0

label = Win7_2
platform = windows
snapshot = SnapShotName
ip =
tags = Win7,Office07,Adobe11

Community Modules

There are several community contributions that are useful to have so we want to grab these as well. Some of the community modules can be noisy so remove them as you see fit. they can be found under /modules/signatures

cd utils
./ -a

Django Web Interface

Cuckoo comes with two web interfaces. A basic Bottle interface and a more feature full Django interface. This guide will be using the latter of these options.

sudo apt-get install mongodb python-django



We could add the cuckkoo main thread as an upstart job as well but this could be problemtic when debugging issues.

As an example
add this content to \etc\init\cuckooapi.conf

description "Cuckoo Web API Service"
author "Kevin Breen @kevthehermit"

start on runlevel [234]
stop on runlevel [0156]

setuid thehermit
setgid thehermit

chdir /home/thehermit/cuckoo/utils
exec python -H -p 5556

add this content to \etc\init\cuckooweb.conf

description "Cuckoo Web API Service"
author "Kevin Breen @kevthehermit"
start on runlevel [234]
stop on runlevel [0156]
setuid thehermit
setgid thehermit
chdir /home/thehermit/cuckoo/utils
exec python -H -p 5556

And dont forget to replace the uid and gid with your own. DO NOT LEAVE EMPTY AND DO NOT USE ROOT

And change the chdir line as required. -H says listen on any IP address i have configured. If you use localhost no one external can use the api or web interface

  • SpiK369

    I follow your guide and I find these problems:
    1) mysql > why you use the command &gt ?
    2) mysql FLUSH PRIVLIGES; is missing the I

    Do you solve the problem with cuckoo option mem dump analisys with ESX? I receive an libvirt error….

  • Jason Alexander

    Can you describe your vswitch configuration. I assume you have interface on for the cuckoo server in the internet vswitch and then a second vswitch which eth1 and eth2 and all the victim vM’s live in?