<commit_before>#VMAttack **IDA** PRO Plugin
**IDA Pro Plugin for static and dynamic virtualization-based packed analysis and deobfuscation.**

**VMAttack was awarded the _second place_ at the annual [IDA Pro Plug-in Contest in 2016](https://www.hex-rays.com/contests/2016/index.shtml)!**

##Introduction

VMAttack is an **IDA PRO** Plug-in which enables the reverse engineer to use additional analysis features designed to counter _virtualization-based obfuscation_. For now the focus is on **stack based virtual machines**, but will be broadened to support more architectures in the future. The plugin supports static and dynamic analysis capabilities which use **IDA API** features in conjunction with the plugins own analysis capabilities to provide automatic, semi-automatic and manual analysis functionality. 
The main goal of this plugin is to assist the reverse engineer in undoing the _virtualization-based obfuscation_ and to automate the reversing process where possible.

##Installation
###Prerequisites

- IDA Pro >= 6.6

- Python 2.7.10/.11 

- Tested with Windows 7 and Windows 10.



###Guided Install

To install the plugin simply run the setup.py:

```python
python setup.py install
```

You will be prompted for the full path to your **IDA PRO** installation, aside from that no user interaction should be required.

###Alternative manual Install:
Should the guided install fail for any reason a manual installation is also possible.

The only required python dependencies are `distorm3` and `idacute` which can be installed via pip:

```python
pip install distorm3 idacute
```

Next the Windows environment variable should be set:

```
setx VMAttack X:full\path\to\plugin
```

Last you should copy the `VMAttack_plugin_stub.py` into your **IDA PRO** Plugins directory. That's it, now you're good to go!

##Quick start guide

The Example folder contains the obfuscated binary and source binary of an add function. The obfuscated **addvmp** contains the VM function which we will analyze now.

![alt text](screenshots/overview.png "Problem Statement")

After a quick glance over the binary we see the simple structure: two arguments, `0AFFE1` and `0BABE5` are deployed on the stack and then a stub is called.
 
![alt text](screenshots/stub.png "Problem Statement")
 
The stub starts the virtual machine function with a reference to the start of the VM byte code pushed onto the stack.

![alt text](screenshots/stub2.png "Problem Statement")

Following the address we see the virtual machine function which is basically an interpreter for the received byte code.

![alt text](screenshots/switch.png "Interpreter")

A solution to this obfuscation would be the reversal of the interpreter and the interpretation of the byte code by the reverse engineer. Due to the time consuming nature of this task we will try to reverse the binary with our VMAttack plugin.

VMAttacks static analysis functionality is enabled by default. The dynamic analysis capabilities however require an extra step. Since we want to use the static and dynamic capabilities for this demo, first we need to enable the dynamic functionality of VMAttack. This is done by either generating an instruction trace dynamically or loading an instruction trace from file. Trace generation is automatic and upon completion it will produce a success notification in **IDA**s _output window_. Traversed paths will be colored in a shade of blue, where a darker shade represents a higher number of traversals. Alternatively the loaded trace will only produce the success notification in **IDA**s _output window_.
With the newly generated/loaded trace we now have dynamic and static capabilities enabled and can start the _grading system analysis_. Starting with the _grading analysis_ is usually a good fit, since it is automated and takes several analysis capabilities into account. This enables a **cumulative** result which can even tolerate analysis errors to some extent and still produce good results. At the end of the grading analysis the now graded trace will be presented in the **grading viewer**. The trace can now be filtered either by double clicking a grade or via context menu where the user will be prompted to input the grade threshold to display.
In the case of addvmp it will be enough to select the highest grade to be presented with the deobfuscated function (since the original function is quite simple in this case). In becomes obvious, that the two values passed over the stack are added together. Additionally, should the result be not satisfiable, the user can change the importance of an analysis function (**see settings**) or even disable them (by setting the importance to 0), to produce better results. Simply change the importance and re-run the grading analysis.

![alt text](screenshots/grading4.png "Grading Success")<commit_msg>added issues section;<commit_after>#VMAttack **IDA** PRO Plugin
**IDA Pro Plugin for static and dynamic virtualization-based packed analysis and deobfuscation.**

**VMAttack was awarded the _second place_ at the annual [IDA Pro Plug-in Contest in 2016](https://www.hex-rays.com/contests/2016/index.shtml)!**

##Introduction

VMAttack is an **IDA PRO** Plug-in which enables the reverse engineer to use additional analysis features designed to counter _virtualization-based obfuscation_. For now the focus is on **stack based virtual machines**, but will be broadened to support more architectures in the future. The plugin supports static and dynamic analysis capabilities which use **IDA API** features in conjunction with the plugins own analysis capabilities to provide automatic, semi-automatic and manual analysis functionality. 
The main goal of this plugin is to assist the reverse engineer in undoing the _virtualization-based obfuscation_ and to automate the reversing process where possible.

##Installation
###Prerequisites

- IDA Pro >= 6.6

- Python 2.7.10/.11 

- Tested with Windows 7 and Windows 10.

###Guided Install

To install the plugin simply run the setup.py:

```python
python setup.py install
```

You will be prompted for the full path to your **IDA PRO** installation, aside from that no user interaction should be required.

###Alternative manual Install:
Should the guided install fail for any reason a manual installation is also possible.

The only required python dependencies are `distorm3` and `idacute` which can be installed via pip:

```python
pip install distorm3 idacute
```

Next the Windows environment variable should be set:

```
setx VMAttack X:full\path\to\plugin
```

Last you should copy the `VMAttack_plugin_stub.py` into your **IDA PRO** Plugins directory. That's it, now you're good to go!

###Possible Issues

 - Unable to find vcvarsall.bat => you need to install 'Microsoft Visual C++ Compiler for Python 2.7'

##Quick start guide

The Example folder contains the obfuscated binary and source binary of an add function. The obfuscated **addvmp** contains the VM function which we will analyze now.

![alt text](screenshots/overview.png "Problem Statement")

After a quick glance over the binary we see the simple structure: two arguments, `0AFFE1` and `0BABE5` are deployed on the stack and then a stub is called.
 
![alt text](screenshots/stub.png "Problem Statement")
 
The stub starts the virtual machine function with a reference to the start of the VM byte code pushed onto the stack.

![alt text](screenshots/stub2.png "Problem Statement")

Following the address we see the virtual machine function which is basically an interpreter for the received byte code.

![alt text](screenshots/switch.png "Interpreter")

A solution to this obfuscation would be the reversal of the interpreter and the interpretation of the byte code by the reverse engineer. Due to the time consuming nature of this task we will try to reverse the binary with our VMAttack plugin.

VMAttacks static analysis functionality is enabled by default. The dynamic analysis capabilities however require an extra step. Since we want to use the static and dynamic capabilities for this demo, first we need to enable the dynamic functionality of VMAttack. This is done by either generating an instruction trace dynamically or loading an instruction trace from file. Trace generation is automatic and upon completion it will produce a success notification in **IDA**s _output window_. Traversed paths will be colored in a shade of blue, where a darker shade represents a higher number of traversals. Alternatively the loaded trace will only produce the success notification in **IDA**s _output window_.
With the newly generated/loaded trace we now have dynamic and static capabilities enabled and can start the _grading system analysis_. Starting with the _grading analysis_ is usually a good fit, since it is automated and takes several analysis capabilities into account. This enables a **cumulative** result which can even tolerate analysis errors to some extent and still produce good results. At the end of the grading analysis the now graded trace will be presented in the **grading viewer**. The trace can now be filtered either by double clicking a grade or via context menu where the user will be prompted to input the grade threshold to display.
In the case of addvmp it will be enough to select the highest grade to be presented with the deobfuscated function (since the original function is quite simple in this case). In becomes obvious, that the two values passed over the stack are added together. Additionally, should the result be not satisfiable, the user can change the importance of an analysis function (**see settings**) or even disable them (by setting the importance to 0), to produce better results. Simply change the importance and re-run the grading analysis.

![alt text](screenshots/grading4.png "Grading Success")
{'fraction_non_alphanumeric': 0.051525354555657585, 'fraction_numerical': 0.005917763493521069, 'mean_word_length': 4.869461077844312, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 6, 'https://': 2, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1286168', 'n_tokens_mistral': 2432, 'n_tokens_neox': 2275, 'n_words': 1432}