Install CuckooBox for Malware and Virus Analysis

wpid-featuredImage.pngCuckooBox is an automatic malware analysis tool written 100% in Python, the architecture is very interesting and it is based on a virtualisation engine like virtualbox to maintain a “fresh” pc always at hand to run the malware called the client, inside this client it is run an agent also written 100% in Python to monitor the different calls that the malware do to the dll’s, host that try to connect, etc… The CuckooBox per se it is called the server on this architecture, and it is used to send the binaries, urls, documents, etc.. to test on the clients once the analysis is done the report is send back and stored on the server, where it could be seen through the server web interface.

It is important to mention that the connection between the Server and the client is done through an isolated network set up by virtual box, it is configured that way in order to avoid the propagation of the malware and to communicate effectively between the client and the server to send the analysis report, infected binaries, etc….The first thing that we’re gonna need for the CuckooBox Installation is a Virtual Machine with Ubuntu 12.04 LTS Desktop fully updated with virtual box guest additions installed, I used the Desktop version instead of the server version only to get the gnome desktop installed that is going to facilitate a little bit the installation.

Installing the Server

Installing Python Libraries

Python 2.7.3 is preinstalled on the Ubuntu Desktop, so we are going to need to install the different python libraries, these are:

  • Sqlalchemy
  • Bson
  • DPKT
  • Jinja2
  • Magic
  • Pydeep
  • Pymongo
  • Yara
  • Libvirt
  • Bottlepy
  • Django
  • Pefile
  • Volatility
  • MAEC Python bindings
  • Chardet
Some of this libraries could be installed with “apt-get” utility of ubuntu, others could be installed with “pip”and others should be installed manually because require the compilation of son C libraries first, lets make the installation step by step.
Install the libraries with “apt-get” first with the following command:

sudo apt-get install apt-get python-sqlalchemy python-bson python-dpkt python-jinja2 python-magic python-pymongo python-libvirt python-bottle python-pefile python-chardet

We managed to install almost all the libraries, lets install those that could be installed with “pip”, but first pip should be installed so issue the command to install “pip” and some python developer files:

sudo apt-get install python-pip python-dev libxml2-dev libxslt-dev

and now the libraries with:

sudo pip install django cybox

once finished:

sudo pip install MAEC

At this point remains only three libraries left to install, yara is used to match signatures, pydeep is used to calculate fuzzy hashes, while Volatility is a whole framework used for the forensic analysis on memory, we’re going to install yard and pydeep but volatile will be installed at the end.

Install Pydeep

To install pydeep you should first install ssdeep through “apt-get” by issuing the following command:

sudo apt-get install ssdeep libfuzzy-dev

Install also “git’ to clone the project directory:

sudo apt-get install git

Go to the directory Download, clone the pydeep project and install the library manually:

git clone

cd pydeep

sudo python install

Install Yara

Previously to the installation of yard we should install libtool and automate on the Ubuntu Desktop:

sudo apt-get install libtool automake

Then download yara form the git repository and install it:

cd && cd Downloads


tar -xvzf 2.1.0.tar.gz

cd yara-2.1.0

chmod a+x


sudo make install

Once Yara was installed it is time to install yara-python to do that please issue the following commands:

cd yara-python

sudo python install


CuckooBox needs tcpdump installed, fortunately it is already installed on the Ubuntu Desktop, so at this time we only need to change the permissions so cuckoo could run it without root permissions, that is done with the following command:

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

Installing Virtualbox Engine

In theory when you installed the virtual box guest additions you installed virtual box on your Desktop, to verify if that is correct please issue:

sudo virtualbox

and the Virtualbox manager gui should open, if that not happens then you could install it with the following command:

sudo apt-get install virtualbox

 Installing MongoDb

MongoDB is used by cuckoo, to install it just type:

sudo apt-get install mongodb

Installing Volatility

Volatility will give you the option to analyse the memory of the guest once is attacked by the malware, so to install it you should download the source with:

cd && cd Download

wget wget

Once downloaded, unzip it and install it:


cd volatility-2.3.1

sudo python install

Creating a guest Machine

Before to configure the guest machine, it is important to configure a Host-Only network, to do so, open the VirtualBox manager inside Ubuntu and go to “File —> Preferences”, then on the menu of the left select “Network”, then add a new network with the button with the plus sign to the right of the windows.
Now there should be a network called vboxnet0, with an ip address of for the host machine and a DHCP server giving address on that network beginning with the and finishing with
It is recommended to use a Windows XP with SP3 for the guest machine, create a new virtual machine inside Ubuntu with the specifications that better suit your needs, it is important to take into account that if you want to test malwares and viruses inside documents, the application must be installed, for example if you want to check malwares in pdf files the Acrobat reader should be installed.
The only requisite is that the network adapter should be set to “Host-only Adapter” setup to the recently created network “vboxnet0″

Once installed Windows XP, you should install some software the best thing to do it is to set a shared folder between  the ubuntu host and the windows guest.

The ip address of the Windows XP should be set to an address on the subnet not used by the DHCP Server, use as gateway address the host machine and use for the fns server the dns of your local network the automatic updates should be disables as well as the Windows XP Firewall. Make sure that you could ping the host machine from the guest windows machine.

