# plyara
[](https://pypi.python.org/pypi/plyara)
Parse [YARA](https://virustotal.github.io/yara/) rules into a dictionary representation.
Plyara is a script and library that lexes and parses a file consisting of one more YARA rules into a python dictionary representation. The goal of this tool is to make it easier to perform bulk operations or transformations of large sets of YARA rules, such as extracting indicators, updating attributes, and analyzing a corpus. Other applications include linters and dependency checkers.
Plyara leverages the Python module [PLY](https://ply.readthedocs.io/en/latest/) for lexing YARA rules.
This is a community-maintained fork of the [original plyara](https://github.com/8u1a/plyara) by [8u1a](https://github.com/8u1a). The "plyara" trademark is used with permission.
## Installation
Plyara requires Python 3.10+.
Install with pip:
```sh
pip install plyara
```
## Usage
Use the plyara Python library in your own applications:
``` python
>>> import plyara
>>> parser = plyara.Plyara()
>>> mylist = parser.parse_string('rule MyRule { strings: $a="1" \n condition: false }')
>>>
>>> import pprint
>>> pprint.pprint(mylist)
[{'condition_terms': ['false'],
'raw_condition': 'condition: false ',
'raw_strings': 'strings: $a="1" \n ',
'rule_name': 'MyRule',
'start_line': 1,
'stop_line': 2,
'strings': [{'name': '$a', 'type': 'text', 'value': '1'}]}]
>>>
```
Or, use the included `plyara` script from the command line:
```sh
$ plyara -h
usage: plyara [-h] [--log] FILE
Parse YARA rules into a dictionary representation.
positional arguments:
FILE File containing YARA rules to parse.
optional arguments:
-h, --help show this help message and exit
--log Enable debug logging to the console.
```
The command-line tool will print valid JSON output when parsing rules:
```sh
$ cat example.yar
rule silent_banker : banker
{
meta:
description = "This is just an example"
thread_level = 3
in_the_wild = true
strings:
$a = {6A 40 68 00 30 00 00 6A 14 8D 91}
$b = {8D 4D B0 2B C1 83 C0 27 99 6A 4E 59 F7 F9}
$c = "UVODFRYSIHLNWPEJXQZAKCBGMT"
condition:
$a or $b or $c
}
```
```sh
$ plyara example.yar
[
{
"condition_terms": [
"$a",
"or",
"$b",
"or",
"$c"
],
"metadata": [
{
"description": "This is just an example"
},
{
"thread_level": 3
},
{
"in_the_wild": true
}
],
"raw_condition": "condition:\n $a or $b or $c\n",
"raw_meta": "meta:\n description = \"This is just an example\"\n thread_level = 3\n in_the_wild = true\n ",
"raw_strings": "strings:\n $a = {6A 40 68 00 30 00 00 6A 14 8D 91}\n $b = {8D 4D B0 2B C1 83 C0 27 99 6A 4E 59 F7 F9}\n $c = \"UVODFRYSIHLNWPEJXQZAKCBGMT\"\n ",
"rule_name": "silent_banker",
"start_line": 1,
"stop_line": 13,
"strings": [
{
"name": "$a",
"type": "byte",
"value": "{6A 40 68 00 30 00 00 6A 14 8D 91}"
},
{
"name": "$b",
"type": "byte",
"value": "{8D 4D B0 2B C1 83 C0 27 99 6A 4E 59 F7 F9}"
},
{
"name": "$c",
"type": "text",
"value": "UVODFRYSIHLNWPEJXQZAKCBGMT"
}
],
"tags": [
"banker"
]
}
]
```
## Reusing The Parser
If you want to reuse a single instance of the parser object for efficiency when parsing large quantities of rule or rulesets, the new clear() method must be used.
``` python
rules = list()
parser = plyara.Plyara()
for file in files:
with open(file, 'r') as fh:
yararules = parser.parse_string(fh.read())
rules += yararules
parser.clear()
```
## Breaking Change: Import Effects
### Background
Imports are available to be used in a rule even if not used in a condition. Also, any module which is imported at all is used in processing all files scanned using the ruleset regardless if the import is used anywhere. Some users require that all rules affected by a particular import include that import in the dictionary output of plyara. At the same time, many users expect that a particular rule not include an import if that import is not used in the rule.
### New Parameter: Import Effects
A new class constructor parameter called `import_effects` has been added to the parser. This parameter defaults to `False` which is a breaking change. Users who wish to retain the behavior from versions before 2.2, will need to set this parameter to `True` like so:
```python
parser = plyara.Plyara(import_effects=True)
```
### Note
When reusing a `parser` for multiple rules and/or files and `import_effects` is enabled, be aware that imports are now shared across all rules - if one rule has an import, that import will be added to all rules in your parser object.
## Known Issues
Due to an unsolved issue with precendece, a `-` operator is being considered a negative number. Until this is fixed, it is recommended that users employ YARA-X's `fmt` command to pre-process yara rulesets for automatic formatting before using plyara on problematic rulesets.
```bash
yr fmt foo.yar
```
More information here: https://github.com/plyara/plyara/issues/112
## Contributing
- If you find a bug, or would like to see a new feature, [Pull Requests](https://github.com/plyara/plyara/pulls) and [Issues](https://github.com/plyara/plyara/issues) are always welcome.
- By submitting changes, you agree to release those changes under the terms of the [LICENSE](https://github.com/plyara/plyara/blob/master/LICENSE).
- Writing passing unit tests for your changes, while not required, is highly encouraged and appreciated.
- Please run all code contributions through each of the linters that we use for this project:
- pycodestyle
- pydocstyle
- pyflakes
- For more information on these linters, please refer to the [Python Code Quality Authority](https://pycqa.org/)
## Unit Tests
```bash
python -m unittest discover
```
## Coverage
```bash
coverage run -m unittest discover
coverage report -m
```
Raw data
{
"_id": null,
"home_page": null,
"name": "plyara",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "malware, analysis, yara",
"author": "plyara Maintainers",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/2d/53/ebd0ea7227c2c51fc685b921e106874e7664c1232fa116397c2300fa96df/plyara-2.2.2.tar.gz",
"platform": null,
"description": "# plyara\n\n[](https://pypi.python.org/pypi/plyara)\n\nParse [YARA](https://virustotal.github.io/yara/) rules into a dictionary representation.\n\nPlyara is a script and library that lexes and parses a file consisting of one more YARA rules into a python dictionary representation. The goal of this tool is to make it easier to perform bulk operations or transformations of large sets of YARA rules, such as extracting indicators, updating attributes, and analyzing a corpus. Other applications include linters and dependency checkers.\n\nPlyara leverages the Python module [PLY](https://ply.readthedocs.io/en/latest/) for lexing YARA rules.\n\nThis is a community-maintained fork of the [original plyara](https://github.com/8u1a/plyara) by [8u1a](https://github.com/8u1a). The \"plyara\" trademark is used with permission.\n\n## Installation\n\nPlyara requires Python 3.10+.\n\nInstall with pip:\n\n```sh\npip install plyara\n```\n\n## Usage\n\nUse the plyara Python library in your own applications:\n\n``` python\n>>> import plyara\n>>> parser = plyara.Plyara()\n>>> mylist = parser.parse_string('rule MyRule { strings: $a=\"1\" \\n condition: false }')\n>>>\n>>> import pprint\n>>> pprint.pprint(mylist)\n[{'condition_terms': ['false'],\n 'raw_condition': 'condition: false ',\n 'raw_strings': 'strings: $a=\"1\" \\n ',\n 'rule_name': 'MyRule',\n 'start_line': 1,\n 'stop_line': 2,\n 'strings': [{'name': '$a', 'type': 'text', 'value': '1'}]}]\n>>>\n```\n\nOr, use the included `plyara` script from the command line:\n\n```sh\n$ plyara -h\nusage: plyara [-h] [--log] FILE\n\nParse YARA rules into a dictionary representation.\n\npositional arguments:\n FILE File containing YARA rules to parse.\n\noptional arguments:\n -h, --help show this help message and exit\n --log Enable debug logging to the console.\n```\n\nThe command-line tool will print valid JSON output when parsing rules:\n\n```sh\n$ cat example.yar\nrule silent_banker : banker\n{\n meta:\n description = \"This is just an example\"\n thread_level = 3\n in_the_wild = true\n strings:\n $a = {6A 40 68 00 30 00 00 6A 14 8D 91}\n $b = {8D 4D B0 2B C1 83 C0 27 99 6A 4E 59 F7 F9}\n $c = \"UVODFRYSIHLNWPEJXQZAKCBGMT\"\n condition:\n $a or $b or $c\n}\n```\n\n```sh\n$ plyara example.yar\n[\n {\n \"condition_terms\": [\n \"$a\",\n \"or\",\n \"$b\",\n \"or\",\n \"$c\"\n ],\n \"metadata\": [\n {\n \"description\": \"This is just an example\"\n },\n {\n \"thread_level\": 3\n },\n {\n \"in_the_wild\": true\n }\n ],\n \"raw_condition\": \"condition:\\n $a or $b or $c\\n\",\n \"raw_meta\": \"meta:\\n description = \\\"This is just an example\\\"\\n thread_level = 3\\n in_the_wild = true\\n \",\n \"raw_strings\": \"strings:\\n $a = {6A 40 68 00 30 00 00 6A 14 8D 91}\\n $b = {8D 4D B0 2B C1 83 C0 27 99 6A 4E 59 F7 F9}\\n $c = \\\"UVODFRYSIHLNWPEJXQZAKCBGMT\\\"\\n \",\n \"rule_name\": \"silent_banker\",\n \"start_line\": 1,\n \"stop_line\": 13,\n \"strings\": [\n {\n \"name\": \"$a\",\n \"type\": \"byte\",\n \"value\": \"{6A 40 68 00 30 00 00 6A 14 8D 91}\"\n },\n {\n \"name\": \"$b\",\n \"type\": \"byte\",\n \"value\": \"{8D 4D B0 2B C1 83 C0 27 99 6A 4E 59 F7 F9}\"\n },\n {\n \"name\": \"$c\",\n \"type\": \"text\",\n \"value\": \"UVODFRYSIHLNWPEJXQZAKCBGMT\"\n }\n ],\n \"tags\": [\n \"banker\"\n ]\n }\n]\n```\n\n## Reusing The Parser\n\nIf you want to reuse a single instance of the parser object for efficiency when parsing large quantities of rule or rulesets, the new clear() method must be used.\n\n``` python\nrules = list()\nparser = plyara.Plyara()\n\nfor file in files:\n with open(file, 'r') as fh:\n yararules = parser.parse_string(fh.read())\n rules += yararules\n parser.clear()\n```\n\n## Breaking Change: Import Effects\n\n### Background\n\nImports are available to be used in a rule even if not used in a condition. Also, any module which is imported at all is used in processing all files scanned using the ruleset regardless if the import is used anywhere. Some users require that all rules affected by a particular import include that import in the dictionary output of plyara. At the same time, many users expect that a particular rule not include an import if that import is not used in the rule.\n\n### New Parameter: Import Effects\n\nA new class constructor parameter called `import_effects` has been added to the parser. This parameter defaults to `False` which is a breaking change. Users who wish to retain the behavior from versions before 2.2, will need to set this parameter to `True` like so:\n\n```python\nparser = plyara.Plyara(import_effects=True)\n```\n\n### Note\n\nWhen reusing a `parser` for multiple rules and/or files and `import_effects` is enabled, be aware that imports are now shared across all rules - if one rule has an import, that import will be added to all rules in your parser object.\n\n## Known Issues\n\nDue to an unsolved issue with precendece, a `-` operator is being considered a negative number. Until this is fixed, it is recommended that users employ YARA-X's `fmt` command to pre-process yara rulesets for automatic formatting before using plyara on problematic rulesets.\n\n```bash\nyr fmt foo.yar\n```\n\nMore information here: https://github.com/plyara/plyara/issues/112\n\n## Contributing\n\n- If you find a bug, or would like to see a new feature, [Pull Requests](https://github.com/plyara/plyara/pulls) and [Issues](https://github.com/plyara/plyara/issues) are always welcome.\n- By submitting changes, you agree to release those changes under the terms of the [LICENSE](https://github.com/plyara/plyara/blob/master/LICENSE).\n- Writing passing unit tests for your changes, while not required, is highly encouraged and appreciated.\n- Please run all code contributions through each of the linters that we use for this project:\n - pycodestyle\n - pydocstyle\n - pyflakes\n- For more information on these linters, please refer to the [Python Code Quality Authority](https://pycqa.org/)\n\n## Unit Tests\n\n```bash\npython -m unittest discover\n```\n\n## Coverage\n\n```bash\ncoverage run -m unittest discover\ncoverage report -m\n```\n",
"bugtrack_url": null,
"license": null,
"summary": "Parse YARA rules",
"version": "2.2.2",
"project_urls": {
"Homepage": "https://github.com/plyara/plyara",
"Issues": "https://github.com/plyara/plyara/issues"
},
"split_keywords": [
"malware",
" analysis",
" yara"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "fc469b0d7836056c7404fc88444d701d0b9a5488395aaaed135b836c0c2a5f27",
"md5": "0fff16dd1d171bd42afe057c06e99876",
"sha256": "8776cae3018dcc99e3cceadf9a267f6facf11b38320b30356aab731f8087f12f"
},
"downloads": -1,
"filename": "plyara-2.2.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0fff16dd1d171bd42afe057c06e99876",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 24231,
"upload_time": "2024-12-12T04:10:39",
"upload_time_iso_8601": "2024-12-12T04:10:39.693151Z",
"url": "https://files.pythonhosted.org/packages/fc/46/9b0d7836056c7404fc88444d701d0b9a5488395aaaed135b836c0c2a5f27/plyara-2.2.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "2d53ebd0ea7227c2c51fc685b921e106874e7664c1232fa116397c2300fa96df",
"md5": "3e3fe1c32746116ec764a71a0b69d415",
"sha256": "008c57b6ef4873437c236f70da1fec3f911d5acb1c996cdaf56921572be54acd"
},
"downloads": -1,
"filename": "plyara-2.2.2.tar.gz",
"has_sig": false,
"md5_digest": "3e3fe1c32746116ec764a71a0b69d415",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 35196,
"upload_time": "2024-12-12T04:10:40",
"upload_time_iso_8601": "2024-12-12T04:10:40.931853Z",
"url": "https://files.pythonhosted.org/packages/2d/53/ebd0ea7227c2c51fc685b921e106874e7664c1232fa116397c2300fa96df/plyara-2.2.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-12 04:10:40",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "plyara",
"github_project": "plyara",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "plyara"
}
JSON
