Skip to content

Instantly share code, notes, and snippets.

What would you like to do?
Mostly painless Cuckoo Sandbox install

How to Build a Cuckoo Sandbox Malware Analysis System

I had a heck of a time getting a Cuckoo sandbox running, and below I hope to help you get one up and running relatively quickly by detailing out the steps and gotchas I stumbled across along the way. I mention this in the references at the end of this gist, but what you see here is heavily influenced by this article from Nviso

Build your Linux Cuckoo VM

  1. Setup a Ubuntu 16.04 64-bit desktop VM (download here) in VMWare with the following properties:
  • 100GB hard drive
  • 2 procs
  • 8 gigs of RAM
  1. Run through the full Ubuntu install, then log in as root and run this to install all the latest packages:
apt-get update && apt-get upgrade -y
  1. I would also recommend that if you're going to create an admin user outside of root, call it radmin or something that is not "cuckoo" as that user gets installed later in this doc. I had a few goofy instances where the Cuckoo install script didn't run right and while I can't be 100% sure, I think this was because my Ubuntu system already had a "cuckoo" user, so I think it's better to just let the script create this for you.

  2. Create a /cuckoo folder which you'll use later for the Cuckoo install script and vulnerable VM.

Build your base Windows VM

Inside ESXi spin up a new Windows 10 Pro 64-bit VM (get the ISO here) Update: I learned Windows 10 is not supported, so use Windows 7 instead with the following properties:

  • 40GB hard drive
  • 1 proc
  • 4 gigs of RAM

Make the machine intentionally vulnerable

Once the machine is fired up, make some tweaks to keep it as vulnerable as possible. This will include turning off automatic updates, disabling UAC, shutting down Windows Defender and disabling the firewall:

  • In gpedit.msc disable Windows Updates by navigating to Computer Configuration > Administrative Templates > Windows Components\Windows Update, double-click Configure Automatic Updates, set it to Enabled and set to Notify for download and notify for install.

  • In gpedit.msc disable UAC by navigating to Computer Configuration > Policies > Windows Settings > Security Settings > Local Policies > Security Options and make these changes:

    • User Account Control: Behavior of the elevation prompt for administrators in Admin Approval Mode - right click policy setting, click Properties. Check the box Define this policy setting and choose Elevate without prompting.

    • User Account Control: Detect application installations and prompt for elevation - right-click policy setting, click Properties. Check the box Define this policy setting and choose Disabled.

    • User Account Control: Run all administrators in Admin Approval Mode - right-click policy setting, click Properties. Check the box Define this policy setting and choose Disabled.

  • In gpedit.msc disable the firewall by navigating to Computer Configuration > Administrative Templates > Network > Network connections > Windows Firewall > Domain Profile > Windows Firewall and change Protect all network connections to Disabled.

Alternatively, you can use the NetSh Advfirewall set allprofiles state off command.

  • In gpedit.msc disable Windows Defender by navigating to Computer Configuration > Administrative Templates > Windows Components > Windows Defender Antivirus then set Turn off Windows Defender Antivirus to Enabled.

Install Python and Pillow

  • Install Python 2.7

  • Install Pillow, which is a utility that allows Cuckoo to take screen captures while your analysis jobs are running. I followed this guide to get Pillow installed:

  • Download

  • Open an administrative command prompt

  • Navigate to C:\Python27 and issuing python C:\wherever-you-saved\

  • Type cd scripts and then run easy_install pillow

Install additional apps

The Cuckoo requirements don't list too much detail except that you may want to install additional things like browsers, PDF readers, etc. Some suggestions:

  • Adobe Reader
  • An old version of Office (I used 2013 with no updates)

When finished, shut down the VM.

Export the base Windows VM

Within ESXi, export the .OVA file of the Windows VM. From the vSphere Client, you can do:

  1. Click File > Export > Export OVF Template
  2. In the Format drop-down, click Single File (OVA)
  3. Save the .OVA to your desktop
  4. Using a file transfer program like FileZilla, transfer the .OVA file to your Ubuntu VM and store it in the /cuckoo folder.

