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).
- Results returned from a
- 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
- This module contains an equivalent
Rules
¶
-
class
yara.rules.
Rules
(paths={}, defines={}, include_path=[], strings=[], externals={}, fast_match=False)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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/stable/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/stable/bin', '/usr/local/sbin', '/usr/local/bin', '/usr/sbin', '/usr/bin', '/sbin', '/bin'], **rules_kwargs)[source]¶ 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)[source]¶ 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