Nowadays in the reverse-engineering world, almost everything is scriptable using Python: IDA Pro, WinDbg, ImmunitDebugger, etc. The thing is OllyDbg2 wasn't. The only way to interact with OllyDbg2's API was by creating a C/C++ plugin. But we all know everything is easier in Python, that's the reason why I started this project back in 2012 summer.
To be able to export OllyDbg2's API to Python (currently Py275), we need two important things:
- python-loader: this is an OllyDbg2 plugin that imports the Python engine ; with that plugin you can launch some Python into your debugger
- python-bindings-swig: this project builds the connectors you need to poke OllyDbg2's API with Python
The python-loader tries also to enhance user experience by adding a command-line edit bar in order to write easily Python one-liner without loading a script. At the moment, that bar isn't working very well (I'm not a GUI expert at all.), but I will give it a try to build better one.
The python-bindings-swig project is a bit more touchy, it is using SWIG in order to generate the bindings automatically and it seems to work pretty great so far. But SWIG can be sometimes a bit weird to play with, so if I made some mistakes don't hesitate to pull-requests corrections!
I've tried to expose the main features we would like to have when it comes to script a debugger:
- CPU state inspection: get/set x86 registers, get information about segment selectors
- memory: read, write in the debuggee memory ; also obtain information about specific memory regions
- assembler/disassembler: interact with the internal x86 assembler/disassembler
- breakpoints: easily set/remove software/hardware normal/conditionnal breakpoints wherever you want
- symbols: try to use Microsoft/OllyDbg2 API to obtain symbols information (like a function name by its address)
- enhance the disassembly: you can add comments and/or labels easily
- looking for something in memory: there are also a couple of methods to look for some hexadecimal bytes or instructions in memory, really handy
- instrument the debugger: ask the debugger to StepInto/StepOver/ExecuteUntilRet in the debuggee
- etc.
If you want to see real examples, check out the samples/ directory! If you have idea of cool examples to show case the API feel free to contact me.
You will need Python development files, I'm currently using Python 275.
Building the Python bindings via SWIG
To build the API bindings you will need SWIG and Python 275.
- Fetch the last Ollydbg2's development files. Move the
plugin.hin theollydbg2-plugin-development-files/inc/directory, and theollydbg.libinollydbg2-plugin-development-files/lib/. - Then copy the
plugin.htoplugin-swig.h. Here are the things you have to change in theplugin-swig.hfile:
- Some API are declared in the
plugin.hfile, but in fact they aren't in Ollydbg2's export address table ; so comment them. Here is the list:SetcaseA,SetcaseW,StrcopycaseA,StrcopycaseW,Strnst,StrnstrW,StrcmpW,Div64by32,CRCcalc,Getcpuidfeatures,Maskfpu,Clearfpu. - Remove the
__cdeclfrom thestdapi,varapi,oddata,pentry. There is also another one inEMUFUNC's typedef. - Remove the
constfrom theoddatadeclaration (like that you will be able to interact with internal variables) both inplugin.h&plugin-swig.h. - Remove the
_importkeyword fromoddata's definition. - Rename the
Readmemory's first argument intochar *buff, add before%pybuffer_mutable_string(char *buf), add after%typemap(in) char *buf;. Do the same thing with the following API: Disasmand its first argumentAssembleallformsand its last argumentGetanalysercommentand its third argumentGetproccommentand its third argumentDecodeaddressand its fourth argumentDecoderelativeoffsetand its third argument- Anonymous nested structures aren't supported, so you have to give a name to the unions in the following structure:
t_result.
- Open the
python-bindings-swigproject and build the Python bindings. - You're ready to go!
-
git clone https://github.com/0vercl0k/ollydbg2-python.git -
Move all your
OllyDbg2binaries in theollydbg2-pythondirectory. It should looks like this:D:\tmp\ollydbg2-python>ls -la . total 3572 drw-rw-rw- 8 0vercl0k 0 4096 2013-09-22 16:17 . drw-rw-rw- 5 0vercl0k 0 4096 2013-09-22 16:13 .. drw-rw-rw- 7 0vercl0k 0 4096 2013-09-22 16:13 .git -rw-rw-rw- 1 0vercl0k 0 1061944 2008-03-21 01:44 dbghelp.dll drw-rw-rw- 2 0vercl0k 0 0 2013-09-22 16:13 ollyapi -rwxrwxrwx 1 0vercl0k 0 2547200 2012-11-18 21:46 ollydbg.exe -rw-rw-rw- 1 0vercl0k 0 13705 2013-09-22 16:18 ollydbg.ini drw-rw-rw- 7 0vercl0k 0 4096 2013-09-22 16:13 ollydbg2-plugin-development-files drw-rw-rw- 2 0vercl0k 0 0 2013-09-22 16:17 plugins -rw-rw-rw- 1 0vercl0k 0 2713 2013-09-22 16:13 README.md drw-rw-rw- 11 0vercl0k 0 4096 2013-09-22 16:13 samples drw-rw-rw- 2 0vercl0k 0 4096 2013-09-22 16:17 udds -
Build the python-loader project in Release mode and check you have a
python-loader.dllfile inplugins/:D:\tmp\ollydbg2-python>ls -la plugins total 24 drw-rw-rw- 2 0vercl0k 0 0 2013-09-22 16:22 . drw-rw-rw- 8 0vercl0k 0 4096 2013-09-22 16:17 .. -rw-rw-rw- 1 0vercl0k 0 18432 2013-09-22 16:22 python-loader.dll -
Build the python-buildings-swig project in Release mode, check you have a
_python_bindings_swig.pydfile and apython_bindings_swig.pyinollyapi/:D:\tmp\ollydbg2-python>ls -la ollyapi total 1436 drw-rw-rw- 2 0vercl0k 0 4096 2013-09-22 16:26 . drw-rw-rw- 8 0vercl0k 0 4096 2013-09-22 16:17 .. [...] -rw-rw-rw- 1 0vercl0k 0 971776 2013-09-22 14:09 _python_bindings_swig.pyd -rw-rw-rw- 1 0vercl0k 0 416207 2013-09-22 14:08 python_bindings_swig.py -
Now launch
ollydbg.exe, and check the log window to see if the python-loader plugin has been successfully loaded. -
Script and have fun!
If you encounter any issues please let me know by filling an issue here: https://github.com/0vercl0k/ollydbg2-python/issues. Also try to be explicit, and give me enough details to be able to repro the issue on my machine: OS version, OllyDbg2 configuration, script, etc.
Contributing ============Feel free to contribute to this project: if you're used to play with Windows' GUI API please help me to make a working bar, if you have idea about cool samples to show case the API send me your ideas, if you want to implement some high level API methods please do! If you have also any comments, remarks I would love to hear them :).