yarabuilder 0.0.6
A package to build YARA rules using Python
Requires Python: >=3.6

yarabuilder
===========

.. image:: https://readthedocs.org/projects/yarabuilder/badge/?version=latest
  :target: https://yarabuilder.readthedocs.io/en/latest/?badge=latest
  :alt: Documentation Status
.. image:: http://img.shields.io/pypi/v/yarabuilder.svg
  :target: https://pypi.org/project/yarabuilder/
  :alt: PyPi Version

Python module to create Yara rules.

Installation
------------

yarabuilder requires Python 3+::

    pip install yarabuilder
    
Usage
-----
Creating and printing a rule
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. code-block:: python

    >>> import yarabuilder
    >>> import pprint
    >>>
    >>> yara_builder = yarabuilder.YaraBuilder()
    >>>
    >>> yara_builder.create_rule("my_rule")
    >>> yara_builder.add_meta("my_rule", "description", "Generated by yarabuilder")
    >>> yara_builder.add_import("my_rule", "pe")
    >>> yara_builder.add_tag("my_rule", "yarabuilder")
    >>> yara_builder.add_text_string("my_rule", "Anonymous string")
    >>> yara_builder.add_text_string("my_rule", "Named string", name="str", modifiers=["ascii", "wide"])
    >>> yara_builder.add_string_comment("my_rule", "str", "example comment")
    >>> yara_builder.add_hex_string("my_rule", "DE AD BE EF")
    >>> yara_builder.add_regex_string("my_rule", "regex[0-9]{2}")
    >>> yara_builder.add_regex_string("my_rule", "/regex_with_flags/i")
    >>> yara_builder.add_condition("my_rule", "any of them")
    >>>
    >>> rule = yara_builder.build_rules()
    >>> print(rule)
    import "pe"
    
    rule my_rule : yarabuilder {
        meta:
            description = "Generated by yarabuilder"
    
        strings:
            $ = "Anonymous string"
            $str = "Named string" ascii wide // example comment
            $ = {DE AD BE EF}
            $ = /regex[0-9]{2}/
            $ = /regex_with_flags/i
    
        condition:
            any of them
    }
    >>>

Converting a YaraBuilder object to lists and dictionaries (and back again)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. code-block:: python

    >>> dict_yara_rules = yara_builder.get_yara_rules()
    >>> pprint.pprint(dict_yara_rules)
    [{'condition': 'any of them',
    'imports': ['pe'],
    'meta': OrderedDict([('description',
                            [{'meta_type': 'text',
                            'name': 'description',
                            'position': 0,
                            'value': 'Generated by yarabuilder'}])]),
    'rule_name': 'my_rule',
    'strings': OrderedDict([('@anon0',
                            {'is_anonymous': True,
                                'name': '@anon0',
                                'str_type': 'text',
                                'value': 'Anonymous string'}),
                            ('str',
                            {'comment': {'inline': 'example comment'},
                                'is_anonymous': False,
                                'modifiers': ['ascii', 'wide'],
                                'name': 'str',
                                'str_type': 'text',
                                'value': 'Named string'}),
                            ('@anon1',
                            {'is_anonymous': True,
                                'name': '@anon1',
                                'str_type': 'hex',
                                'value': 'DE AD BE EF'}),
                            ('@anon2',
                            {'is_anonymous': True,
                                'name': '@anon2',
                                'str_type': 'regex',
                                'value': 'regex[0-9]{2}'}),
                            ('@anon3',
                            {'is_anonymous': True,
                                'name': '@anon3',
                                'regex_flags': 'i',
                                'str_type': 'regex',
                                'value': 'regex_with_flags'})]),
    'tags': ['yarabuilder']}]
    >>>
    >>> new_builder = yarabuilder.YaraBuilder()
    >>> new_builder.set_yara_rules(dict_yara_rules)
    >>>

TODO
----
- More logging in the classes
- Add optional validation for building YARA rules (e.g. checking imports are valid, and more longer term check the condition is valid)