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 . Therefore, to ease the pain we've described the process of how to install Cuckoo on Debian operating system together will all dependencies.
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 http://sourceforge.net/projects/ssdeep/files/ssdeep-2.12/ssdeep-2.12.tar.gz # tar xvzf ssdeep-2.12.tar.gz # cd ssdeep-2.12/ # ./configure && make && make install # git clone https://github.com/kbandla/pydeep # cd pydeep # python setup.py build # python setup.py install # wget https://yara-project.googlecode.com/files/yara-1.7.tar.gz # tar xvzf yara-1.7.tar.gz # cd yara-1.7/ # ./configure && make && make install # echo "/usr/local/lib" >> /etc/ld.so.conf # ldconfig # wget https://yara-project.googlecode.com/files/yara-python-1.7.tar.gz # tar xvzf yara-python-1.7.tar.gz # cd yara-python-1.7/ # python setup.py build # python setup.py 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 https://distorm.googlecode.com/files/distorm3.zip # unzip distorm3.zip # cd distorm3/ # python setup.py build # python setup.py install # wget https://volatility.googlecode.com/files/volatility-2.3.1.tar.gz # tar xvzf volatility-2.3.1.tar.g # cd volatility-2.3.1/ # python setup.py build # python setup.py install
At last, it's time to install Cuckoo.
# adduser cuckoo # usermod -G vboxusers cuckoo # git clone git://github.com/cuckoobox/cuckoo.git
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 http://download.virtualbox.org/virtualbox/4.3.18/virtualbox-4.3_4.3.18-96516~Debian~wheezy_amd64.deb # dpkg -i virtualbox-4.3_4.3.18-96516~Debian~wheezy_amd64.deb
Since Cuckoo expects to use the IP address 192.168.56.1, 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 192.168.56.1:2042 and terminate. To create appropriate networking interface, we can execute the following commands.
# VBoxManage hostonlyif create # ip link set vboxnet0 up # ip addr add 192.168.56.1/24 dev vboxnet0
Next we can start Cuckoo normally by running the cuckoo.py script as shown below. Note that the script start listening on IP 192.168.56.1 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 http://download.virtualbox.org/virtualbox/4.3.18/Oracle_VM_VirtualBox_Extension_Pack-4.3.18-96516.vbox-extpack # 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 http://python.org/download/ 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/agent.py 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 agent.py automatically at startup, we can add the "HKLMSOFTWAREMicrosoftWindowsCurrentVersionRunAgent" registry key with a value “C:agent.py”.
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 agent.py 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.
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 192.168.56.101 as specified in the virtualbox.conf configuration file.
From the host we should connect to the IP 192.168.56.101 on port 8000 where agent.py 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 cuckoo.py 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.
Auxiliary modules, which run concurrently to malware analysis. The following options are most commonly used:
General Cuckoo settings and analysis options. The following options are most commonly used:
|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:
|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:
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.
Options for VirtualBox virtualization software. The following options are most commonly used:
|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 http://192.168.56.1:2042/ 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 submit.py is called with various parameters to analyze the malware sample on Windows platform on WindowsXPSP3 virtual machine.
Every configuration option of the submit.py util can be seen below and is presented for completeness.
Using Web Interface
To start a web interface, we have to run the utils/web.py utility, which will start listening on port 8080.
To start the web interface, all we need to do is run web.py, 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 submit.py 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 wsgi.py 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> ServerAdmin firstname.lastname@example.org ServerName analyzemalware WSGIDaemonProcess web user=cuckoo group=cuckoo processes=1 threads=5 WSGIScriptAlias / /srv/cuckoo/web/web/wsgi.py <Directory /srv/cuckoo/web/web/> AllowOverride All Order deny,allow Allow from all </Directory> Alias /static /srv/cuckoo/web/static <Directory /srv/cuckoo/web/static> AllowOverride All Order deny,allow Allow from all </Directory> 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 </VirtualHost>
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 ./cuckoo.py 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 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.|
|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 exe.py 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/abstracts.py 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/process.py.
Cuckoo will then try to inject the DLL into the process by using the following functions: VirtualAllocEx, WriteProcessMemory, CreateEventA and 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.
 Cuckoo Installation, http://docs.cuckoosandbox.org/en/latest/installation/.