Cuckoo 0.5 on OS X Mountain Lion

Christmas CuckooClaudio Guarnieri and his developers gave us a great gift to finish the year. A few days before Christmas, they released the version 0.5 of Cuckoo, the open source malware analysis system. What’s new in this release? Plenty of nice stuffs! I won’t review there here, have a look at the blog post published to announce this new release. While enjoying some holidays, I took the time to upgrade my Cuckoo environment. Basically, I’m running two different Cuckoo instances: one linked to my CuckooMX script to automate the analysis of attachments extracted from my SMTP flows. And one running on my Macbook for on-demand analysis and while I’m on the road. In the Cuckoo documentation, Ubuntu is referenced as the reference platform but it does not mean that other operating systems can’t run Cuckoo! Here are some information I would like to share if you plan to install Cuckoo on Mac OS X.

I’m running Mountain Lion (10.8.1) on my Macbook. The good news: Python 2.7 is the default version enabled on Mac OS and is recommended to run Cuckoo. The installation is pretty straight forward: deploy the tar ball in your preferred directory and review the *.conf files in the conf/ directory. But the very first (and critical!) step is to have a valid Python and libraries environment. First, check that your active version of Python is 2.7:

snowwhite:~ xavier$ python -V
Python 2.7.2

Than install the required Python decencies. To manage my Python libraries, I’m using the easy_install script. In my environment, I had to install the following ones:

snow-white:~ xavier$ easy_install sqlalchemy
snow-white:~ xavier$ easy_install Jinja2
snow-white:~ xavier$ easy_install Bottle

The last library is required by (the Cuckoo web front-end). Since version 0.4, Cuckoo completely changed the way it analyses the network traffic. Today, it uses tcpdump to capture packets and generate a .cap file. Then, the content is analysed with the dpkt library. I was not able to install it via easy_install. Just download the latest version and install it manually:

snow-white:~ xavier$ wget \
snow-white:~ xavier$ python install

Once Cuckoo installed, you must prepare your virtual machine(s) to analyse malwares. The documentation is very clear but only the network configuration is a little bit tricky. There are two main requirements:

  • Cuckoo must talk with the virtual machine. A Python script is running on the guest to handle XMLRPC requests.
  • Cuckoo must be able to see (and capture) all the traffic generated by the guest.

If you travel a lot like me, you must have an easy setup which will work in all environment. The best way to setup the network connectivity for your guest is the “host-only” networking feature (I’m using VirtualBox, please refer to your other virtualisation environment to find the corresponding connectivity). By definition, a “host only” network permits only traffic across multiple guests and the host using a private subnet. How to allow a guest to access the Internet? If it’s easy in a Linux environment (using IPtables), how to achieve the same with OS X? No stress, it’s also easy!

First, make your OS act as a router:

snow-white:~ xavier$ sudo sysctl -w net.inet.ip.forwarding=1

Then, enable NAT. No need to play with firewall rules on OS X, there is a nice daemon which takes care of this job. Note: ‘en0‘ is the interface used to get your Internet connectivity, change it to yours if different.

snow-white:~ xavier$ sudo natd -interface en0

Finally, add a firewall rules:

snow-white:~ xavier$ sudo ipfw add divert natd ip from \
any to any via en0

Boot your guest and try to access the Internet, it works! My ‘host-only’ network interface is vboxnet0. Inspect the traffic with tcpdump, you must see all the traffic between the guest and the Internet. Two important remarks:

  • For security reasons, I do not execute the commands above at boot time. I prefer to start a small script before launching Cuckoo. Having your OS X acting permanently as a router is not recommended.
  • When you will analyze malwares, some malicious traffic could potentially be sent outside your OS X via the same network interface used for your regular traffic. This could make your OS X detected as “malicious” and generate alerts or unsuspected behaviors like being completely banned from the network! Don’t do this on a corporate LAN.

Please post your comments or tips to use Cuckoo in an OS X environment! Happy New Year and happy malware analysis!


  1. Aye I’ve got it working now fusion was having issues restoring the snapshot so I switched it up to virtual box. Im using host only networking untill I get my amazon cloud built out 🙂

  2. Hi C,
    Is ‘SQLAlchemy’ properly installed? Did you run in debut mode?
    Does it create the cuckoo.db (or the DB name your provided in the conf file)

  3. Kick ass however when attempting to import samples I get a generic error: adding to DB, haven’t quite figured out why…

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.