| Name | defender2yara JSON |
| Version |
1.0.2
JSON |
| download |
| home_page | None |
| Summary | Convert Microsoft Defender Antivirus Signatures(VDM) to YARA rules. |
| upload_time | 2024-07-25 16:44:48 |
| maintainer | None |
| docs_url | None |
| author | Tomoaki Tani |
| requires_python | <4.0,>=3.10 |
| license | None |
| keywords |
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# defender2yara
`defender2yara` is a Python tool that converts Microsoft Defender Antivirus Signatures (VDM) into YARA rules. This tool facilitates the creation of custom YARA rules from the latest signature databases or manually provided .vdm files from Microsoft Defender, allowing for enhanced malware detection,analysis and threat hunting.
This project focuses solely on antivirus signatures and does NOT address EDR signatures or detection logic.
## Features
- Convert Microsoft Defender Antivirus Signatures (VDM) to YARA rules.
- Supports strings and hex bytes pattern matching with regex-like expression
- Supports to convert scoring rules into YARA conditions
- Download the latest signature database.
- Export YARA rules into a single file or files per malware family.
- Add file-header checks to the rules to optimize the scan with the generated YARA rules.
- Manually specify the paths for base and delta VDM files.
## Generated YARA rules
Users can find the generated rules by `defender2yara` in the [*yara-rules*](https://github.com/t-tani/defender2yara/tree/yara-rules) branch.
This branch updates the rules every 30 minutes.
## Installation
Users can install `defender2yara` using `pip` or `Poetry`.
### Using `pip`
Ensure the user has Python 3.10 or later installed on the system. Users can install the tool using `pip`:
```sh
pip install defender2yara
```
### Using `Poetry`
1. Clone the GitHub repository:
```sh
git clone https://github.com/t-tani/defender2yara.git
```
2. Move to the cloned directory:
```sh
cd defender2yara
```
3. Install the dependencies using `Poetry`:
```sh
poetry install
```
## Usage
The following options are available for using `defender2yara`:
```txt
usage: defender2yara [options]
Convert Microsoft Defender Antivirus Signatures(VDM) to YARA rules.
options:
-h, --help show this help message and exit
-v, --version show defender2yara version
-l, --latest_signature_version
show latest signature version
-o OUTPUT, --output OUTPUT
output directory for YARA rules [default: ./rules]
-d, --download only download the latest signature database
-c CACHE, --cache CACHE
directory to save signature database(vdm/dll files) [default: ./cache]
-s, --single_file export YARA rules into a single file
--header_check add file header check to generated YARA rules
--full_engine FULL_ENGINE, --fe FULL_ENGINE
manually specify the path of mpam-fe.exe
--base BASE manually specify the path of mpa{v|s}base.vdm
--delta DELTA manually specify the path of mpa{v|s}dlta.vdm
--proxy PROXY use a proxy to download signatures (e.g. http://localhost:8000)
--debug print detailed logs
--suppress suppress all logs
```
## Examples
### Download and Convert the Latest Signatures to YARA Rules
To download the latest signature database and convert it to YARA rules, use the following command:
```sh
defender2yara
```
`defender2yara` generates the following files:
- ./rules/[signature_version]/[platform]/[malware_type]/[family_name].yara
If the user wants to change the directory from .rules, they can use the `--output` or `-o` option to specify the directory.
### Download the Latest Signature
To download the latest signature database, use the following command:
```sh
defender2yara -d
```
`defender2yara` downloads the latest signatures into the following directory:
- ./cache/vdm/[major_version]/0.0/mpa{s,v}base.vdm
- ./cache/vdm/[major_version]/[minor_version]/mpa{s,v}dlta.vdm
- ./cache/engine/[engine_version]/mpengine.dll
If the user wants to change the directory from .cache, they can use the `--cache` or `-c` option to specify their directory.
### Convert Signatures to a Single YARA File
To export the YARA rules into a single file, use the `--single_file` option:
```sh
defender2yara --single_file
```
`defender2yara` generates the following two files:
- ./rules/[signature_version]/anti-virus.yara
- ./rules/[signature_version]/anti-spyware.yara
### Add File Header Check to YARA Rules
To add file header checks to the generated YARA rules, use the `--header_check` option:
```sh
defender2yara --header_check
```
Currently, the `--header_check` option adds the following header checks to YARA rules that aim to detect the following files:
- PE File
- MACH-O File
- ELF File
### Manually Specify Signature Update File(mpam-fe.exe)
If the user wants to manually specify the paths of the mpam-fe.exe, use the `--fe` or `--full_engine` options:
```sh
defender2yara --fe /path/to/mpam-fe.exe
```
### Manually Specify Base and Delta VDM Files
If the user wants to manually specify the paths of the base and delta VDM files, use the `--base` and `--delta` options:
```sh
defender2yara --base /path/to/mpavbase.vdm --delta /path/to/mpavdlta.vdm
```
### Use a Proxy for Downloading Signatures
If the user needs to use a proxy to download the signatures, specify the proxy URL using the `--proxy` option:
```sh
defender2yara --proxy http://localhost:8000
```
### Debugging and Logging
Use the `--debug` option to show detailed logs. Use the `--suppress` option to suppress all logs.
```sh
defender2yara --debug
```
```sh
defender2yara --suppress
```
## Limitations
- Some regex-like pattern matching in Microsoft Defender cannot be fully converted due to:
- Limitations of the YARA engine
- Undocumented or unknown implementations within `mpengine.dll`
- Several advanced features of Microsoft Defender are not supported, such as:
- Emulator engines
- Logic implemented in Lua
- Unpacker modules
- And other proprietary technologies
## License
This project is licensed under the MIT License. See the [LICENSE](./LICENSE) file for details.
## Contributing
Contributions are welcome. Please submit a pull request or open an issue to discuss changes or improvements.
## Contact
For any questions or issues, please open an issue on [this GitHub repository](https://github.com/t-tani/defender2yara).
## Acknowledgments
This project would not have been possible without the valuable resources and insights provided by the following:
- **GitHub - commial/experiments** and **Windows Defender: Demystifying and Bypassing ASR by Understanding the AVS Signatures**: A special thanks to the author of the [commial/experiments](https://github.com/commial/experiments) repository on GitHub and the insightful paper [Windows Defender: Demystifying and Bypassing ASR by Understanding the AVS Signatures](https://i.blackhat.com/EU-21/Wednesday/EU-21-Mougey-Windows-Defender-demystifying-and-bypassing-asr-by-understanding-the-avs-signatures.pdf), presented at Black Hat Europe 2021. His work and research have significantly aided our understanding of various aspects of antivirus signatures and provided deep insights into the workings of Windows Defender signatures.
- **GitHub—taviso/loadlibrary**: A special thanks to Tavis Ormandy's repository [loadlibrary] (https://github.com/taviso/loadlibrary) on GitHub. This repository provided great insights into Microsoft Defender and was an entry point for reversing `msmpeng.dll`.
- **Retooling Blog**: We also appreciate the author of the Retooling blog for their detailed article [An Unexpected Journey into Microsoft Defender's Signature World](https://retooling.io/blog/an-unexpected-journey-into-microsoft-defenders-signature-world). Their exploration and documentation of Microsoft Defender's signature mechanisms have been invaluable to this project.
- **Threat Name Definitions**: We acknowledge Microsoft for their detailed [Threat Name Definitions](https://learn.microsoft.com/en-us/defender-xdr/malware-naming?view=o365-worldwide). This documentation has been essential in understanding the malware naming conventions used by Microsoft Defender.
Thank you to all these sources for contributing to the field and sharing their knowledge with the community.
Raw data
{
"_id": null,
"home_page": null,
"name": "defender2yara",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.10",
"maintainer_email": null,
"keywords": null,
"author": "Tomoaki Tani",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/d2/88/4d3a084c07474c048738c58bf839dd14a97bbc39e89c8467c2a766b1602c/defender2yara-1.0.2.tar.gz",
"platform": null,
"description": "\n\n# defender2yara\n\n`defender2yara` is a Python tool that converts Microsoft Defender Antivirus Signatures (VDM) into YARA rules. This tool facilitates the creation of custom YARA rules from the latest signature databases or manually provided .vdm files from Microsoft Defender, allowing for enhanced malware detection,analysis and threat hunting.\n\nThis project focuses solely on antivirus signatures and does NOT address EDR signatures or detection logic.\n\n## Features\n\n- Convert Microsoft Defender Antivirus Signatures (VDM) to YARA rules.\n - Supports strings and hex bytes pattern matching with regex-like expression\n - Supports to convert scoring rules into YARA conditions\n- Download the latest signature database.\n- Export YARA rules into a single file or files per malware family.\n- Add file-header checks to the rules to optimize the scan with the generated YARA rules.\n- Manually specify the paths for base and delta VDM files.\n\n## Generated YARA rules \n\nUsers can find the generated rules by `defender2yara` in the [*yara-rules*](https://github.com/t-tani/defender2yara/tree/yara-rules) branch.\nThis branch updates the rules every 30 minutes.\n\n## Installation\n\nUsers can install `defender2yara` using `pip` or `Poetry`.\n\n### Using `pip`\n\nEnsure the user has Python 3.10 or later installed on the system. Users can install the tool using `pip`:\n\n```sh\npip install defender2yara\n```\n\n### Using `Poetry`\n\n1. Clone the GitHub repository:\n\n```sh\ngit clone https://github.com/t-tani/defender2yara.git\n```\n\n2. Move to the cloned directory:\n\n```sh\ncd defender2yara\n```\n\n3. Install the dependencies using `Poetry`:\n\n```sh\npoetry install\n```\n\n## Usage\n\nThe following options are available for using `defender2yara`:\n\n```txt\nusage: defender2yara [options]\n\nConvert Microsoft Defender Antivirus Signatures(VDM) to YARA rules.\n\noptions:\n -h, --help show this help message and exit\n -v, --version show defender2yara version\n -l, --latest_signature_version\n show latest signature version\n -o OUTPUT, --output OUTPUT\n output directory for YARA rules [default: ./rules]\n -d, --download only download the latest signature database\n -c CACHE, --cache CACHE\n directory to save signature database(vdm/dll files) [default: ./cache]\n -s, --single_file export YARA rules into a single file\n --header_check add file header check to generated YARA rules\n --full_engine FULL_ENGINE, --fe FULL_ENGINE\n manually specify the path of mpam-fe.exe\n --base BASE manually specify the path of mpa{v|s}base.vdm\n --delta DELTA manually specify the path of mpa{v|s}dlta.vdm\n --proxy PROXY use a proxy to download signatures (e.g. http://localhost:8000)\n --debug print detailed logs\n --suppress suppress all logs\n```\n\n## Examples\n\n### Download and Convert the Latest Signatures to YARA Rules\n\nTo download the latest signature database and convert it to YARA rules, use the following command:\n\n```sh\ndefender2yara\n```\n\n`defender2yara` generates the following files:\n\n- ./rules/[signature_version]/[platform]/[malware_type]/[family_name].yara\n\nIf the user wants to change the directory from .rules, they can use the `--output` or `-o` option to specify the directory.\n\n\n### Download the Latest Signature\n\nTo download the latest signature database, use the following command:\n\n```sh\ndefender2yara -d\n```\n\n`defender2yara` downloads the latest signatures into the following directory:\n\n- ./cache/vdm/[major_version]/0.0/mpa{s,v}base.vdm\n- ./cache/vdm/[major_version]/[minor_version]/mpa{s,v}dlta.vdm\n- ./cache/engine/[engine_version]/mpengine.dll\n\nIf the user wants to change the directory from .cache, they can use the `--cache` or `-c` option to specify their directory.\n\n### Convert Signatures to a Single YARA File\n\nTo export the YARA rules into a single file, use the `--single_file` option:\n\n```sh\ndefender2yara --single_file\n```\n\n`defender2yara` generates the following two files:\n\n- ./rules/[signature_version]/anti-virus.yara\n- ./rules/[signature_version]/anti-spyware.yara\n\n\n### Add File Header Check to YARA Rules\n\nTo add file header checks to the generated YARA rules, use the `--header_check` option:\n\n```sh\ndefender2yara --header_check\n```\n\nCurrently, the `--header_check` option adds the following header checks to YARA rules that aim to detect the following files:\n\n- PE File\n- MACH-O File\n- ELF File\n\n### Manually Specify Signature Update File(mpam-fe.exe)\n\nIf the user wants to manually specify the paths of the mpam-fe.exe, use the `--fe` or `--full_engine` options:\n\n```sh\ndefender2yara --fe /path/to/mpam-fe.exe\n```\n\n### Manually Specify Base and Delta VDM Files\n\nIf the user wants to manually specify the paths of the base and delta VDM files, use the `--base` and `--delta` options:\n\n```sh\ndefender2yara --base /path/to/mpavbase.vdm --delta /path/to/mpavdlta.vdm\n```\n\n### Use a Proxy for Downloading Signatures\n\nIf the user needs to use a proxy to download the signatures, specify the proxy URL using the `--proxy` option:\n\n```sh\ndefender2yara --proxy http://localhost:8000\n```\n\n### Debugging and Logging\n\nUse the `--debug` option to show detailed logs. Use the `--suppress` option to suppress all logs.\n\n```sh\ndefender2yara --debug\n```\n\n```sh\ndefender2yara --suppress\n```\n\n## Limitations\n\n- Some regex-like pattern matching in Microsoft Defender cannot be fully converted due to:\n - Limitations of the YARA engine\n - Undocumented or unknown implementations within `mpengine.dll`\n- Several advanced features of Microsoft Defender are not supported, such as:\n - Emulator engines\n - Logic implemented in Lua\n - Unpacker modules\n - And other proprietary technologies\n\n## License\n\nThis project is licensed under the MIT License. See the [LICENSE](./LICENSE) file for details.\n\n## Contributing\n\nContributions are welcome. Please submit a pull request or open an issue to discuss changes or improvements.\n\n## Contact\n\nFor any questions or issues, please open an issue on [this GitHub repository](https://github.com/t-tani/defender2yara).\n\n## Acknowledgments\n\nThis project would not have been possible without the valuable resources and insights provided by the following:\n\n- **GitHub - commial/experiments** and **Windows Defender: Demystifying and Bypassing ASR by Understanding the AVS Signatures**: A special thanks to the author of the [commial/experiments](https://github.com/commial/experiments) repository on GitHub and the insightful paper [Windows Defender: Demystifying and Bypassing ASR by Understanding the AVS Signatures](https://i.blackhat.com/EU-21/Wednesday/EU-21-Mougey-Windows-Defender-demystifying-and-bypassing-asr-by-understanding-the-avs-signatures.pdf), presented at Black Hat Europe 2021. His work and research have significantly aided our understanding of various aspects of antivirus signatures and provided deep insights into the workings of Windows Defender signatures.\n\n- **GitHub\u2014taviso/loadlibrary**: A special thanks to Tavis Ormandy's repository [loadlibrary] (https://github.com/taviso/loadlibrary) on GitHub. This repository provided great insights into Microsoft Defender and was an entry point for reversing `msmpeng.dll`.\n\n- **Retooling Blog**: We also appreciate the author of the Retooling blog for their detailed article [An Unexpected Journey into Microsoft Defender's Signature World](https://retooling.io/blog/an-unexpected-journey-into-microsoft-defenders-signature-world). Their exploration and documentation of Microsoft Defender's signature mechanisms have been invaluable to this project.\n\n- **Threat Name Definitions**: We acknowledge Microsoft for their detailed [Threat Name Definitions](https://learn.microsoft.com/en-us/defender-xdr/malware-naming?view=o365-worldwide). This documentation has been essential in understanding the malware naming conventions used by Microsoft Defender.\n\nThank you to all these sources for contributing to the field and sharing their knowledge with the community.\n\n",
"bugtrack_url": null,
"license": null,
"summary": "Convert Microsoft Defender Antivirus Signatures(VDM) to YARA rules.",
"version": "1.0.2",
"project_urls": null,
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "bd0f8dd323c74225bca73cee2a0c9f6c495933a6f05c04cb928a21f72585d3a2",
"md5": "7d3e9364e94af61f9a710e40d1c33c73",
"sha256": "692d6e0261c95ebfe153449a9551823f6f54ccbac25b55363e487658761a89aa"
},
"downloads": -1,
"filename": "defender2yara-1.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7d3e9364e94af61f9a710e40d1c33c73",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.10",
"size": 34431,
"upload_time": "2024-07-25T16:44:47",
"upload_time_iso_8601": "2024-07-25T16:44:47.761150Z",
"url": "https://files.pythonhosted.org/packages/bd/0f/8dd323c74225bca73cee2a0c9f6c495933a6f05c04cb928a21f72585d3a2/defender2yara-1.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "d2884d3a084c07474c048738c58bf839dd14a97bbc39e89c8467c2a766b1602c",
"md5": "6dc941b98e18817f50c3bc22f23d8dbc",
"sha256": "281a072f84d86920e0d2e4237be1190f294e3f57d0327838d55b37a296c1e183"
},
"downloads": -1,
"filename": "defender2yara-1.0.2.tar.gz",
"has_sig": false,
"md5_digest": "6dc941b98e18817f50c3bc22f23d8dbc",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.10",
"size": 29282,
"upload_time": "2024-07-25T16:44:48",
"upload_time_iso_8601": "2024-07-25T16:44:48.937897Z",
"url": "https://files.pythonhosted.org/packages/d2/88/4d3a084c07474c048738c58bf839dd14a97bbc39e89c8467c2a766b1602c/defender2yara-1.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-07-25 16:44:48",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "defender2yara"
}
