ViperMonkey
by decalage2
ViperMonkey is a Python-based VBA parser and emulation engine designed to analyze and deobfuscate malicious macros in Microsoft Office files.
A VBA parser and emulation engine to analyze malicious macros.
Primary Use Case
This tool is primarily used by malware analysts and security researchers to detect, analyze, and understand malicious VBA macros embedded in Office documents. It helps automate the deobfuscation and behavioral emulation of VBA code to reveal potentially harmful actions without executing the macros in a live environment.
- VBA parsing and emulation engine for Microsoft Office macros
- Supports Word, Excel, PowerPoint, Publisher, and other Office files
- Deobfuscates complex and obfuscated VBA malware macros
- Written in Python with optional PyPy support for performance
- Docker container available for easy setup and execution
- Open-source and actively maintained with community contributions
- Includes API tutorial and documentation for integration
- Demonstrated at Black Hat Europe 2019 with real-world examples
Installation
- Install Docker for containerized usage.
- Run `docker/dockermonkey.sh MYFILE` to analyze a file using Docker.
- Download and install PyPy 2.7 for improved performance (recommended).
- Ensure pip is installed for PyPy (`pypy -m pip`), install if missing (`pypy -m ensurepip`).
- Upgrade pip using `pypy -m pip install -U pip`.
- Download the ViperMonkey repository archive from GitHub and extract it.
- On Ubuntu, install pypy-dev with `sudo apt-get install pypy-dev`.
- Install dependencies with `pypy -m pip install -U -r requirements.txt`.
- Verify installation by running `pypy vmonkey.py`.
- Alternatively, install Python 2.7 and upgrade pip (`pip install -U pip`).
Usage
>_ docker/dockermonkey.sh MYFILERuns ViperMonkey inside a Docker container to analyze the specified Office file.
>_ pypy vmonkey.pyRuns ViperMonkey using the PyPy interpreter for faster VBA macro analysis.
>_ pypy -m pip install -U -r requirements.txtInstalls all required Python dependencies for ViperMonkey using PyPy.
>_ pypy -m ensurepipInstalls pip for PyPy if it is not already installed.
>_ pip install -U pipUpgrades pip to the latest version for Python 2.7 environment.
- Integrate ViperMonkey into automated malware triage pipelines to accelerate macro malware detection.
- Use ViperMonkey’s emulation outputs to enrich SIEM alerts with behavioral context for faster incident response.
- Leverage the tool in purple team exercises to simulate and analyze macro-based attack vectors.
- Combine ViperMonkey with sandbox environments to validate emulation results and improve detection accuracy.
- Deploy ViperMonkey in threat hunting workflows to proactively identify obfuscated macro threats in enterprise document stores.
Docs Take 2 Hours. AI Takes 10 Seconds.
Ask anything about ViperMonkey. Installation? Config? Troubleshooting? Get answers trained on real docs and GitHub issues—not generic ChatGPT fluff.
This tool hasn't been indexed yet. Request indexing to enable AI chat.
Admin will review your request within 24 hours
Related Tools
x64dbg
x64dbg/x64dbg
An open-source user mode debugger for Windows. Optimized for reverse engineering and malware analysis.
theZoo
ytisf/theZoo
A repository of LIVE malwares for your own joy and pleasure. theZoo is a project created to make the possibility of malware analysis open and available to the public.
flare-vm
mandiant/flare-vm
A collection of software installations scripts for Windows systems that allows you to easily setup and maintain a reverse engineering environment on a VM.
capa
mandiant/capa
The FLARE team's open-source tool to identify capabilities in executable files.
retoolkit
mentebinaria/retoolkit
Reverse Engineer's Toolkit
awesome-yara
InQuest/awesome-yara
A curated list of awesome YARA rules, tools, and people.