Installing Cuckoo

In the first post of the Cuckoo Sandbox series, we will cover installation and basic configuration to get you started with automated dynamic malware analysis. 

Background

Cuckoobox is an open source platform for automated dynamic analysis written by Claudio Guarnieri (nex) for the Google Summer of Code project in 2010. In 2012, Cuckoo was sponsored by Rapid7's Magnificent7 program "due to [its] innovative approach to traditional malware analysis". Currently Cuckoo can analyze Windows Executables, DLLs, PDF's, Office Docs, and URLs. Each sample to be analyzed is run through its own "clean" virtual machine, execution is tracked, and after completion the virtual machine is reverted back to its original "clean" state. A detailed report of the behavior the sample produced is generated and cataloged for later review. The system is written in Python and is very modular so it could be leveraged in other frameworks as well as extended for additional analysis or reporting. 

Installation

Cuckoo has EXCELLENT documentation so check there for any questions that may arise after running through this installation. There is also an IRC channel (#cuckoosandbox on freenode) and community question portal for additional help. 

As with the MASTIFF installation I am assuming a base installation of Ubuntu 12.10. As always the first step I perform is ensure that I have a fully updated system and have openssh installed for remote management. 

sudo apt-get update; sudo apt-get upgrade -y; sudo apt-get dist-upgrade -y; sudo apt-get autoremove -y; sudo apt-get install openssh-server -y; sudo shutdown -r now later

Next we will begin the installation of the required dependencies.

sudo apt-get install python python-dev python-sqlalchemy python-dpkt python-jinja2 python-magic python-pymongo python-bottle -y

It is also recommended to install python-pefile, this could be accomplished by installing pefile from the apt repo or from source. I mention this as MASTIFF required pefile to be built from source. If both applications will be installed on the same machine I recommend going with the source option. 

PEfile from APT

sudo apt-get install python-pefile

PEfile from source 

cd /opt

svn checkout http://pefile.googlecode.com/svn/trunk/ pefile

cd /opt/pefile

python setup.py build

sudo python setup.py build install

Next we need to install pydeep for ssdeep fuzzy hashes of samples.

sudo apt-get install build-essential git libpcre3 libpcre3-dev libpcre++-dev -y

cd /opt/

wget http://sourceforge.net/projects/ssdeep/files/ssdeep-2.9/ssdeep-2.9.tar.gz

tar -xvzf ssdeep-2.9.tar.gz

rm -f ssdeep-2.9.tar.gz

mv ssdeep-2.9 ssdeep

cd /opt/ssdeep/

./configure

make

sudo make install

sudo ldconfig

cd /opt/

git clone https://github.com/kbandla/pydeep.git pydeep

cd /opt/pydeep/

https://github.com/kbandla/pydeep.git

python setup.py build

sudo python setup.py install

Yara and Yara Python also need to be installed for Yara signature analysis.

sudo apt-get install automake -y

cd /opt

svn checkout http://yara-project.googlecode.com/svn/trunk/ yara

cd /opt/yara

sudo ln -s /usr/bin/aclocal-1.11 /usr/bin/aclocal-1.12

./configure

make

sudo make install

cd yara-python

python setup.py build

sudo python setup.py install

We need to install tcpdump in order to dump network traffic occurring during analysis. 

sudo apt-get install tcpdump

To ensure we do not need to run Cuckoo as root we need to set Linux capabilities for tcpdump.

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

Since Cuckoo leverages virtualization we will need to install a virtualization hypervisor. Since version 0.4 Cuckoo has been architecturally independent from the virtualization software. This means Cuckoo can leverage KVM, Virtualbox, or VMware as the hypervisor and could potentially be extended for use with other hypervisors. That being said THIS guide will focus on installation with VirtualBox for simplicity. However, there are pros and cons for each hypervisor that need to be taken into account for your specific environment. The following will document installing the latest version (as of this writing) of VirtualBox. 

sudo apt-get install libqt4-opengl libsdl1.2debian -y

wget http://download.virtualbox.org/virtualbox/4.2.8/virtualbox-4.2_4.2.8-83876~Ubuntu~quantal_amd64.deb

wget http://download.virtualbox.org/virtualbox/4.2.8/Oracle_VM_VirtualBox_Extension_

Pack-4.2.8-83876.vbox-extpack

sudo dpkg -i virtualbox-4.2_4.2.8-83876~Ubuntu~quantal_amd64.deb

sudo VBoxManage extpack install Oracle_VM_VirtualBox_Extension_Pack-4.2.8-83876.vbox-extpack

sudo /etc/init.d/vboxdrv setup

Now that VirtualBox is installed, create a user for cuckoo to utilize

sudo useradd cuckoo

sudo usermod -g vboxusers cuckoo

Now we are ready to pull down Cuckoo

git clone https://github.com/cuckoobox/cuckoo.git cuckoo

Thats it! Now we need to configure Cuckoo and create some analysis VMs. Change directories into /opt/cuckoo/conf. You will notice there are a few files, we will concern ourselves with three of them: cuckoo.conf, virtualbox.conf, and reporting.conf. First up cuckoo.conf - there is not much to change here if you are working with VirtualBox. The only thing you will need to do is specify some database credentials if you want to utilize something other than the default sqlite. I prefer mysql so I will install and configure that.

sudo apt-get install mysql-server python-mysqldb -y

mysql -u root -p

create database cuckoo;

grant all privileges on cuckoo.* to cuckoo@localhost identified by 'Cuck00@n@lyst!' ;

flush privileges;

quit;

Once  mysql is installed edit cuckoo.conf to reflect the database connection parameters you configured above, in this add  mysql://cuckoo:Cuck00@n@lyst!@localhost/cuckoo to the connection line under database.

Next we will look at virtualbox.conf.

[virtualbox]

mode = gui

path = /usr/bin/VBoxManage

machines = cuckoonode01, cuckoonode02, cuckoonode10,cuckoonode20

[cuckoonode01]

label = cuckoonode01

platform = windows

ip = 192.168.56.101

[cuckoonode02]

label = cuckoonode02

platform = windows

ip = 192.168.56.102

[cuckoonode10]

label = cuckoonode10

platform = darwin

ip = 192.168.56.110

[cuckoonode20]

label = cuckoonode20

platform = linux

ip = 192.168.56.120

The mode defaults to gui which means that you will be able to see the VirtualBox guest as the malware is executed. This option can also be changed to headless if you do not wish to see the VM. Next you will see the virtual machines directive. This is a comma separated list for each virtual machine that will be defined beneath the virtual machine list. Finally the details of the individual VMs are supplied. Platform can be either Windows, Darwin, or Linux. The IP address of the VM MUST be static as cuckoo needs to know this prior to booting the machine.

The last configuration file we need to concern ourselves with is the reporting.conf. This file contains the format of the reports that will be produced upon completion of analyzing a sample. By default the only output options that are enabled are jsondump and reporthtml. This is enough to produce a nice web report but I also like to enable the hpfclient option as well. If you haven't heard about hpfeeds, it is definitely worth the research. Setting up hpfeeds will be the topic of another blog post in the near future.

We are now done with the configuration of CuckooBox. We still need to build an analysis platform prior to submitting any samples. The installation and configuration of a "victim" machine / analysis platform is outside of the scope of this blog post. I will however briefly describe the steps necessary to build out a functioning VM for use in Cuckoo.

• Install Windows XP SP3 or Windows 7 with UAC disabled
• Disable Windows Firewall
• Configure the network
  • Set a static IP address in the network range of the vboxnet0 (default host only network)
  • Configure iptables
    • sudo iptables -A FORWARD -o eth0 -i vboxnet0 -s 192.168.56.0/24 -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
  • Enable forwarding
    • sudo sysctl -w net.ipv4.ip_forward=1
    • sudo sysctl -p
• Rename VM based on virtualbox.conf
• Install Python 2.7
• Install Python Imaging Library 1.7 for Python 2.7 
• Install additional software (not required but recommended)
  • Microsoft Office
  • Adobe Reader
  • Additional browsers
  • etc
• Install the Cuckoo agent.py
  • Download from \\vboxsvr\ TEMPORARY share (remove prior to snapshot)
  • cd /opt/cuckoo/agent; python -m SimpleHTTPServer - and download to VM
  • Save/Rename agent.py to agent.pyw if you do not want the terminal window present
• Execute agent.pyw
• Snapshot the VM
  • VBoxManage snapshot "cuckoonode01" take "pristine" --pause
  • VBoxManage controlvm "cuckoonode01" poweroff
  • VBoxManage snapshot "cuckoonode01" restorecurrent

We are now done with the first analysis platform. To save time, this process can be simplified to a clone operation. Once the clone of the template is complete you will need to make a few small modifications:

• Rename the VM (based on virtualbox.conf)
• ReIP the machine (based on virtualbox.conf)
• Stop the process associated with agent.py and reexecute agent.pyw
• Take a new "pristine" snapshot using the steps outlined above

For the next step I recommend installing tmux or screen to manage cuckoo in one terminal (especially if you are remotely managing the machine).

sudo apt-get install tmux -y

tmux

cd /opt/cuckoo

Next start cuckoo with the following

python cuckoo.py

If you do not receive any errors and the status message indicates one or more VMs are loaded you are good to go. Open another screen in tmux (<ctrl>+b).

cd /opt/cuckoo/utils

python web.py

This should launch a web server on port 8080 for all interfaces. The web utility is a simple interface that will allow you to view the reports of submitted samples (clicking browse) and will also let you submit individual samples for processing. If you are adding multiple samples for processing it is best to utilize the submit.py utility. By default you can submit:

• Windows PEs
• DLLs
• PDFs
• Office Documents
• URLs

usage: submit.py [-h] [--url] [--package PACKAGE] [--custom CUSTOM]

                 [--timeout TIMEOUT] [--options OPTIONS] [--priority PRIORITY]

                 [--machine MACHINE] [--platform PLATFORM] [--memory]

                 [--enforce-timeout]

                 target

positional arguments:

  target               URL, path to the file or folder to analyze

optional arguments:

  -h, --help           show this help message and exit

  --url                Specify whether the target is an URL

  --package PACKAGE    Specify an analysis package

  --custom CUSTOM      Specify any custom value

  --timeout TIMEOUT    Specify an analysis timeout

  --options OPTIONS    Specify options for the analysis package (e.g.

                       "name=value,name2=value2")

  --priority PRIORITY  Specify a priority for the analysis represented by an

                       integer

  --machine MACHINE    Specify the identifier of a machine you want to use

  --platform PLATFORM  Specify the operating system platform you want to use

                       (windows/darwin/linux)

  --memory             Enable to take a memory dump of the analysis machine

  --enforce-timeout    Enable to force the analysis to run for the full

                       timeout period

The options above provide a lot of flexibility to script the submission process, but it is as simple as

python submit.py --url http://www.tekdefense.com

python submit.py malware.exe

python submit.py malware.pdf

python submit.py malware.doc

Simple right? The above would have produced 4 entries in the submission queue. If there are more entries in the queue than machines available for processing, the sample will be submitted as soon as a VM is freed up and returned to its pristine state. It is also possible to pass a directory containing samples to submit.py. This will cause all samples contained within the directory to be processed. It is very powerful when used in conjunction with delete_original = on in the cuckoo.conf. Adding a large number of samples to the directory and deleting them after processing (copies are contained in storage/analyses/<sample number>). This approach is nice when using something like maltrieve and cron. 

Another nice utility is community.py also found in /opt/cuckoo/utils which will allow you to download the community signatures, machine manager, reporting, and processing modules. 

Cuckoo is an awesome product well worth the small amount of time you will need to invest to get it installed and configured. The amount of data that can be attained with it is astonishing and it can definitely help to speed up some of that analysis or at least help in determining which samples you should devote more of your precious time to.

Cheers