Submit an Analysis¶

Submission Utility

API

Web Utility

Python Functions

Submission Utility¶

The easiest way to submit an analysis is to use the provided submit.py command-line utility. It currently has the following options available:

usage: submit.py [-h] [--url] [--package PACKAGE] [--custom CUSTOM]
                 [--timeout TIMEOUT] [--options OPTIONS] [--priority PRIORITY]
                 [--machine MACHINE] [--platform PLATFORM] [--memory]
                 [--enforce-timeout]
                 target

positional arguments:
  target               URL, path to the file or folder to analyze

optional arguments:
  -h, --help           show this help message and exit
  --url                Specify whether the target is an URL
  --package PACKAGE    Specify an analysis package
  --custom CUSTOM      Specify any custom value
  --timeout TIMEOUT    Specify an analysis timeout
  --options OPTIONS    Specify options for the analysis package (e.g.
                       "name=value,name2=value2")
  --priority PRIORITY  Specify a priority for the analysis represented by an
                       integer
  --machine MACHINE    Specify the identifier of a machine you want to use
  --platform PLATFORM  Specify the operating system platform you want to use
                       (windows/darwin/linux)
  --memory             Enable to take a memory dump of the analysis machine
  --enforce-timeout    Enable to force the analysis to run for the full
                       timeout period

If you specify a directory as path, all the files contained in it will be submitted for analysis.

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:

$ ./utils/submit.py /path/to/binary

Example: submit an URL:

$ ./utils/submit.py --url http://www.example.com

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

$ ./utils/submit.py --priority 5 /path/to/binary

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

$ ./utils/submit.py --timeout 60 /path/to/binary

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

$ ./utils/submit.py --package <name of package> /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):

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

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

$ ./utils/submit.py --machine cuckoo1 /path/to/binary

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

$ ./utils/submit.py --platform windows /path/to/binary

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

$ ./utils/submit.py --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):

$ ./utils/submit.py --enforce-timeout /path/to/binary

API¶

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

Web Utility¶

Cuckoo provides a very basic web utility that you can use to submit files to be analyzed.

You can find the script at path utils/web.py and you can start it with:

$ python utils/web.py

By default it will create a webserver on localhost and port 8080. Open your browser at http://localhost:8080 and it will prompt you a simple form that allows you to upload a file, specify some options (with the same format as the submit.py utility) and submit it.

In the Browse section you can track the status of pending, failed and succeeded analyses and, when available, you’ll be prompted a link to view the HTML report.

Note

This is by no means supposed to be a full fledged web interface: it’s a very simple utility that we put together to allow users to simply upload files and consumes the generated HTML report. Despite being incorporated and rendered dynamically, the results displayed are nothing else than the report.html file, therefore it is supposed to be independent from the utility.

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, 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 the case you want to write your own Python submission script, you can use the add_path() and add_url() functions.

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

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
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)
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 executuion for the full timeout

Return type:

integer

Example usage:

>>> from lib.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[, machine=None[, platform=None[, memory=False[, enforce_timeout=False]]]]]]]]])¶

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
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)
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 executuion for the full timeout

Return type:

integer

Example Usage:

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