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).
Installing the latest version of Cuckoo is as simple as follows. Note that it
is recommended to first upgrade the
setuptools libraries as
they’re often outdated, leading to issues when trying to install Cuckoo (see
also DistributionNotFound / No distribution matching the version..).
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
looks roughly as follows:
$ virtualenv venv $ . venv/bin/activate (venv)$ pip install -U pip setuptools (venv)$ pip install -U cuckoo
Depending on how you have set up your environment (virtualenvs etc.) you
may need to specify the version of
pip to use. Just replace
in the commands above with
Some reasons for using a
- 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
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
$ 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.