Cuckoo Working Directory Usage
Before reading this page, please read on installing Cuckoo and the :doc:`../installation/host/cwd`.
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 :doc:`../installation/host/installation` 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
CWDall configurable files will be in one centralized place in logically structured subdirectories.
- Given that a
CWDdenotes 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
cuckooexecutable and its associated :ref:`cuckoo_apps` (subcommands) the various Cuckoo commands are now centralized into one command.
After having installed the
Cuckoo Package (:ref:`installing`) and setup
Cuckoo Working Directory (:doc:`../installation/host/cwd`) 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
$ 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
$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
:doc:`../installation/guest/index`). 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
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
(e.g., after running
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 :ref:`submitpy`. 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.,
# 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 :ref:`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
(:ref:`cuckoo-clean`), the :ref:`rooter`, and various other utilities listed
in :ref:`cuckoo_apps`, but other than that there's not much more to learn
about installing and running Cuckoo Sandbox - so, happy analyzing.