Install Cuckoautoinstall

  1. On the Ubuntu desktop, login as root and download the cuckoo-install script to /cuckoo.

  2. Open it with nano and edit the following values as necessary:

  • CUCKOO_GUEST_IMAGE should point to the full path of your .OVA file
  • CUCKOO_GUEST_NAME should be the name of the VM as it appeared in your ESXi console
  • CUCKOO_GUEST_IP can remain at the default, and in fact, I'd recommend you not change it. I once tried to use because that was easier to remember, but then a bunc hof stuff broke.
  • INTERNET_INT_NAME should be the name of your LAN interface on the Ubuntu box - run ifconfig to figure out what that is.

This area of my looked like this:

  1. Now run the script:
./ --verbose

By adding the --verbose option you should be able to troubleshoot anything that doesn't work right (basically you want all green checks :-)

One issue I've run into sometimes is after getting through the script, there will be some errors I have to cleanup or a reboot I need to do, etc., and then next time I run the script I'll get an error like:

Virtualbox is running, please close it

Sometimes I can get around that by killing the service manually and running the script again:

sudo service vboxdrv stop
./ --verbose

In a recent install though, I had to completely nuke Vbox from the system before I could re-run the script:

sudo apt-get remove virtualbox-* --purge -y
./ --verbose

Prepare the freshly imported OVA file for malware analysis

Now that the OVA file is imported into VirtualBox, we need to tweak it a little further so that the Ubuntu VM can talk to it properly when doing malware analysis.

  1. From the Ubuntu machine, log in as user cuckoo (password is cuckoo)

  2. Open VirtualBox and you should see your imported VM. You might need to power the VM off before you can proceed to the next step.

  3. Right-click your VM and choose Settings and verify the following:

  • Under General > Basic tab, the Type is Microsoft Windows and Version is appropriate for the base OS on your VM. So in my case I chose Windows 7 (64-bit)
  • Under Network > Adapter 1 > Host-Only adapter should be selected, and under the Advanced drop-down choose the Adapter Type of Intel Pro / 1000 MT Desktop
  1. Now boot the VM. If you can an error right away, like Failed to open a session for the virtual machine YOUR-VIRTUAL-MACHINE-NAME check the Details tab and you'll probably see something like VT-x is disabled in the BIOS for all CPU modes. If that's the case, head here to learn about how to enable VT-x.

When the VM is booted, login and wait a few moments. Sometimes extra drivers get installed and you'll be prompted to reboot. Do that, then login again (if necessary) and make the following changes:

  1. Run ncpa.cpl and change the IP address to be the one you selected earlier in The subnet mask should be and default gateway of DNS can be and something else Internet-facing, like

  2. Copy the /home/cuckoo/.cuckoo/agent/ to the Desktop of the now-booted Windows VM (for this I usually go to Device > Insert Guest Additions CD Image..., finish the install and then do a drag-and-drop of to the Windows desktop).

Note: sometimes I've found that trying to install the guest additions CD image gives an error indicating the network connection is invalid. Check a couple things:

  • In the main Vbox GUI, check File > Host Network Manager and look at vboxnet0 and ensure the IPv4 Address is If it's not, change it! You should always be able to ping from the guest VM, and also ping from the Ubuntu command line.

  • At the Ubuntu terminal, open /etc/resolv.conf. Sometimes I've found that these settings got jacked up by the Cuckoo install, and that my DNS is pointed to some weird IP. So if you've got like nameserver in there, edit that line to be some public DNS server, like nameserver

  • One last thing to check is you might get an "Could not insert the /home/cuckoo/blah/blah.iso" error message. This is likely because your software CD-ROM drive didn't come over properly when you exported the OVA. If that's the case, shut the VM down and open the settings for it. Under Storage > Controller: IDE click Add and click Leave Empty. Now boot the VM again and try to install the guest additions. It should go.

  1. Now open a privileged command prompt, and run C:\Python27\python.exe Since I personally usually have to troubleshoot other stuff after this and end up running this a lot, I save myself some time by creating a batch file with echo "c:\python27\python.exe" > start-agent.bat. Leave this box open.

  2. Back at the VirtualBox GUI, go into the Machine Tools > Snapshots menu and delete all snapshots (there should be at least one there with the name of clean).

  3. SSH into the Ubuntu VM as cuckoo and run the following commands (which will take a new snapshot called clean, power off the VM and revert to the clean snapshot):

