A VBA parser and emulation engine to analyze malicious macros.
Python

README.md

ViperMonkey

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 deobfucation with ViperMonkey.

DISCLAIMER:

  • ViperMonkey is a very incomplete and experimental VBA Engine. For now it will NOT handle most real-life macros without errors.
  • VBA parsing and emulation is extremely slow for now.
  • 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 on my scarce spare time, so do not expect miracles. Any help from you will be very appreciated!

Quick links: Report Issues/Suggestions/Questions - Contact the Author - Repository - Updates on Twitter

News

  • 2016-09-26 v0.02: First published version
  • 2015-02-28 v0.01: First development version
  • see changelog in source code for more info.

Download and Install:

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

Usage:

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

python vmonkey.py <file>

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

python vmonkey.py -l warning <file>

Documentation:

Winter is coming.

How to Suggest Improvements, Report Issues or Contribute:

This is a personal open-source project, developed on my spare time. Any contribution, suggestion, feedback or bug report is welcome.

To suggest improvements, report a bug or any issue, please use the issue reporting page, providing all the information and files to reproduce the problem.

You may also contact the author directly to provide feedback.

The code is available in a GitHub repository. You may use it to submit enhancements using forks and pull requests.

License

This license applies to the ViperMonkey package, apart from the thirdparty folder which contains third-party files published with their own license.

The ViperMonkey package is copyright (c) 2015-2016 Philippe Lagadec (http://www.decalage.info)

All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  • Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
  • Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.