yara.rules — YARA namespaces, compilation, and matching

Compiles a YARA rules files into a thread safe Rules object ready for matching.

Features:

• Provides a thread safe yara context manager.
• Detailed control over the loading of multiple YARA rules files into a
• single context.
• A C-like preprocessor for yar files. Allows for #ifdef #ifndef etc.

Key differences to yara-python.c:

• Results returned from a Rules.match(_??) function are stored in a dict of {namespace:[match,...]}...
• When a callback hander is passed into a Rules.match(_??) function, the match function will return an empty dict. It is assumed that the callback handler will retain the match objects that it cares about.
• The match dict inside of a dict returned from a Rules.match(_??) function no longer contain the namespace (namespace is the key used to reference the match dict).

Compatibility with yara-python.c

• This module contains an equivalent compile() function
• The Rules object contains an equivalent match() function
• Match objects passed into the registered callback handler are the equivalent

Rules

class yara.rules.Rules(paths={}, defines={}, include_path=[], strings=[], externals={}, fast_match=False)

Rules manages the seamless construction of a new context per thread and exposes libyara’s match capability.

__init__(paths={}, defines={}, include_path=[], strings=[], externals={}, fast_match=False)

Defines a new yara context with specified yara sigs

Options:

paths - {namespace:rules_path,...} include_path - a list of paths to search for given #include

directives.

defines - key:value defines for the preprocessor. Sub in

strings or macros defined in your rules files.

strings - [(namespace, filename, rules_string),...] externals - define boolean, integer, or string variables

{var:val,...}

fast_match - enable fast matching in the YARA context

Note:

namespace - defines which namespace we’re building our rules under rules_path - path to the .yar file filename - filename which the rules_string came from rules_string - the text read from a .yar file

match(filepath=None, pid=None, data=None, **match_kwargs)

Match on one of the following: pid= filepath= or data= Require one of the following:

filepath - filepath to match against pid - process id data - filepath to match against

Options:

externals - define boolean, integer, or string variables callback - provide a callback function which will get called with

the match results as they comes in.

Note #1: If callback is set, the Rules object doesn’t bother

storing the match results and this func will return []... The callback hander needs to deal with individual matches.

Note #2:

The callback can abort the matching sequence by returning a CALLBACK_ABORT or raising a StopIteration() exception. To continue, a return object of None or CALLBACK_CONTINUE is required.

Functionally equivalent to (yara-python.c).match

match_data(data, externals={}, callback=None)

Match data against the compiled rules Required argument:

data - filepath to match against

Options:

externals - define boolean, integer, or string variables callback - provide a callback function which will get called with

the match results as they comes in.

Note #1: If callback is set, the Rules object doesn’t bother

storing the match results and this func will return []... The callback hander needs to deal with individual matches.

Note #2:

The callback can abort the matching sequence by returning a CALLBACK_ABORT or raising a StopIteration() exception. To continue, a return object of None or CALLBACK_CONTINUE is required.

Return a dictionary of {“namespace”:[match1,match2,...]}

match_path(filepath, externals={}, callback=None)

Match a filepath against the compiled rules Required argument:

filepath - filepath to match against

Options:

externals - define boolean, integer, or string variables callback - provide a callback function which will get called with

the match results as they comes in.

Note #1: If callback is set, the Rules object doesn’t bother

storing the match results and this func will return []... The callback hander needs to deal with individual matches.

Note #2:

The callback can abort the matching sequence by returning a CALLBACK_ABORT or raising a StopIteration() exception. To continue, a return object of None or CALLBACK_CONTINUE is required.

Return a dictionary of {“namespace”:[match1,match2,...]}

match_proc(pid, externals={}, callback=None)

Match a process memory against the compiled rules Required argument:

pid - process id

Options:

externals - define boolean, integer, or string variables callback - provide a callback function which will get called with

the match results as they comes in.

Note #1: If callback is set, the Rules object doesn’t bother

storing the match results and this func will return []... The callback hander needs to deal with individual matches.

Note #2:

The callback can abort the matching sequence by returning a CALLBACK_ABORT or raising a StopIteration() exception. To continue, a return object of None or CALLBACK_CONTINUE is required.

Return a dictionary of {“namespace”:[match1,match2,...]}

yara.rules.load_rules()

yara.rules.load_rules(rules_rootpath='/home/docs/checkouts/readthedocs.org/user_builds/yara-ctypes/envs/latest/local/lib/python2.7/site-packages/yara-1.7.7-py2.7.egg/yara/rules', blacklist=[], whitelist=[], include_path=['/home/docs/checkouts/readthedocs.org/user_builds/yara-ctypes/envs/latest/bin', '/usr/local/sbin', '/usr/local/bin', '/usr/sbin', '/usr/bin', '/sbin', '/bin'], **rules_kwargs)

A simple way to build a complex yara Rules object with strings equal to [(namespace:filepath:source),...]

YARA rules files found under the rules_rootpath are loaded based on the exclude namespace blacklist or include namespace whitelist.

i.e. Where rules_rootpath = ‘./rules’ which contained:

./rules/hbgary/libs.yar ./rules/hbgary/compression.yar ./rules/hbgary/fingerprint.yar

The resultant Rules object would contain the following namespaces:

hbgary.libs hbgary.compression hbgary.fingerprint

Optional YARA rule loading parameters:

rules_rootpath - root dir to search for YARA rules files blacklist - namespaces “starting with” to exclude whitelist - namespaces “starting with” to include

Rule options:

externals - define boolean, integer, or string variables {var:val,...} fast_match - enable fast matching in the YARA context

yara.rules.compile()

yara.rules.compile(filepath=None, source=None, fileobj=None, filepaths=None, sources=None, **rules_kwargs)

Compiles a YARA rules file and returns an instance of class Rules

Require one of the following:

filepath - str object containing a YARA rules filepath source - str object containing YARA source fileobj - a file object containing a set of YARA rules filepaths - {namespace:filepath,...} sources - {namespace:source_str,...}

Rule options:

externals - define boolean, integer, or string variables {var:val,...} fast_match - enable fast matching in the YARA context

Functionally equivalent to (yara-python.c).compile