PyREBox: a Python scriptable Reverse Engineering sandbox

by do son · Published June 21, 2019 · Updated December 5, 2019

PyREBox is a Python scriptable Reverse Engineering sandbox. It is based on QEMU, and its goal is to aid reverse engineering by providing a dynamic analysis and debugging capabilities from a different perspective. PyREBox allows to inspect a running QEMU VM, modify its memory or registers, and to instrument its execution, by creating simple scripts in python to automate any kind of analysis. QEMU (when working as a whole-system-emulator) emulates a complete system (CPU, memory, devices…). By using VMI techniques, it does not require to perform any modification into the guest operating system, as it transparently retrieves information from its memory at run-time.

Several academic projects such as DECAF, PANDA, S2E, or AVATAR, have previously leveraged QEMU based instrumentation to overcome reverse engineering tasks. These projects allow to write plugins in C/C++ and implement several advanced features such as dynamic taint analysis, symbolic execution, or even record and replay of execution traces. With PyREBox, we aim to apply this technology focusing on keeping the design simple, and on the usability of the system for threat analysis.

Goals

Provide a whole system emulation platform with a simple interface for inspecting the emulated guest system.
- Finely grained instrumentation of system events.
- Integrated Virtual Machine Introspection (VMI), based on volatility. No agent or driver needs to be installed into the guest.
- An IPython based shell interface.
- A Python-based scripting engine, that allows integrating into the scripts any of the security tools based on this language (one of the biggest ecosystems).
Have a clean design, de-coupled from QEMU. Many projects that are built over QEMU do not evolve when QEMU gets upgraded, missing new features and optimizations, as well as security updates. In order to achieve this, PyREBox is implemented as an independent module that can be compiled together with QEMU requiring a minimal set of modifications.
Support for different architectures. Currently, PyREBox only supports Windows for x86 and x86-64 bit architectures, but its design allows us to support other architectures such as an ARM, MIPS, or PowerPC, and other operating systems as well.

IPython shell

Starting a PyREBox shell is as easy as typing the sh command on QEMU’s monitor. It will immediately start an IPython shell. This shell records the command history as well as the defined variables. For instance, you can save a value and recover it later at a different point of the execution, when you start the shell again. PyREBox takes advantage of all the available features in IPython such as auto-completion, command history, multi-line editing, and automated command help generation.

PyREBox will allow you to debug the system (or a process) in a fairly stealthy way. Unlike traditional debuggers that stay in the system being debugged (even modifying the memory of the debugged process to insert breakpoints), PyREBox stays completely outside the inspected system, and it does not require the installation of any driver or component into the guest.

PyREBox offers a complete set of commands to inspect and modify the state of the running VM. Just type list_commands to obtain a complete list. You can run any volatility plugin just by typing vol and the corresponding volatility command. For a complete list of available volatility plugins, you can type list_vol_commands. This list is generated automatically, so it will also show any volatility plugin you install on PyREBox’s volatility/ path.

You can also define your own commands! It is as simple as declaring a function in a script and loading it.

If you need something more expressive than a command, you can write a Python snippet leveraging the API. For a detailed description of the API, see Documentation or type help(api) in the shell.

Scripting

PyREBox allows to dynamically load scripts that can register callback functions that are called when certain events occur, like instructions executed, memory read/written, processes created/destroyed, and so on.

Given that PyREBox is integrated with Volatility, it will let you take advantage of all the volatility plugins for memory forensics in your python scripts. Many of the most famous reverse engineering tools are implemented in Python or at least have Python bindings. Our approach allows integrating any of these tools into a script.

Finally, given that python callbacks can introduce a performance penalty on frequent events such as instructions executed, it is also possible to create triggers. Triggers are native-code plug-in’s (developed in C/C++) that can be inserted dynamically at run-time on an event just before the Python callback is executed. This allows limiting the number of events that hit the python code, as well as to precompute values in native code.

In this repository, you will find example scripts that can help you to write your owncode.

Changelog

[Dec 5, 2019] Beta version of PyREBox3, ready on the python3migration branch. The tool has been ported to Python3 and Volatility3. Plugins have not been ported yet.

Install

Starting a VM

PyREBox is based on QEMU, so in order to start a VM withing PyREBox, you need to run it exactly as you were booting up a QEMU VM. A couple of example scripts are provided: start_i386.sh, start_x86_64.sh, you can use them as an example.

The only QEMU monitor option supported currently is stdio (-monitor stdio).

Tutorial

Source: https://github.com/Cisco-Talos/