Software to install on the Windows Guest

On the Windows Xp guest you should install the following software:
Add “C:\Python27” to the Environmental Variables of Windows XP, to do this follow the following steps:
  1. Right Click on My Computer and select Properties
  2. Click on Advanced tab
  3. Click on the Button Environment Variables
  4. On System Variables select Path and click on Edit
  5. At the end of the variable value add a semicolon and the add “C:\Python27”
  6. Restart the virtual Machine

Once finished the installation you should copy the agent script from the host to the guest using the share folder created previously, the agent is located in “/opt/cuckoo/agent/” on the windows machine should be renamed to “agent.pyw”

Copy the agent to “C:\Python27\Scripts” and modify the registry following these steps:
  1. Click on Start Menu and select Run
  2. Type regedit and press return
  3. Navigate to HKEY_LOCAL_MACHINESOFTWAREMicrosoftWindowsCurrentVersionRun
  4. Right click on the right pane and select new string value
  5. On name type: Agent
  6. On data type: C:\Python27\Scripts\agent.pyw

Now start agent.pyw it should not open a console, to see if agent is running open a command line and type “netstat -na” you should see a socket created listening on

The last step is to save the state of the virtual machine, but before do that do a restart of the windows machine and make sure that the agent is running with the command specified earlier.
Create a snapshot of the machine and save it with the name “WinXPAgent01” and power off the guest machine.

Grant Access to internet from the Windows guest

To grant access to Internet from the Windows guest you should configure some rules with iptables on the Ubuntu host, we are not going to manage traffic inbound or outbound the host but only the forwarding traffic through the host, once the rules are added we should enable ipv4 routing and make the iptable rules persistent.
Before adding the rules to iptables lets install a package that is going to permit to make the rules persistent:

sudo apt-get install iptables-persistent

Then we need to add the following rules:

sudo iptables -A FORWARD -o eth0 -i vboxnet0 -s -m conntrack –ctstate NEW -j ACCEPT

sudo iptables -A FORWARD -m conntrack –ctstate ESTABLISHED,RELATED -j ACCEPT

sudo iptables -A POSTROUTING -t nat -j MASQUERADE

sudo iptables -P FORWARD DROP

And make the rules persistent persistent with:

sudo sh -c “iptables-save > /etc/iptables-persistent/rules.v4”

The last step is to enable routing on the Host:

sudo sysctl -w net.ipv4.ip_forward=1

Check if your windows guest has access to internet, this is going to be useful to analyse malwares on url’s.

Install Cuckoo

Creating a user

Lets create a new user to run cuckoo and lets add it to the vboxusers group so it have the permissions to run virtualbox.

sudo adduser cuckoo

sudo usermod -G vboxusers cuckoo

Installing cuckoo

To install cuckoo we should clone the git directory wherever we want, we are going to install it in /opt directory with the following commands:

cd /opt

sudo git clone

sudo chown -R user:usergroup cuckoo

Where user:usergroup is the user used to login to the ubuntu machine and the group is the group to which user belongs

Configuring cuckoo

There are a few things to change on the configuration files, because CuckooBox works pretty much out of the box (obviously check the files to see if there are some parameters that you are interested in), the modifications to do to the configuration files are:



memory_dump = on


ip = [ip address of the vboxnet0 interface, to check it issue on terminal ifconfig vboxnet0, usually]



label = [Name of the Windows guest virtual machine as configured on VirtualBox]

ip = [ip address configured i the windows guest]

snapshot = [the name of the snapshot taken with virtual box]



delete_memdump = yes



enabled = yes


enabled = yes

key = [key of the virus total API, could be obtained registering in]



enabled = yes


enabled = yes

Starting Cuckoo

The installation and the configuration is done, to start cuckoo use the command:

sudo python /opt/cuckoo/

To send binaries, files or url’s to the guest machine use the following command:

sudo python /opt/cuckoo/utils/ PATH_TO_BINARY

sudo python /opt/cuckoo/utils/ —url http://URL_TO_MALICIOUS_SITE

If the file to analyse is a cpl, zip, etc you should specify the type of package sent with:

sudo python /opt/cuckoo/utils/ —package PACKAGE PATH_TO_FILE

Cuckoo is capable to analyse different types of packages like:

  • applets —> To analyse java Applets
  • bin —> To analyse generic binary data
  • cpl —> To analyse Control Panel Applets
  • dll —> To analyse Dynamically Linked Libraries
  • doc —> To analyse Ms Word Documents
  • exe —> Default Package for Windows Executables
  • generic —> To analyse generic samples via cmd.exe
  • html —>  To analyse Internet Explorer behaviour opening an html file
  • ie —> To analyze Internet Explorer behaviour opening an url
  • jar —> To analyse Java JAR
  • pdf —> To analyse PDF Documents
  • vbs —> To analyse VBScripts files
  • xls —> To analyse Ms Excel Documents
  • zip —> To analyse ZIP Archives

You could specify also different options for each package, go to the Cuckoo documentation for more information.

Another method to send files to the Guest Machine is through the Web Interface, to start the web interface use the command:

sudo python /opt/cuckoo/utils/

The Web Interface is also useful to see the reports generated by the Host server.

Virus and Malware resources

Cuckoo Sandbox Documentation