{"id":15037256,"url":"https://github.com/decalage2/vipermonkey","last_synced_at":"2025-05-16T00:09:08.181Z","repository":{"id":38392966,"uuid":"69185746","full_name":"decalage2/ViperMonkey","owner":"decalage2","description":"A VBA parser and emulation engine to analyze malicious macros.","archived":false,"fork":false,"pushed_at":"2024-07-10T06:28:56.000Z","size":3342,"stargazers_count":1092,"open_issues_count":74,"forks_count":186,"subscribers_count":60,"default_branch":"master","last_synced_at":"2025-05-16T00:09:01.602Z","etag":null,"topics":["emulation","macros","malware-analysis","parser","pyparsing","python","security","vba"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/decalage2.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-09-25T19:27:22.000Z","updated_at":"2025-05-13T17:23:54.000Z","dependencies_parsed_at":"2024-04-25T23:31:50.952Z","dependency_job_id":"c627a870-f0ae-4c01-aba0-941883650a17","html_url":"https://github.com/decalage2/ViperMonkey","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/decalage2%2FViperMonkey","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/decalage2%2FViperMonkey/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/decalage2%2FViperMonkey/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/decalage2%2FViperMonkey/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/decalage2","download_url":"https://codeload.github.com/decalage2/ViperMonkey/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254442856,"owners_count":22071878,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["emulation","macros","malware-analysis","parser","pyparsing","python","security","vba"],"created_at":"2024-09-24T20:34:01.228Z","updated_at":"2025-05-16T00:09:03.154Z","avatar_url":"https://github.com/decalage2.png","language":"Python","readme":"ViperMonkey\n===========\n\nViperMonkey is a VBA Emulation engine written in Python, designed to analyze\nand deobfuscate malicious VBA Macros contained in Microsoft Office files\n(Word, Excel, PowerPoint, Publisher, etc).\n\nSee the article \"[Using VBA Emulation to Analyze Obfuscated Macros](http://decalage.info/vba_emulation)\",\nfor real-life examples of malware deobfucation with ViperMonkey.\n\nViperMonkey was also demonstrated at the Black Hat Europe 2019 conference: \nsee the [slides](https://decalage.info/en/bheu2019) \nand [video](https://youtu.be/l5sMPGjtKn0?list=PLH15HpR5qRsXiPOP3gxN6ultoj0rAR6Yn\u0026t=1118) (at 18:38).\n\nViperMonkey was created by [Philippe Lagadec](https://github.com/decalage2) in 2015-2016, and the project\nis maintained in the repository https://github.com/decalage2/ViperMonkey. \nSince November 2017, most of the development is done by [Kirk Sayre](https://github.com/kirk-sayre-work) \nand other contributors in the repository https://github.com/kirk-sayre-work/ViperMonkey. \nThe main repository is synchronised regularly, but cutting edge improvements are usually\navailable first in Kirk's version.\n\n**Quick links:**\n[Report Issues/Suggestions/Questions](https://github.com/decalage2/ViperMonkey/issues) -\n[Contact the Author](http://decalage.info/contact) -\n[Repository](https://github.com/decalage2/ViperMonkey) -\n[Updates on Twitter](https://twitter.com/decalage2) -\n[API Tutorial](docs/APITutorial.md)\n\n\n**DISCLAIMER**:\n- ViperMonkey is an experimental VBA Engine targeted at analyzing maldocs. It works on some but not all maldocs. \n- VBA parsing and emulation is *extremely* slow for now (see the speedup section for how to improve the speed).\n- VBA Emulation is hard and complex, because of all the features of the VBA language, of Microsoft\nOffice applications, and all the DLLs and ActiveX objects that can be called from VBA.\n- This open-source project is only developed on my scarce spare time, so do not expect\nmiracles. Any help from you will be very appreciated!\n\nDownload and Install:\n---------------------\n\n**Easy Install**\n\n1. Install docker.\n2. Run `docker/dockermonkey.sh MYFILE` to analyze file MYFILE.\n\ndockermonkey.sh wil automatically pull down a preconfigured docker container, update ViperMonkey to\nthe latest version in the container, and then analyze MYFILE by running ViperMonkey in the\ncontainer. No other packages or configuration will need to be performed.\n\nFor information on using dockermonkey.sh run `docker/dockermonkey.sh -h`.\n\n**Installation using PyPy (recommended)**\n\nFor performance reasons, it is highly recommended to use PyPy (5x faster), but it is\nalso possible to run Vipermonkey with the normal Python interpreter\n(CPython) if you cannot use PyPy.\n\n1. If PyPy is not installed on your system, see http://pypy.org/download.html and download **PyPy 2.7**. (not 3.x)\n2. Check if pip is installed for pypy: run `pypy -m pip`\n3. If pip is not installed yet, run `pypy -m ensurepip` on Windows, or `sudo -H pypy -m ensurepip` on Linux/Mac\n4. Make sure pip is up-to-date, by running `pypy -m pip install -U pip`\n5. Download the archive from the repository: https://github.com/decalage2/ViperMonkey/archive/master.zip\n6. Extract it in the folder of your choice, and open a shell/cmd window in that folder.\n7. Under Ubuntu install pypy-dev (sudo apt-get install pypy-dev).\n8. Install dependencies by running `pypy -m pip install -U -r requirements.txt` on Windows, or `sudo -H pypy -m pip install -U -r requirements.txt` on Linux/Mac\n9. Check that Vipermonkey runs without error: `pypy vmonkey.py`\n\n**Installation using CPython**\n\n1. Make sure you have the latest Python 2.7 installed: https://www.python.org/downloads/\n2. If you have both Python 2 and 3 versions installed, use `pip2` instead of `pip` in the \n   following commands, to install in Python 2 and not 3.\n4. Make sure pip is up-to-date, by running `pip install -U pip`\n2. Use pip to download and install vipermonkey with all its dependencies,\n   by running the following command on Windows:\n```\npip install -U https://github.com/decalage2/ViperMonkey/archive/master.zip\n```\nOn Linux/Mac:\n```\nsudo -H pip install -U https://github.com/decalage2/ViperMonkey/archive/master.zip\n```\n3. Check that Vipermonkey runs without error: open a shell/cmd window\n   in any directory, an simply run `vmonkey`\n\n\nUsage:\n------\n\nTo run ViperMonkey in a Docker container with the `-s`, `--jit`, and\n`--iocs` options do:\n\n```text\ndocker/dockermonkey.sh \u003cfile\u003e\n```\n\nTo parse and interpret VBA macros from a document, use the vmonkey script:\n\n```text\nvmonkey.py \u003cfile\u003e\n```\n\nTo make analysis faster (see the Speedup section), do:\n\n```text\npypy vmonkey.py -s \u003cfile\u003e\n```\n\n*Note:* It is recommended to always use the `-s` option. When given\n the `-s` option ViperMonkey modifies some difficult to parse Visual\n Basic language constructs so that the ViperMonkey parser can\n correctly parse the input.\n\nIf the output is too verbose and too slow, you may reduce the logging level using the\n-l option:\n\n```text\nvmonkey.py -l warning \u003cfile\u003e\n```\n\nIf the sample being analyzed has long running loops that are causing\nemulation to be unacceptably slow, use the `--jit` option to convert\nVB loops directly to Python in a JIT fashion during emulation.\n\n```text\nvmonkey.py --jit \u003cfile\u003e\n```\n\n*Note:* ViperMonkey's Python JIT loop conversion converts VB loops to\n Python and `evals` the generated Python code. While the Python\n conversion process is based on the parsed AST (not directly on the VB\n text) and VB data values are escaped/converted/modified to become\n valid in Python, any use of `eval` in Python potentially introduces a\n security risk. If this is a concern the `dockermonkey.sh` script can be\n used to run ViperMonkey in a sandboxed manner. `dockermonkey.sh` runs\n ViperMonkey in a fresh Docker container on each run (no file system\n modifications persist between runs) and networking is turned off in\n the Docker container.\n\nSometimes a malicious VBScript or Office file will generate IOCs\nduring execution that are not used or that ViperMonkey does not see\nused. These intermediate IOCs are tracked by ViperMonkey during the\nemulation process and can be reported with the `--iocs` option.\n\n```text\nvmonkey --iocs \u003cfile\u003e\n```\n\nNote that one of the intermediate IOCs reported by ViperMonkey is\ninjected shell code bytes. If the sample under analysis performs\nprocess injection directly in VB, ViperMonkey will report the injected\nbyte values as an intermediate IOC with the `--iocs` flag. These byte\nvalues can then be written into a raw shell code file which can be\nfurther analyzed with a shell code emulator.\n\n**oletools Version**\n\nViperMonkey requires the most recent version of\n[oletools](https://github.com/decalage2/oletools), at least v0.52.3. Make sure to either install the most recent oletools\nversion by running `pip install -U oletools`, or make sure\nthe most recent oletools install directory appears in PYTHONPATH, or\ninstall the most recent development version of oletools using pip as described\n[here](https://github.com/decalage2/oletools/wiki/Install#how-to-install-the-latest-development-version). \n\n**Speedup**\n\n***pypy***\n\nThe parsing library used by default in ViperMonkey can take a long\ntime to parse some samples. ViperMonkey can be sped up considerably (~5\ntimes faster) by running ViperMonkey using [pypy](https://pypy.org/)\nrather than the regular Python interpreter. To use pypy do the\nfollowing:\n\n1. Install pypy following the instructions [here](https://pypy.org/download.html).\n2. Install the following Python packages. This can be done by\n   downloading the .tar.gz for each package and running 'sudo pypy\n   setup.py install' (note the use of pypy rather than python) for\n   each package.\n   1. [setuptools](https://pypi.python.org/pypi/setuptools)\n   2. [colorlog](https://pypi.python.org/pypi/colorlog)\n   3. [olefile](https://pypi.python.org/pypi/olefile)\n   4. [prettytable](https://pypi.python.org/pypi/PrettyTable)\n   5. [pyparsing](https://pypi.python.org/pypi/pyparsing/2.2.0)\n\n***Stripping Useless Statements***\n\nThe \"-s\" ViperMonkey command line option tells VipeMonkey to strip out\nuseless statements from the Visual Basic macro code prior to parsing\nand emulation. For some maldocs this can significantly speed up\nanalysis.\n\n**Emulating File Writes**\n\nViperMonkey emulates some file writing behavior. The SHA256 hash of\ndropped files is reported in the ViperMonkey analysis results and the\nactual dropped files are saved in the directory MALDOC_artifacts/,\nwhere MALDOC is the name of the analyzed maldoc file.\n\nViperMonkey also searches Office 97 and Office 2007+ files for\nembedded PE files. These are automatically extracted and reported as\ndropped files in the MALDOC_artifacts/ directory.\n\n**Emulating Specific VBA Functions**\n\nBy default ViperMonkey emulates maldoc behavior starting from standard\nmacro auto run function (like AutoOpen, Document_Open, Document_Close,\netc.). In some cases you may want to emulate the behavior starting\nfrom a non-standard auto run function. This is supported via the -i\ncommand line option. To emulate maldoc behavior starting from function\nFoo, use the command line option '-i Foo'. To emulate behavior\nstarting from multiple non-standard entry points, use the command line\noption '-i \"Foo,Bar,Baz\"' (note that the entry point function names\nare comma seperated and must appear in a double quoted string).\n\n\n[//]: # (Home page http://www.decalage.info/vipermonkey)\n[//]: # (Documentation https://github.com/decalage2/ViperMonkey/wiki)\n[//]: # (Download/Install https://github.com/decalage2/ViperMonkey/wiki/Install)\n\n\nAPI Interface:\n--------------\n\nViperMonkey also includes a Python API interface that can be used for\n finer control emulation of your sample or for integration \n into an existing project.\n\nPlease see the [API Tutorial](docs/APITutorial.md) for more information.\n\n\nNews\n----\n\n- **2018-03-22 v0.06**: new features and bug fixes contributed by Kirk Sayre\n- 2018-3:\n  - Added support for parsing some technically invalid VBA statements.\n  - Additional parsing fixes.\n  - Added support for starting emulation at non-standard functions.\n- 2018-2:\n  - Added support for Environ, IIf, Base64DecodeString, CLng, Close, Put, Run, InStrRev,\n    LCase, RTrim, LTrim, AscW, AscB, and CurDir functions.\n- 2018-1\n  - Added emulation support for saving dropped files.\n  - Added support for For Each loops.\n  - Added support for While Wend loops.\n  - Handle 'Exit Do' instructions.\n- 2018-01-12 v0.05: a lot of new features and bug fixes contributed by Kirk Sayre\n- 2017-12-15:\n  - Added support for Select and Do loops.\n  - Added support for 'End Sub' and 0 argument return statements.\n  - Added support for #if constructs.\n  - Each VBA stream is now parsed in a separate thread (up to the # of machine cores).\n- 2017-11-28:\n  - Added parsing for private type declarations.\n  - Report calls to CreateProcessA in final report.\n  - Handle Application.Run() of locally defined methods.\n- 2017-11-23:\n  - Added VBA functions Abs, Fix, Hex, String, CByte, Atn, Dir, RGB, Log, Cos, Exp, Sin, Str, and Val.\n  - Added support for 'Exit Function' operator.\n  - Changed math operators to also work with string representations of integers.\n  - Added a configurable iteration limit on loops.\n- 2017-11-14:\n  - Added support for InStr, Replace, Sgn, Sqr, UBound, LBound, Trim, StrConv, Split, StrReverse, and Int VB functions.\n  - Added support for string character subscripting.\n  - Added support for negative integer literals.\n  - Added support for if-then-else statements.\n  - Added support for Const and initial values for global variable declarations.\n  - Handle assignments of boolean expressions to variables.\n- 2017-11-03:\n  - Added support for Left(), Right(), Array(), and BuiltInDocumentProperties() functions.\n  - Added support for global variables.\n  - Fixed some parse errors.\n  - Added analysis of AutoClose() functions.\n- 2016-09-26 v0.02: First published version\n- 2015-02-28 v0.01: [First development version](https://twitter.com/decalage2/status/571778745222242305)\n- see changelog in source code for more info.\n\nHow to Suggest Improvements, Report Issues or Contribute:\n---------------------------------------------------------\n\nThis is a personal open-source project, developed on my spare time. Any contribution, suggestion, feedback or bug\nreport is welcome.\n\nTo suggest improvements, report a bug or any issue, please use the\n[issue reporting page](https://github.com/decalage2/ViperMonkey/issues), providing all the\ninformation and files to reproduce the problem.\n\nYou may also [contact the author](http://decalage.info/contact) directly to provide feedback.\n\nThe code is available in [a GitHub repository](https://github.com/decalage2/ViperMonkey). You may use it\nto submit enhancements using forks and pull requests.\n\nLicense\n-------\n\nThis license applies to the ViperMonkey package, apart from the thirdparty folder which contains third-party files\npublished with their own license.\n\nThe ViperMonkey package is copyright (c) 2015-2020 Philippe Lagadec (http://www.decalage.info)\n\nAll rights reserved.\n\nRedistribution and use in source and binary forms, with or without modification,\nare permitted provided that the following conditions are met:\n\n * Redistributions of source code must retain the above copyright notice, this\n   list of conditions and the following disclaimer.\n * Redistributions in binary form must reproduce the above copyright notice,\n   this list of conditions and the following disclaimer in the documentation\n   and/or other materials provided with the distribution.\n\nTHIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \"AS IS\" AND\nANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED\nWARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE\nDISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE\nFOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL\nDAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR\nSERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER\nCAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,\nOR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE\nOF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.\n\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdecalage2%2Fvipermonkey","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdecalage2%2Fvipermonkey","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdecalage2%2Fvipermonkey/lists"}