YARA can be also used from Python through the yara-python library. Once the library is built and installed as described in Compiling and installing YARA you’ll have access to the full potential of YARA from your Python scripts.
The first step is importing the YARA library:
Then you will need to compile your YARA rules before applying them to your data, the rules can be compiled from a file path:
The default argument is filepath, so you don’t need to explicitly specify its name:
You can also compile your rules from a file object:
Or you can compile them directly from a Python string:
If you want to compile a group of files or strings at the same time you can do it by using the filepaths or sources named arguments:
Notice that both filepaths and sources must be dictionaries with keys of string type. The dictionary keys are used as a namespace identifier, allowing to differentiate between rules with the same name in different sources, as occurs in the second example with the dummy name.
The compile method also have an optional boolean parameter named includes which allows you to control whether or not the include directive should be accepted in the source files, for example:
If the source file contains include directives the previous line would raise an exception.
If you are using external variables in your rules you must define those externals variables either while compiling the rules, or while applying the rules to some file. To define your variables at the moment of compilation you should pass the externals parameter to the compile method. For example:
The externals parameter must be a dictionary with the names of the variables as keys and an associated value of either string, integer or boolean type.
The compile method also accepts the optional boolean argument error_on_warning . This arguments tells YARA to raise an exception when a warning is issued during compilation. Such warnings are typically issued when your rules contains some construct that could be slowing down the scanning. The default value for the error_on_warning argument is False.
In all cases compile returns an instance of the class yara.Rules Rules. This class have a save method that can be used to save the compiled rules to a file:
The compiled rules can be loaded later by using the load method:
Starting with YARA 3.4 both save and load accept file objects. For example, you can save your rules to a memory buffer with this code:
The saved rules can be loaded from the memory buffer:
The result of load is also an instance of the class yara.Rules .
Instances of Rules also have a match method, which allows to apply the rules to a file:
But you can also apply the rules to a Python string:
Or to a running process:
As in the case of compile , the match method can receive definitions for externals variables in the externals argument.
Externals variables defined during compile-time don’t need to be defined again in subsequent calls to the match method. However you can redefine any variable as needed, or provide additional definitions that weren’t provided during compilation.
In some situations involving a very large set of rules or huge files the match method can take too much time to run. In those situations you may find useful the timeout argument:
If the match function does not finish before the specified number of seconds elapsed, a TimeoutError exception is raised.
You can also specify a callback function when invoking match method. The provided function will be called for every rule, no matter if matching or not. Your callback function should expect a single parameter of dictionary type, and should return CALLBACK_CONTINUE to proceed to the next rule or CALLBACK_ABORT to stop applying rules to your data.
Here is an example:
The passed dictionary will be something like this:
The matches field indicates if the rules matches the data or not. The strings fields is a list of matching strings, with vectors of the form:
The match method returns a list of instances of the class Match . Instances of this class have the same attributes as the dictionary passed to the callback function.
Reference¶
Compile YARA sources.
Either filepath, source, file, filepaths or sources must be provided. The remaining arguments are optional.
Parameters:
filepath (str) – Path to the source file.
source (str) – String containing the rules code.
file (file-object) – Source file as a file object.
filepaths (dict) – Dictionary where keys are namespaces and values are paths to source files.
sources (dict) – Dictionary where keys are namespaces and values are strings containing rules code.
externals (dict) – Dictionary with external variables. Keys are variable names and values are variable values.
includes (boolean) – True if include directives are allowed or False otherwise. Default value: True.
error_on_warning (boolean) – If true warnings are treated as errors, raising an exception.
YARA is a multi-platform program running on Windows, Linux and Mac OS X. You can find the latest release at https://github.com/VirusTotal/yara/releases.
Compiling and installing YARA¶
Download the source tarball and get prepared for compiling it:
Make sure you have automake , libtool , make and gcc and pkg-config installed in your system. Ubuntu and Debian users can use:
If you plan to modify YARA’s source code you may also need flex and bison for generating lexers and parsers:
Compile and install YARA in the standard way:
Run the test cases to make sure that everything is fine:
Some of YARA’s features depend on the OpenSSL library. Those features are enabled only if you have the OpenSSL library installed in your system. If not, YARA is going to work fine but you won’t be able to use the disabled features. The configure script will automatically detect if OpenSSL is installed or not. If you want to enforce the OpenSSL-dependent features you must pass —with-crypto to the configure script. Ubuntu and Debian users can use sudo apt-get install libssl-dev to install the OpenSSL library.
The following modules are not compiled into YARA by default:
If you plan to use them you must pass the corresponding —enable- name> arguments to the configure script.
Modules usually depend on external libraries, depending on the modules you choose to install you’ll need the following libraries:
cuckoo: Depends on Jansson for parsing JSON. Some Ubuntu and Debian versions already include a package named libjansson-dev , if sudo apt-get install libjansson-dev doesn’t work for you then get the source code from its repository.
magic: Depends on libmagic, a library used by the Unix standard program file. Ubuntu, Debian and CentOS include a package libmagic-dev . The source code can be found here.
Installing with vcpkg¶
You can also download and install YARA using the vcpkg dependency manager:
The YARA port in vcpkg is kept up to date by Microsoft team members and community contributors. If the version is out of date, please create an issue or pull request on the vcpkg repository.
Installing on Windows¶
Compiled binaries for Windows in both 32 and 64 bit flavors can be found in the link below. Just download the version you want, unzip the archive, and put the yara.exe and yarac.exe binaries anywhere in your disk.
To install YARA using Scoop or Chocolatey, simply type scoop install yara or choco install yara . The integration with both Scoop and Chocolatey are not maintained their respective teams, not by the YARA authors.
Installing on Mac OS X with Homebrew¶
To install YARA using Homebrew, simply type brew install yara .
Installing yara-python В¶
If you plan to use YARA from your Python scripts you need to install the yara-python extension. Please refer to https://github.com/VirusTotal/yara-python for instructions on how to install it.
Running YARA for the first time¶
Now that you have installed YARA you can write a very simple rule and use the command-line tool to scan some file:
Don’t get confused by the repeated my_first_rule in the arguments to yara , I’m just passing the same file as both the rules and the file to be scanned. You can pass any file you want to be scanned (second argument).
If everything goes fine you should get the following output:
Which means that the file my_first_rule is matching the rule named dummy .
If you get an error like this:
It means that the loader is not finding the libyara library which is located in /usr/local/lib . In some Linux flavors the loader doesn’t look for libraries in this path by default, we must instruct it to do so by adding /usr/local/lib to the loader configuration file /etc/ld.so.conf :
If you’re using Windows PowerShell as your command shell, yara my_first_rule my_first_rule may return this error:
You can avoid this by using the Set-Content cmdlet to specify ascii output when creating your rule file:
YARA can be also used from Python through the yara-python library. Once the library is built and installed as described in Compiling and installing YARA you’ll have access to the full potential of YARA from your Python scripts.
The first step is importing the YARA library:
Then you will need to compile your YARA rules before applying them to your data, the rules can be compiled from a file path:
The default argument is filepath, so you don’t need to explicitly specify its name:
You can also compile your rules from a file object:
Or you can compile them directly from a Python string:
If you want to compile a group of files or strings at the same time you can do it by using the filepaths or sources named arguments:
Notice that both filepaths and sources must be dictionaries with keys of string type. The dictionary keys are used as a namespace identifier, allowing to differentiate between rules with the same name in different sources, as occurs in the second example with the dummy name.
The compile method also has an optional boolean parameter named includes which allows you to control whether or not the include directive should be accepted in the source files, for example:
If the source file contains include directives the previous line would raise an exception.
If includes are used, a python callback can be set to define a custom source for the imported files (by default they are read from disk). This callback function is set through the include_callback optional parameter. It receives the following parameters:
requested_filename : file requested with ‘include’
filename : file containing the ‘include’ directive if applicable, else None
namespace : namespace
And returns the requested rules sources as a single string.
If you are using external variables in your rules you must define those external variables either while compiling the rules, or while applying the rules to some file. To define your variables at the moment of compilation you should pass the externals parameter to the compile method. For example:
The externals parameter must be a dictionary with the names of the variables as keys and an associated value of either string, integer or boolean type.
The compile method also accepts the optional boolean argument error_on_warning . This arguments tells YARA to raise an exception when a warning is issued during compilation. Such warnings are typically issued when your rules contains some construct that could be slowing down the scanning. The default value for the error_on_warning argument is False.
In all cases compile returns an instance of the class yara.Rules Rules. This class has a save method that can be used to save the compiled rules to a file:
The compiled rules can be loaded later by using the load method:
Starting with YARA 3.4 both save and load accept file objects. For example, you can save your rules to a memory buffer with this code:
The saved rules can be loaded from the memory buffer:
The result of load is also an instance of the class yara.Rules .
Instances of Rules also have a match method, which allows you to apply the rules to a file:
But you can also apply the rules to a Python string:
Or to a running process:
As in the case of compile , the match method can receive definitions for external variables in the externals argument.
External variables defined during compile-time don’t need to be defined again in subsequent calls to the match method. However you can redefine any variable as needed, or provide additional definitions that weren’t provided during compilation.
In some situations involving a very large set of rules or huge files the match method can take too much time to run. In those situations you may find useful the timeout argument:
If the match function does not finish before the specified number of seconds elapsed, a TimeoutError exception is raised.
You can also specify a callback function when invoking the match method. By default, the provided function will be called for every rule, no matter if matching or not. You can choose when your callback function is called by setting the which_callbacks parameter to one of yara.CALLBACK_MATCHES , yara.CALLBACK_NON_MATCHES or yara.CALLBACK_ALL . The default is to use yara.CALLBACK_ALL . Your callback function should expect a single parameter of dictionary type, and should return CALLBACK_CONTINUE to proceed to the next rule or CALLBACK_ABORT to stop applying rules to your data.
Here is an example:
The passed dictionary will be something like this:
The matches field indicates if the rule matches the data or not. The strings fields is a list of matching strings, with vectors of the form:
The match method returns a list of instances of the class yara.Match . Instances of this class have the same attributes as the dictionary passed to the callback function.
You can also specify a module callback function when invoking the match method. The provided function will be called for every imported module that scanned a file. Your callback function should expect a single parameter of dictionary type, and should return CALLBACK_CONTINUE to proceed to the next rule or CALLBACK_ABORT to stop applying rules to your data.
Here is an example:
The passed dictionary will contain the information from the module.
You may also find that the default sizes for the stack for the matching engine in yara or the default size for the maximum number of strings per rule is too low. In the C libyara API, you can modify these using the YR_CONFIG_STACK_SIZE and YR_CONFIG_MAX_STRINGS_PER_RULE variables via the yr_set_configuration function in libyara. The command-line tool exposes these as the —stack-size ( -k ) and —max-strings-per-rule command-line arguments. In order to set these values via the Python API, you can use yara.set_config with either or both stack_size and max_strings_per_rule provided as kwargs. At the time of this writing, the default stack size was 16384 and the default maximum strings per rule was 10000 .
Also, yara.set_config accepts the max_match_data argument for controlling the maximum number of bytes that will be returned for each matching string. This is equivalent to using YR_CONFIG_MAX_MATCH_DATA with the yr_set_configuration in the C API. By the default this is set to 512.
Here are a few example calls:
Reference¶
Compile YARA sources.
Either filepath, source, file, filepaths or sources must be provided. The remaining arguments are optional.
Parameters:
filepath (str) — Path to the source file.
source (str) — String containing the rules code.
file (file-object) — Source file as a file object.
filepaths (dict) — Dictionary where keys are namespaces and values are paths to source files.
sources (dict) — Dictionary where keys are namespaces and values are strings containing rules code.
externals (dict) — Dictionary with external variables. Keys are variable names and values are variable values.
includes (boolean) — True if include directives are allowed or False otherwise. Default value: True.
error_on_warning (boolean) — If true warnings are treated as errors, raising an exception.
Returns:
Compiled rules object.
Raises:
yara.SyntaxError — If a syntax error was found.
yara.Error — If an error occurred.
yara. load ( . ) В¶
Changed in version 3.4.0.
Load compiled rules from a path or file object. Either filepath or file must be provided.
Parameters:
filepath (str) — Path to a compiled rules file
file (file-object) — A file object supporting the read method.
Returns:
Compiled rules object.
yara.Error: If an error occurred while loading the file.
yara. set_config ( . ) В¶
Set the configuration variables accessible through the yr_set_configuration API.
Provide either stack_size, max_strings_per_rule, or max_match_data. These kwargs take unsigned integer values as input and will assign the provided value to the yr_set_configuration(. ) variables YR_CONFIG_STACK_SIZE , YR_CONFIG_MAX_STRINGS_PER_RULE , and YR_CONFIG_MAX_MATCH_DATA respectively.
Parameters:
stack_size (int) — Stack size to use for YR_CONFIG_STACK_SIZE
max_strings_per_rule (int) — Maximum number of strings to allow per yara rule. Will be mapped to YR_CONFIG_MAX_STRINGS_PER_RULE .
max_match_data (int) — Maximum number of bytes to allow per yara match. Will be mapped to YR_CONFIG_MAX_MATCH_DATA .
Returns:
NoneType
yara.Error: If an error occurred.
class yara. Rules В¶
Instances of this class are returned by yara.compile() and represents a set of compiled rules.
Either filepath, pid or data must be provided. The remaining arguments are optional.
Parameters:
filepath (str) — Path to the file to be scanned.
pid (int) — Process id to be scanned.
data (str) — Data to be scanned.
externals (dict) — Dictionary with external variables. Keys are variable names and values are variable values.
callback (function) — Callback function invoked for each rule.
fast (bool) — If true performs a fast mode scan.
timeout (int) — Aborts the scanning when the number of specified seconds have elapsed.
modules_data (dict) — Dictionary with additional data to modules. Keys are module names and values are bytes objects containing the additional data.
modules_callback (function) — Callback function invoked for each module.
which_callbacks (int) — An integer that indicates in which cases the callback function must be called. Possible values are yara.CALLBACK_ALL , yara.CALLBACK_MATCHES and yara.CALLBACK_NON_MATCHES .
Raises:
yara.TimeoutError — If the timeout was reached.
yara.Error — If an error occurred during the scan.
save ( . ) В¶
Changed in version 3.4.0.
Save compiled rules to a file. Either filepath or file must be provided.
Parameters:
filepath (str) — Path to the file.
file (file-object) — A file object supporting the write method.
Raises:
yara.Error: If an error occurred while saving the file.
class yara. Match В¶
Objects returned by :py:method:`yara.Rules.match` , representing a match.
Name of the matching rule.
Namespace associated to the matching rule.
Array of strings containig the tags associated to the matching rule.
Dictionary containing metadata associated to the matching rule.
List of tuples containing information about the matching strings. Each tuple has the form: ( , , ) .
