A 2020 guide to installing a Cuckoo Sandbox!

Listen here, people. There is some amazing documentation within the Cuckoo Sandbox documents...alongside some amazing grammar issues that make interpretation of the material a hinderance to the layman. They and those on the Github message boards are savage. They forget most of us are students or hobbyists, saying things like "did you check the boards?" or,  "read the documentation". I got frustrated with this, so here is my guide on installing a Cuckoo Sandbox with what I believe are real-world explanations of what you might encounter as issues...the same ones I did and suffered through. I have compiled the best guides AND the best common troubleshooting issues below. The guide below assumes a VirtualBox Host and a Windows 7 analysis guest.

P.S. Many of these steps are taken right from the Cuckoo install pages, but I added some (hopefully) useful context and pre-attack common issues.

[The Easy Parts - PreReqs]

Most guides suggest installing Ubuntu, but I suggest expanding your toolbox and install this distro on a SANS SIFT machine. SIFT, if you've never heard of it, is a collection of open-source forensic tools on-top of Ubuntu desktop. This will improve your analysis by allowing you to run your evidence on the Cuckoo sandbox as well as execute analytical tools on the results!

Step #1 - Prep Your Host: Install Ubuntu Standard Desktop/Server and add SIFT on top by following this guide. (This can be done at a later date, but you might not want to break your Cuckoo install)

- Update fully with sudo apt-get update && sudo apt-get dist-upgrade -y

-Install VirtualBox (probably best to obtain a WinXP or 7 ISO here at this point)

Step #2: Install Cuckoo dependancies

$ sudo apt-get install python python-pip python-dev libffi-dev libssl-dev

$ sudo apt-get install python-virtualenv python-setuptools

$ sudo apt-get install libjpeg-dev zlib1g-dev swig

In order to use the Django-based Web Interface, MongoDB is required:

$ sudo apt-get install mongodb

In order to use PostgreSQL as database (our recommendation), PostgreSQL will have to be installed as well:

$ sudo apt-get install postgresql libpq-dev

In order to dump the network activity performed by the malware during execution, you’ll need a network sniffer properly configured to capture the traffic and dump it to a file.

Install it on Ubuntu:

$ sudo apt-get install tcpdump apparmor-utils

$ sudo aa-disable /usr/sbin/tcpdump

Step #3: Create the Cuckoo User 

Create a new user:

$ sudo adduser cuckoo

If you’re using VirtualBox, make sure the new user belongs to the “vboxusers” group (or the group you used to run VirtualBox):

$ sudo usermod -a -G vboxusers cuckoo

you’re using KVM or any other libvirt based module, make sure the new user belongs to the “libvirtd” group (or the group your Linux distribution uses to run libvirt):

$ sudo usermod -a -G libvirtd cuckoo

Step #4: Install Cuckoo (you may be asked to install "pip" here - do it)

$ sudo pip install -U pip setuptools

$ sudo pip install -U cuckoo

--- This is where most people have issues ---

Some points here:

1. Cuckoo should never be run as "sudo".
2. You may receive permission issues on cuckoo files, simply chmod them to the user cuckoo, do not bypass with sudo!
3. Every error Cuckoo passes makes sense, don't overthink it. Check your IP addresses, interfaces, and permissions. Post below if you get errors and I will respond.
4. Cuckoo suggests a CWD, I did not follow this and work directly in ~.\.cuckoo for the remainder of this install.
5. The .cuckoo.cong file is heavily commented and is your bible. Any issue is probably due to this file being incorrect.

Step #5: Configure Cuckoo.conf - open it up and fill in the blanks. 

machinery in [cuckoo]:

This option defines which Machinery module you want Cuckoo to use to interact with your analysis machines. The value must be the name of the module without extension (e.g., virtualbox or vmware).

ip and port in [resultserver]:

These define the local IP address and port that Cuckoo is going to try to bind the result server on. Make sure this matches the network configuration of your analysis machines or they won’t be able to return any results.

Here are the critical requirements for the .conf file.

1. Guest IP: 192.168.56.101
2. Subnet: 255.255.255.0
3. Gateway: 192.168.56.1
4. Virtualbox (or VMware if you're using it)

Step #6: Prepare the guest

1. Install your sandbox, best to use Win 7 or lower.
2. Host-only adaptor and correct Vbox host adaptor configured
3. Check interface is up with "ifconfig"
4. Name the machine cuckoo1
5. Shut off all firewalls, User Access Control (UAC), and updates.
6. Install Python 2.7 for Windows.

---YOU MUST BE ABLE TO PING TO AND FROM YOUR HOST---

If you cant, check that your VirtualBox Host adaptor has the correct settings as above. You can change the adapter while windows are running to test it, each change will prompt the machine to re-try connections. Don't move on until you can ping from both sides. Keep in mind your 

1. Download the Cuckoo Agent to the Windows guest.
1. I downloaded this file directly from the GitHub for cuckoo separately right onto my guest VM.
2. Or, you can also copy and paste it into a text file, then ensure you set the default program to python.
2. Run the agent! You should see a simple black text box appear.
3. If all is good so far, the most critical function at this point is to snapshot the RUNNING MACHINE. With your agent running and your connection functional, snapshot the running VM (yes, you can do this).
4. Name the snapshot "Snapshot1" NOT the default "Snapshot 1". Your .conf snapshot name and this name must match exactly.

Step #7: Test and Troubleshoot.

In two separate terminals, turn on cuckoo and the analysis web server.

1. $ cuckoo
1. If your config is off, you will receive an error here. It is almost certainly because your VM
2. $ cuckoo run webserver

Put any file into the analysis portion. I copied a real .DLL from my machine. You know its functional if you see the VirtualBox preview pane. (Make sure it's on). If you get ONLY VirusTotal results back you are on the right track BUT your agent is not configured correctly.

Here are some useful Ubuntu commands I used regularly when troubleshooting:

Permission to files:

Verify if /opt/cuckoo exists. It does? 

Ok, use sudo chown -R cuckoo:cuckoo /opt/cuckoo
It does not? Ok, use: sudo cuckoo --cwd /opt/cuckoo --debug init. 

Now perform step 2 <-3a .="" any="" configuration="" div="" if="" perform="" required="" settings="">

Start Cuckoo by executing: cuckoo --cwd /opt/cuckoo --debug --user cuckoo

Webserver already running:

sudo kill -9 `sudo lsof -t -i:8000`

Networking messed up:

sudo service network-manager restart