Modules¶
Modules are the way YARA provides for extending its features. They allow to define data structures and functions which can be used in your rules to express more complex conditions. Here you’ll find described some modules officially distributed with YARA, but you can also learn how to write your own modules in the Writing your own modules section.
PE module¶
The PE module allows you to create more fine-grained rules for PE files by using attributes and features of the PE file format. This module exposes most of the fields present in a PE header and provides functions which can be used to write more expressive and targeted rules. Let’s see some examples:
import "pe"
rule single_section
{
condition:
pe.number_of_sections == 1
}
rule control_panel_applet
{
condition:
pe.exports("CPlApplet")
}
rule is_dll
{
condition:
pe.characteristics & pe.DLL
}
PE module reference¶
- machine¶
Integer with one of the following values:
- MACHINE_I386¶
- MACHINE_AMD64¶
Example: pe.machine == pe.MACHINE_AMD64
- subsystem¶
Integer with one of the following values:
- SUBSYSTEM_UNKNOWN¶
- SUBSYSTEM_NATIVE¶
- SUBSYSTEM_WINDOWS_GUI¶
- SUBSYSTEM_WINDOWS_CUI¶
- SUBSYSTEM_OS2_CUI¶
- SUBSYSTEM_POSIX_CUI¶
- SUBSYSTEM_NATIVE_WINDOWS¶
Example: pe.subsystem == pe.SUBSYSTEM_NATIVE
- timestamp¶
PE timestamp.
- entry_point¶
Entry point raw offset or virtual address depending if YARA is scanning a file or process memory respectively. This is equivalent to the deprecated entrypoint keyword.
- image_base¶
Image base relative virtual address.
- characteristics¶
Bitmap with PE characteristics. Individual characteristics can be inspected by performing a bitwise AND operation with the following constants:
- RELOCS_STRIPPED¶
- EXECUTABLE_IMAGE¶
- LINE_NUMS_STRIPPED¶
- LOCAL_SYMS_STRIPPED¶
- AGGRESIVE_WS_TRIM¶
- LARGE_ADDRESS_AWARE¶
- BYTES_REVERSED_LO¶
- 32BIT_MACHINE¶
- DEBUG_STRIPPED¶
- REMOVABLE_RUN_FROM_SWAP¶
- NET_RUN_FROM_SWAP¶
- SYSTEM¶
- DLL¶
- UP_SYSTEM_ONLY¶
- BYTES_REVERSED_HI¶
Example: pe.characteristics & pe.DLL
- linker_version¶
An object with two integer attributes, one for each major and minor linker version.
- major¶
Major linker version.
- minor¶
Minor linker version.
- os_version¶
An object with two integer attributes, one for each major and minor OS version.
- major¶
Major OS version.
- minor¶
Minor OS version.
- image_version¶
An object with two integer attributes, one for each major and minor image version.
- major¶
Major image version.
- minor¶
Minor image version.
- subsystem_version¶
An object with two integer attributes, one for each major and minor subsystem version.
- major¶
Major subsystem version.
- minor¶
Minor subsystem version.
- number_of_sections¶
Number of sections in the PE.
- sections¶
An zero-based array of section objects, one for each section the PE has. Individual sections can be accessed by using the [] operator. Each section object has the following attributes:
- name¶
Section name.
- characteristics
Section characteristics.
- virtual_address¶
Section virtual address.
- virtual_size¶
Section virtual size.
- raw_data_offset¶
Section raw offset.
- raw_data_size¶
Section raw size.
Example: pe.sections[0].name == ”.text”
- exports(function_name)¶
Function returning true if the PE exports function_name or false otherwise.
Example: pe.exports(“CPlApplet”)
- imports(dll_name, function_name)¶
Function returning true if the PE imports function_name from dll_name, or false otherwise. dll_name is case insensitive.
Example: pe.imports(“kernel32.dll”, “WriteProcessMemory”)
Cuckoo module¶
The Cuckoo module enables you to create YARA rules based on behavioral information generated by a Cuckoo sandbox. 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 in what it contains, but also in what it does.
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:
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:
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:
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:
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)})
Important
The cuckoo module is not built into YARA by default, to learn how to build YARA with Cuckoo support refer to Compiling and installing YARA.
Cuckoo module reference¶
- network¶
- 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/)
- http_get(regexp)¶
Similar to http_request(), but only takes into account GET requests.
- http_post(regexp)¶
Similar to http_request(), but only takes into account POST requests.
- registry¶
- 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/)