Utilities¶

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¶

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¶

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¶

Machine utility¶

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¶

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¶

Setup script¶