Installing Cuckoo

Create a user

You can either run Cuckoo from your own user or create a new one dedicated just for your sandbox setup. Make sure that the user that runs Cuckoo is the same user that you will use to create and run the virtual machines (at least in the case of VirtualBox), otherwise Cuckoo won’t be able to identify and launch these Virtual Machines.

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

If 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

Raising file limits

As outlined in the FAQ entry IOError: [Errno 24] Too many open files one may want to bump the file count limits before starting Cuckoo as otherwise some samples will fail to properly process the report (due to opening more files than allowed by the Operating System).

Install Cuckoo

Installing the latest version of Cuckoo is as simple as follows. Note that it is recommended to first upgrade the pip and setuptools libraries as they’re often outdated, leading to issues when trying to install Cuckoo (see also DistributionNotFound / No distribution matching the version..).

Warning

It is not unlikely that you’ll be missing one or more system packages required to build various Python dependencies. Please read and re-read Requirements to resolve these sorts of issues.

$ sudo pip install -U pip setuptools
$ sudo pip install -U cuckoo

Although the above, a global installation of Cuckoo in your OS works mostly fine, we highly recommend installing Cuckoo in a virtualenv, which looks roughly as follows:

$ virtualenv venv
$ . venv/bin/activate
(venv)$ pip install -U pip setuptools
(venv)$ pip install -U cuckoo

Note

Depending on how you have set up your environment (virtualenvs etc.) you may need to specify the version of pip to use. Just replace pip in the commands above with pip2.

Some reasons for using a virtualenv:

  • Cuckoo’s dependencies may not be entirely up-to-date, but instead pin to a known-to-work-properly version.
  • The dependencies of other software installed on your system may conflict with those required by Cuckoo, due to incompatible version requirements (and yes, this is also possible when Cuckoo supports the latest version, simply because the other software may have pinned to an older version).
  • Using a virtualenv allows non-root users to install additional packages or upgrade Cuckoo at a later point in time.
  • And simply put, virtualenv is considered a best practice.

Please refer to Cuckoo Working Directory and Cuckoo Working Directory Usage to learn more about the Cuckoo Working Directory and how to operate it.

Install Cuckoo from file

By downloading a hard copy of the Cuckoo Package and installing it offline, one may set up Cuckoo using a cached copy and/or have a backup copy of current Cuckoo versions in the future. We also feature the option to download such a tarball on our website.

Obtaining the tarball of Cuckoo and all of its dependencies manually may be done as follows:

$ pip download cuckoo

You will end up with a file Cuckoo-2.0.0.tar.gz (or a higher number, depending on the latest released stable version) as well as all of its dependencies (e.g., alembic-0.8.8.tar.gz).

Installing that exact version of Cuckoo may be done as you’re familiar with from installing it using pip directly, except now using the filename of the tarball:

$ pip install Cuckoo-2.0.0.tar.gz

On systems where no internet connection is available, the $ pip download cuckoo command may be used to fetch all of the required dependencies and as such one should be able to - in theory - install Cuckoo completely offline using those files, i.e., by executing something like the following:

$ pip install *.tar.gz

Build/Install Cuckoo from source

By cloning Cuckoo Sandbox from our official repository, you can install it from source. After cloning, follow the steps mentioned in Development with the Python Package to start the installation.