ViperMonkey v0.08 released: A VBA parser and emulation engine to analyze malicious macros

ViperMonkey is a VBA Emulation engine written in Python, designed to analyze and deobfuscate malicious VBA Macros contained in Microsoft Office files (Word, Excel, PowerPoint, Publisher, etc).

See my article “Using VBA Emulation to Analyze Obfuscated Macros“, for real-life examples of malware deobfuscation with ViperMonkey.



  • ViperMonkey is an experimental VBA Engine targeted at analyzing maldocs. It works on some but not all maldocs.
  • VBA parsing and emulation is extremely slow for now (see the speedup section for how to improve the speed).
  • VBA Emulation is hard and complex, because of all the features of the VBA language, of Microsoft Office applications, and all the DLLs and ActiveX objects that can be called from VBA.
  • This open-source project is only developed in my scarce spare time, so do not expect miracles. Any help from you will be very appreciated!

oletools Version

ViperMonkey requires the most recent version of oletools, not the version downloaded by the standard pip install. Make sure to either install the most recent oletools version by running the oletools ‘ install’, or make sure the most recent oletools install directory appears in PYTHONPATH, or install the most recent version of oletools using pip as described here.



The parsing library used by default in ViperMonkey can take a long time to parse some samples. ViperMonkey can be sped up considerably (~5 times faster) by running ViperMonkey using pypy rather than the regular Python interpreter. To use pypy do the following:

  1. Install pypy following the instructions here.
  2. Install the following Python packages. This can be done by downloading the .tar.gz for each package and running ‘sudo pypy install’ (note the use of pypy rather than python) for each package.
    1. setuptools
    2. colorlog
    3. olefile
    4. prettytable
    5. pyparsing

Stripping Useless Statements

The “-s” ViperMonkey command line option tells VipeMonkey to strip out useless statements from the Visual Basic macro code prior to parsing and emulation. For some maldocs, this can significantly speed up analysis.

Download and Install:

For now, there is no package on PyPI for automated installation. It must be done manually:

  • Download the archive from the repository.
  • Extract it in the folder of your choice
  • Install dependencies by running sudo -H pip install -U -r requirements.txt on Linux/Mac or pip install -U -r requirements.txt on Windows


To parse and interpret VBA macros from a document, use the vmonkey script:

python <file>

To make analysis faster (see the Speedup section), do:

pypy -s <file>

If the output is too verbose and too slow, you may reduce the logging level using the -l option:

python -l warning <file>

The ViperMonkey package is copyright (c) 2015-2018 Philippe Lagadec (