Submit an Analysis¶

Submission Utility
API
Distributed Cuckoo
Python Functions

Submission Utility¶

The easiest way to submit an analysis is to use the cuckoo submit utility. It currently has the following options available:

$ cuckoo submit --help
Usage: cuckoo submit [OPTIONS] [TARGET]...

  Submit one or more files or URLs to Cuckoo.

Options:
  -u, --url           Submitting URLs instead of samples
  -o, --options TEXT  Options for these tasks
  --package TEXT      Analysis package to use
  --custom TEXT       Custom information to pass along this task
  --owner TEXT        Owner of this task
  --timeout INTEGER   Analysis time in seconds
  --priority INTEGER  Priority of this task
  --machine TEXT      Machine to analyze these tasks on
  --platform TEXT     Analysis platform
  --memory            Enable memory dumping
  --enforce-timeout   Don't terminate the analysis early
  --clock TEXT        Set the system clock
  --tags TEXT         Analysis tags
  --baseline          Create baseline task
  --remote TEXT       Submit to a remote Cuckoo instance
  --shuffle           Shuffle the submitted tasks
  --pattern TEXT      Provide a glob-pattern when submitting a
                      directory
  --max INTEGER       Submit up to X tasks at once
  --unique            Only submit samples that have not been
                      analyzed before
  -d, --debug         Enable verbose logging
  -q, --quiet         Only log warnings and critical messages
  --help              Show this message and exit.

You may specify multiple files or directories at once. For directories cuckoo submit will enumerate all its files and submit them one by one.

The concept of analysis packages will be dealt later in this documentation (at Analysis Packages). Following are some usage examples:

Example: submit a local binary:

$ cuckoo submit /path/to/binary

Example: submit an URL:

$ cuckoo submit --url http://www.example.com

Example: submit a local binary and specify an higher priority:

$ cuckoo submit --priority 5 /path/to/binary

Example: submit a local binary and specify a custom analysis timeout of 60 seconds:

$ cuckoo submit --timeout 60 /path/to/binary

Example: submit a local binary and specify a custom analysis package:

$ cuckoo submit --package <name of package> /path/to/binary

Example: submit a local binary and specify a custom route:

$ cuckoo submit -o route=tor /path/to/binary

Example: submit a local binary and specify a custom analysis package and some options (in this case a command line argument for the malware):

$ cuckoo submit --package exe --options arguments=--dosomething /path/to/binary.exe

Example: submit a local binary to be run on virtual machine cuckoo1:

$ cuckoo submit --machine cuckoo1 /path/to/binary

Example: submit a local binary to be run on a Windows machine:

$ cuckoo submit --platform windows /path/to/binary

Example: submit a local binary and take a full memory dump of the analysis machine:

$ cuckoo submit --memory /path/to/binary

Example: submit a local binary and force the analysis to be executed for the full timeout (disregarding the internal mechanism that Cuckoo uses to decide when to terminate the analysis):

$ cuckoo submit --enforce-timeout /path/to/binary

Example: submit a local binary and set virtual machine clock. Format is %m-%d-%Y %H:%M:%S. If not specified, the current time is used. For example if we want run a sample the 24 january 2001 at 14:41:20:

$ cuckoo submit --clock "01-24-2001 14:41:20" /path/to/binary

Example: submit a sample for Volatility analysis (to reduce side effects of the cuckoo hooking, switch it off with options free=True):

$ cuckoo submit --memory --options free=yes /path/to/binary

API¶

Detailed usage of the REST API interface is described in REST API.

Distributed Cuckoo¶

Detailed usage of the Distributed Cuckoo API interface is described in Distributed Cuckoo.

Python Functions¶

In order to keep track of submissions, samples and overall execution, Cuckoo uses a popular Python ORM called SQLAlchemy that allows you to make the sandbox use SQLite, MySQL or MariaDB, PostgreSQL and several other SQL database systems.

Cuckoo is designed to be easily integrated in larger solutions and to be fully automated. In order to automate analysis submission we suggest to use the REST API interface described in REST API, but in case you want to write your own Python submission script, you can also use the add_path() and add_url() functions.

add_path(file_path[, timeout=0[, package=None[, options=None[, priority=1[, custom=None[, owner=""[, machine=None[, platform=None[, tags=None[, memory=False[, enforce_timeout=False], clock=None[]]]]]]]]]]]]])¶

Add a local file to the list of pending analysis tasks. Returns the ID of the newly generated task.

Parameters:

file_path (string) – path to the file to submit
timeout (integer) – maximum amount of seconds to run the analysis for
package (string or None) – analysis package you want to use for the specified file
options (string or None) – list of options to be passed to the analysis package (in the format key=value,key=value)
priority (integer) – numeric representation of the priority to assign to the specified file (1 being low, 2 medium, 3 high)
custom (string or None) – custom value to be passed over and possibly reused at processing or reporting
owner (string or None) – task owner
machine (string or None) – Cuckoo identifier of the virtual machine you want to use, if none is specified one will be selected automatically
platform (string or None) – operating system platform you want to run the analysis one (currently only Windows)
tags (string or None) – tags for machine selection
memory (True or False) – set to True to generate a full memory dump of the analysis machine
enforce_timeout (True or False) – set to True to force the execution for the full timeout
clock (string or None) – provide a custom clock time to set in the analysis machine

Return type:

integer

Example usage:

>>> from cuckoo.core.database import Database
>>> db = Database()
>>> db.add_path("/tmp/malware.exe")
1
>>>

add_url(url[, timeout=0[, package=None[, options=None[, priority=1[, custom=None[, owner=""[, machine=None[, platform=None[, tags=None[, memory=False[, enforce_timeout=False], clock=None[]]]]]]]]]]]]])¶

Add a local file to the list of pending analysis tasks. Returns the ID of the newly generated task.

Parameters:

url (string) – URL to analyze
timeout (integer) – maximum amount of seconds to run the analysis for
package (string or None) – analysis package you want to use for the specified URL
options (string or None) – list of options to be passed to the analysis package (in the format key=value,key=value)
priority (integer) – numeric representation of the priority to assign to the specified URL (1 being low, 2 medium, 3 high)
custom (string or None) – custom value to be passed over and possibly reused at processing or reporting
owner (string or None) – task owner
machine (string or None) – Cuckoo identifier of the virtual machine you want to use, if none is specified one will be selected automatically
platform (string or None) – operating system platform you want to run the analysis one (currently only Windows)
tags (string or None) – tags for machine selection
memory (True or False) – set to True to generate a full memory dump of the analysis machine
enforce_timeout (True or False) – set to True to force the execution for the full timeout
clock (string or None) – provide a custom clock time to set in the analysis machine

Return type:

integer

Example Usage:

>>> from cuckoo.core.database import Database
>>> db = Database()
>>> db.connect()
>>> db.add_url("http://www.cuckoosandbox.org")
2
>>>