Permalink
Branch: master
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
226 lines (167 sloc) 8.82 KB

Submit an Analysis

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 :doc:`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 :doc:`api`.

Distributed Cuckoo

Detailed usage of the Distributed Cuckoo API interface is described in :doc:`dist`.

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

.. function:: 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.

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

    Example usage:

    .. code-block:: python
        :linenos:

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

.. function:: 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.

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

Example Usage: