Cuckoo Working Directory Usage

Note

Before reading this page, please read on installing Cuckoo and the Cuckoo Working Directory.

Before we go into the subject of using the CWD we’re first going to walk you through the many improvements on your Quality of Life during your daily usage of Cuckoo Sandbox with the introduction of the Cuckoo Package and CWD and some of the new features that come along with this.

So simply put, the CWD is a per-Cuckoo instance configuration directory. While people generally speaking only run one Cuckoo instance per server, this still yields a lot of maintenance-related improvements:

  • As outlined by Installing Cuckoo installing Cuckoo and updating it will now be pretty much pip install -U cuckoo.
  • Due to Cuckoo now being an official Python Package we have a much tighter control on how its installed on users’ systems. No longer will users have incorrect versions of third party libraries installed breaking their setup.
  • Because updating is much easier (again, pip install -U cuckoo) we will be able to put out new versions more often. E.g., when one or more users run into a bug, we’ll be able to put out a fix quickly - this has happened a few times in the past in a way that we weren’t able to properly mitigate such issues (leaving users high & dry for months).
  • The Cuckoo Configuration is no longer part of the Git repository. Users who have updated Cuckoo in the past will have seen the effort involved in making a backup of their configuration, pulling a new version of Cuckoo, and either restoring their old configuration or applying the configuration against the new Cuckoo version by hand.
  • With the new CWD all configurable files will be in one centralized place in logically structured subdirectories.
  • Given that a CWD denotes one Cuckoo instance, it is possible to have multiple Cuckoo instances through multiple CWD’s while having installed/deployed Cuckoo only once.
  • With the addition of the cuckoo executable and its associated Cuckoo Apps (subcommands) the various Cuckoo commands are now centralized into one command.

Usage

After having installed the Cuckoo Package (Installing Cuckoo) and setup the initial Cuckoo Working Directory (Cuckoo Working Directory) it is time to actually get started with Cuckoo. Just to reiterate, installing the latest version of Cuckoo in a virtualenv environment may look roughly as follows (note the pip install -U pip setuptools, for more information see also DistributionNotFound / No distribution matching the version..).

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

First of all you’ll probably want to update the default Cuckoo configuration in the $CWD/conf/ directory. If just to switch from the default SQLite3 database to, e.g., PostgreSQL, or to register some virtual machines (more information on setting up Virtual Machines can be found in Preparing the Guest). Note that in order to view the results of analyses in the Web Interface later on it is necessary to enable the mongodb reporting module in $CWD/conf/reporting.conf (see also Web interface).

We then proceed by downloading the Cuckoo Community which includes over 300 Cuckoo Signatures which summarize a wide array of malicious behavior in a digestible way, simplifying the final results of an analysis. Downloading the Cuckoo Community into our CWD may be done as follows:

(venv)$ cuckoo community

Alternatively, if you have a local copy of the community .tar.gz file (e.g., after running wget https://github.com/cuckoosandbox/community/archive/master.tar.gz) this can be imported as follows:

(venv)$ cuckoo community --file master.tar.gz

Now we’re good to go let’s submit some samples and URLs using the command-line Submission Utility. Note that multiple tasks may be submitted at once:

(venv)$ cuckoo submit /tmp/sample1.exe /tmp/sample2.exe /tmp/sample3.exe
Success: File "/tmp/sample1.exe" added as task with ID #1
Success: File "/tmp/sample2.exe" added as task with ID #2
Success: File "/tmp/sample3.exe" added as task with ID #3
(venv)$ cuckoo submit --url google.com bing.com
Success: URL "google.com" added as task with ID #4
Success: URL "bing.com" added as task with ID #5

For the actual analysis of these samples, one will have to run the Cuckoo daemon. Which is equally straightforward. Do keep in mind that, by default, the command will run indefinitely (unless a maximum analysis count was provided through the -m parameter, e.g., -m 5).

# This command is equal to what used to be "./cuckoo.py -d".
(venv)$ cuckoo -d

Now in order to inspect the analyses that have run we start the Web Interface. For small and/or home setups this may be done using the built-in Django web server as follows, although we recommend a proper Web Deployment for any bigger setup.

(venv)$ cuckoo web
Performing system checks...

System check identified no issues (0 silenced).
March 31, 2017 - 12:10:46
Django version 1.8.4, using settings 'cuckoo.web.web.settings'
Starting development server at http://localhost:8000/
Quit the server with CONTROL-C.

There are some additional Cuckoo Apps such as cuckoo clean (Clean all Tasks and Samples), the Cuckoo Rooter, and various other utilities listed in Cuckoo Apps, but other than that there’s not much more to learn about installing and running Cuckoo Sandbox - so, happy analyzing.