su cuckoo
vboxmanage snapshot "NAME-OF-YOUR-VM" take "clean" --pause
vboxmanage controlvm "NAME-OF-YOUR-VM" poweroff
vboxmanage snapshot "NAME-OF-YOUR-VM" restorecurrent
vboxmanage startvm "NAME-OF-YOUR-VM"

You should now be back at a root prompt.

  1. Reboot the Ubuntu box (don't ask me why. Just because reasons :-)

Setup iptables to protect guest VM from the rest of your internal LANs

One thing that either I'm not configuring right or isn't covered in the documentation is how to setup your guest VM so it can talk to the Internet and nothing else. I thought that by selecting the Host-only Adapter that would accomplish what I wanted, but apparently it opens up the VM to talking to ANYTHING on your connected subnets, not just the Internet. You can issue a iptables -L from your Ubuntu command line to see what I mean. So, here's what I did to flush out all the default rules and set up my system so that my guest VM on could only talk to the Internet and no other private IPs. Note that in this case my Ethernet interface (that you can view by doing ifconfig at the command line) is enp0s31f6 and my VBox guest VM sits in the range:

sudo apt-get install iptables-save -y
sudo apt-get install iptables-persistent -y
sudo iptables -A INPUT -i lo -j ACCEPT
sudo iptables -A INPUT -m conntrack --ctstate ESTABLISHED,RELATED -j ACCEPT
sudo iptables -A FORWARD -s -d -i vboxnet0 -o enp0s31f6 -j DROP
sudo iptables -A FORWARD -s -d -i vboxnet0 -o enp0s31f6 -j DROP
sudo iptables -A FORWARD -s -d -i vboxnet0 -o enp0s31f6 -j DROP
sudo iptables -A INPUT -m state --state NEW -m tcp -p tcp --dport 22 -j ACCEPT
sudo iptables -A INPUT -m state --state NEW -m tcp -p tcp --dport 5900 -j ACCEPT
sudo iptables -A INPUT -m state --state NEW -m tcp -p tcp --dport 5901 -j ACCEPT
sudo iptables -A INPUT -m state --state NEW -m tcp -p tcp --dport 8000 -j ACCEPT
sudo iptables -P INPUT DROP
sudo iptables-save > /etc/iptables/rules.v4
sudo gsettings set org.gnome.Vino require-encryption false

You may have noticed in the commands above that I also allowed in SSH and VNC ports (see later in this gist for why)

Start the Cuckoo sandbox interface

From the Ubuntu machine at a Terminal command, login as your primary user and type:

sudo apt-get install screen -y
screen -R cuckoo
sudo /root/

Then press Ctrl+A and then D to escape this screen session. You can issue this command to see open screen sessions:

screen -ls

When you see one you want to reattach to, like the "cuckoo" one we just created, type:


This will start the Cuckoo interface on port 8000. You should now be able to load the interface on http://your-linux-vm-ip:8000.

Testing your first malware sample

From the Cuckoo Web interface:

  1. Click Submit a File for Analysis

  2. Load a malware sample (if you need some to play with, get a free VirusBay account and download a sample with the name 93b0e83334836a4a811fef354d31fdb5 - it is ransomware so be careful!)

  3. At the next screen, click Analyze

  4. The Cuckoo sandbox will chew on the file for a while, and eventually the Web interface will show a status of Reported and you can click the report to see the results. Your report should definitely show that this file shows several signs of being malicious. If not, read the Troubleshooting section below.

  5. When your analysis work is done shut down the Cuckoo sandbox:


Setting up remote access to the Ubuntu box itself

When setting this up for clients I like to have the Ubuntu box available via VNC for remote troubleshooting. With Ubuntu 18.x installed, I followed this guide to turn on VNC remotely. IBut I still had issues with RealVNC complaining about "Unable to connect to VNC server using your chosen security setting." I tried upgrading to the latest VNC Viewer but that wouldn't work. This site recommends running gsettings set org.gnome.Vino require-encryption false which did do the trick for me, but it disables encryption for VNC which I don't love. However, I've not yet found a more elegant solution.

Update: actually this guide really helped me get up and running with VNC pretty fast on Ubuntu 18.x. Only part I got hung up on was I forgot that I had iptables setup so I had to add in an extra config line for that:

sudo iptables -A INPUT -m state --state NEW -m tcp -p tcp --dport 5900 -j ACCEPT
sudo iptables -A INPUT -m state --state NEW -m tcp -p tcp --dport 5901 -j ACCEPT


With the /root/ script running, the Terminal should continually feed you updates as to the status of your Cuckoo sandbox server as well as any issues that pop up. Here are a few warnings I've seen pop up in the console, and how I resolved them:

"Timeout hit while for machine to change status"

This was because in VirtualBox, my snapshot called clean was in a powered off state. Your clean VM needs to be in a booted state for Cuckoo to work right.

"ERROR: Error processing task #1: it appears that the Virtual Machine hasn't been able to contact back to the Cuckoo Host.""

The error may have additional information, like:

There could be a few reasons for this, please refer to our documentation on the matter:

This likely means the Cuckoo sandbox and your VM cannot properly communicate to one another. To fix this, open VirtualBox and fire up your clean snapshot. From a command line, do a ping and ensure you get a response. From your Ubuntu box, do a ping and ensure you get a response. Ensure that your Windows firewall is disabled (see instructions above).

"WARNING: cuckoo1: analysis caught an exception"

You might see some additional details follow this error, such as:

Traceback (most recent call last):
  File "C:/tmpabyldd/", line 798, in <module>
    success =
  File "C:/tmpabyldd/", line 650, in run
    pids = self.package.start(
  File "C:\tmpabyldd\modules\packages\", line 23, in start
    return self.execute(path, args=shlex.split(args))
  File "C:\tmpabyldd\lib\common\", line 166, in execute
    "Unable to execute the initial process, analysis aborted."
CuckooPackageError: Unable to execute the initial process, analysis aborted.

I noticed this message after I had gone through my first malware sample analysis. I was pretty sure everything in the setup guide above was done right, but my malware samples were all reporting back as pretty benign.

Turns out the issue was the script was not running as administrator. So make sure when you launch cmd you do a right-click and Run as administrator.

Once the agent is working right, you should see a line in the console that looks like this after you run your next malware analysis job:

INFO: Guest is running Cuckoo Agent 0.8 (id=cuckoo1, ip=

Internet access isn't working on the VM, the Linux box, or both!

Maybe I'm insane but my Ubuntu 18.x box keeps losing its DNS servers I set. If you're having the same problem, check this out.



This comment has been minimized.

Copy link

@asif48 asif48 commented Jun 30, 2019

Hi fellow...

great work w.r.t the installation of the VM. Would it be convenient for you to share or upload the VM of Cuckoo in order to kill the time and efforts required for its installation.


This comment has been minimized.

Copy link

@asif48 asif48 commented Jul 7, 2019

I have been going through the blog to set up the VMs. I have stuck thrice on an issue Virtualbox is running, please close it when I ran ./ under the heading Install Cuckoautoinstall. I completely remove the VirtualBox from the Ubuntu OS and then listed down the number of VB process using ps -A | grep vb and kill down all of them. One was unable to kill which was iprt-VBoxWQueue. I left no stone un turned to kill it but all in van.

Then I just created a fresh VM of Ubuntu 16.04 Desktop 64-bit without any further update and installation of packages and just wanted to see if any VB process resides in the VM . I just surprised to see when I ran on a terminal ps -A | grep vb. It shows the same process running iprt-VBoxWQueue. The screen shots attached...

What are the reasons for this? Please let me know the solution or any help in this regard would be much appreciated. I am facing the issue from the last two days and still suffering from it.


This comment has been minimized.

Copy link
Owner Author

@braimee braimee commented Jul 9, 2019

Hi there, sorry for the delay.

To address your first question, no unfortunately I can't post the VM as the Office and Windows OSs are licensed to me.

Regarding the second issue, you might have better luck under the Cuckoo issues area ( as the setup can be really finicky and I'm certainly no expert. I did try to put any of the issues I found in the "Troubleshooting" section but I've not run into this exact one before.

Good luck!



This comment has been minimized.

Copy link

@tndnz tndnz commented Jul 11, 2019

Hi guys!

Thanks a lot @braimee for your efforts to bundle all the information needed for others to reproduce your sandbox configuration, really appreciated here.

@asif48. Just in case the problem you're encountering is not about cleaning in depth virtualbox of your system, but having a Cuckoo sandbox up and running, I suggest a thing, without being yet entirely sure it will work:
You edit the "" script, comment (with a '#' in the beginning of the line) the line run_and_log prepare_virtualbox "Getting virtualbox repo ready" "Virtualbox is running, please close it".

Screenshot from 2019-07-11 07-08-39
You install separately Virtualbox on your host OS, ad the VM, export the OVA and follow the rest of the instructions by @braimee. Besides, I don't think the process linked to Virtual Box is a real problem (check the function prepare_virtualbox() in the script if you want to go further), it is why I suggest you to bypass the control on the script as long as you did closed Virtual Box properly before executing the script.

I hope it will work for you, good luck.


This comment has been minimized.

Copy link

@asif48 asif48 commented Jul 13, 2019

@tndnz thanks for your suggestion of commenting vbox line. I ran script after line comment , all went well but the import machine failed as displayed below...
after running cuckoo-install-sh

The script has clearly mentioned the machine configuration as below...

win config at cuckoo-install-sh

I would be glad if you can help...


This comment has been minimized.

Copy link

@asif48 asif48 commented Jul 14, 2019

Edit to my upper post (i am not been able to edit the above post )...

I have ran the VM with the following edit event then the same error pops up...


kindly make some arrangements to share VM as lots of people are suffering from its installation...It can be seen from here.


This comment has been minimized.

Copy link

@AgeOfMarcus AgeOfMarcus commented Jul 15, 2019

@asif48 I had that same error. Check the permissions of your ova file. Make sure the ova file is in the correct directory, and run sudo chmod 777 /cuckoo/Win7-64.ova.


This comment has been minimized.

Copy link

@asif48 asif48 commented Jul 16, 2019

I have overcome the new error comes up , the Windows VM inside Ubuntu just looping through

  1. Winldows is loading files
  2. Restarts again

I am just trying to combat with that.


This comment has been minimized.

Copy link

@asif48 asif48 commented Jul 27, 2019

HI Braimee...
I am very near to launch cuckoo...I am just stuck at ""...

Start the Cuckoo sandbox interface

I am not been able to find this script at the root...let me know where i can find this script..


This comment has been minimized.

Copy link

@asif48 asif48 commented Jul 28, 2019

(In reply to above email)

I re-ran the "" in order to confirm that whether the script ran successfully; I got to see that the green checks are not marked on the following entries...

Screenshot from 2019-07-27 13-10-51

Three components

If anybody can help...


This comment has been minimized.

Copy link

@AgeOfMarcus AgeOfMarcus commented Jul 29, 2019

@asif48 Are you running the install script as root? Make sure you are, or add sudo before all of the runuser commands in the script.


This comment has been minimized.

Copy link

@asif48 asif48 commented Aug 1, 2019

@AgeOfMarcus : Yes I am running all scripts using sudo...


This comment has been minimized.

Copy link

@AgeOfMarcus AgeOfMarcus commented Aug 2, 2019

@asif48 well you're getting an error saying runuser can only be run as root so maybe make sure that those commands in the script are being run with root privileges

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment