Utilities

Cuckoo comes with a set of pre-built utilities to automate several common tasks. Before these utilities could be found in the utils/ directory but since then we have moved to Cuckoo Apps.

Cuckoo Apps

A Cuckoo App is essentially just a Cuckoo sub-command. There exist a couple of Cuckoo Apps, each with their own functionality. It is important to note that each Cuckoo App can be invoked in the same way. Following are some examples:

$ cuckoo submit --help
$ cuckoo api --help
$ cuckoo clean --help

In these examples we provided the --help parameter which shows the functionality and all available parameters for the particular Cuckoo App.

Submission Utility

Submits samples to analysis. This tool is described in Submit an Analysis.

Web Utility

Cuckoo’s web interface. This tool is described in Web interface.

Processing Utility

Changed in version 2.0.0: We used to have longstanding issues with ./utils/process.py randomly freezing up and ./utils/process2.py only being able to handle PostgreSQL-based databases. These two commands have now been merged into one Cuckoo App and no longer show signs of said issues or limitations.

For bigger Cuckoo setups it is recommended to separate the results processing from the Cuckoo analyses due to performance issues (with multiple threads & the Python GIL). Using cuckoo process it is also possible to re-generate Cuckoo reports, this is mostly used while developing and debugging Cuckoo Processing modules, Cuckoo Signatures, and Cuckoo Reporting modules.

In order to do results processing in one or more separate process(es) one has to disable the process_results configuration item in $CWD/conf/cuckoo.conf by setting the value to off. Then a Cuckoo Processing instance has to be started, this can be done as follows:

$ cuckoo process instance1

If one Cuckoo Processing instance is not enough to handle all the incoming analyses, simply create a second, third, and possibly more instances:

$ cuckoo process instance2

In order to re-generate a Cuckoo report of an analysis task, use the -r switch:

$ cuckoo process -r 1

It is also possible to re-generate multiple or a range of Cuckoo reports at once. The following will reprocess tasks 1, 2, 5, 6, 7, 8, 9, 10:

$ cuckoo process -r 1,2,5-10

For more information see also the help on this Cuckoo App:

$ cuckoo process --help
Usage: cuckoo process [OPTIONS] [INSTANCE]

  Process raw task data into reports.

Options:
  -r, --report TEXT       Re-generate one or more reports
  -m, --maxcount INTEGER  Maximum number of analyses to process
  --help                  Show this message and exit.

In automated mode an instance name is required (e.g., instance1) as seen in the examples earlier above!

Community Download Utility

This Cuckoo App downloads Cuckoo Signatures, the latest monitoring binaries, and other goodies from the Cuckoo Community Repository and installs them in your CWD.

To get all the latest and greatest from the Cuckoo Community simply execute as follows and wait until it finishes - it currently doesn’t have any progress indication:

$ cuckoo community

For more usage see as follows:

$ cuckoo community --help
Usage: cuckoo community [OPTIONS]

  Utility to fetch supplies from the Cuckoo Community.

Options:
  -f, --force              Overwrite existing files
  -b, --branch TEXT        Specify a different community branch rather than
                           master
  --file, --filepath PATH  Specify a local copy of a community .tar.gz file
  --help                   Show this message and exit.

Database migration utility

Changed in version 2.0.0: This used to be a special process, but has since been integrated properly as a Cuckoo App.

This utility helps migrating your data between Cuckoo releases. It’s developed on top of the Alembic framework and it should provide data migration for both SQL database and Mongo database. This tool is already described in Upgrading from a previous release.

Stats utility

Deprecated since version 2.0-rc2: This utility will not be ported to a Cuckoo App as this information can also be retrieved through both the Cuckoo API as well as the Cuckoo Web Interface.

Machine utility

Changed in version 2.0.0: This used to be a standalone and hacky script directly modifying the Cuckoo configuration. It’s now much better integrated and will be able to somewhat properly interact with Cuckoo.

The machine Cuckoo App is designed to help you automatize the configuration of virtual machines in Cuckoo. It takes a list of machine details as arguments and write them in the specified configuration file of the machinery module enabled in cuckoo.conf. Following are the available options:

$ cuckoo machine --help
Usage: cuckoo machine [OPTIONS] VMNAME [IP]

Options:
  --debug              Enable verbose logging
  --add                Add a Virtual Machine
  --delete             Delete a Virtual Machine
  --platform TEXT      Guest Operating System
  --options TEXT       Machine options
  --tags TEXT          Tags for this Virtual Machine
  --interface TEXT     Sniffer interface for this Virtual Machine
  --snapshot TEXT      Specific Virtual Machine Snapshot to use
  --resultserver TEXT  IP:Port of the Result Server
  --help               Show this message and exit.

As an example, a machine may be added to Cuckoo’s configuration as follows:

$ cuckoo machine --add cuckoo1 192.168.56.101 --platform windows --snapshot vmcloak

Distributed scripts

This tool is described in Distributed Cuckoo.

Mac OS X Bootstrap scripts

Deprecated since version 2.0.0: These files will be moved elsewhere in an upcoming update and so should any documentation that references these scripts.

A couple of bootstrap scripts used for Mac OS X analysis are located in utils/darwin folder, they are used to bootstrap the guest and host system for Mac OS X malware analysis. Some settings are defined as constants inside them, so it is suggested to have a look at them and configure them for your needs.

SMTP Sinkhole

Deprecated since version 2.0.0: This script has been removed since this functionality should be implemented properly using a Postfix setup.

Setup script

Deprecated since version 2.0.0: This script has been replaced by a similar but much more powerful SaltStack state.