Cuckoo module - Yara

.. _cuckoo-module:

############# Cuckoo module #############

The Cuckoo module enables you to create YARA rules based on behavioral information generated by Cuckoo sandbox <https://cuckoosandbox.org/>_. While scanning a PE file with YARA, you can pass additional information about its behavior to the cuckoo module and create rules based not only on what it contains, but also on what it does.

.. important:: This module is not built into YARA by default, to learn how to include it refer to :ref:compiling-yara. Good news for Windows users: this module is already included in the official Windows binaries.

Suppose that you're interested in executable files sending a HTTP request to http://someone.doingevil.com. In previous versions of YARA you had to settle with:

.. code-block:: yara

rule evil_doer
{
    strings:
        $evil_domain = "http://someone.doingevil.com"

    condition:
        $evil_domain
}

The problem with this rule is that the domain name could be contained in the file for perfectly valid reasons not related with sending HTTP requests to http://someone.doingevil.com. Furthermore, the malicious executable could contain the domain name ciphered or obfuscated, in which case your rule would be completely useless.

But now with the cuckoo module you can take the behavior report generated for the executable file by your Cuckoo sandbox, pass it alongside the executable file to YARA, and write a rule like this:

.. code-block:: yara

import "cuckoo"

rule evil_doer
{
    condition:
        cuckoo.network.http_request(/http:\/\/someone\.doingevil\.com/)
}

Of course you can mix your behavior-related conditions with good old string-based conditions:

.. code-block:: yara

import "cuckoo"

rule evil_doer
{
    strings:
        $some_string = { 01 02 03 04 05 06 }

    condition:
        $some_string and
        cuckoo.network.http_request(/http:\/\/someone\.doingevil\.com/)
}

But how do we pass the behavior information to the cuckoo module? Well, in the case of the command-line tool you must use the -x option in this way::

$yara -x cuckoo=behavior_report_file rules_file pe_file

behavior_report_file is the path to a file containing the behavior file generated by the Cuckoo sandbox in JSON format.

If you are using yara-python then you must pass the behavior report in the modules_data argument for the match method:

.. code-block:: python

import yara
rules = yara.compile('./rules_file')
report_file = open('./behavior_report_file')
report_data = report_file.read()
rules.match(pe_file, modules_data={'cuckoo': bytes(report_data)})

Reference

.. default-domain:: c

.. type:: network

.. function:: http_request(regexp)

    Function returning true if the program sent a HTTP request to a URL
    matching the provided regular expression.

    *Example: cuckoo.network.http_request(/evil\\.com/)*

.. function:: http_get(regexp)

    Similar to :func:`http_request`, but only takes into account GET
    requests.

.. function:: http_post(regexp)

    Similar to :func:`http_request`, but only takes into account POST
    requests.
   
.. function:: http_user_agent(regexp)

    Function returning true if the program sent a HTTP request with a
    user agent matching the provided regular expression.

    *Example: cuckoo.network.http_user_agent(/MSIE 6\\.0/)*   

.. function:: dns_lookup(regexp)

    Function returning true if the program sent a domain name resolution
    request for a domain matching the provided regular expression.

    *Example: cuckoo.network.dns_lookup(/evil\\.com/)*
    
.. function:: host(regexp)

    Function returning true if the program contacted an IP address
    matching the provided regular expression.

    *Example: cuckoo.network.host(/192\\.168\\.1\\.1/)*  

  .. function:: tcp(regexp, port)

    Function returning true if the program contacted an IP address
    matching the provided regular expression, over TCP on the provided
    port number.

    *Example: cuckoo.network.tcp(/192\\.168\\.1\\.1/, 443)*  

  .. function:: udp(regexp, port)

    Function returning true if the program contacted an IP address
    matching the provided regular expression, over UDP on the provided
    port number.

    *Example: cuckoo.network.udp(/192\\.168\\.1\\.1/, 53)*

.. type:: registry

.. function:: key_access(regexp)

    Function returning true if the program accessed a registry entry
    matching the provided regular expression.

    *Example: cuckoo.registry.key_access(/\\\\Software\\\\Microsoft\\\\Windows\\\\CurrentVersion\\\\Run/)*

.. type:: filesystem

.. function:: file_access(regexp)

    Function returning true if the program accessed a file matching the
    provided regular expression.

    *Example: cuckoo.filesystem.file_access(/autoexec\\.bat/)*

.. type:: sync

.. function:: mutex(regexp)

    Function returning true if the program opens or creates a mutex matching
    the provided regular expression.

    *Example: cuckoo.sync.mutex(/EvilMutexName/)*